# CertiSigma Census — Roadmap

**Version:** 0.6.0
**Date:** 2026-03-19
**Status:** Phase 5 completata

---

## Visione

Census è un prodotto applicativo che utilizza l'infrastruttura CertiSigma (API + SDK) per il censimento crittografico di asset informativi, il rilevamento di esfiltrazioni e la cooperazione selettiva con soggetti terzi (analisti forensi, operatori threat intelligence).

Census è un **client** dell'API, non un'estensione del backend. Il valore di Census non si esaurisce nell'attestare l'esistenza di un contenuto: rende quel contenuto classificabile e operativamente verificabile da terzi senza trasferirne il dato né il significato.

**Documento di riferimento:** `/opt/app-certisigma/docs/commercial/CERTISIGMA-CENSUS-v2.md`

---

## Fase 1 — CLI Core (v0.1.0)

**Obiettivo:** Tool a linea di comando funzionante per scan, attest e compare.

| Feature | Dipendenza API/SDK | Status API | Status Census |
|---------|-------------------|------------|---------------|
| Scan directory + SHA-256 | `hash_file()` | ✅ SDK v1.5.0 | ✅ Implementato |
| Manifest locale (JSON→SQLite v2) | Nessuna (locale) | N/A | ✅ Implementato |
| Batch attest (100/call) | `POST /attest/batch` | ✅ API operativo | ✅ Implementato |
| Batch verify (100/call) | `POST /verify/batch` | ✅ API operativo | ✅ Implementato |
| Source label | campo `source` | ✅ API operativo | ✅ Implementato |
| Dry run mode | Nessuna | N/A | ✅ Implementato |
| Compare report (JSON) | `batch_verify()` | ✅ SDK v1.5.0 | ✅ Implementato |
| Manifest status | Nessuna (locale) | N/A | ✅ Implementato |
| CLI via `click` | Nessuna | N/A | ✅ Implementato |

**Stima:** Pronto per test e raffinamento.

---

## Fase 2 — Produzione e robustezza (v0.2.1)

**Obiettivo:** Hardening per uso enterprise reale.

| Feature | Dipendenza API/SDK | Status API | Status Census |
|---------|-------------------|------------|---------------|
| Ripresa scansione interrotta (`--resume`) | Nessuna (locale) | N/A | ✅ Implementato |
| Retry con backoff su 429/5xx | `RateLimitError`, `Retry-After` | ✅ SDK v1.5.0 | ✅ Implementato |
| Progress bar (file grandi) | Nessuna | N/A | ✅ Implementato |
| Filtri per estensione/dimensione | Nessuna (locale) | N/A | ✅ Implementato |
| Esclusione pattern (glob) | Nessuna (locale) | N/A | ✅ Implementato |
| Report CSV export | Nessuna (locale) | N/A | ✅ Implementato |
| Logging strutturato (JSON) | Nessuna | N/A | ✅ Implementato |
| Test suite + CI (106 test + 17 markers) | Nessuna | N/A | ✅ Implementato |
| Documentazione features (`docs/features/`) | Nessuna | N/A | ✅ Implementato |
| Pubblicazione PyPI | Nessuna | N/A | ✅ Implementato |

**Completata** il 2026-03-18.

---

## Fase 3 — Watch mode + SQLite manifest (v0.3.0)

**Obiettivo:** Monitoraggio continuo filesystem, manifest scalabile, attestazione automatica.

| Feature | Dipendenza API/SDK | Status API | Status Census |
|---------|-------------------|------------|---------------|
| Manifest SQLite (WAL, schema v2) | Nessuna (locale) | N/A | ✅ Implementato |
| Migrazione automatica JSON→SQLite | Nessuna (locale) | N/A | ✅ Implementato |
| `census watch /path` (inotify/fsevents) | `attest()` | ✅ SDK v1.5.0 | ✅ Implementato |
| Debounce su modifiche rapide | Nessuna | N/A | ✅ Implementato |
| Aggiornamento incrementale manifest | Nessuna (locale) | N/A | ✅ Implementato |
| Per-event handling (CREATE/MODIFY/MOVE/DELETE) | Nessuna | N/A | ✅ Implementato |
| Baseline scan on start | Nessuna | N/A | ✅ Implementato |
| PollingObserver per NFS/CIFS | Nessuna | N/A | ✅ Implementato |
| Rilevamento limite inotify | Nessuna | N/A | ✅ Implementato |
| Shutdown graceful (SIGINT/SIGTERM) | Nessuna | N/A | ✅ Implementato |
| Prevenzione symlink escape | Nessuna | N/A | ✅ Implementato |
| Delete policies (ignore/mark/remove) | Nessuna | N/A | ✅ Implementato |
| Template systemd / launchd | Nessuna | N/A | ✅ Documentato |

