Skip to main content

WitnessOS Verifier

OpenSSF Best Practices - Baseline 1 OpenSSF Best Practices - Baseline 2 OpenSSF Best Practices - Baseline 3

E4 verification implemented with explicit external trust. Real RFC 3161 signatures are verified against operator-provisioned trust roots. An authenticated retention receipt is recorded and reported as an attribute of the bundle. It is made a requirement only where an operator's trust policy sets require_retention. Both bundled fixtures reach E4 under a policy that does not require custody. See E4-BUNDLE-FORMAT.md and E4-IMPLEMENTATION-REPORT.md.

Standalone verifier for WitnessOS evidence. It checks event and manifest signatures in any of Ed25519, ML-DSA-65 or a hybrid suite declaring both, plus canonical event chains, sequence bounds, event membership and binding to the signed batch root. It also verifies engine-native records directly, so a counterparty can check one with the engine absent. Bundled keys prove consistency with those keys; authenticate their identity independently.

Composite signatures. Where a manifest declares a hybrid suite such as ed25519+ml-dsa-65, the verifier performs both halves over the same bytes and names the declared suite in its verdict, so the result states what was checked rather than passing silently. It refuses a manifest that declares a hybrid suite but carries no countersignature and it refuses one that carries a countersignature while declaring no suite. A hybrid record therefore cannot be downgraded to its classical half after the fact.

Proven with the engine absent. On 2026-10-04 the verifier graded a live hybrid record at E4, exit 0, in a virtual environment where import witnessos fails, so the run rests on the record and two public keys and not on any Empire Labs component. The same run refused both tamper variants by name. The record and its landing evidence are published with the post-quantum programme.

Grade Required evidence
E0 No events loaded (grade-derivation API)
E1 Events loaded
E2 E1 plus valid event/manifest signatures, chain, sequence and signed batch binding
E3 E2 plus corroboration: a party other than the deployment, whose identity the verifier establishes from its own trust input, confirming the outcome and bound to this action
E4 E3 plus bound inclusion proof and an authenticated timestamp, anchored to operator-provisioned TSA trust roots

E3 is an appraisal, not an event type. The verifier reads the acknowledgement's provider signature, resolves that key only from the operator's trust input, checks it is not one of the bundle's own signing keys, checks the acknowledgement names the provider's own record, and checks it commits to this case's prior events and to the action it claims. One provider record cannot substantiate two actions: the first claimant in sealed event order owns it. An acknowledgement the deployment wrote and signed is the deployment agreeing with itself and grades E2. See CORROBORATION.md.

The anchor is the cryptography: the signature, the RFC 3161 timestamp and the Merkle inclusion proof, verified directly by the parties to the record. A signed retention receipt from a custodian you trust is recorded and reported as an attribute of the bundle. It is made a requirement only where your policy sets require_retention, and even then it changes the receipt's custody verdict rather than its evidence grade. A matching local WORM checksum is not immutability evidence.

The CLI returns exit 1 when supplied evidence fails or cannot be verified. A lower grade may describe checks that passed; it does not override an invalid bundle result.

Installation

pip install witnessos-verifier

Or from source:

git clone https://github.com/narko4u/witnessos-verifier.git
cd witnessos-verifier
pip install -e ".[dev]"

Requires Python 3.12+ and OpenSSL 3 on PATH for timestamp authentication.

Usage

# Verify using independently provisioned trust
witnessos-verifier verify ./path/to/evidence-bundle/ \
  --trust-policy /path/to/operator-policy.json --tsa-url https://freetsa.org/tsr

# Verify in Alpha mode - grades capped at E3
witnessos-verifier verify --alpha ./path/to/evidence-bundle/

# Get version
witnessos-verifier --version

Example fixtures

There are two families of fixture, and they answer different questions.

Canonical packages (fixtures/canonical-e2, canonical-e3, canonical-e4) are minted by the WitnessOS engine with witnessos-gateway/scripts/gen_verifier_fixtures.py and committed frozen. Each carries a governed-effect chain: request, policy permit, dispatch, execution and, where the package is meant to be corroborated, a provider attestation bound to a retained provider record. Each carries a real RFC 3161 token signed by a fixture TSA.

The grade is never written into the package. The verifier derives it:

  • canonical-e2: governed action, no independent corroboration. E2, exit 1.
  • canonical-e3: corroborated, but the fixture CA is not published, so the anchor cannot authenticate and cannot lift the grade. E3, exit 1.
  • canonical-e4: corroborated and the anchor authenticates against the fixture CA under scripts/canonical_policy.py. E4, exit 0.

Because the TSA and its CA both live in the tree, no test or gate touches a public TSA or CRL. The release gate builds each package's operator policy at run time and asserts the derived grade.

