CertiSigma Census

How It Works #

Census computes SHA-256 hashes of files, sends only hashes to the CertiSigma API, and receives three layers of cryptographic proof:

1. T0 — ECDSA Signature — Immediate, server signs the hash with P-256
2. T1 — TSA Timestamp — Minutes, Merkle tree + RFC 3161 Time Stamping Authority
3. T2 — Bitcoin Anchor — Hours, Merkle root anchored via OpenTimestamps

Installation #

Python 3.10+. TOML config support on 3.10 uses tomli (auto-installed).

# Base install
pip install certisigma-census

# With watch mode (filesystem monitoring)
pip install certisigma-census[watch]

# With PDF report generation
pip install certisigma-census[report]

# Everything
pip install "certisigma-census[watch,report]"

Quick Start #

Inventory scan

export CERTISIGMA_API_KEY=cs_...

# Scan and attest all file hashes
census scan /path/to/sensitive-files --source inventory-hr

# Dry run (hash only, no attestation)
census scan /path/to/files --dry-run

Breach comparison

# Compare suspect files against the registry
census compare /path/to/suspect-files --manifest inventory.db

# Exit 0 = no matches, 1 = exfiltration detected

Integrity check

# Check files against manifest baseline (100% local)
census integrity manifest.db

# Differential: only new findings since last run
census integrity manifest.db --since auto --write-state auto

GitHub Action #

Composite action with zero Docker overhead. SARIF auto-upload to GitHub Security tab.

# Breach detection with SARIF upload
- uses: certisigma/census-action@v1
  with:
    command: compare
    target: ./artifacts
    manifest: ./inventory.db
  env:
    CERTISIGMA_API_KEY: ${{ secrets.CERTISIGMA_API_KEY }}

# Integrity check (no API key needed)
- uses: certisigma/census-action@v1
  with:
    command: integrity
    manifest: ./inventory.db

Commands #

Census provides 40+ commands. Expand each for options and examples.

census compliance-report manifest.db -o report.html
census compliance-report manifest.db --template dora -o report.html
census compliance-report manifest.db --template iso27001 --json
census compliance-report manifest.db --integrity -o report.html

census ai-policy init                           # generate .census-ai-policy.toml template
census ai-policy apply manifest.db --dry-run    # classify only, no API calls
census ai-policy apply manifest.db              # classify and tag attestations
census ai-policy report manifest.db -o ai.html  # HTML compliance report
census ai-policy report manifest.db --json      # JSON output

census sbom attest sbom.spdx.json --source "ci-pipeline"
census sbom attest bom.cdx.json --dry-run --json
census sbom verify sbom.spdx.json --json
census sbom verify bom.cdx.json --exit-zero --detailed
census sbom summary sbom.spdx.json --json

Output Formats #

All JSON output includes census_version and elapsed_seconds for forensic traceability. JSONL streams end with a _summary trailer.

Forensic Features #

• Evidence chain — census verify with T0/T1/T2 details, OTS proof export
• Forensic reports — HTML, PDF, evidence bundles (ZIP with OTS proofs + SHA256SUMS)
• Audit log — Tamper-evident JSONL with SHA-256 hash chain (census audit-log verify)
• Named snapshots — Compliance baselines with diff comparison
• Manifest seal — HMAC-SHA256 tamper-evidence (Tripwire/AIDE pattern)
• Differential integrity — --since auto --write-state auto for new-findings-only mode
• Baseline update — AIDE-style detect → review → accept workflow
• Forensic annotation — Case IDs, notes, tags with AES-256-GCM zero-knowledge encryption
• Forensic archive — census archive packages manifest, inventory, chain of custody, and SHA256SUMS into a verifiable ZIP. census verify-archive checks integrity.
• Webhook evidence — census webhook verify-payload cryptographically verifies a saved webhook delivery against its HMAC-SHA256 signature, proving authenticity in the evidence chain.
• File attribution — Owner, group, and permissions captured during scan (schema v3), available in reports and archives.
• Attested reports — census report --attest attests the report’s own hash for tamper-evidence. census verify-report verifies it.

Cooperation #

Share forensic data with third parties without exposing original content.

• Derived lists — HMAC-SHA256 opaque hash lists for third-party breach detection. The third party can match suspects without seeing your inventory.
• Share tokens — Time-limited, use-limited tokens for chain of custody.
• Structured tagging — Key-value classification with encrypted tags and cursor-paginated query.
• Annotations — Add forensic notes, case IDs, and metadata to attestations.

