aap-verify

Public verifier and CLI for AAP Core evidence bundles (.aap).

aap-verify is verification-only. It does not generate or export bundles.

Status

• License: Apache-2.0 (LICENSE)
• Development stage: Alpha (0.1.x)
• Python: >=3.10

Install

From source:

pip install -e .

Quickstart

Verify a bundle:

aap-verify evidence.aap

JSON output:

aap-verify evidence.aap --output json

Strict profile path checks:

aap-verify evidence.aap --strict-profiles

Show CLI version:

aap-verify --version

CLI

usage: aap-verify [--version] [--output {text,json}] [--strict-profiles] package_file

Arguments:

• package_file: Path to .aap bundle.
• --output {text,json}: Output format. Default is text.
• --json: Legacy alias for --output json.
• --strict-profiles: Enforce declared profile.path_prefix file presence.
• --version: Print CLI version.

Exit codes:

• 0: Verification passed.
• 4: Verification failed.
• 2: CLI usage error (argument parsing).

Verification Model

The verifier currently checks:

• Manifest shape and required fields.
• Integrity profile constraints (sha256, sha384, sha512).
• Declared file hashes.
• Archive strictness: rejects files not declared in manifest.file_hashes.
• Event chain integrity (sequence_index, prev_hash, data_hash).
• Merkle root integrity for batches.
• Anchor/proof integrity (including local-hmac-* local proofs).
• evidence_scope consistency against discovered sessions/batches/anchors.
• timestamp_evidence consistency with anchors and file hashes.
• Optional profile-required files.

Trust Model and Limits

• aap-verify validates bundle consistency and cryptographic linkage.
• Verification of trust in an external anchor service/operator is out of scope for this package.
• Local anchor (local-hmac-*) verification depends on local key material (AAP_ANCHOR_KEY or dev fallback).

See docs/verification-model.md and docs/threat-model.md for details.

Spec Compatibility

Normative spec and schemas are maintained in aap-spec.

• Local workspace path: ../aap-spec
• Canonical URL: https://github.com/cynsta/aap-spec
• Compatibility notes: docs/spec-compatibility.md

Development

Run tests:

python -m unittest discover -s tests -p "test_*.py"

Run formatting/lint checks:

python -m black --check .
python -m ruff check .

Security

Please report vulnerabilities according to SECURITY.md.

Contributing

See CONTRIBUTING.md, CODE_OF_CONDUCT.md, and the issue/PR templates in .github/.