Legacy fixtures (e4-gmail-approved-send, e4-stripe-refund) are kept as a negative regression. Their chain is a request, a policy decision, an approval, a dispatch, a legacy provider confirmation and an anchor, with no executed action and no attestation bound to a retained provider record. That is not corroboration under the hardened model, so both are E2 and exit 1, whatever their names say. test_legacy_provider_confirmed_chain_cannot_self_promote_to_e3_or_e4 asserts it.

The historical claim that both legacy fixtures reached E4 under a live FreeTSA policy described the previous evidence model. It is recorded here so the change is legible, not repeated as a current claim.

Development

# Clone
git clone https://github.com/narko4u/witnessos-verifier.git
cd witnessos-verifier

# Install dev dependencies
pip install -e ".[dev]"

# Run tests (all offline)
pytest tests/ -v

# Verify the fixture
witnessos-verifier verify fixtures/e4-gmail-approved-send/

Architecture

src/witnessos_verifier/
├── __init__.py          # Package version
├── cli.py               # Click CLI
├── verifier.py          # Main orchestrator
├── events.py            # Event loading + canonical hashing
├── signatures.py        # Ed25519 signature verification
├── key_registry.py      # Public key management
├── case_chain.py        # Case hash chain verification
├── ledger.py            # Global ledger verification
├── merkle.py            # CT Merkle tree proofs
├── manifest.py          # Signed batch manifest verification
├── timestamp.py         # RFC 3161 timestamp verification
├── worm.py              # WORM evidence integrity
├── der.py               # Minimal ASN.1 DER parser (stdlib only)
└── grades.py            # E1-E4 evidence grade derivation

Timestamp and retention trust

CMS signatures, ESS signer binding, certificate paths at genTime, timestamping purpose/EKU, digest/policy/nonce constraints and the timestamp trust window are verified. STANDARD does not check revocation. STRICT/revocation-required policies fail closed until authenticated CRL/OCSP support exists. Signed retention receipts prove what an independently trusted custodian attested; the offline verifier does not query live storage. Whether a receipt is required is an operator decision: require_retention in the trust policy, default false, so a two-party record reaches E4 on the cryptography alone. Two named profiles are defined so a procurement or assessment document can cite the exact configuration rather than describe it: WOS-E4-TWO-PARTY and WOS-E4-TWO-PARTY-RETENTION. See PROFILES.md and the exact bundle recipe.

Dependencies

  • pynacl - Ed25519 signature verification
  • click - CLI
  • asn1crypto - ASN.1/CMS structure parsing
  • cryptography - X.509 certificate parsing
  • OpenSSL 3 executable - RFC 3161 signature and certificate-path verification
  • Optional S3 adapters require boto3; they are not used for E4 verification

No gateway, no credentials, no network. Verification happens on your machine.

Dependency management

The project follows a deliberate, minimal dependency policy:

  1. Selection - new dependencies are avoided unless a standard-library alternative does not exist. Cryptographic and ASN.1 dependencies support real signature and certificate verification; see pyproject.toml.
  2. Obtaining - dependencies are declared in pyproject.toml and pinned through the uv.lock lockfile, so every build uses a reproducible set of package versions.
  3. Tracking - dependencies are monitored three ways:
    • SCA: every push/PR runs OSV-Scanner in the security workflow to detect known vulnerabilities in the lockfile.
    • SBOM: every release ships a CycloneDX SBOM (sbom.cdx.json) listing the exact dependency set of the released artifact.
    • Integrity: every release asset ships with a Sigstore signature and a SHA256SUMS checksum manifest (see Verifying releases).

Verifying releases

1. Integrity (checksums)

Each release ships a SHA256SUMS file listing the hashes of every release asset. To verify that a downloaded asset matches the published release:

sha256sum -c SHA256SUMS

This checks the integrity of the wheel, source tarball, and SBOM against the hashes generated at release time. The SHA256SUMS file itself is attached to the GitHub release (see the Releases page), so integrity can be checked without trusting the download mirror.

2. Authenticity (Sigstore/cosign signatures)

Every release asset is signed keylessly with Sigstore at build time by the Release GitHub Actions workflow. Each asset is shipped with a .sig signature and a .pem signing certificate. To verify the signature of an asset:

# install cosign: https://docs.sigstore.dev/cosign/installation/
TAG=$(gh release view --repo narko4u/witnessos-verifier --json tagName -q .tagName)  # e.g. v0.3.4
V="${TAG#v}"   # 0.3.4
ART="witnessos_verifier-${V}-py3-none-any.whl"

