WitnessOS Verifier
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-44, ML-DSA-65 or ML-DSA-87. A hybrid suite declaring two of them also performs. Beyond signatures it checks 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 underscripts/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:
- 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. - Obtaining - dependencies are declared in
pyproject.tomland pinned through theuv.locklockfile, so every build uses a reproducible set of package versions. - Tracking - dependencies are monitored three ways:
- SCA: every push/PR runs OSV-Scanner
in the
securityworkflow 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
SHA256SUMSchecksum manifest (see Verifying releases).
- SCA: every push/PR runs OSV-Scanner
in the
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 carryhttps://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.0andv0.2.0were published by a manual backfill that executed againstmain, so their certificates carry...release.yml@refs/heads/mainrather 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
Related
- Conformance profiles - the citable named profiles
- WitnessOS Spec - the protocol specification
- Contact Empire Labs
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.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| witnessos_verifier-1.2.0.tar.gz | 245.0 kB | With provenance | Details for witnessos_verifier-1.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| witnessos_verifier-1.2.0-py3-none-any.whl | Python 3 | none | any | Details for witnessos_verifier-1.2.0-py3-none-any.whl |
Total release size: 365.3 kB
Release files / witnessos_verifier-1.2.0.tar.gz
| Download URL | witnessos_verifier-1.2.0.tar.gz |
|---|---|
| Size | 245.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c35ce4a42c5aea0dc26b3c66861109eaa88c8a54af35de477fd0e1c4ee521cab
|
|
BLAKE2b-256 checksum How to use checksums |
183779893a572e5326056f32f6544928433ac36aec44ce36438ee25183bedd6c
|
| 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 logRelease files / witnessos_verifier-1.2.0-py3-none-any.whl
| Download URL | witnessos_verifier-1.2.0-py3-none-any.whl |
|---|---|
| Size | 120.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4ff302feb6b1d1708bdf4447c4e035148d62ba6ed2e04033b0032f904bf7ba57
|
|
BLAKE2b-256 checksum How to use checksums |
b99ab0a352fb3a9f38d875f84b8ee65c7cade3d5cccbd0e610fd27784fe07555
|
| 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 logSecurity for witnessos-verifier 1.2.0
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.
Attestation for witnessos_verifier-1.2.0.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 logA 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.