Version: 0.2.1 License: Apache 2.0 Status: Stable

The GuardSpine Evidence Bundle Specification defines a vendor-neutral, verifiable format for packaging governance evidence. Bundles can be verified offline by any party without trusting the issuing system.

In AI-mediated work governance, trust cannot depend on a single vendor. This specification enables:

• Offline verification: Auditors can verify bundles without network access
• Vendor neutrality: Any system can produce or consume compliant bundles
• Cryptographic integrity: Hash chains and signatures prove no tampering
• Regulatory compliance: Bundles meet evidentiary standards for SOX, HIPAA, SOC2

# Clone and install dependencies
git clone https://github.com/DNYoussef/guardspine-spec.git
cd guardspine-spec
npm install

# Validate bundles against schema
npm run validate

# Run interoperability tests
pip install pytest jsonschema
pytest tests/ -v

# Install the verifier
pip install guardspine-verify

# Verify a bundle
guardspine-verify bundle.json

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

A GuardSpine Evidence Bundle (v0.2.x) contains:

EvidenceBundle
+-- bundle_id          # Unique identifier (UUID)
+-- version            # "0.2.0" | "0.2.1"
+-- created_at         # ISO 8601 timestamp
+-- items[]            # Evidence items
|   +-- item_id
|   +-- content_type   # guardspine/* type tag
|   +-- content_hash   # SHA-256 of canonical JSON content
|   +-- content        # The actual evidence
|   +-- sequence       # 0-based index
+-- immutability_proof # Hash chain + root hash
|   +-- hash_chain[]
|   |   +-- sequence
|   |   +-- item_id
|   |   +-- content_type
|   |   +-- content_hash
|   |   +-- previous_hash
|   |   +-- chain_hash
|   +-- root_hash
+-- signatures[]       # Optional cryptographic signatures
|   +-- signature_id   # Unique signature ID
|   +-- signer_id      # Human or AI identity ID
|   +-- algorithm      # ed25519 | rsa-sha256 | ecdsa-p256
|   +-- signature_value
|   +-- signed_at      # ISO 8601 timestamp
|   +-- content_hash
+-- metadata           # Bundle metadata
|   +-- retention      # Retention policy
+-- sanitization       # Optional redaction/sanitization attestation (v0.2.1+)
|   +-- engine_name
|   +-- engine_version
|   +-- method
|   +-- token_format   # [HIDDEN:<id>]
|   +-- redaction_count
+-- audit_trail        # Who accessed/modified

A bundle is VERIFIED if and only if:

1. Version Valid: Bundle version field equals "0.2.0" or "0.2.1"
2. Hash Chain Valid: Each entry's previous_hash matches the prior entry's chain_hash (NOT content_hash)
3. Chain Binding: Hash chain entries map 1:1 to items (same count, same item_id, same content_hash, same order)
4. Root Hash Valid: Computed Merkle root matches immutability_proof.root_hash
5. Content Hashes Valid: Each item's content_hash matches SHA-256 of its canonical JSON content
6. Signatures Valid: Each signature verifies against the signer's public key
7. No Gaps: Hash chain sequence numbers are contiguous starting from 0
8. Sanitization Contract (Optional): If sanitization is present, it matches schema rules (v0.2.1+)

Important: The chain links via chain_hash, not content_hash. This is a common implementation error.

Bundles may optionally include:

• sanitization.engine_name / engine_version
• sanitization.method (deterministic_hmac, provider_native, entropy+hmac)
• sanitization.token_format ([HIDDEN:<id>])
• sanitization.redaction_count and redactions_by_type
• sanitization.status (sanitized, none, partial, error)

This field documents redaction behavior for downstream policy checks.

The sanitization attestation schema was designed in collaboration with PII-Shield, a Go-based Kubernetes sidecar that detects secrets via Shannon entropy analysis and replaces them with deterministic HMAC tokens.

Why: Evidence bundles may contain secrets or PII from code diffs, approval messages, or integration payloads. The sanitization attestation block provides a standardized way for any implementation to document what was redacted, how, and by which engine -- enabling downstream verifiers to validate the sanitization contract.

Where: The sanitization schema is defined in:

• schemas/evidence-bundle.schema.json (v0.2.0 base)
• schemas/evidence-bundle-v0.2.1.schema.json (v0.2.1 with full sanitization support)

How implementations use it: Any bundle producer (codeguard-action, rlm-docsync, adapter-webhook, local-council) that sanitizes content before sealing populates the sanitization block. The verifier (guardspine-verify) checks that redaction_count matches actual token count and that engine_version is valid semver.

The spec defines a crypto field registry that identifies which JSON fields contain intentionally high-entropy values (hashes, signatures) vs. fields that might contain accidental secrets. This matters because PII-Shield's entropy detector will flag SHA-256 hashes as secrets without it.

Reserved field patterns: *_hash, *_digest, *_checksum, *_hmac, *_signature, signature_value, signed_hash.

The HMAC salt used for deterministic redaction ([HIDDEN:<id>] tokens) must be org-wide and immutable. If different services use different salts, the same secret produces different tokens across bundles, breaking cross-bundle correlation and audit trail consistency. See SPECIFICATION.md for the full contract.

The spec includes a guide for integrating GuardSpine evidence bundles with the Z-Inspection process for trustworthy AI assessment. Evidence bundles provide the artifact trail that Z-Inspection panels need for socio-technical evaluation. See docs/z-inspection-guide.md.

For AI-generated evidence, signers include model provenance:

{
  "signer_type": "ai_model",
  "signer_id": "claude-3-opus-20240229",
  "display_name": "Claude 3 Opus",
  "ai_model_id": "claude-3-opus-20240229",
  "ai_model_version": "20240229",
  "organization": "Anthropic"
}

Bundles can include evidence from:

• GitHub: Push events, PR reviews, code scanning alerts
• Jira: Issue links, status changes
• Slack: Approval decisions, rejection rationale
• Microsoft 365: Document changes, sensitivity labels
• DLP/CASB: Classification signals, policy violations

This specification is open for community input. To propose changes:

1. Open an issue describing the change
2. Submit a PR with spec updates + schema changes
3. Include test vectors for verification

The fixtures/golden-vectors/ directory contains:

v0.2.0.json is the primary cross-implementation test vector. All language implementations (TypeScript, Python) MUST produce byte-identical hashes for the items, chain links, and root hash defined in this fixture.

The examples/ directory contains illustrative examples:

Note: Examples in examples/ use legacy field names (evidence_type instead of content_type). For v0.2.0 compliant examples, see fixtures/golden-vectors/.

# Run schema validation on all fixtures and examples
npm run validate

# Output shows: valid bundles, expected failures, any errors

The validation script uses AJV with JSON Schema 2020-12 support.

This specification provides evidence infrastructure, not compliance certification.

• Bundles support audits; they don't replace auditor judgment
• Hash chains detect tampering; they don't prevent all attacks
• Control mappings are supportive metadata, not certification
• See CLAIMS_GUARDRAIL.md for detailed guidance

Apache 2.0 - See LICENSE

GuardSpine: Evidence infrastructure for the AI office.