Search Evidence - Examples

The following examples demonstrate how to use the Search Evidence API effectively:

Example 1: Find all evidence for an artifact

This common use case finds all attestations for a given artifact.

query FindAllEvidenceForArtifact {
  evidence {
    searchEvidence(
      first: 20
      where: {
        hasSubjectWith: {
          repositoryKey: "docker-local"
          path: "my-app/latest"
          name: "manifest.json"
        }
      }
    ) {
      totalCount
      edges {
        node {
          name
          predicateType
          verified
          createdBy
        }
      }
    }
  }
}

Example 2: Find evidence by checksum

Using the SHA-256 checksum, you can find all evidence attached to an artifact, regardless of its name or path. This is a highly reliable method for identifying artifact evidence.

query FindEvidenceByChecksum {
  evidence {
    searchEvidence(
      where: {
        hasSubjectWith: {
          sha256: "7ab0a6527f661c55b02b29fbb3b7d2a7313215c1140337b0cd980d06c3975a14"
          repositoryKey: "npm-local" # Repository is still needed for scoping
        }
      }
    ) {
      edges {
        node {
          name
          verified
          subject {
            name
            path
          }
        }
      }
    }
  }
}

Example 3: Paginate through all evidence for an artifact

If an artifact has many evidence records, you might need to paginate through the results to retrieve all of them.

Fetch the first page and the endCursor.

query SearchAndPaginate_Page1 {
  evidence {
    searchEvidence(
      first: 10
      where: { hasSubjectWith: { repositoryKey: "generic-local", name: "large-component.zip" } }
    ) {
      edges {
        node { name }
      }
      pageInfo {
        hasNextPage
        endCursor # <-- Save this value
      }
    }
  }
}

Use the endCursor to fetch the next page.

query SearchAndPaginate_Page2 {
  evidence {
    searchEvidence(
      first: 10
      after: "CURSOR_FROM_PAGE_1" # <-- Use the cursor from the previous query
      where: { hasSubjectWith: { repositoryKey: "generic-local", name: "large-component.zip" } }
    ) {
      edges {
        node { name }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}

Example 4: Find the latest verified security scan

This workflow demonstrates a common policy enforcement scenario. The query fetches all evidence for an artifact. Your client-side code would then iterate through the results to find the most recent, verified security scan and check its contents.

query FindLatestVerifiedScan {
  evidence {
    searchEvidence(
      first: 50 # Fetch a large number to ensure you get all relevant scans
      where: {
        hasSubjectWith: {
          repositoryKey: "libs-release-local"
          name: "critical-library.jar"
        }
      }
    ) {
      edges {
        node {
          name
          predicateSlug # e.g., "xray-scan-v1"
          verified
          createdAt
          predicate
        }
      }
    }
  }
}

The client-side logic is as follows:

Filter the results where predicateSlug matches your security scan type (for example, xray-scan-v1).
Find the record with the most recent createdAt date from the filtered list.
Check whether verified is true.
Parse the predicate JSON to check for critical vulnerabilities.
Pass or fail the policy based on the results.

Example 5: Create a full audit trail for an artifact

This workflow demonstrates how to combine search and get to create a detailed audit trail. First, you find an artifact using its unique checksum. Next, you identify a specific piece of evidence (like an SBOM) from the search results. Finally, use the details from the search results to fetch the full evidence content using a getEvidence query.

Search for the artifact and identify the target evidence.

query FindArtifactAndEvidencePath {
  evidence {
    searchEvidence(
      where: {
        hasSubjectWith: {
          sha256: "7ab0a6527f661c55b02b29fbb3b7d2a7313215c1140337b0cd980d06c3975a14"
          repositoryKey: "generic-local"
        }
      }
    ) {
      edges {
        node {
          # Identify the evidence you want to inspect further
          name
          downloadPath
          predicateSlug
        }
      }
    }
  }
}

Use details from the search to get the complete evidence.
The client-side logic is as follows:
1. Run the query in step 1 above.
2. Iterate through the results and find the evidence with the desired p redicateSlug (for example, cyclonedx-sbom-v1).
3. Extract the downloadPath and name for that evidence.
4. Use the details to perform a getEvidence query to retrieve the full predicate for deep inspection.

Example 6: Cross-reference a security scan with build information

This advanced workflow ensures that a security scan corresponds to a specific build. You search for an artifact, find its security scan evidence, and then get the full predicate to extract a build identifier.

Search for an artifact to find its security scan.

query FindSecurityScanForArtifact {
  evidence {
    searchEvidence(
      where: {
        hasSubjectWith: {
          repositoryKey: "my-app-builds"
          name: "my-app-1.2.3.zip"
        }
      }
    ) {
      edges {
        node {
          name
          predicateSlug
          downloadPath
        }
      }
    }
  }
}

Get the full predicate of the scan to find the build ID.
The client-side logic is as follows:
1. Run the query in step 1.
2. Filter the results to find the node with a predicateSlug that matches your scan type.
3. Use the downloadPath and name from the node to run a getEvidence query.
4. Parse the predicate JSON to find a field such as build_id or source_commit_hash.
5. Cross-reference this identifier with your CI server or other build evidence to confirm the scan is for the correct version.