# CertiSigma Census — Roadmap

**Version:** 0.2.1
**Date:** 2026-03-18
**Status:** Fase 2 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) | 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 (66 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 / Daemon (v0.3.0)

**Obiettivo:** Monitoraggio continuo filesystem con attestazione automatica.

| Feature | Dipendenza API/SDK | Status API | Status Census |
|---------|-------------------|------------|---------------|
| `census watch /path` (inotify/fsevents) | `attest()` | ✅ SDK v1.5.0 | 📋 Da fare |
| Debounce su modifiche rapide | Nessuna | N/A | 📋 Da fare |
| Aggiornamento incrementale manifest | Nessuna (locale) | N/A | 📋 Da fare |
| Systemd unit / launchd plist | Nessuna | N/A | 📋 Da fare |

**Stima:** 1-2 settimane.
**Dipendenze OS:** `watchdog` (Python, cross-platform inotify/fsevents/kqueue).

---

## Fase 4 — 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 5 — 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 | 📋 Da fare |

**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 6 — 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