**Completata** il 2026-03-19.
**Dipendenze:** `watchdog>=4.0.0` (opzionale, `pip install certisigma-census[watch]`).

**Debito tecnico correlato:** vedi `docs/TECHNICAL-DEBT.md` per eBPF (TD-001) e auditd/who-data (TD-002).

---

## Phase 3.5 — Forensic Evidence Pipeline (v0.4.0)

**Obiettivo:** Verifica hash, integrity check e reportistica forense.

| Feature | Dipendenza API/SDK | Status API | Status Census |
|---------|-------------------|------------|---------------|
| `census verify <hash>` (T0/T1/T2 chain) | `verify()`, `get_evidence()` | ✅ API operativo | ✅ Implementato |
| `census verify --file` (hash then verify) | `hash_file()` + `verify()` | ✅ SDK v1.5.0 | ✅ Implementato |
| `census verify --save-ots` (OTS export) | `save_ots_proof()` | ✅ SDK v1.5.0 | ✅ Implementato |
| `census integrity manifest.db` | Nessuna (locale) | N/A | ✅ Implementato |
| `census integrity --strict` (exit code 1) | Nessuna (locale) | N/A | ✅ Implementato |
| Report HTML (zero deps) | Nessuna | N/A | ✅ Implementato |
| Report PDF (fpdf2) | `fpdf2>=2.8.0` (opzionale) | N/A | ✅ Implementato |
| Evidence bundle (ZIP + OTS + SHA256SUMS) | `save_ots_proof()` | ✅ SDK v1.5.0 | ✅ Implementato |
| XSS prevention in HTML | Nessuna | N/A | ✅ Implementato |
| Path traversal prevention in ZIP | Nessuna | N/A | ✅ Implementato |
| Test suite (149 test + 17 markers) | Nessuna | N/A | ✅ Implementato |

**Completata** il 2026-03-18.
**Dipendenze:** `fpdf2>=2.8.0` (opzionale, `pip install certisigma-census[report]`).

---

## Phase 4 — Forensic Diff and CLI Maturity (v0.5.0)

**Obiettivo:** Manifest diffing, standalone hashing, attestation tracking, config file, shell completions.

| Feature | Dipendenza API/SDK | Status API | Status Census |
|---------|-------------------|------------|---------------|
| `census diff m1.db m2.db` (manifest comparison) | Nessuna (locale) | N/A | ✅ Implementato |
| Diff HTML report (color-coded added/removed/modified) | Nessuna (locale) | N/A | ✅ Implementato |
| Diff bitmask exit codes (AIDE-style: 1=added, 2=removed, 4=modified) | Nessuna | N/A | ✅ Implementato |
| `census hash <file\|dir>` (standalone SHA-256) | `hash_file()` | ✅ SDK v1.5.0 | ✅ Implementato |
| `census hash --verify <hash>` (hash and compare) | `hash_file()` | ✅ SDK v1.5.0 | ✅ Implementato |
| `census track <att_id>` (attestation status) | `client.status()` | ✅ API operativo | ✅ Implementato |
| `census track --poll` (wait for T2 anchoring) | `client.status()` | ✅ API operativo | ✅ Implementato |
| Config file (TOML) con precedenza CLI > env > project > user | Nessuna | N/A | ✅ Implementato |
| `census config show\|init\|paths` | Nessuna | N/A | ✅ Implementato |
| `census completion bash\|zsh\|fish` (shell completions) | Click built-in | N/A | ✅ Implementato |

