certisigma-census 0.2.1

Cryptographic file inventory and exfiltration detection — powered by CertiSigma

CertiSigma Census

Cryptographic file inventory and exfiltration detection — powered by CertiSigma.

Census scans directories, computes SHA-256 hashes, attests them via the CertiSigma API (three-layer cryptographic proof: ECDSA T0, qualified TSA T1, Bitcoin T2), and maintains a local manifest. When suspect files surface, Census compares their hashes against the registry to prove — with cryptographic certainty — whether they match inventoried assets.

Installation

pip install certisigma-census

Requires Python 3.10+.

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.json --resume

This produces a .census-manifest.json mapping each hash to its file path, size, and attestation metadata.

2. Breach comparison

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

# 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.json

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

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

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
Atomic saves	Manifest writes via tmp+rename prevent corruption	manifest.md

Full documentation: docs/features/

CLI Reference

Global options

Option	Description
-v / --verbose	Enable debug logging
--log-format text|json	Log output format (default: text)
--version	Show version

census scan

Option	Description
--source LABEL	Source label for attestations
--manifest PATH	Manifest output path (default: <dir>/.census-manifest.json)
--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)

census compare

Option	Description
--manifest PATH	Local manifest for cross-referencing
--output PATH	Save report (.json or .csv by extension)
--include/--exclude/--min-size/--max-size	Same filters as scan

census export

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

census status

Takes a manifest path as argument. No additional options.

Dependencies

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

No additional runtime dependencies. All features use Python stdlib (fnmatch, csv, json, logging).

License

MIT — Ten Sigma Sagl