guardspine-verify 0.2.1

Offline verification for GuardSpine evidence bundles

guardspine-verify

Verify GuardSpine evidence bundles offline - no trust required.

Spec Version: v0.2.0 + v0.2.1 | Package Version: 0.2.1

Installation

pip install guardspine-verify

Or install from source:

git clone https://github.com/DNYoussef/guardspine-verify.git
cd guardspine-verify
pip install -e .

Quick Start

# Verify a JSON bundle
guardspine-verify bundle.json

# Verify a ZIP export
guardspine-verify evidence-bundle-2024-01-15.zip

# Verbose output
guardspine-verify bundle.json --verbose

# Output JSON report
guardspine-verify bundle.json --format json > report.json

What It Verifies

Check	Description
Version	Bundle version must be one of 0.2.0, 0.2.1
Hash Chain	Each entry's previous_hash matches prior chain_hash
Chain Binding	Chain entries map 1:1 to items (count, item_id, content_hash)
Root Hash	Computed Merkle root matches stored root
Content Hashes	Each item's content_hash matches SHA-256 of canonical JSON content
Sequence	Chain sequence numbers are contiguous starting from 0
Signatures	Cryptographic signatures verify (Ed25519, RSA, ECDSA)
Sanitization (optional)	--check-sanitized validates redaction metadata and token consistency

CLI sanitization flags:

• --check-sanitized: evaluate optional sanitization contract and [HIDDEN:*] token consistency
• --require-sanitized: fail if sanitization block is missing or invalid
• --fail-on-raw-entropy: treat post-sanitization high-entropy survivors as hard failures

Exit Codes

Code	Meaning
0	Bundle verified successfully
1	Verification failed
2	Invalid input (file not found, parse error)

Python API

from guardspine_verify import verify_bundle_data, VerificationResult

# Verify bundle data directly
import json
with open("bundle.json") as f:
    bundle = json.load(f)

result = verify_bundle_data(bundle)

if result.verified:
    print("Bundle verified!")
else:
    print(f"Verification failed:")
    for error in result.errors:
        print(f"  - {error}")

print(f"Status: {result.status}")
print(f"Hash chain: {result.hash_chain_status}")
print(f"Signatures: {result.signature_status}")

Note: A verify_bundles() batch API is planned for a future release.

Verification Result

@dataclass
class VerificationResult:
    verified: bool
    status: str  # "verified" | "mismatch" | "error"
    hash_chain_status: str
    root_hash_status: str
    content_hash_status: str
    signature_status: str
    errors: list[str]
    warnings: list[str]
    verified_at: datetime
    details: dict[str, Any]

Supported Algorithms

Algorithm	Status
SHA-256	Supported
Ed25519	Supported
RSA-SHA256	Supported
ECDSA-P256	Supported

Supported Input Formats

Format	Extension	Description
JSON	.json	Single bundle file
ZIP	.zip	Exported bundle package
Directory	folder	Unpacked bundle with manifest

Integration with CI/CD

# GitHub Actions
- name: Verify Evidence Bundles
  run: |
    pip install guardspine-verify
    guardspine-verify ./evidence/*.json

# GitLab CI
verify-evidence:
  script:
    - pip install guardspine-verify
    - guardspine-verify ./evidence/*.json

Security

This verifier:

• Does not require network access
• Does not phone home
• Does not store any data
• Is fully auditable (open source)
• Has no external dependencies for core verification

PII-Shield Integration

guardspine-verify validates PII-Shield sanitization attestations embedded in evidence bundles.

Why

When bundles are sanitized before sealing (e.g., by codeguard-action or rlm-docsync), the sanitization block attests what engine was used, how many redactions were applied, and what token format was used. The verifier checks this attestation for consistency and can also detect secrets that survived sanitization via entropy analysis.

Where

Sanitization verification runs inside guardspine_verify/verifier.py as an optional verification pass, controlled by CLI flags.

How

# Check sanitization attestation (warn on issues)
guardspine-verify bundle.json --check-sanitized

# Require sanitization (fail if missing or invalid)
guardspine-verify bundle.json --require-sanitized

# Treat post-sanitization high-entropy survivors as failures
guardspine-verify bundle.json --require-sanitized --fail-on-raw-entropy

The verifier checks:

• sanitization.redaction_count matches actual [HIDDEN:<id>] token count
• engine_version is valid semver
• token_format matches the tokens found in bundle content
• High-entropy strings that survived sanitization (optional hard fail)

GuardSpine's own hash fields (content_hash, chain_hash, root_hash, etc.) are excluded from entropy analysis to avoid false positives.

Related Projects

Project	Description
guardspine-spec	Bundle specification
GuardSpine	Full governance platform
guardspine-connector-template	Connector SDK

Contributing

See CONTRIBUTING.md.

License

Apache 2.0 - See LICENSE.

---

GuardSpine: Verifiable governance evidence you don't have to trust.