certisigma-census 1.28.2

Cryptographic file inventory and authorized inventory matching — powered by CertiSigma

CertiSigma Census

Cryptographic file inventory and authorized inventory matching — powered by CertiSigma.

Census scans directories, computes SHA-256 hashes, attests them via the CertiSigma API (three-layer evidence chain: ECDSA T0, qualified TSA T1, public anchoring T2), and maintains a local manifest. When suspect files surface, Census compares their hashes against the registry to determine whether they match inventoried assets, with investigative context supplied by the operator.

Installation

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]"

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

Quick Start

1. Inventory scan

export CERTISIGMA_API_KEY=cs_...

# Scan a directory 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

# Scan only PDFs and Word docs, skip files over 100 MB
census scan /data --include "*.pdf" --include "*.docx" --max-size 100M

# Resume an interrupted scan
census scan /data --source quarterly --manifest inventory.db --resume

# Parallel hashing for large directories (4 CPU cores)
census scan /data --workers 4

# Attest the manifest itself (proves manifest existed at scan time)
census scan /data --attest-manifest

This produces a .census-manifest.db (SQLite) mapping each hash to its file path, size, and attestation metadata.

2. Inventory comparison

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

# Save report as JSON or CSV
census compare /suspect --output report.json
census compare /suspect --output report.csv

Exit code: 0 if no matches, 1 if matches found.

3. Manifest status and export

# Show summary
census status /path/to/.census-manifest.db

# Export manifest as CSV for compliance reporting
census export manifest.db --format csv --output inventory.csv

# Export as JSON
census export manifest.db --format json --output inventory.json

# Export as sha256sum (GNU coreutils compatible — works with sha256sum -c)
census export manifest.db --format sha256sum --output checksums.sha256

4. Evidence verification

# Verify a hash against the CertiSigma registry
census verify a1b2c3d4e5f67890...

# Verify a file (hash it first, then check)
census verify /path/to/document.pdf --file

# Full-chain manifest verification (all hashes against the registry)
census verify-manifest inventory.db --strict
census verify-manifest inventory.db --detailed --json

# Hash from stdin (for pipes and CI/CD)
echo "data" | census hash --stdin

# Save OpenTimestamps proof
census verify a1b2c3... --save-ots proof.ots

No API key required — all verification endpoints are public.

5. Integrity check

# Check files against manifest baseline
census integrity manifest.db

# Strict mode: exit 1 on any discrepancy
census integrity manifest.db --strict

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

# Atomic update: detect + accept changes in one step (AIDE parity)
census integrity manifest.db --auto-update
census integrity manifest.db --auto-update --since auto --write-state auto

100% local operation — no API calls, no network needed.

5b. Update baseline (AIDE-style)

# Accept verified changes into manifest (interactive confirmation)
census update manifest.db

# Non-interactive (CI/cron)
census update manifest.db --yes

# Then attest new hashes
census scan /data --resume --manifest manifest.db

Completes the FIM workflow: detect → review → accept. New entries are unattested until the next scan. For automated pipelines, use --auto-update on the integrity command instead.

6. Forensic reports

# HTML report (always available, zero dependencies)
census report manifest.db -o report.html

# PDF report (requires: pip install certisigma-census[report])
census report manifest.db -o report.pdf --evidence --integrity

# Chain of custody metadata (examiner, case ID, signature lines in PDF)
census report manifest.db -o report.pdf \
  --examiner "Dr. Jane Forensic" --case-id "INC-2026-042" \
  --organization "CertiSigma AG" --notes "Initial breach assessment"

# Evidence bundle: ZIP with report + OTS proofs + checksums + chain_of_custody.json
census report manifest.db -o bundle.zip --bundle --evidence \
  --examiner "J. Doe" --case-id "INC-001"

# Attest the report itself (three-layer cryptographic proof)
census report manifest.db -o report.pdf --attest --api-key cs_...
# → writes report.pdf + report.pdf.attestation.json

# Verify a previously attested report
census verify-report report.pdf

7. Manifest diff

# Compare two manifests
census diff baseline.db current.db

# HTML diff report
census diff baseline.db current.db -o diff.html

# Machine-readable (exit codes: 0=none, 1=added, 2=removed, 4=modified)
census diff baseline.db current.db --json

8. Standalone hashing

# Hash a file
census hash document.pdf

# Hash a directory
census hash /path/to/files

# Verify against known hash
census hash document.pdf --verify a1b2c3d4e5...

8b. Duplicate analysis

# Local-only duplicate listing by SHA-256
census duplicates /path/to/files

# Machine-readable report
census duplicates /path/to/files --json

# Reuse duplicate locations already preserved in a manifest
census duplicates --manifest inventory.db --json

# Save review artifacts without attesting paths or file contents
census duplicates /path/to/files --format csv --output duplicates.csv
census duplicates /path/to/files --format html --output duplicates.html

Live duplicates reuses scan-style filters (--include, --exclude, --min-size, --max-size, --workers). Manifest mode reads schema v5 locations without rescanning. Both modes avoid API calls and report duplicate groups, duplicate file observations and estimated wasted bytes; neither mode deletes, deduplicates, hardlinks or quarantines anything.

8c. Container inspection

# Inspect archive/container artifacts without extraction
census container inspect release.zip

# Machine-readable local evidence
census container inspect release.zip --json

# ZIP-family alias remains available
census zip inspect app.jar --json

# TAR/GZIP support through the container command
census container inspect backup.tar.gz --json
census container inspect payload.txt.gz --json

# Save an HTML review report
census container inspect evidence.docx --format html --output container-report.html

# Persist outer artifact and hashable member observations to manifest v5
census container inspect release.zip --manifest inventory.db --json

# Build a reviewable report and evidence bundle
census container report release.zip --output report.html
census container report release.zip --evidence-bundle container-evidence.zip
census container report release.zip --attest-container --attest-report

# Find duplicate member content and duplicate ZIP member names
census container duplicates release.zip --json

# Compare two container builds
census container diff old-release.zip new-release.zip --json

# Compare an artifact against a prior inspect JSON baseline
census container inspect old-release.zip --json --output baseline.json
census container drift new-release.zip --baseline baseline.json --json

container inspect reports the outer artifact hash, member hashes, sizes, compression methods, CRCs and safety findings such as path traversal, ZIP slip risk, duplicate member names, encrypted entries, TAR symlink/device entries, high expansion ratios and CRC/read errors. container duplicates, container diff and container drift reuse that local inspection model for duplicate-member, build-diff and baseline-review evidence. container report --attest-container can explicitly attest the outer artifact hash, and --attest-report can explicitly attest the rendered report hash. Member hashes and names stay local and are not attested by default.

8d. Assurance score and policy gates

# Score local evidence readiness for a manifest
census assurance score --manifest inventory.db

# Machine-readable output for CI or review systems
census assurance score --manifest inventory.db --json

# Verify the local HMAC seal while scoring
census assurance score --manifest inventory.db --seal-key "$CENSUS_SEAL_KEY"

# Create a local policy-as-code gate
census policy init --output census-policy.toml

# Fail CI when local evidence does not meet the policy
census policy check --policy census-policy.toml --manifest inventory.db

# Machine-readable policy output for CI systems
census policy check --policy census-policy.toml --manifest inventory.db --format sarif

assurance score is local-only and deterministic. It summarizes manifest coverage, attestation markers, seal status, duplicate-location signals and container outer-artifact backing as an evidence-readiness score. Container member observations do not reduce attestation coverage by themselves: Census scores whether the outer ZIP/TAR/GZIP artifact is backed by local attestation metadata. The score is not a legal compliance verdict and does not contact the CertiSigma API.

policy init/check adds a deterministic CI gate over that local score. Policies are TOML files with baseline or strict templates, explicit pass/fail gates, JSON/SARIF output and stable exit codes: 0 passed, 1 policy failed and 2 usage or invalid policy. Future gates for T2, SBOM, provenance, drift, KEV, secrets and certificate expiry are present as disabled placeholders; enabling one before its evidence input exists fails closed.

8e. Release evidence packs and receipts

# Capture local Git release-ref evidence first, when relevant
census git ref-snapshot --repo . --output git-refs.json
census git tag-drift --baseline git-refs.json --repo . \
  --release-ref v1.28.2 --format json --output git-drift.json --exit-zero

# Build a local release evidence pack without copying artifact bytes
census release pack 1.28.2 \
  --artifact dist/certisigma_census-1.28.2-py3-none-any.whl \
  --manifest inventory.db \
  --policy census-policy.toml \
  --sbom sbom.json \
  --provenance provenance.json \
  --git-ref-snapshot git-refs.json \
  --git-drift-report git-drift.json \
  --output release-evidence.zip

# Generate a public receipt from the pack
census receipt generate --release-evidence release-evidence.zip \
  --output receipt.json

# Verify the receipt and pack checksums offline
census receipt verify receipt.json --release-evidence release-evidence.zip

release pack creates a local ZIP with release-evidence.json, receipt.json, VERIFY.md and SHA256SUMS. It hashes release artifacts, selected evidence files, optional assurance score, optional policy result and optional Git ref/tag drift evidence. Artifact bytes are not copied by default; use --include-artifacts only for a controlled internal pack. Default path labels use basenames, not absolute paths. receipt generate/verify produces and checks a public proof card over the local evidence. No API calls, attestations, QR dependency or legal compliance verdicts are introduced in this phase.

8f. Git ref and tag drift evidence

# Snapshot current local branch/tag/remote state
census git ref-snapshot --repo . --output git-refs.json

# Compare current local state against a prior snapshot
census git tag-drift --baseline git-refs.json --repo .

