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 30+ 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

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

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.

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.
• API key scoping — RBAC scoped keys allow read-only access for analysts with full audit trail.

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 #