# Create an opaque derived list from your manifest
census derived-list create --manifest ./inventory.db --label "Q1 2026"

# Third party matches their suspects
census derived-list match <list_id> --list-key <hex64> --hashes-file suspects.txt

CI/CD Integration #

Census is designed for automation. Exit codes, report-only mode, and SARIF output integrate with any CI/CD pipeline.

Exit Codes

Webhooks #

Push-based T1/T2 lifecycle notifications. Instead of polling for attestation completion, register a webhook and receive server-side callbacks when proofs are ready.

Register a webhook

# Register and save the signing secret
census webhook register \
  --url https://hooks.example.com/certisigma \
  --events t1_complete,t2_complete \
  --label prod-monitor \
  --save-secret .census-webhook-secret

Manage webhooks

# List registered webhooks
census webhook list --json

# Show delivery history
census webhook deliveries wh_abc123

# Delete a webhook
census webhook delete wh_abc123

Receive webhooks

Start a lightweight HTTP receiver with HMAC-SHA256 verification, anti-replay guard, and hook dispatch:

# Standalone receiver with shell hooks
census webhook serve \
  --secret-file .census-webhook-secret \
  --on-t1 'notify-send "T1 certified"' \
  --on-t2 'curl -X POST https://slack/hook -d @-'

# Or embed in watch mode for full lifecycle
census watch /data \
  --on-change 'echo "changed"' \
  --on-t1 'echo "T1 done"' \
  --on-t2 'echo "T2 anchored"' \
  --webhook-secret-file .census-webhook-secret

Forensic verification

Verify a saved webhook delivery is authentic and unmodified:

census webhook verify-payload delivery.json \
  --signature "sha256=abc..." \
  --secret-file .census-webhook-secret

Security properties

• HMAC-SHA256 on every delivery — Signature verified before JSON parsing. Invalid signatures are rejected (401).
• Anti-replay guard — Bounded delivery ID deduplication (10K entries, FIFO) + timestamp window (300s). Prevents replay attacks.
• Secret file permissions — --save-secret writes with 0o600 (owner-only). Load strips comments and whitespace.
• Loopback by default — Binds to 127.0.0.1. For public exposure, use --bind 0.0.0.0 behind a reverse proxy with TLS termination.
• Optional built-in TLS — --tls-cert / --tls-key for environments without a reverse proxy. Minimum TLS 1.2.
• Payload size limit — 1 MB maximum. Requests exceeding this are rejected before reading the body.
• Graceful shutdown — SIGINT/SIGTERM cleanly stops the receiver.

Configuration #

Census reads configuration from TOML files with user/project precedence:

1. CLI flags (highest priority)
2. Environment variables (CERTISIGMA_API_KEY, CERTISIGMA_BASE_URL)
3. Project config (.census.toml in current directory)
4. User config (~/.config/census/config.toml)

# Create a project config template
census config init --project

# View effective configuration
census config show

# Shell completions
eval "$(census completion bash)"

Security Model #

• Content never leaves the client — Only SHA-256 hashes are transmitted to the API. The original file content stays on your infrastructure.
• Zero-knowledge metadata — Annotations and tag values can be encrypted client-side with AES-256-GCM before sending to the API. The server stores ciphertext only.
• HMAC-derived lists — Third-party breach detection uses HMAC-SHA256 derivation. The third party sees opaque derived hashes, not your original inventory.
• Manifest is local — The hash-to-filepath mapping lives on your filesystem. CertiSigma never sees file paths or directory structure.
• Manifest encryption at rest — Manifests can be encrypted with AES-256-GCM using --encryption-key or CENSUS_ENCRYPTION_KEY env var. Encrypted files use a compact binary format with 96-bit random nonce and authenticated encryption. Auto-detected on load.
• API key scoping — RBAC scoped keys allow read-only access for analysts with full audit trail.
• Webhook HMAC-SHA256 — Every webhook delivery is signed with a per-webhook secret. The receiver verifies signatures before processing. Anti-replay guard prevents stored replay attacks.
• Secret file management — Webhook secrets are written with 0o600 permissions (owner-only). Never logged, never committed. Display-once semantics at registration.

Compliance Mapping #

Census provides cryptographic evidence chains that map to regulatory requirements:

Architecture #

Census is a client of the CertiSigma API. It uses the published Python SDK and treats it as a black box.

Global Options #