# CI-friendly JSON/SARIF output and release tag binding
census git tag-drift --baseline git-refs.json --repo . \
  --release-ref v1.28.2 --format sarif --output git-drift.sarif --exit-zero

git ref-snapshot and git tag-drift use read-only local Git commands. They detect moved/deleted/added refs, rewritten branches, remote URL changes, detached HEAD changes and optional release-ref mismatch against current HEAD. They do not fetch, push, repair refs, call the CertiSigma API or prove compromise. Remote credentials are redacted, repo root is stored as a basename label plus a SHA-256 of the local absolute path, and commit messages/authors, file paths and diffs are not captured.

8g. Trust surface snapshots

# Capture passive TLS certificate snapshot evidence
census tls snapshot example.com

# Machine-readable local evidence for CI or audit handover
census tls snapshot example.com --json

# Use a bounded timeout and save the report
census tls snapshot example.com --timeout 3 --format json --output tls-snapshot.json

# Capture passive DNS snapshot evidence
census dns snapshot example.com

# Machine-readable DNS evidence for CI or audit handover
census dns snapshot example.com --json

# Select records, add an explicit DKIM selector and save the report
census dns snapshot example.com --record MX --record TXT --dkim-selector default \
  --format json --output dns-snapshot.json

# Capture passive web/header snapshot evidence
census web snapshot https://example.com/

# Add bounded SEO/GEO publication artifact evidence
census web snapshot https://example.com/ --seo-geo --json

# Bound redirects and response bytes, then save the report
census web snapshot https://example.com/ --timeout 3 --max-redirects 3 \
  --max-bytes 1M --format json --output web-snapshot.json

# Compare two saved trust surface snapshot JSON files locally
census snapshot diff --snapshot-files tls-old.json tls-new.json
census snapshot diff --snapshot-files web-old.json web-new.json \
  --format json --output snapshot-diff.json --exit-zero

tls snapshot performs one operator-directed TLS handshake and records certificate chain evidence when available: subject, issuer, SANs, validity window, algorithms and fingerprints. dns snapshot performs bounded DNS queries against the local resolver or an explicit resolver for A/AAAA/MX/TXT/CAA/NS/DS/DNSKEY, SPF/DMARC evidence and explicitly supplied DKIM selectors. web snapshot performs bounded HTTP(S) GET or HEAD requests for one explicit URL plus bounded redirects, records status/header evidence, content digest evidence and canonical URL evidence without storing response bodies. With --seo-geo, it also records bounded same-origin publication artifact evidence for robots.txt, sitemap.xml, llms.txt, canonical tags, hreflang links and schema.org/JSON-LD signals without following sitemap/HTML links or storing raw page/artifact bodies. Reports include a canonical snapshot_sha256 so local snapshot evidence can be archived or attested in a later workflow. These commands do not crawl, run active vulnerability tests, try alternate ports, transfer zones, enumerate subdomains, guess DKIM selectors, submit forms, execute JavaScript, use a browser/headless runtime, call the CertiSigma API or make a legal conclusion or policy result.

snapshot diff --snapshot-files compares already saved TLS/DNS/web snapshot JSON files locally and emits snapshot diff evidence with a canonical diff_sha256 that does not depend on report generation time. It ignores runtime-only fields such as generation timestamps and wrapper timing metadata, reports deterministic evidence deltas and returns exit code 1 when drift is found unless --exit-zero is supplied. It does not capture new evidence, crawl, probe, attest, call the API or decide whether a target is compliant.

8h. Append-only log seal evidence

# Create a local Merkle sidecar for an append-only log
census log seal audit.jsonl --window 1h

# Save to an explicit sidecar and print JSON evidence
census log seal audit.jsonl --window 15m --output audit.jsonl.logseal --json

# Verify the sidecar against the inferred log path
census log verify audit.jsonl.logseal

# Verify with an explicit log path for moved evidence handoff
census log verify audit.jsonl.logseal --log audit.jsonl --json

log seal streams one explicit local log file, groups timestamped JSONL into fixed evidence windows when possible, falls back to deterministic line-range evidence otherwise and writes a .logseal sidecar with SHA-256/Merkle roots. The sidecar stores hashes and aggregate metadata, not raw log lines. log verify recomputes the same evidence and returns exit code 1 when findings are detected unless --exit-zero is supplied. These commands do not ship logs, monitor in the background, call the CertiSigma API, attest automatically or make legal/security/compliance conclusions.

9. Attestation tracking

# Check attestation status
census track att_12345

# Wait for Bitcoin anchoring (default)
census track att_12345 --poll --timeout 7200

# Wait for TSA certification only (faster than T2)
census track att_12345 --poll --level T1

10. Webhooks (T1/T2 lifecycle push notifications)

# Register a webhook for T1 (TSA) and T2 (Bitcoin) events
census webhook register --url https://hooks.example.com/certisigma \
    --events t1_complete,t2_complete --label prod-monitor \
    --save-secret .census-webhook-secret

# List registered webhooks
census webhook list --json

# View delivery history
census webhook deliveries wh_abc123

# Start a webhook receiver with T1/T2 hooks
census webhook serve --secret-file .census-webhook-secret \
    --on-t1 'echo "T1 certified" | tee -a /var/log/census.log' \
    --on-t2 'curl -X POST https://slack.webhook/...'

# Verify a saved webhook payload (forensic evidence chain)
census webhook verify-payload delivery.json \
    --signature "sha256=abc..." --secret-file .census-webhook-secret

# Delete a webhook
census webhook delete wh_abc123

11. Self-diagnostic

# Run all health checks
census doctor

# Check including a specific manifest
census doctor --manifest inventory.db

# Machine-readable output for CI
census doctor --json

12. Manifest merging

# Merge manifests from different servers
census merge server1.db server2.db -o combined.db