**Completata** il 2026-03-19.
**Dipendenze:** `tomli>=2.0; python_version < "3.11"` (per config TOML su Python 3.10).

---

## Phase 5 — Enterprise Readiness (v0.6.0)

**Obiettivo:** Self-diagnostics, distributed workflows, e automation-ready JSON output per tutti i comandi.

| Feature | Dipendenza API/SDK | Status API | Status Census |
|---------|-------------------|------------|---------------|
| `census doctor` (connectivity, config, inotify, deps) | `client.health()` | ✅ SDK v1.5.0 | ✅ Implementato |
| `census merge m1.db m2.db -o out.db` (merge manifests) | Nessuna (locale) | N/A | ✅ Implementato |
| `census scan --json` (structured output) | Nessuna | N/A | ✅ Implementato |
| `census compare --json` (structured output) | Nessuna | N/A | ✅ Implementato |
| `census status --json` (structured output) | Nessuna | N/A | ✅ Implementato |

**Completata** il 2026-03-19.
**Dipendenze:** Nessuna.

---

## Fase 6 — Bulk scale (v1.0.0)

**Obiettivo:** Inventari enterprise (>10K file) con performance ottimali.

| Feature | Dipendenza API/SDK | Status API | Status Census |
|---------|-------------------|------------|---------------|
| Bulk attest (10K/call) | `POST /attest/bulk` | ❌ Pianificato (§10 Tech Debt) | 🔒 Bloccato |
| Bulk verify/scan (50K) | `POST /verify/bulk`, `/scan` | ❌ Pianificato (§10 Tech Debt) | 🔒 Bloccato |
| Parallelismo scan (multiprocessing) | Nessuna | N/A | 📋 Da fare |
| Manifest compresso (gzip) | Nessuna (locale) | N/A | 📋 Da fare |

**Stima:** 2-3 settimane (Census) + tempo backend per endpoint bulk.
**Bloccante:** Richiede implementazione endpoint bulk lato API (§10 TECHNICAL-DEBT.md).

---

## Fase 7 — Classificazione e cooperazione selettiva (v1.1)

**Obiettivo:** Tagging strutturato e derived lists per cooperazione forense con soggetti terzi.

| Feature | Dipendenza API/SDK | Status API | Status Census |
|---------|-------------------|------------|---------------|
| Tagging strutturato (`--tag key=value`) | `PATCH /attestation/{id}/metadata` §32 | ❌ Pianificato | 🔒 Bloccato |
| Filtraggio per tag (query manifest) | §32 | ❌ Pianificato | 🔒 Bloccato |
| `census list create` (derived list) | `POST /census/list` §33 | ❌ Pianificato | 🔒 Bloccato |
| `census list verify` (match terzi) | `POST /census/list/{id}/match` §33 | ❌ Pianificato | 🔒 Bloccato |
| Report PDF forense | Nessuna (locale) | N/A | ✅ Implementato (v0.4.0) |

**Bloccante:** Richiede implementazione §32 (Structured Tagging) e §33 (Derived Lists) lato API.

**Protocollo Derived Lists (da §33):**
1. Organizzazione seleziona sottoinsieme di hash (in futuro per tag).
2. Server genera `list_key` casuale (32 byte).
3. Per ogni hash H: `derived_H = HMAC-SHA256(H, list_key)`.
4. CertiSigma firma l'insieme derivato con chiave ECDSA.
5. Il terzo riceve `list_key` + URL → può verificare match ma non enumerare gli hash originali.

**Stima:** 2-3 settimane Census + tempo backend per §32/§33.

---

## Fase 8 — Integrazioni (v2.x)

**Obiettivo:** Canali di distribuzione, integrazioni e casi d'uso avanzati.

| Feature | Dipendenza | Priorità | Note |
|---------|-----------|----------|------|
| Nextcloud app | Plugin PHP/app esterna | P3 | Solo se mercato PMI lo richiede |
| GUI desktop (Tauri/Electron) | Census CLI come backend | P3 | Versione consumer, settimane di lavoro |
| Webhook su match trovato | Webhook API | ✅ Già disponibile | Census come consumer di webhook |
| AI governance: allow/deny lists | §32 + §33 | P2 | Tag `ai_training=allowed/excluded`, derived lists per dataset AI |
| RBAC scoped keys | §31 | P3 | API key read-only per analisti terzi con audit trail |