cosign verify-blob \
  --certificate-identity-regexp "^https://github\.com/narko4u/witnessos-verifier/\.github/workflows/release\.yml@refs/(tags/v[0-9]+\.[0-9]+\.[0-9]+|heads/main)$" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  --signature "${ART}.sig" \
  --certificate "${ART}.pem" \
  "${ART}"

The .pem asset is stored base64-wrapped. cosign reads it as it comes out of the release; a tool that wants a plain PEM (for example openssl x509) needs it decoded first:

base64 -d "${ART}.pem" > cert.pem

--certificate-identity compares against one exact string; the v* used in earlier revisions of this section was a glob that no certificate ever carried, so that command could not have succeeded. Use the regexp form above, or pin the exact identity of the release you are checking.

3. Release author identity

Releases are authored by the Empire Labs Pty Ltd maintainer team and built automatically by the Release GitHub Actions workflow in the narko4u/witnessos-verifier repository. The Sigstore certificate embedded in each .pem file binds the asset to that workflow and to the git ref the run executed on, so the ref is part of the identity:

  • Releases published by pushing a v*.*.* tag carry https://github.com/narko4u/witnessos-verifier/.github/workflows/release.yml@refs/tags/<tag>. The workflow refuses to run from any other ref, so a release cannot be signed under an identity that does not name a tag.
  • v0.1.0 and v0.2.0 were published by a manual backfill that executed against main, so their certificates carry ...release.yml@refs/heads/main rather than a tag ref. Those assets are genuine; their identity does not name the tag they belong to.

Either way the issuer is https://token.actions.githubusercontent.com, and the repository and workflow in the identity must be the ones above - if the certificate identity does not match, the asset was not produced by this project's release process.

Note the two cosign flags are not interchangeable: --certificate-identity-regexp accepts a pattern, --certificate-identity is an exact string comparison.

4. Software Bill of Materials (SBOM)

Each release ships a CycloneDX SBOM (sbom.cdx.json) generated from the built artifacts by the Release workflow. The SBOM lists every runtime and build dependency so consumers can inventory the supply chain of the wheel and source tarball. Verify it with the same checksum and signature verification steps above.

5. VEX and threat assessment

The repository also publishes a VEX document accounting for known vulnerabilities that do not affect the project, and a threat assessment covering the attack surface and mitigations for each release.


Acknowledgements

The verifier stands on these independent projects:

  • PyNaCl - Ed25519 signature verification, binding to libsodium.
  • cryptography - X.509 certificate parsing.
  • asn1crypto - ASN.1 and CMS structure parsing.
  • Click - command-line interface.
  • OpenSSL 3 - RFC 3161 timestamp signature and certificate-path verification, invoked as an external executable.
  • boto3 - optional, for the S3 storage adapters only; not used for E4 verification.

Each is an independent project with its own maintainers and release cycle, credited here as a dependency. None of them has reviewed, endorsed or certified this verifier.


License

Apache 2.0 - see LICENSE


Built by Empire Labs Pty Ltd. WitnessOS is a trademark of Empire Labs.


Part of the WitnessOS launch family: eu-ai-act-compliance-grade · witnessos-verifier · agent-interaction-specs · aci-spec · aip-spec · ajson - Empire Labs Pty Ltd

Metadata

Release files for witnessos-verifier 1.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for witnessos-verifier 1.1.1
File Size Uploaded Provenance Actions
witnessos_verifier-1.1.1.tar.gz 243.6 kB With provenance Details for witnessos_verifier-1.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for witnessos-verifier 1.1.1
File Interpreter ABI Platform Actions
witnessos_verifier-1.1.1-py3-none-any.whl Python 3 none any Details for witnessos_verifier-1.1.1-py3-none-any.whl

Total release size: 363.5 kB

Release files / witnessos_verifier-1.1.1.tar.gz

Download URL witnessos_verifier-1.1.1.tar.gz
Size 243.6 kB
Tags Source
SHA-256 checksum
How to use checksums
354da96e6efb4c79d50b119b4ed40b80228bd91aa8bfbb4a3de5cfc43fb15119
BLAKE2b-256 checksum
How to use checksums
48869715ad18a701c2446bbaa034d081307e703849d9e3239df381fcae80d453
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

Release files / witnessos_verifier-1.1.1-py3-none-any.whl

Download URL witnessos_verifier-1.1.1-py3-none-any.whl
Size 119.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
06a1af19d1abd2d5a2db6b70c16d34a8621f4628cf3dbb86a3be0ccfbda7b1dd
BLAKE2b-256 checksum
How to use checksums
a55c78dcac1c3bfd260fb7c377dc7b91d1d06dd2637cdce8a160702edec595ac
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

Security for witnessos-verifier 1.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for witnessos_verifier-1.1.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page