Merge pull request #22 from RedHatProductSecurity/update-readme

update readme with details of trust-prime and production URLs for Atlas

Author: jasinner

README.md

@@ -15,16 +15,22 @@ $ pip install git+https://github.com/RedHatProductSecurity/trustshell.git#egg=tr
 
 Ensure the following environment variables are set:
 
-`export TRUSTIFY_URL="https://atlas.release.stage.devshift.net"`
+Atlas Production:
+`export TRUSTIFY_URL="https://atlas.release.devshift.net"`
+`export AUTH_ENDPOINT="https://auth.redhat.com/auth/realms/EmployeeIDP/protocol/openid-connect"`
 
 
-stage:
+Atlas Stage:
 
+`export TRUSTIFY_URL="https://atlas.release.stage.devshift.net"`
 `export AUTH_ENDPOINT="https://auth.stage.redhat.com/auth/realms/EmployeeIDP/protocol/openid-connect"`
 
 ## Usage
 
 ### Find matching PackageURLs in Trustify:
+Each component in Atlas has a PackageURL (purl). This helps remove ambiguity around the type of component.
+Before relating a component to a product, you first need to determine the purl of the component.
+You can do using trustshell, eg:
 
 ```commandline
 $ trust-purl qemu
@@ -35,6 +41,7 @@ pkg:rpm/redhat/[email protected]+el8.10.0+22375+ea5e8167.2
 ```
 
 ### Find matching products for purl:
+Once you have a PackageURL, you can then relate that to any products using the `trust-products` command. For example:
 
 ```commandline
 $ trust-products pkg:oci/quay-builder-qemu-rhcos-rhel8
@@ -44,3 +51,18 @@ pkg:oci/quay-builder-qemu-rhcos-rhel8
 └── pkg:oci/quay-builder-qemu-rhcos-rhel8?tag=v3.12.8-1
     └── cpe:/a:redhat:quay:3:*:el8:*
 ```
+
+### Prime the Trusify graph:
+If components are found with the trust-purl command, but they are not being linked to products with
+trust-products, it could be because the Trustify graph cache is not yet primed. In order to prime the graph
+cache run the `trust-prime` command as follows.
+
+```commandline
+# trust-prime
+Status before prime:
+graph count: 0
+sbom_count: 673
+Priming graph ...
+```
+
+It can also be run with `--check` to see the graph and sbom counts without actually priming the garph cache.

src/trustshell/products.py

@@ -32,7 +32,7 @@
 @click.command()
 @click.option("--check", "-c", is_flag=True, help="Check the status only, don't prime")
 def prime_cache(check: bool):
-    """Prime the analysis/component cache"""
+    """Prime the analysis/component graph cache"""
     auth_header = {}
     if AUTH_ENABLED:
         access_token = check_or_get_access_token()
@@ -48,7 +48,7 @@ def prime_cache(check: bool):
     console.print(f"graph count: {graph_count}")
     console.print(f"sbom_count: {sbom_count}")
     if not check:
-        console.print("Priming graph ...")
+        console.print("Priming graph cache...")
         httpx.get(f"{TRUSTIFY_URL}analysis/component", headers=auth_header, timeout=60)