Verify evidence in the CI pipeline with kya-verify

Key points

• kya-verify verifies evidence in any CI pipeline with clear exit codes.
• Every code other than 0 should fail the run.
• Public keys and status lists belong in the repository, private keys never.

Get to know the command line

The package includes the kya-verify command line. It takes a file or standard input, optionally keys, status lists, timestamp anchors and a verification time, and outputs the verdict as text or, with --json, as a complete report:

npx kya-verify evidence.json --keys issuer-jwks.json --lists status-list.jwt --json > report.json
echo "exit code: $?"

Use the exit codes

kya-verify exits with 0 for VALID, 1 for INVALID, 2 for INDETERMINATE and 64 for incorrect usage. In a pipeline, every code other than 0 should fail the run, because an indeterminate verdict also means that evidence is missing.

Keep trust in the repository

Store the issuers' public keys and the status lists in a separate directory, such as trust/. Private keys never belong in the repository. Update the status lists regularly so revocations reach the verification.

Create the workflow

A GitHub Actions workflow installs the package and verifies all evidence in the evidence/ directory:

name: Verify agent evidence
on: [push, pull_request]
jobs:
  kya:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24
      - run: npm install --no-save https://knowyouragent.ch/downloads/knowyouragent-verify-core-1.2.0.tgz
      - name: Verify all evidence files
        run: |
          for f in evidence/*.json; do
            npx kya-verify "$f" --keys trust/issuer-jwks.json --lists trust/status-list.jwt || exit 1
          done

The same pattern works in GitLab CI, Jenkins or any other pipeline with Node.js.

Keep the reports

With --json, store the complete report as an artifact of the run. The reportDigest makes every report recomputable later; the error reference explains reason codes.

Troubleshooting

If a run fails, kya-verify's output shows the verdict and, with --json, all checks. Common causes are an outdated status list in the trust/ directory, a rotated issuer key that has not yet been provided and evidence whose validity has expired. For reproducible tests with fixed test data, set --now to a fixed time.

Frequently asked questions

Why does the run fail on an indeterminate verdict?

Because INDETERMINATE means that evidence is missing. Whoever wants to allow this can handle exit code 2 specifically, but should decide so deliberately.

Can I verify only changed evidence?

Yes, for example by passing the list of changed files from the version control system to the loop.

How do I keep test data stable when mandates expire?

With the --now option set to a fixed time. Test results then stay the same even when the test data's validity expires in reality.

How long does verification take in the pipeline?

Verification itself takes milliseconds per piece of evidence. Most of the run time is spent installing the package, which can be cached.

Does kya-verify work without internet?

Yes. After installation, the command line needs no network access; keys and status lists come from the repository.

Can I show the reports in the pull request?

Yes. The output with --json can be evaluated and displayed as a comment or a summary of the run.

Can I use the pipeline for my own test vectors too?

Yes. Store evidence with a known result and compare the verdict and reason codes from the JSON report with the expected values.

How do I secure the installation?

Check the package checksum in the workflow before installing it, and store the expected checksum in the repository.

Sources

1. @knowyouragent/verify-core (Paket): https://knowyouragent.ch/downloads/knowyouragent-verify-core-1.2.0.tgz
2. GitHub Actions: Dokumentation: https://docs.github.com/actions