# Merge with glob
census merge scans/*.db -o full-inventory.db --json

13. Audit log

# View all operations
census audit-log show

# Verify hash chain integrity
census audit-log verify

# Machine-readable
census audit-log show --last 10 --json

14. Named snapshots

# Create a compliance baseline
census snapshot create q1-baseline --manifest inventory.db

# List snapshots
census snapshot list

# Compare two snapshots
census snapshot diff q1-baseline q2-baseline

15. Forensic annotation

# Annotate an attestation with case metadata
census annotate att_123 --note "Evidence for case FR-2026-42" --tag "case-2026-001"

# Zero-knowledge mode: encrypt before sending
census annotate att_123 --note "Confidential" --encrypt --encryption-key <key>

# GDPR right-to-erasure
census annotate att_123 --delete

16. Configuration

# Create config template
census config init --project

# View effective config
census config show

# Enable shell completions
eval "$(census completion bash)"

17. Forensic share tokens

# Create a share token (chain of custody)
census share create <att_id> --expires 24h --recipient "Legal Dept" --max-uses 5

# List / inspect / revoke
census share list --json
census share info <token_id>
census share revoke <token_id>

18. Structured tagging

# Tag attestations for classification
census tag set <att_id> -t department=legal -t case=2026-001

# Encrypted tags (client-side encrypted)
census tag set <att_id> -t classification=confidential --encrypt

# Query by tags (AND logic, cursor pagination)
census tag query -f department=legal --limit 50 --json

19. Key rotation

# Rotate encryption key (NIST SP 800-57)
census key-rotate <att_id> --old-key <hex64> --new-key <hex64>

20. Derived lists (third-party inventory matching)

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

# Third party matches their suspects (server never sees plaintext)
census derived-list match <list_id> --list-key <hex64> --hashes-file suspects.txt

# Audit trail
census derived-list access-log <list_id>

21. Metadata read

census metadata get <att_id> --json
census metadata get <att_id> --decrypt --encryption-key <hex64>

22. Git integration (commit attestation)

# Install post-commit hook
census git-hook install

# Verify installation
census git-hook status

# Every git commit now auto-attests changed files
git add . && git commit -m "update"
# → Files hashed, manifest updated, batch attestation with source=git-commit:<sha>

# Manual trigger (for testing)
census git-hook run

# Remove hook
census git-hook uninstall

23. Watch mode (continuous monitoring)

# Watch a directory for changes and attest new/modified files
census watch /path/to/files --source "production"

# Dry run — hash only, no attestation
census watch /data --dry-run

# Network mount — use polling
census watch /mnt/share --polling --poll-interval 10

# Event hooks — run commands on change/attestation (JSON on stdin)
census watch /data --on-change "jq . >> /var/log/census-changes.jsonl" \
                   --on-attest "curl -X POST https://slack.webhook/..."

# Full T1/T2 lifecycle hooks via webhooks
census watch /data \
    --on-change "jq . >> /var/log/census-changes.jsonl" \
    --on-attest "echo 'T0 attested'" \
    --on-t1 "echo 'T1 TSA certified'" \
    --on-t2 "curl -X POST https://slack.webhook/..." \
    --webhook-secret-file .census-webhook-secret \
    --webhook-port 9514

# Velocity alerting — detect abnormal file-change rates
census watch /data/sensitive \
    --alert-threshold 100 \
    --alert-window 300 \
    --on-alert 'jq . >> /var/log/census-alerts.jsonl'

Requires: pip install certisigma-census[watch]

Production deployment via systemd: see contrib/census-watch@.service.

23. Manifest seal (tamper evidence)

# Create an HMAC-SHA256 seal for a manifest
census seal ./manifest.db --key $(census key-gen)

# Verify the seal before trusting a manifest
census verify-seal ./manifest.db --key <hex64>

# JSON output
census verify-seal ./manifest.db --key <hex64> --json

The seal proves the manifest has not been modified since it was sealed. Follows the Tripwire/AIDE signed-database pattern.

24. Quiet mode (scripting)

# Suppress informational output — only errors and exit codes
census -q scan /data --dry-run
census -q compare /suspects

# Quiet + JSON — clean machine-readable output
census -q scan /data --json --attest-manifest

25. Bulk inventory matching

# Scan a suspect drive against your org inventory (up to 50K hashes/call)
census bulk-scan /mnt/suspect-drive --json

# Cross-reference with a local manifest
census bulk-scan ./data --manifest inventory.db --workers 4

# Dry run — hash and count, no API call (save rate limit)
census bulk-scan /data --dry-run

# Label the scan for incident tracking
census bulk-scan /exports --source incident-2026-003 --json

# Save results to file
census bulk-scan /exports --output results.json

# Report-only mode — always exit 0 (for CI pipelines)
census bulk-scan /data --exit-zero --json > results.json

# Summary mode — counts only, no match details
census bulk-scan /data --summary --exit-zero

Exit code: 0 if no matches (or --exit-zero), 1 if matches found and review is required.

26. Organization statistics

# View org-level inventory stats
census stats

# Machine-readable
census stats --json

27. SARIF output (CI/CD integration)

# Compare with SARIF output for GitHub Security tab
census compare /suspects --format sarif > results.sarif

# Write SARIF directly to file (recommended for CI/CD)
census compare /suspects --format sarif --output results.sarif

# Report-only mode — always exit 0 (upload SARIF without pipeline failure)
census compare /suspects --format sarif --output results.sarif --exit-zero

# Summary mode — counts only, concise CI logs
census compare /suspects --summary --exit-zero

# SARIF + JSON are also available
census compare /suspects --format json

SARIF v2.1.0 output can be uploaded to GitHub Security tab, VS Code SARIF Viewer, and other compatible tools.

28. JSONL streaming output

# Stream results to a log file (one JSON object per line)
census compare /suspects --format jsonl >> /var/log/census/matches.jsonl

# Pipe to jq for real-time filtering
census compare /suspects --format jsonl | jq 'select(.level=="T2")'

# JSONL is available on compare, bulk-scan, integrity, verify-manifest, and diff
census integrity manifest.db --format jsonl
census diff base.db current.db --format jsonl

29. On-match notification hooks

# Execute a command when matches are found (JSON on stdin)
census compare /suspects --on-match './scripts/alert.sh'

# POST to a webhook
census compare /suspects --on-match 'curl -s -X POST -d @- https://hooks.slack.com/...'

# Also available on bulk-scan
census bulk-scan /data --on-match 'python3 scripts/notify.py'

The --on-match command is only executed when matches > 0. Match data (JSON) is piped to stdin.

30. GitHub Actions

# Breach detection with SARIF upload (3 lines)
- 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

# Inventory scan on release
- uses: certisigma/census-action@v1
  with:
    command: scan
    target: ./src
    source: release-${{ github.ref_name }}
  env:
    CERTISIGMA_API_KEY: ${{ secrets.CERTISIGMA_API_KEY }}

Composite action — zero Docker overhead, SARIF auto-upload to GitHub Security tab, step summary, masked secrets. Full docs: docs/features/github-action.md

31. Compliance reports

# NIS2 compliance report (default)
census compliance-report manifest.db -o report.html

# DORA compliance report
census compliance-report manifest.db --template dora -o report.html

# ISO 27001
census compliance-report manifest.db --template iso27001 -o report.html

# With integrity check included
census compliance-report manifest.db --integrity -o report.html

# Machine-readable JSON
census compliance-report manifest.db --json

Maps Census data to regulatory requirements (NIS2, DORA, ISO 27001). 100% local — no API calls. Uses manifest data and optional integrity check.

32. Forensic archive

# Create a forensic evidence package from a manifest
census archive manifest.db -o evidence-2026-03-18.zip

# With chain of custody metadata
census archive manifest.db -o case-42.zip \
  --examiner "J. Doe" --case-id CASE-42 --organization "Acme Corp"

# Verify archive integrity
census verify-archive evidence-2026-03-18.zip

Creates a self-contained ZIP with: manifest database, full inventory (JSON), system metadata, chain of custody, SHA256SUMS for offline verification. Follows EnCase/FTK conventions for evidence packaging.

33. AI Governance

# Generate a policy template
census ai-policy init

# Edit .census-ai-policy.toml to define allow/exclude rules

# Classify assets (dry run — no API calls)
census ai-policy apply manifest.db --dry-run

# Apply classifications and tag attestations
census ai-policy apply manifest.db --api-key cs_...

# Generate HTML compliance report
census ai-policy report manifest.db -o ai-report.html

# JSON output
census ai-policy report manifest.db --json

Classify inventoried assets for ML/AI training compliance using TOML-based policies. Rules match files by glob patterns and size filters. Safety-first: unmatched files default to exclude. Supports EU AI Act, ISO/IEC 42001, and C2PA frameworks. Classification is 100% local; only apply (without --dry-run) makes API calls to tag attestations.

34. SBOM Attestation

# Attest an SPDX SBOM
census sbom attest sbom.spdx.json --source "ci-pipeline"

# Attest the exact SBOM document digest too
census sbom attest sbom.spdx.json --attest-document --source "ci-pipeline"

# Attest a CycloneDX SBOM (dry run)
census sbom attest bom.cdx.json --dry-run --json

# Verify SBOM components against the registry
census sbom verify sbom.spdx.json --json

# CI-friendly verify (never fails on missing)
census sbom verify bom.cdx.json --exit-zero

# Validate local SBOM evidence readiness
census sbom validate bom.cdx.json --profile bsi --json
census sbom validate bom.cdx.json --profile enterprise --report-format sarif

# Compare SBOM drift locally
census sbom diff old-bom.cdx.json new-bom.cdx.json --json

# Create a local SBOM evidence bundle
census sbom bundle bom.cdx.json --output sbom-evidence.zip

# Generate a reference CI workflow
census sbom pipeline init --generator syft --profile bsi

# Ingest local vulnerability intelligence and match it against an SBOM
census sbom vuln cache --feed osv.json --source osv --cache-dir .census/sbom-vuln
census sbom vuln match bom.cdx.json --cache-dir .census/sbom-vuln --report-format sarif

# Summarize local VEX/CSAF status evidence
census sbom vex summarize supplier-vex.json --json

# Evaluate supplier SBOM evidence readiness against a local policy
census sbom intake supplier-bom.cdx.json --policy supplier-policy.toml --json

# Inspect SBOM structure and hash coverage
census sbom summary sbom.spdx.json --json

Validates local SBOM evidence readiness, compares release-to-release SBOM drift, creates local SBOM evidence bundles, generates reference CI workflows, matches explicit local vulnerability feeds, applies VEX/CSAF status context, runs supplier intake policy results and extracts SHA-256 hashes from SPDX 2.x/3.0.1 and CycloneDX JSON SBOMs for CertiSigma batch attestation. Each attested component hash receives the same three-layer proof (ECDSA T0, TSA T1, Bitcoin T2) as file attestations. --attest-document can also attest the exact SBOM file digest. Validation, diff, bundle, pipeline generation, vulnerability matching, VEX/CSAF summary and intake are local-only; bundles exclude the original SBOM body unless --include-sbom is explicit.

35. Forensic Timeline & DFIR Export

# Build timeline from audit log
census timeline build

# Build with manifest enrichment
census timeline build --manifest .census-manifest.db

# Query events (text output)
census timeline query --action scan --start -7d

# Export to TSK body file (for Autopsy / Sleuth Kit)
census timeline query --format bodyfile --output timeline.bodyfile

# Export to Plaso l2tcsv
census timeline query --format l2tcsv --output timeline.csv

# Export to CASE/UCO JSON-LD (for AXIOM / X-Ways)
census timeline query --format case-json --output case.json --case-name "Investigation-2026" --examiner "Dr. Smith"

# Export to HTML forensic report
census timeline query --format html --output timeline.html

# Timeline statistics with anomaly detection
census timeline stats --window 1h --json

# Query around a specific event (5-minute window)
census timeline query --around "2026-04-10T10:30:00" --window 300

Queryable SQLite timeline derived from the tamper-evident audit log. Supports time-range, action, path, and hash filters. Export to standard DFIR formats: TSK 3.x body file, Plaso l2tcsv, CASE/UCO JSON-LD, HTML, JSON, JSONL, CSV. Timeline DB is always rebuildable from the audit log — never the source of truth.

36. SIEM-Native Event Correlation

# Run built-in correlation rules against the timeline
census correlate run

# JSON output (includes risk_score + census_version)
census correlate run --json

# CEF output for Splunk/ArcSight/QRadar
census correlate run --format cef --output alerts.cef

# ECS NDJSON for Elasticsearch/OpenSearch
census correlate run --format ecs --output alerts.ndjson

# Multi-host correlation
census correlate run --timeline-dir /data/host1 --timeline-dir /data/host2

# List built-in rules
census correlate list-rules

# Validate custom rules file
census correlate validate ./my-rules.toml

Threshold-based correlation over the timeline index — multi-event patterns, optional unattested-content escalation, and exports for SIEM pipelines. 100% local; no API calls.

37. String Attestation & Identifier Census

# Hash a string identifier
census hash --string "SN-2026-0042"

# Hash strings from file (one per line, comments with #)
census hash --strings-file serial-numbers.txt

# Attest string identifiers (source label mandatory)
census attest --strings-file serial-numbers.txt --source "production-batch-Q1"
census attest --string "LICENSE-KEY-ABC123" --source "license-registry" --json

# Verify a string identifier
census verify --string "SN-2026-0042"

# Breach detection against string identifiers
census compare --strings-file leaked-serials.txt --manifest inventory.db --json

# Bulk scan strings
census bulk-scan --strings-file identifiers.txt --manifest inventory.db

# Derived list from strings
census derived-list create --strings-file assets.txt --label "Q1 identifiers"
census derived-list match <list-id> --list-key <key> --string "SN-CHECK"

Extends Census beyond files: cryptographic attestation of serial numbers, license keys, batch codes, URNs. Manifest schema v5 keeps entry_type (file | string) on objects and locations. --source is mandatory for string attestation. PII-safe: raw strings never appear in audit logs.

38. Multi-Manifest Federation

# Federate two manifests
census federate site-a.db site-b.db -o global.db

# With conflict resolution strategy
census federate *.db -o combined.db --strategy skip --show-conflicts

# Named source labels
census federate prod.db staging.db -o merged.db --label production --label staging

# JSON output with conflicts and federation metadata
census federate a.db b.db c.db -o all.db --strategy latest_mtime --json

Aggregates manifests from multiple sites, teams, or CI pipelines. Four conflict resolution strategies: latest_mtime (default), latest_source, first, skip. Federation metadata (sources, strategy, timestamp, conflict count) stored in the output manifest.

How It Works

1. Scan — Census walks the directory, computes SHA-256 for each file (streamed, constant memory), and builds a local manifest.
2. Attest — Hashes are sent in batches (up to 100 per call) to the CertiSigma API. Each hash receives a three-layer cryptographic proof (T0 ECDSA signature, T1 qualified TSA timestamp, T2 Bitcoin anchor).
3. Compare — Suspect files are hashed and verified against the registry via POST /verify/batch. Matches prove the file was previously inventoried, regardless of filename or directory structure changes.

The original file content never leaves the client. Only SHA-256 hashes are transmitted.

Features

Feature	Description	Docs
File filters	--include, --exclude globs; --min-size, --max-size	scanning.md
Resume scans	--resume skips unchanged files, preserves attestation state	scanning.md
CSV/JSON export	Compare reports and manifest export in both formats	comparison.md
Retry with backoff	Automatic retry on 429/5xx with exponential backoff	retry-and-resilience.md
Structured logging	--log-format json for SIEM/ELK integration	logging.md
Progress bars	Visual feedback for scan, attest, and compare operations	scanning.md
SQLite manifest	WAL mode, schema v5 objects/locations, indexed lookups, auto-migration from JSON/v2-v4	manifest.md
Watch mode	Continuous filesystem monitoring with batch attestation	watching.md
Velocity alerting	Exfiltration/ransomware detection via rolling-window event counting in watch mode	velocity-alerting.md
Evidence verification	Full T0/T1/T2 chain, OTS proof export	evidence.md
Integrity check	Tamper detection against manifest baseline, differential mode	integrity.md
Forensic reports	HTML, PDF, evidence bundles (ZIP) with chain-of-custody	reporting.md
Chain of custody	Examiner, case ID, organization, signature lines (PDF)	chain-of-custody.md
Manifest diff	Compare snapshots, AIDE-style exit codes, HTML reports	diff.md
Standalone hashing	SHA-256 without manifests or API calls	hash.md
Duplicate analysis	duplicates — live or manifest-backed SHA-256 duplicate groups, wasted bytes, JSON/CSV/HTML, no API calls	duplicates.md
Container analysis	container inspect / report / duplicates / diff / drift — local ZIP/TAR/GZIP inventory, report bundle, duplicate review, build drift, no extraction	container-analysis.md
Assurance score & policy gates	assurance score, policy init/check — local evidence-readiness scoring and CI gates with JSON/SARIF output, no API calls	assurance.md
Release evidence	release pack, receipt generate/verify — local release evidence ZIP, SHA256SUMS, public receipt, offline verification	release-evidence.md
Git ref/tag drift	git ref-snapshot, git tag-drift — read-only local release-ref drift evidence with JSON/SARIF output, no fetch or API calls	git-ref-drift.md
Trust surface snapshots	tls snapshot, dns snapshot, web snapshot, web snapshot --seo-geo, snapshot diff --snapshot-files — passive TLS certificate, DNS record, web/header and SEO/GEO publication artifact snapshot evidence plus local snapshot diff evidence with canonical hashes, no crawling, sitemap URL fetching, zone transfer, browser runtime or API calls	trust-surface.md
Append-only log seal	log seal, log verify — local SHA-256/Merkle sidecars for append-only logs, no raw log lines, shipping, monitoring, API calls or automatic attestation	log-seal.md
Attestation tracking	Monitor T0/T1/T2 progression with --poll or --level T1|T2	tracking.md
Webhooks	Push-based T1/T2 lifecycle notifications with HMAC verification	—
Config files	TOML config with user/project precedence	config.md
Shell completions	bash, zsh, fish via census completion	—
Self-diagnostic	API health, config, inotify, manifest integrity	doctor.md
Manifest merging	Combine manifests from distributed scans	merge.md
JSON output	--json on all major commands (scan, compare, integrity, verify, status, doctor, merge, bulk-scan, stats, and more)	—
Audit log	Tamper-evident JSONL with SHA-256 hash chain	audit-log.md
Named snapshots	Compliance baselines with diff comparison	snapshots.md
Forensic annotation	Metadata, tags, case IDs on attestations	annotate.md
Client-side metadata encryption	AES-256-GCM client-side metadata encryption	annotate.md
Forensic sharing	Time-limited, use-limited share tokens (chain of custody)	sharing.md
Structured tagging	Key-value classification with encrypted tags and query	tagging.md
Key rotation	NIST SP 800-57 AES-256 key rotation for metadata + tags	key-rotation.md
Derived lists	HMAC-SHA256 opaque third-party inventory matching	derived-lists.md
Metadata read	Read attestation metadata with optional decryption	—
Manifest seal	HMAC-SHA256 tamper-evidence seal (Tripwire/AIDE pattern)	seal.md
Quiet mode	--quiet / -q suppresses info output for scripting	—
Manifest self-attestation	--attest-manifest anchors manifest hash at scan time	—
Bulk inventory matching	bulk-scan — 50K hashes/call, --dry-run, --source, --output	—
Organization stats	stats — total claims, unique hashes, monthly breakdown	—
SARIF output	compare --format sarif — v2.1.0 with help, tags, invocations, file write	—
Baseline update	update — AIDE-style accept verified changes into manifest (detect → review → accept)	—
JSONL streaming	--format jsonl on compare, bulk-scan, integrity, verify-manifest, diff	—
On-match hooks	--on-match CMD — execute command with results on stdin (compare, bulk-scan)	—
CI/CD integration	--exit-zero (report-only mode), --summary (counts only) on compare and bulk-scan	—
--no-color	Disable colored output; also respects NO_COLOR env var (no-color.org)	—
Forensic JSON metadata	census_version and elapsed_seconds in all JSON output	—
GitHub Action	certisigma/census-action@v1 — composite action for CI/CD with SARIF upload	github-action.md
Compliance reports	compliance-report — NIS2, DORA, ISO 27001 mapping from manifest data (100% local)	—
Developers page	Standalone HTML documentation at developers.certisigma.ch/census	census.html
AI governance	ai-policy init/apply/report — TOML policy engine for ML/AI training asset classification (EU AI Act, ISO 42001, C2PA)	—
Manifest encryption	AES-256-GCM encryption at rest for manifest files (--encryption-key / CENSUS_ENCRYPTION_KEY)	—
Man pages	Pre-generated man pages for all commands via click-man in docs/man/	—
PEP 561	py.typed marker for mypy/pyright inline type annotation support	—
File attribution	Captures file owner, group, POSIX permissions during scan (manifest schema v3)	—
Attested reports	report --attest + verify-report — three-layer proof on the report itself	—
Forensic archive	archive + verify-archive — evidence ZIP with manifest, chain of custody, OTS proofs, SHA256SUMS (0o600 permissions)	—
Git integration	git-hook install/uninstall/status/run — post-commit attestation with commit SHA provenance	git-hooks.md
SBOM assurance	sbom validate/diff/bundle/pipeline/attest/verify/summary — local SBOM evidence-readiness profiles, drift reports, evidence bundles, CI templates and SPDX 2.x/3.0.1 + CycloneDX JSON supply-chain attestation	sbom.md
SLSA provenance	provenance generate/verify — in-toto Statement v1 + SLSA v1.0 provenance with CI auto-detection, SBOM integration, and CertiSigma attestation	provenance.md
Forensic timeline	timeline build/query/stats — queryable SQLite timeline with export to TSK body file, Plaso l2tcsv, CASE/UCO JSON-LD, HTML	timeline.md
Forensic event correlation	correlate run/list-rules/validate — SIEM-native rules on timeline data; text, JSON, JSONL, CEF, ECS (Phase 35)	correlate.md
String attestation	attest --string, hash --string, verify --string, compare --strings-file — cryptographic inventory of identifiers (serial numbers, license keys, URNs)	string-attestation.md
Multi-manifest federation	federate — aggregate 2+ manifests with conflict resolution (latest_mtime, latest_source, first, skip)	federation.md
Docker image	ghcr.io/certisigma/census for CI/CD scanning	—

Full documentation: docs/features/

CLI Reference

Global options

Option	Description
-v / --verbose	Enable debug logging
-q / --quiet	Suppress informational output (errors and --json always shown)
--log-format text|json	Log output format (default: text). Also: CENSUS_LOG_FORMAT env var
--encryption-key HEX	AES-256 key (64 hex) for manifest encryption at rest. Also: CENSUS_ENCRYPTION_KEY env var
--no-color	Disable colored output (also respects NO_COLOR env, see no-color.org)
--version	Show version

census scan

Option	Description
--source LABEL	Source label for attestations
--manifest PATH	Manifest output path (default: <dir>/.census-manifest.db)
--api-key KEY	API key (or set CERTISIGMA_API_KEY)
--base-url URL	Override API base URL
--dry-run	Hash only, no attestation
--resume	Resume interrupted scan
--include GLOB	Include files matching pattern (repeatable)
--exclude GLOB	Exclude files matching pattern (repeatable)
--min-size SIZE	Skip files smaller than SIZE (e.g. 1K, 10M)
--max-size SIZE	Skip files larger than SIZE (default: 5G)
--workers N	Parallel hashing workers (default: 1, max: 8)
--attest-manifest	Attest the manifest's own SHA-256 after scan
--json	Machine-readable JSON summary

census compare

Option	Description
--manifest PATH	Local manifest for cross-referencing
--output PATH	Save report (.json or .csv by extension)
--format text|json|sarif|jsonl	Output format (default: text). sarif emits SARIF v2.1.0; jsonl streams one JSON object per match
--include/--exclude/--min-size/--max-size	Same filters as scan
--detailed	Enriched results: source label, T0/T1/T2 level (requires API key)
--workers N	Parallel hashing workers (default: 1, max: 8)
--json	Machine-readable JSON output (equivalent to --format json)
--exit-zero	Always exit 0 (report-only mode for CI pipelines)
--summary	Show only counts, no match details
--on-match CMD	Execute CMD with match results as JSON on stdin (only if matches > 0)

census export

Option	Description
--format csv|json|sha256sum	Output format (default: csv)
--output PATH	Output file (default: stdout)

census verify

Option	Description
--file	Treat argument as a file path (hash it first)
--save-ots PATH	Save OTS proof to this path
--json	Machine-readable JSON output
--api-key KEY	API key (optional for verify)
--base-url URL	Override API base URL

census verify-manifest

Option	Description
--detailed	Fetch enriched data (source, level) per hash
--strict	Exit with code 1 if any hash is not attested
--json	Machine-readable JSON output
-o/--output PATH	Save report (.csv or .json)
--api-key KEY	API key (optional, needed for --detailed)
--base-url URL	Override API base URL

census integrity

Option	Description
--json	Machine-readable JSON output
--format text|json|jsonl	Output format (default: text)
--output PATH	Save results (.csv or .json by extension)
--strict	Exit with code 1 on any discrepancy
--since PATH	Differential: load previous state, suppress known findings (auto = sidecar)
--write-state PATH	Save current state for next differential run (auto = sidecar)
--auto-update	Atomically accept discrepancies into the manifest baseline after the check

census update

Option	Description
--yes / -y	Skip confirmation prompt (non-interactive)
--json	Machine-readable JSON output

Runs integrity check, then applies changes (remove missing, re-hash modified, add new). New entries are attested=False.

census report

Option	Description
-o/--output PATH	Output file (.html, .pdf, or .zip) required
--evidence	Fetch T0/T1/T2 evidence chain for attested files
--integrity	Run integrity check and include results
--bundle	Generate evidence bundle (ZIP)
--attest	Attest the report's own hash via CertiSigma (three-layer proof)
--examiner TEXT	Forensic examiner name for chain of custody
--case-id TEXT	Case identifier for chain of custody
--organization TEXT	Organization name for chain of custody
--notes TEXT	Free-text notes for chain of custody
--api-key KEY	API key (needed with --evidence or --attest)

census verify-report

Option	Description
--sidecar PATH	Custom sidecar path (default: <report>.attestation.json)
--json	Machine-readable JSON output

census status

Option	Description
--json	Machine-readable JSON output

census doctor

Option	Description
--manifest PATH	Check health of a specific manifest file
--json	Machine-readable JSON output
--api-key KEY	API key
--base-url URL	Override API base URL

census merge

Option	Description
-o/--output PATH	Output manifest path required
--json	Machine-readable JSON summary

census diff

Option	Description
--json	Machine-readable JSON output
-o/--output PATH	Save report (.html, .csv, or .json by extension)
--summary	Show only counts, no individual file details

Exit codes: 0=none, 1=added, 2=removed, 4=modified (bitmask, OR'd together).

census hash

Option	Description
--stdin	Read data from stdin instead of a file
--string VALUE	Hash a string identifier instead of a file
--strings-file PATH	Hash all identifiers from file (one per line, # comments)
--verify HASH	Compare computed hash against expected SHA-256
--json	Output as JSON array

census duplicates

Option	Description
--manifest PATH	Read duplicate locations from an existing schema v5 manifest without rescanning
--include GLOB	Include files matching pattern (repeatable)
--exclude GLOB	Exclude files matching pattern (repeatable)
--min-size SIZE	Skip files smaller than SIZE
--max-size SIZE	Skip files larger than SIZE (default: 5G)
--workers N	Parallel hashing workers (default: 1, max: 8)
--format text|json|csv|html	Output format (default: text)
--output PATH	Save duplicate report to a file
--json	Shorthand for --format json

Local-only evidence command: groups equal SHA-256 digests and reports duplicate_groups, duplicate_files, unique_files, wasted_bytes and paths. --include, --exclude, size filters and --workers apply only to live directory scans. No API call, no manifest mutation and no destructive remediation.

census container inspect

Option	Description
--format text|json|html	Output format (default: text)
--output PATH	Save inspect report to a file
--json	Shorthand for --format json
--manifest PATH	Persist outer artifact and hashable member locations to manifest v5
--max-members N	Maximum container members to analyze (default: 10000)
--max-member-size SIZE	Maximum uncompressed size per member (default: 512M)
--max-total-size SIZE	Maximum total uncompressed size (default: 2G)
--max-ratio N	Maximum per-member expansion ratio (default: 100)

census container inspect supports ZIP, TAR and single-member GZIP through stdlib readers. census zip inspect remains a ZIP-family alias. archive inspect is deferred to avoid breaking the existing census archive MANIFEST command.

census container report

Renders a reviewable container report and can optionally create a local evidence bundle, attest the outer artifact hash or attest the rendered report hash. It does not attest internal members.

Option	Description
--format html|json|text	Output format (default: html)
--output PATH	Save report to a file
--json	Shorthand for --format json
--evidence-bundle PATH	Write ZIP bundle with report, inspect JSON, metadata and SHA256SUMS
--attest-container	Attest only the outer artifact SHA-256 via CertiSigma
--attest-report	Attest the rendered report SHA-256 via CertiSigma
--api-key KEY	API key for attestation flags
--base-url URL	API base URL override for attestation flags
--max-members N	Maximum container members to analyze
--max-member-size SIZE	Maximum uncompressed size per member
--max-total-size SIZE	Maximum total uncompressed size
--max-ratio N	Maximum per-member expansion ratio

census container duplicates

Local-only duplicate analysis inside one supported artifact. Reports duplicate member content by SHA-256 and duplicate member names.

Option	Description
--format text|json	Output format (default: text)
--output PATH	Save duplicate report to a file
--json	Shorthand for --format json
--max-members N	Maximum container members to analyze
--max-member-size SIZE	Maximum uncompressed size per member
--max-total-size SIZE	Maximum total uncompressed size
--max-ratio N	Maximum per-member expansion ratio

census container diff

Compares two supported artifacts without extraction. JSON output is deterministic and reports added, removed and modified members, metadata drift, duplicate-name drift and safety-finding drift.

census container diff old.zip new.zip --json

census container drift

Compares a current artifact against a prior container inspect --json baseline. Baseline JSON is size-limited and schema-validated before use.

census container drift new.zip --baseline baseline.json --json

census assurance score

Local-only evidence-readiness score for a Census manifest. It reports a 0-100 score, grade, aggregate signals and explainable findings. It never contacts the CertiSigma API and does not make legal compliance claims.

census assurance score --manifest inventory.db
census assurance score --manifest inventory.db --json

Option	Description
--manifest PATH	Census manifest to score
--format text|json	Output format (default: text)
--json	Shorthand for --format json
--seal-key KEY	Optional HMAC key for local seal verification (CENSUS_SEAL_KEY)

The score uses local manifest coverage, attestation markers, manifest seal presence/verification, duplicate-location concentration and container outer-artifact backing. Container-member-only observations are treated as local analysis evidence and are not expected to be individually attested.

census policy init/check

Local policy-as-code gates over the assurance score. The commands are designed for CI and release review: they read only the policy TOML, manifest database and optional local seal sidecar, then return deterministic pass/fail output without contacting the CertiSigma API.

census policy init --output census-policy.toml
census policy init --profile strict --output census-policy.toml
census policy check --policy census-policy.toml --manifest inventory.db
census policy check --policy census-policy.toml --manifest inventory.db --format json
census policy check --policy census-policy.toml --manifest inventory.db --format sarif

census policy init options:

Option	Description
--output PATH	Policy file to create (default: census-policy.toml)
--profile baseline|strict	Template profile
--force	Overwrite an existing policy file
--json	Machine-readable creation result

census policy check options:

Option	Description
--policy PATH	Census assurance policy TOML file
--manifest PATH	Census manifest to evaluate
--format text|json|sarif	Output format (default: text)
--json	Shorthand for --format json
--output PATH	Write result to file
--seal-key KEY	Optional HMAC key for local seal verification (CENSUS_SEAL_KEY)
--exit-zero	Render the result but always exit 0

Exit codes are stable: 0 means all enabled gates passed, 1 means at least one policy gate failed, and 2 means usage or invalid policy input. Policy results are internal evidence-readiness gates, not legal compliance verdicts.

census release pack

Creates a local release evidence ZIP. Artifact hashes are always recorded, but artifact bytes are excluded unless --include-artifacts is explicit.

census release pack 1.28.2 --artifact dist/pkg.whl --manifest inventory.db
census release pack 1.28.2 --artifact dist/pkg.whl --sbom sbom.json --provenance provenance.json
census release pack 1.28.2 --artifact dist/pkg.whl --git-ref-snapshot git-refs.json --git-drift-report git-drift.json
census release pack 1.28.2 --artifact dist/pkg.whl --include-artifacts

Option	Description
VERSION	Release version label
--artifact PATH	Release artifact to hash; repeatable and required
--manifest PATH	Optional Census manifest for embedded assurance score
--policy PATH	Optional Census policy TOML; requires --manifest
--sbom PATH	Optional SBOM evidence file
--provenance PATH	Optional provenance evidence file
--changelog PATH	Optional changelog evidence file
--git-ref-snapshot PATH	Optional Git ref snapshot evidence file
--git-drift-report PATH	Optional Git drift report evidence file
--metadata KEY=VALUE	Build metadata; repeatable
--profile release|auditor|customer|public	Evidence profile label
--output PATH	Output ZIP path
--include-artifacts	Copy artifact bytes into the pack
--digest-only	Store only hashes for selected evidence files
--path-policy basename|relative|full	Path labels stored in the pack
--base-dir PATH	Base directory for relative labels
--seal-key KEY	Optional HMAC key for local seal verification
--json	Machine-readable creation result

Pack contents: release-evidence.json, receipt.json, VERIFY.md, SHA256SUMS, selected evidence/* files and optional artifacts/* files.

census receipt generate/verify

Generates and verifies public release receipts from a release evidence ZIP or release-evidence.json.

census receipt generate --release-evidence release-evidence.zip --output receipt.json
census receipt generate --release-evidence release-evidence.zip --output receipt.html --format html
census receipt verify receipt.json --release-evidence release-evidence.zip --json

census receipt generate options:

Option	Description
--release-evidence PATH	Release evidence ZIP or JSON
--output PATH	Receipt output path
--format json|html	Receipt format
--json	Machine-readable command result

census receipt verify options:

Option	Description
RECEIPT_PATH	JSON receipt to verify
--release-evidence PATH	Release evidence ZIP or JSON
--json	Machine-readable verification result
--exit-zero	Render verification but always exit 0

Verification is offline. It checks receipt/evidence consistency and, for ZIP packs, validates SHA256SUMS. Exit code 0 means valid, 1 means mismatch and 2 means usage or invalid input.

census git ref-snapshot

Captures local Git branch, remote-tracking branch, tag, HEAD and redacted remote state for release review. It is read-only and does not fetch remotes.

census git ref-snapshot --repo . --output git-refs.json
census git ref-snapshot --repo . --json

Option	Description
--repo PATH	Git repository path; default current directory
--output PATH	Write snapshot JSON
--json	Print snapshot JSON

census git tag-drift

Compares the current local Git state against a prior snapshot and reports release-ref drift as review evidence.

census git tag-drift --baseline git-refs.json --repo .
census git tag-drift --baseline git-refs.json --repo . --release-ref v1.28.2 --json
census git tag-drift --baseline git-refs.json --repo . --format sarif --output git-drift.sarif

Option	Description
--baseline PATH	Baseline git ref-snapshot JSON
--repo PATH	Git repository path; default current directory
--release-ref REF	Optional tag/branch/ref expected to match current HEAD
--format text|json|sarif	Output format
--json	Same as --format json
--output PATH	Write drift report
--exit-zero	Render report but always exit 0

Exit code 0 means no high/medium drift findings, 1 means drift detected and 2 means usage or invalid input. Added refs are informational; moved/deleted tags and release-ref mismatch are high-signal release evidence, not proof of compromise.

census tls snapshot

Captures passive TLS trust surface snapshot evidence for one explicit endpoint.

census tls snapshot example.com
census tls snapshot example.com --json
census tls snapshot example.com --format json --output tls-snapshot.json

Option	Description
DOMAIN	Hostname or IP literal to observe
--port N	TLS port; default 443
--timeout SECONDS	Socket timeout, max 10; default 5
--server-name NAME	Optional SNI/hostname override
--format text|json	Output format
--json	Same as --format json
--output PATH	Write snapshot evidence to file

The command uses one TLS handshake, records certificate metadata and includes a canonical snapshot_sha256. It does not fetch web content, crawl, run active tests, attest, scan ports or call the API.

census dns snapshot

Captures passive DNS trust surface snapshot evidence for one explicit domain.

census dns snapshot example.com
census dns snapshot example.com --json
census dns snapshot example.com --record MX --record TXT --dkim-selector default
census dns snapshot example.com --resolver 9.9.9.9 --timeout 3 --format json --output dns-snapshot.json

Option	Description
DOMAIN	Domain name to observe; IP literals are rejected for this DNS snapshot
--resolver IP	Explicit DNS resolver IP; default is the first system resolver
--timeout SECONDS	UDP query timeout, max 10; default 3
--record A|AAAA|MX|TXT|CAA|NS|DS|DNSKEY	Record type to query; can be repeated
--dkim-selector SELECTOR	Query SELECTOR._domainkey.DOMAIN TXT; can be repeated
--format text|json	Output format
--json	Same as --format json
--output PATH	Write snapshot evidence to file

The command sends bounded UDP DNS queries, records answers, TTLs, truncation flags, SPF/DMARC evidence and DNSSEC-related DS/DNSKEY records when available, then emits a canonical snapshot_sha256. It does not perform zone transfers, zone walking, subdomain enumeration, DKIM selector guessing, recursive crawling, active tests, attestation or API calls.

census web snapshot

Captures passive web/header trust surface snapshot evidence for one explicit HTTP(S) URL.

census web snapshot https://example.com/
census web snapshot https://example.com/ --json
census web snapshot https://example.com/ --seo-geo --json
census web snapshot https://example.com/ --method HEAD
census web snapshot https://example.com/ --timeout 3 --max-redirects 3 --max-bytes 1M --format json --output web-snapshot.json

Option	Description
URL	HTTP(S) URL to observe; credentials and fragments are rejected
--method GET|HEAD	HTTP method; default GET
--timeout SECONDS	HTTP timeout, max 10; default 5
--max-redirects N	Redirect hops to follow, max 10; default 3
--max-bytes SIZE	Response body bytes to hash, max 5M; default 1M
--user-agent TEXT	Optional declared User-Agent
--seo-geo	Add bounded same-origin robots.txt, sitemap.xml, llms.txt, canonical/hreflang and schema.org/JSON-LD evidence
--format text|json	Output format
--json	Same as --format json
--output PATH	Write snapshot evidence to file

The command records status, redirect evidence, sanitized headers, common web header evidence, canonical URL evidence from final URL or HTTP Link header, and a bounded content digest. --seo-geo adds publication/discoverability snapshot evidence for same-origin robots.txt, sitemap.xml, llms.txt, canonical tags, hreflang links and schema.org/JSON-LD signals. It does not store response bodies, crawl links, fetch sitemap URLs, submit forms, execute JavaScript, use a browser/headless runtime, run active tests, attest or call the API. Query strings are redacted in display fields and represented by SHA-256 in full-URL evidence; sensitive headers such as Set-Cookie are redacted while retaining value hashes.

census snapshot diff --snapshot-files

Compares two saved TLS/DNS/web trust surface snapshot JSON files locally. Existing named manifest snapshot diff remains available as census snapshot diff NAME1 NAME2; file diff mode is explicit.

census snapshot diff --snapshot-files old-tls.json new-tls.json
census snapshot diff --snapshot-files old-dns.json new-dns.json --json
census snapshot diff --snapshot-files old-web.json new-web.json --format json --output snapshot-diff.json --exit-zero

Option	Description
--snapshot-files	Interpret the two diff arguments as trust surface snapshot JSON files
--format text|json	Output format; default text
--json	Same as --format json
--output PATH	Write snapshot diff evidence to file
--exit-zero	Render drift evidence but return exit code 0

The diff supports tls-snapshot, dns-snapshot and web-snapshot files of the same kind. It reads local JSON only, ignores runtime-only metadata such as generated_at, census_version, elapsed_seconds and snapshot_sha256, and emits snapshot-diff evidence with deterministic findings plus diff_sha256. Exit code 0 means no drift, 1 means drift evidence was found and 2 means usage or invalid input. The command does not capture new trust surface evidence, crawl, probe, attest or call the API.

census attest

Option	Description
--string VALUE	Attest a single string identifier
--strings-file PATH	Attest identifiers from file (one per line, # comments)
--source LABEL	Source label (mandatory)
--manifest PATH	Manifest path (default: .census-strings-manifest.db)
--dry-run	Hash only, no attestation
--api-key KEY	API key (or set CERTISIGMA_API_KEY)
--base-url URL	Override API base URL
--json	Machine-readable JSON output

census federate

Option	Description
MANIFESTS	Two or more manifest paths to federate (positional)
-o / --output PATH	Output manifest path (required)
--strategy	Conflict resolution: latest_mtime (default), latest_source, first, skip
--label	Source label per manifest (repeatable, auto-derived if omitted)
--show-conflicts	Show conflict details in output
--encryption-key HEX	Encrypt the output manifest
--json	Machine-readable JSON output

census track

Option	Description
--poll	Continuously check until target level reached
--level T1|T2	Target proof level (default: T2). Use T1 for TSA-only
--poll-interval SECS	Seconds between checks (default: 60)
--timeout SECS	Max time to poll (default: 3600)
--json	Machine-readable JSON output
--api-key KEY	API key
--base-url URL	Override API base URL

census webhook

Subcommand	Description
register	Register a webhook for T1/T2 events
list	List registered webhooks
delete WEBHOOK_ID	Delete a webhook and its delivery history
deliveries WEBHOOK_ID	Show delivery history
verify-payload FILE	Verify HMAC signature of a saved payload
serve	Start webhook receiver HTTP server

census webhook register options:

Option	Description
--url URL	HTTPS callback URL (required)
--events LIST	Comma-separated: t1_complete,t2_complete (required)
--label LABEL	Human-readable label (max 200 chars)
--save-secret FILE	Save signing secret to file (0o600 permissions)
--json	Machine-readable JSON output

census webhook serve options:

Option	Description
--secret-file FILE	Signing secret file (required)
--port PORT	Listen port (default: 9514)
--bind ADDR	Bind address (default: 127.0.0.1)
--on-t1 CMD	Shell command on T1 event (JSON on stdin)
--on-t2 CMD	Shell command on T2 event (JSON on stdin)
--tls-cert FILE	PEM certificate for built-in TLS
--tls-key FILE	PEM private key for built-in TLS
--replay-window SECS	Anti-replay window (default: 300)

census config

Action	Description
show	Display effective merged config
init	Create a template config file
paths	Show config file locations
--project	Act on project .census.toml

census audit-log

Action	Description
show	Display audit log entries
verify	Check hash chain integrity
clear	Delete the audit log file
--log-path PATH	Override audit log file path
--last N	Show only last N entries (with show)
--json	Machine-readable JSON output

census snapshot

Action	Description
create <name>	Save a named snapshot of a manifest
list	List all snapshots
diff <name1> <name2>	Compare two snapshots
delete <name>	Remove a snapshot
--manifest PATH	Manifest to snapshot (required for create)
--snapshot-dir PATH	Override snapshot directory
--json	Machine-readable JSON output

census annotate

Option	Description
--note TEXT	Free-text note
--tag TEXT	Tag label (e.g. case number)
--case-id TEXT	Forensic case identifier
--source TEXT	Update source label
--delete	Soft-delete metadata (GDPR)
--encrypt	Encrypt client-side (AES-256-GCM)
--encryption-key HEX	64-char hex AES-256 key
--decrypt	Decrypt and display stored metadata
--json	Machine-readable JSON output
--api-key KEY	API key

census share

Action / Option	Description
create <att_id>...	Create share token for attestation(s)
list	List all share tokens
info <token_id>	Inspect a specific token
revoke <token_id>	Revoke a token
--expires DURATION	Token lifetime: 30m, 24h, 7d (default: 24h)
--recipient TEXT	Recipient label
--max-uses N	Max usage count
--json	Machine-readable JSON output

census tag

Action / Option	Description
set <att_id>	Set tags (requires -t key=value)
get <att_id>	List tags on an attestation
delete <att_id> <key>	Delete a specific tag
query	Query attestations by tag filter
-t, --tag key=value	Tag pair (repeatable)
-f, --filter key=value	Query filter (repeatable, AND logic)
--encrypt	Encrypt tag values (AES-256-GCM)
--decrypt	Decrypt on get
--limit N	Max query results (default: 100)
--cursor TOKEN	Pagination cursor
--json	Machine-readable JSON output

census key-rotate

Option	Description
<attestation_id>	Target attestation
--old-key HEX	Current 64-char hex AES-256 key
--new-key HEX	New 64-char hex AES-256 key
--json	Machine-readable JSON output

census derived-list

Action / Option	Description
create	Create HMAC-SHA256 derived list
list	List all derived lists
info <list_id>	Get list details
match <list_id>	Match suspect hashes against list
access-log <list_id>	View access audit trail
signature <list_id>	ECDSA signature verification (no auth required)
revoke <list_id>	Revoke a list
--manifest PATH	Manifest to read hashes from
--tag-filter JSON	JSON tag filter for server-side selection
--label TEXT	Human-readable label
--expires HOURS	Expiry in hours (max 2160)
--list-key HEX	HMAC key (64 hex chars) for match
--hashes-file PATH	File with one hash per line for match
--json	Machine-readable JSON output

census metadata

Action / Option	Description
get <att_id>	Read attestation metadata
--decrypt	Decrypt encrypted extra_data
--encryption-key HEX	64-char hex AES-256 key
--json	Machine-readable JSON output

census key-gen

Generate a random AES-256 encryption key (64 hex characters, 256 bits). The key is shown only once — store it securely.

census key-gen              # outputs the key to stdout
census key-gen --json       # JSON output: {"key": "...", "algorithm": "AES-256-GCM", "bits": 256}

census completion

Takes a shell name: bash, zsh, or fish.

eval "$(census completion bash)"   # bash
eval "$(census completion zsh)"    # zsh
census completion fish | source    # fish

census watch

Option	Description
--debounce SECS	Quiet period before processing (default: 2.0s)
--batch-interval SECS	Max time between attestation batches (default: 30s)
--scan-on-start / --no-scan-on-start	Baseline scan before watching (default: on)
--on-delete ignore|mark|remove	Action on file deletion (default: ignore)
--polling	Use PollingObserver for NFS/CIFS mounts
--poll-interval SECS	Polling interval (default: 5s)
--source/--manifest/--api-key/--dry-run	Same as census scan
--include/--exclude/--min-size/--max-size	Same filters as scan
--on-change CMD	Shell command on file change (JSON on stdin)
--on-attest CMD	Shell command after attestation (JSON on stdin)
--on-t1 CMD	Shell command on T1 (TSA) webhook event (JSON on stdin)
--on-t2 CMD	Shell command on T2 (Bitcoin) webhook event (JSON on stdin)
--webhook-secret-file FILE	Signing secret for webhook receiver
--webhook-port PORT	Webhook receiver port (default: 9514)
--webhook-bind ADDR	Webhook receiver bind address (default: 127.0.0.1)
--alert-threshold N	Velocity alert: file changes per window
--alert-window SECS	Velocity alert: rolling window (default: 60s)
--alert-cooldown SECS	Velocity alert: cooldown between alerts (default: 300s)
--on-alert CMD	Shell command on velocity alert (JSON on stdin)

Requires: pip install certisigma-census[watch]

census archive

Option	Description
MANIFEST	Path to the manifest database
-o/--output PATH	Output ZIP path (default: evidence-YYYY-MM-DD.census.zip)
--examiner NAME	Examiner name (chain of custody)
--case-id ID	Case identifier (chain of custody)
--notes TEXT	Free-text notes (chain of custody)
--organization NAME	Organization name (chain of custody)
--no-compress	Store files without compression
--no-seal	Exclude manifest seal even if present
--json	Machine-readable JSON output with forensic metadata

census verify-archive

Option	Description
ARCHIVE_PATH	Path to the Census evidence archive
--json	Machine-readable JSON output with forensic metadata

Verifies SHA256SUMS against actual archive contents. Exit code 0 = valid, 1 = tampered. Archives larger than 500 MB are rejected (decompression bomb guard).

census seal

Option	Description
MANIFEST_PATH	Path to the manifest file
--key KEY	HMAC key (64 hex chars = 256 bits)
--json	Machine-readable JSON output

census verify-seal

Option	Description
MANIFEST_PATH	Path to the manifest file
--key KEY	HMAC key used to create the seal
--json	Machine-readable JSON output

Exit code 0 = valid, 1 = invalid or error.

census log seal

Creates local append-only log seal evidence for one explicit log file. The sidecar is JSON even when stdout is text.

Option	Description
LOG_PATH	Local log file to seal
--window DURATION	Evidence window such as 30s, 15m, 1h, 1d; default 1h
--output PATH	Write sidecar path; default LOG.logseal
--format text|json	Output format for stdout
--json	Same as --format json

census log verify

Verifies a local .logseal sidecar by recomputing log hash and Merkle window evidence. Exit code 0 means valid, 1 means findings, and 2 means usage or input error.

Option	Description
SEAL_PATH	.logseal sidecar to verify
--log PATH	Explicit log path; default infers from the sidecar path
--format text|json	Output format
--json	Same as --format json
--exit-zero	Render findings but return exit code 0

census bulk-scan

Option	Description
SUSPECT_DIR	Directory to scan
--manifest PATH	Local manifest for cross-referencing original paths
--include/--exclude/--min-size/--max-size	Same filters as scan
--workers N	Parallel hashing workers (default: 1, max: 8)
--source LABEL	Source label for audit logging (e.g. incident ID)
--dry-run	Hash only, no API call — preview file/hash/chunk counts
--output PATH	Save results to JSON file
--json	Machine-readable JSON output
--exit-zero	Always exit 0 (report-only mode for CI pipelines)
--summary	Show only counts, no match details
--format text|json|jsonl	Output format (default: text)
--on-match CMD	Run command with match results as JSON on stdin (only if matches > 0)
--api-key KEY	API key (requires scan scope)
--base-url URL	Override API base URL

Uses POST /scan — up to 50K hashes per call with automatic chunking. Exit code: 0=no matches, 1=matches found (or always 0 with --exit-zero).

census stats

Option	Description
--json	Machine-readable JSON output
--api-key KEY	API key (requires batch scope)
--base-url URL	Override API base URL

census sbom

Subcommand	Description
validate SBOM_FILE	Validate local SBOM evidence readiness with cra-minimal, bsi or enterprise profiles
diff OLD NEW	Compare two SBOMs locally and report semantic drift
bundle SBOM_FILE	Create a local SBOM evidence ZIP with SHA256SUMS and verification notes
pipeline init	Generate a reference SBOM evidence CI workflow
vuln cache	Ingest an explicit local OSV/NVD/GHSA/EPSS/KEV/Census feed into a local cache
vuln match SBOM_FILE	Match SBOM components against the local vulnerability cache with text/JSON/SARIF output
vex summarize VEX_FILE	Summarize local VEX/CSAF vulnerability status evidence
intake SBOM_FILE	Evaluate supplier SBOM evidence readiness against a local TOML policy
attest SBOM_FILE	Parse SBOM and batch-attest all SHA-256 component hashes
verify SBOM_FILE	Verify SBOM hashes against the CertiSigma registry
summary SBOM_FILE	Inspect SBOM structure, component count, hash coverage

census sbom validate options:

Option	Description
--format auto|spdx|cyclonedx	Force SBOM format (auto-detected by default)
--profile cra-minimal|bsi|enterprise	Select evidence-readiness profile
--report-format text|json|sarif	Output format
--output PATH	Save validation report to a file
--exit-zero	Always exit 0 after producing a report
--json	Shorthand for --report-format json

census sbom diff options:

Option	Description
--format auto|spdx|cyclonedx	Force SBOM format for both inputs
--report-format text|json|sarif	Output format
--output PATH	Save diff report to a file
--exit-zero	Always exit 0 after producing a report
--json	Shorthand for --report-format json

census sbom bundle options:

Option	Description
--format auto|spdx|cyclonedx	Force format
--output PATH	Output ZIP path
--validation-report PATH	Include a local validation report
--diff-report PATH	Include a local diff report
--provenance PATH	Include local provenance evidence
--vulnerability-report PATH	Include a vulnerability evidence file without interpreting it
--component-attestations PATH	Include component-attestation evidence
--metadata KEY=VALUE	Add build metadata; repeatable
--include-sbom	Copy the original SBOM body into the bundle
--json	Machine-readable JSON output

census sbom pipeline init options:

Option	Description
--provider github-actions	Pipeline provider template
--generator syft|cyclonedx-py	External SBOM generator family to reference
--profile cra-minimal|bsi|enterprise	Validation profile used in CI
--output PATH	Workflow file to write
--sbom-path PATH	SBOM path used inside the workflow
--baseline-sbom PATH	Add an sbom diff step against a baseline SBOM
--bundle-output PATH	Evidence bundle path used inside the workflow
--census-version VERSION	Optional certisigma-census package version pin
--attest	Add attestation using CERTISIGMA_API_KEY in CI secrets
--no-upload-sarif	Omit SARIF upload steps
--no-upload-artifact	Omit evidence-bundle artifact upload
--force	Overwrite an existing workflow file
--json	Machine-readable JSON output

census sbom vuln cache options:

Option	Description
--feed PATH	Explicit local feed file to ingest
--source osv|nvd|ghsa|kev|epss|census	Feed source format
--cache-dir PATH	Local cache directory
--json	Machine-readable JSON output

census sbom vuln match options:

Option	Description
--format auto|spdx|cyclonedx	Force SBOM format
--cache-dir PATH	Local vulnerability cache directory
--vex PATH	Apply local VEX/CSAF status evidence; repeatable
--report-format text|json|sarif	Output format
--output PATH	Save vulnerability evidence report
--exit-zero	Always exit 0 after producing a report
--json	Shorthand for --report-format json

census sbom vex summarize options:

Option	Description
--report-format text|json	Output format
--output PATH	Save VEX/CSAF summary
--json	Shorthand for --report-format json

census sbom intake options:

Option	Description
--format auto|spdx|cyclonedx	Force SBOM format
--policy PATH	Supplier intake TOML policy
--vulnerability-report PATH	Local Census vulnerability evidence report
--vex PATH	Include local VEX/CSAF evidence; repeatable
--report-format text|json	Output format
--output PATH	Save supplier intake report
--exit-zero	Always exit 0 after producing a report
--json	Shorthand for --report-format json

census sbom attest options:

Option	Description
--format auto|spdx|cyclonedx	Force format (auto-detected by default)
--source LABEL	Source label for attestations
--manifest PATH	Save attested hashes to this manifest
--dry-run	Parse only, do not call the API
--attest-document	Also attest the exact SBOM document SHA-256
--json	Machine-readable JSON output

census sbom verify options:

Option	Description
--format auto|spdx|cyclonedx	Force format
--detailed	Include attestation level, source, timestamps
--exit-zero	Always exit 0 (report-only, for CI)
--json	Machine-readable JSON output

census sbom summary options:

Option	Description
--format auto|spdx|cyclonedx	Force format
--json	Machine-readable JSON output

Supports SPDX 2.2/2.3 JSON, SPDX 3.0.1 JSON-LD and CycloneDX 1.4/1.5/1.6 JSON. File size limit: 100 MB. sbom validate, sbom diff, sbom bundle, sbom pipeline init, sbom vuln, sbom vex summarize and sbom intake are local-only and do not upload the SBOM body, PURLs, supplier names, license inventory, dependency graph, vulnerability findings or VEX/CSAF statements. sbom bundle excludes the original SBOM body unless --include-sbom is explicit. sbom attest --attest-document sends only the exact document SHA-256 digest.

census provenance

Subcommand	Description
generate MANIFEST	Generate SLSA v1.0 provenance statement
verify PROVENANCE	Verify provenance subjects against CertiSigma registry

census provenance generate options:

Option	Description
--source TEXT	Source label for the scan
--commit TEXT	Git commit SHA
--builder-id TEXT	Builder identity URI
--sbom PATH	Link SBOM components as resolvedDependencies
--output PATH	Output file
--format json|intoto-jsonl	Output format (default: json)
--embed-materials	Include individual file digests
--attest	Attest provenance hash via CertiSigma API
--json	Machine-readable JSON output

census provenance verify options:

Option	Description
--strict	Exit 1 if any subject is unverified
--json	Machine-readable JSON output

Generates in-toto Statement v1 with SLSA v1.0 predicate. Auto-detects GitHub Actions, GitLab CI, Jenkins.

census compliance-report

Option	Description
MANIFEST_PATH	Manifest to analyze
-o/--output PATH	Output file (.html or .json). Default: stdout
--template nis2|dora|iso27001	Compliance framework (default: nis2)
--integrity/--no-integrity	Include integrity check results
--json	Machine-readable JSON output

Maps Census data to regulatory requirements. 100% local — no API calls.

census ai-policy

Subcommand	Description
init	Generate a default .census-ai-policy.toml template
apply MANIFEST	Classify manifest entries and tag attestations
report MANIFEST	Generate an AI governance compliance report (HTML/JSON)

census ai-policy apply options:

Option	Description
-p/--policy PATH	Path to the TOML policy file (default: .census-ai-policy.toml)
--dry-run	Classify only, do not tag
--json	JSON output
--api-key KEY	CertiSigma API key

census ai-policy report options:

Option	Description
-p/--policy PATH	Path to the TOML policy file
-o/--output PATH	Save report to file (HTML or JSON based on extension)
--json	JSON output to stdout

Exit Codes

Code	Context	Meaning
0	All commands	Success (or --exit-zero report-only mode)
1	All commands	General error (API, I/O, config, or matches found)
2	All commands	Usage error (invalid arguments — Click handles this)
1	integrity --strict	Violations detected (missing, modified, or new files)
bitmask	diff	1=added, 2=removed, 4=modified (OR'd together)
0	compare --exit-zero	Always 0, even if matches found (for CI)

Manifest Encryption at Rest

Census can encrypt manifests on disk using AES-256-GCM:

# Generate a key
census key-gen

# Scan with encryption — manifest is saved as .db.enc
census --encryption-key <hex64> scan /data --dry-run

# Load an encrypted manifest
census --encryption-key <hex64> status manifest.db

# Or use the environment variable (recommended for automation)
export CENSUS_ENCRYPTION_KEY=<hex64>
census scan /data --dry-run
census status manifest.db

Key resolution precedence: --encryption-key > CENSUS_ENCRYPTION_KEY env > config file encryption_key.

Encrypted manifests are auto-detected by their CENSUS_ENC\x01 header. census doctor reports encryption status.

Man Pages

Man pages are included in the source repository under docs/man/ but are not installed automatically by pip. To use them:

# Option 1: read directly from the source tree
man docs/man/census.1

# Option 2: install system-wide (requires root)
sudo install -m 644 docs/man/*.1 /usr/local/share/man/man1/

# Regenerate after adding new commands
./scripts/generate-man-pages.sh

For quick CLI help without man pages, use census --help or census <command> --help.

Dependencies

• certisigma — Official CertiSigma Python SDK
• click — CLI framework

Optional:

• watchdog — Filesystem monitoring (only for census watch)
• fpdf2 — PDF report generation (only for census report with .pdf output)

Testing

pip install -e ".[dev]"

# Unit tests (1100+ tests, ~25s)
pytest --tb=short -q

# With coverage report
pytest --cov --cov-report=html

# Integration tests (requires API key)
CERTISIGMA_API_KEY=<CERTISIGMA_API_KEY> pytest -m integration -v

# Performance benchmarks
python scripts/benchmark.py --files 1000 --output results.json

License

MIT — Ten Sigma Sagl