---

## Feature API/Backend da cui Census dipenderà in futuro

Le seguenti feature backend impattano (o impatteranno) Census:

| Feature backend | §Tech Debt | Status | Priorità | Impatto su Census |
|----------------|-----------|--------|----------|-------------------|
| **Request/Correlation IDs** | §29 | ✅ Implementato | — | Trasparente via SDK, nessun codice Census da toccare |
| **Key rotation automatica** | Esistente | ✅ Implementato | — | Trasparente via SDK |
| **Endpoint bulk (10K+)** | §10 | ❌ Pianificato | P3 (P1 per Census) | Abilita inventari enterprise su larga scala |
| **Forensic metadata sharing** | §30 | ❌ Pianificato | P2 | Condivisione prove con analisti terzi senza accesso all'account |
| **RBAC / Scoped read-only keys** | §31 | ❌ Pianificato | P3 | API key per analisti con audit trail |
| **Structured Tagging** | §32 | ❌ Pianificato | P2 | Classificazione multilivello per hash (prerequisito per §33) |
| **Derived Lists (HMAC)** | §33 | ❌ Pianificato | P2 | Cooperazione selettiva: verifica senza rivelare inventario |

**Catena di dipendenze per le feature future:**

```
Backend §32 (Structured Tagging, ~15h) → SDK update → Census: --tag key=value
        ↓
Backend §33 (Derived Lists, ~18h) → SDK update → Census: census list create/verify
```

Census è sempre downstream: consuma l'SDK pubblicato, non anticipa API inesistenti.

---

## Readiness checklist (cosa fare quando arrivano le API)

Test-marcatori in `tests/test_future.py` (skippati, visibili con `pytest -rs`).

### Quando arriva §32 (Structured Tagging)
- [ ] Rimuovere skip da `TestStructuredTagging`
- [ ] Aggiungere `tags: dict[str, str]` a `ManifestEntry`
- [ ] Aggiungere `--tag key=value` (ripetibile) al comando `scan`
- [ ] Aggiungere `--filter key=value` al comando `status`
- [ ] Supporto cifratura client-side per tag values (via SDK crypto)
- [ ] Aggiornare manifest JSON schema (v2) con campo `tags`
- [ ] Test: round-trip save/load con tags

### Quando arriva §33 (Derived Lists)
- [ ] Rimuovere skip da `TestDerivedLists`
- [ ] Nuovo comando `census list create --manifest m.json [--filter key=value] --label <name>`
- [ ] Nuovo comando `census list verify --list-id <uuid> --list-key <hex> /suspect/dir`
- [ ] Validare `derived_H = HMAC-SHA256(H, list_key)` contro test vector noti
- [ ] Gestire scadenza e revoca liste (errore user-friendly)
- [ ] Documentare il protocollo nel README

### Quando arriva §10 (Bulk Endpoints)
- [ ] Rimuovere skip da `TestBulkScale`
- [ ] Rilevare se SDK espone `bulk_attest()` / `bulk_verify()`
- [ ] Usare bulk per default, fallback a batch 100 se non disponibile
- [ ] Aggiornare progress bar per bulk (singola barra, non per-batch)

### Quando arriva §30 (Forensic Sharing)
- [ ] Rimuovere skip da `TestForensicSharing`
- [ ] Nuovo comando `census share --attestation <id> [--expires <duration>]`
- [ ] Documentare workflow di condivisione nel README

---

## Principi architetturali

1. **Census è un client, non un'estensione del backend.** Usa solo il SDK pubblicato (`pip install certisigma`). Zero dipendenze source-level dal backend.
2. **Il contenuto non lascia mai il client.** Solo gli hash SHA-256 vengono trasmessi.
3. **Il manifest è locale.** La mappa hash→filepath vive sul filesystem del cliente. CertiSigma non la vede.
4. **Ogni feature API nuova che Census richiede va nel core**, perché è utile per tutti i clienti, non solo per Census.

---

**Author:** Ten Sigma Sagl
