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

# Atomic update: detect + accept changes in one step
census integrity manifest.db --auto-update

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

census provenance generate manifest.db --source "release-v2.1"
census provenance generate manifest.db --commit abc123 --attest
census provenance generate manifest.db --sbom bom.json --embed-materials
census provenance generate manifest.db --format intoto-jsonl
census provenance verify manifest.db.provenance.json --strict --json

census timeline build --manifest .census-manifest.db
census timeline query --action scan --start -7d
census timeline query --format bodyfile --output timeline.bodyfile
census timeline query --format case-json --output case.json --case-name "Investigation-2026"
census timeline query --format l2tcsv --output timeline.csv
census timeline query --format html --output timeline.html
census timeline stats --window 1h --json

census correlate run --rules census-correlate.toml
census correlate run --format jsonl --timeline-dir ./timeline-db
census correlate run --format cef -o alerts.cef --start -24h
census correlate run --format ecs -o alerts.ndjson --hostname prod-host-01

census attest --string "SN-2026-0042" --source "production-batch-Q1"
census attest --strings-file serial-numbers.txt --source "batch-registry" --json
census attest --strings-file ids.txt --source "inventory" --dry-run

census federate site-a.db site-b.db -o global.db
census federate *.db -o combined.db --strategy skip --show-conflicts
census federate prod.db staging.db -o merged.db --label production --label staging --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 + chain of custody)
• Chain of custody — --examiner, --case-id, --organization, --notes — forensic provenance metadata with signature lines (PDF) and manifest SHA-256 binding. Aligned with NIST SP 800-86 and ISO/IEC 27037.
• 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
• Atomic integrity update — --auto-update combines detection and baseline acceptance in a single atomic operation with backup. No TOCTOU window.
• 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.
• Git commit attestation — census git-hook install attests changed files on every commit, creating commit-level cryptographic provenance.

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 #