Search Evidence (GraphQL)

Description: Returns the requested data from all evidence records associated with the specified subject, as defined by the One Model GraphQL query. Use the Get Evidence API to return the details of a specific evidence file returned by this API.

❗️

Important

When operating in a Self-Hosted environment, you must enable the Evidence service in the system.yaml file as a prerequisite to using this endpoint. Add the following:

evidence:
  enabled: true

Security: Requires a valid token; requires Read permissions to the subject repository

Usage: POST /onemodel/api/v1/graphql

Sample query:

query {
  evidence {
    searchEvidence(
      where: {
        hasSubjectWith: {
          repositoryKey: "my-repo-key"
          path: "images"
          name: "my-artifact.jar"
        }
      }
    ) {
      totalCount
      edges {
        node {
          name
          predicateType
        }
      }
    }
  }
}

Input Types

Output Types

The output types that you include in the search query determine the output you receive from the search results.

Evidence Type

This type represents a single evidence record.

EvidenceSubject Type

This type describes the artifact or build that represents the evidence subject.

EvidenceSigningKey Type

This type represents the key used to sign the evidence.

📘

Tip

We recommend limiting the response data to those fields that are actually of interest. It is also recommended to avoid including fields such as predicate, which are relatively data-heavy. After returning the list of evidence files associated with the subject, you can use the Get Evidence API to return the predicate (that is, the contents) of the specific evidence file you are interested in.

📘

Note

For details about fields that are common across all One Model domains, see One Model GraphQL Common Types and Conventions.

Status Codes

Search Evidence – Examples

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

• Example 1: Find all evidence for an artifact
• Example 2: Find evidence by checksum
• Example 3: Paginate through all evidence for an artifact
• Example 4: Find the latest verified security scan
• Example 5: Create a full audit trail for an artifact
• Example 6: Cross-reference a security scan with build information

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.

1. Fetch the first page and the endCursor.
   GraphQL

   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
         }
       }
     }
   }

2. Use the endCursor to fetch the next page.
   GraphQL

   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:

1. Filter the results where predicateSlug matches your security scan type (for example, xray-scan-v1).
2. Find the record with the most recent createdAt date from the filtered list.
3. Check whether verified is true.
4. Parse the predicate JSON to check for critical vulnerabilities.
5. 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.

1. Search for the artifact and identify the target evidence.
   GraphQL

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

2. 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 predicateSlug (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.

1. Search for an artifact to find its security scan.
   GraphQL

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

2. 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.