doc: add trustification related documentation

docs/trustification.md

@@ -0,0 +1,64 @@
+In order to use `guac-rs` library with [trustification](http://trustification.io), start
+
+* Run core trustification services
+
+```
+$ [trustification/deploy/compose]  docker-compose -f compose.yaml -f compose-guac.yaml up --force-recreate
+```
+
+* You can run the rest of the services manually
+
+```
+$ [trustification] RUST_LOG=info cargo run -p trust -- vexination api --devmode &
+RUST_LOG=info cargo run -p trust -- bombastic api --devmode &
+RUST_LOG=info cargo run -p trust -- v11y api --devmode &
+RUST_LOG=info cargo run -p trust -- vexination indexer --devmode &
+RUST_LOG=info cargo run -p trust -- bombastic indexer --devmode &
+RUST_LOG=info cargo run -p trust -- v11y indexer --devmode &
+```
+
+* You might want to run SPoG API separately as that's the service that uses `guac-rs` library the most
+
+```
+RUST_LOG=info cargo run -p trust -- spog api --devmode
+```
+
+* Ingest SBOM data from the ds1 set
+
+```
+$ [trustification] RUST_LOG=info cargo run -p trust bombastic walker --sink http://localhost:8082 --devmode --source ./data/ds1/sbom
+```
+
+* After SBOMs have been ingested, ingest the VEX files
+
+```
+$ [trustification] RUST_LOG=info cargo run -p trust -- vexination walker --devmode -3 --sink http://localhost:8081/api/v1/vex --source ./data/ds1/csaf
+```
+
+* After this Trustification and Guac should be properly configured and populated with the test dataset
+* You can access [Guac GraphQL explorer](http://localhost:8085)
+* Some example generic queries to run can be found [here](https://github.com/guacsec/guac/tree/main/pkg/assembler/graphql/examples)
+* Examples of trustification specific queries can be found [here](../example/queries/)
+* You can also access the database directly with 
+```
+psql -h localhost -U guac guac
+```
+and explore the data
+* [Examples](../lib/tests/spog.rs) are set to run against the instance of Guac started in the trustification context. These contain a good example of how to use some of these queries.
+
+TODO: They don't work with ds1 dataset and are more examples than tests. If un-ignored, they can be ran as
+
+```
+cargo test product_by_cve -- --nocapture
+```
+
+* SPoG API uses guac-rs to make queries to the Guac. It also contains a few examples currently described as [tests](https://github.com/trustification/trustification/blob/main/spog/api/src/service/guac.rs), which can be ran against running Guac instance
+
+
+* SPoG API can be also tested directly, like for example
+
+```
+$ TOKEN=$(curl -s -d "client_id=walker" -d "client_secret=ZVzq9AMOVUdMY1lSohpx1jI3aW56QDPS" -d 'grant_type=client_credentials' \
+  'http://localhost:8090/realms/chicken/protocol/openid-connect/token' | jq -r .access_token)
+$ curl -v -X GET --oauth2-bearer $TOKEN "http://localhost:8083/api/v1/cve/cve-2023-34454/related-products" | jq
+```

example/queries/product_by_package.gql

@@ -0,0 +1,55 @@
+query dependentProductQuarkus {
+  findDependentProduct(
+    purl: "pkg:maven/org.xerial.snappy/[email protected]"
+  ) {
+    uri
+    subject {
+      ... on Package {
+      type
+      namespaces {
+        namespace
+        names {
+          name
+          versions {
+            id
+            version
+            qualifiers {
+              key
+              value
+            }
+            subpath
+            }
+        }
+      }
+    }
+    }
+  }
+}
+
+query dependentProductUBI8 {
+  findDependentProduct(
+    purl: "pkg:rpm/redhat/[email protected]_8?arch=x86_64", offset: 0, limit: 10
+  ) {
+    uri
+    subject {
+      ... on Package {
+      type
+      namespaces {
+        namespace
+        names {
+          name
+          versions {
+            id
+            version
+            qualifiers {
+              key
+              value
+            }
+            subpath
+            }
+        }
+      }
+    }
+    }
+  }
+}

example/queries/product_by_vulnerability.gql

@@ -0,0 +1,73 @@
+query findTopLevelPackagesRelatedToVulnerability {
+  findTopLevelPackagesRelatedToVulnerability (vulnerabilityID: "cve-2022-2284" ) {
+    __typename
+    ... on CertifyVEXStatement {
+			...allCertifyVEXStatementTree
+    }
+    ... on Package {
+       id
+       type
+       namespaces {
+         id
+         namespace 
+         names {
+           name
+           versions {
+             version
+            }
+         }
+      }
+    }   
+    ... on IsDependency {
+      dependencyType
+    }
+  }
+}
+
+fragment allCertifyVEXStatementTree on CertifyVEXStatement {
+    id
+    subject {
+        __typename
+        ... on Package {
+            id
+            type
+            namespaces {
+                id
+                namespace
+                names {
+                    id
+                    name
+                    versions {
+                        id
+                        version
+                        qualifiers {
+                            key
+                            value
+                        }
+                        subpath
+                    }
+                }
+            }
+        }
+        ... on Artifact {
+            id
+            algorithm
+            digest
+        }
+    }
+    vulnerability {
+        id
+        type
+        vulnerabilityIDs {
+            id
+            vulnerabilityID
+        }
+    }
+    status
+    vexJustification
+    statement
+    statusNotes
+    knownSince
+    origin
+    collector
+}

example/queries/vulnerabilities_by_product.gql

@@ -0,0 +1,103 @@
+query findVulnerabilityBySbomURI {
+ #findVulnerabilityBySbomURI(sbomURI: "https://access.redhat.com/security/data/sbom/beta/spdx/rhel-7.9.z-c98403ce-5e02-4278-98ec-b36ecd1f46a5") {
+ findVulnerabilityBySbomURI(sbomURI: "https://access.redhat.com/security/data/sbom/beta/spdx/quarkus-bom-b52acd7c-3a3f-441e-aef0-bbdaa1ec8acf") {  
+		__typename
+  	... on CertifyVEXStatement {
+			...allCertifyVEXStatementTree
+    }
+  	... on CertifyVuln {
+			...allCertifyVulnTree
+    }
+ }
+}
+
+fragment allCertifyVulnTree on CertifyVuln {
+    id
+    package {
+        id
+        type
+        namespaces {
+            id
+            namespace
+            names {
+                id
+                name
+                versions {
+                    id
+                    version
+                    qualifiers {
+                        key
+                        value
+                    }
+                    subpath
+                }
+            }
+        }
+    }
+    vulnerability {
+        id
+        type
+        vulnerabilityIDs {
+            id
+            vulnerabilityID
+        }
+    }
+    metadata {
+        dbUri
+        dbVersion
+        scannerUri
+        scannerVersion
+        timeScanned
+        origin
+        collector
+    }
+}
+
+
+fragment allCertifyVEXStatementTree on CertifyVEXStatement {
+    id
+    subject {
+        __typename
+        ... on Package {
+            id
+            type
+            namespaces {
+                id
+                namespace
+                names {
+                    id
+                    name
+                    versions {
+                        id
+                        version
+                        qualifiers {
+                            key
+                            value
+                        }
+                        subpath
+                    }
+                }
+            }
+        }
+        ... on Artifact {
+            id
+            algorithm
+            digest
+        }
+    }
+    vulnerability {
+        id
+        type
+        vulnerabilityIDs {
+            id
+            vulnerabilityID
+        }
+    }
+    status
+    vexJustification
+    statement
+    statusNotes
+    knownSince
+    origin
+    collector
+}