# CertiSigma Census — Technical Debt

Items tracked here are improvements or integrations that have been considered and explicitly deferred. Each item includes rationale for deferral and trigger conditions for re-evaluation.

---

## TD-001: eBPF filesystem monitoring

**Category:** Performance / Observability
**Priority:** Low (P4)
**Deferred since:** v0.3.0

### Description

eBPF (extended Berkeley Packet Filter) can intercept filesystem syscalls (`open`, `write`, `rename`, `unlink`) at the kernel level with near-zero overhead. Tools like `bpftrace` and `libbpf` enable real-time monitoring without the inotify watch limit.

### Why deferred

- Requires Linux kernel >= 4.14 (2017), which covers all modern distributions. However, eBPF is a Linux-only technology — it doesn't work on macOS or Windows.
- Requires `CAP_BPF` or root privileges, which narrows the deployment audience.
- `watchdog` + inotify already provides sub-second event delivery on Linux, which is sufficient for Census use cases.
- eBPF integration adds a C/Rust build dependency (libbpf or bcc), breaking the pure-Python packaging model.

### Re-evaluate when

- Census is deployed in environments with >500K watched files (inotify limit becomes a real constraint)
- A mature, maintained Python-native eBPF library emerges (e.g., `pybpf`)
- A customer requires kernel-level audit guarantees for compliance

---

## TD-002: who-data / auditd integration

**Category:** Forensics / Attribution
**Priority:** Medium (P3)
**Deferred since:** v0.3.0

### Description

Linux `auditd` (via Wazuh's `who-data` integration) tracks which **user and process** performed each filesystem operation. This enriches Census events with:
- `uid` / `username` of the actor
- `pid` / `process_name` of the modifying process
- `auid` (audit UID) for tracking across `su`/`sudo`

This is how enterprise FIM tools like Wazuh and OSSEC attribute file changes to specific users.

### Why deferred

- Requires `auditd` running on the system and audit rules configured.
- Linux-only (macOS has Endpoint Security Framework, Windows has ETW — different APIs).
- Census currently treats "what changed" as sufficient for attestation; "who changed it" is an attribution concern outside the hash-and-attest model.
- Adding this changes Census from a pure hash-inventory tool to a partial HIDS (Host-based Intrusion Detection System), which is scope creep.

### Re-evaluate when

- Backend implements §30 (Forensic Metadata Sharing) — attribution data becomes shareable
- A customer needs compliance reporting with user attribution (SOX, PCI-DSS)
- Census adds a `census audit` command for forensic investigation workflows

---

## TD-003: Manifest encryption at rest

**Category:** Security
**Priority:** Medium (P3)
**Deferred since:** v0.3.0

### Description

The SQLite manifest stores file paths, sizes, and timestamps in plaintext. While hashes alone are insufficient to reconstruct content, the path metadata reveals organizational structure (e.g., `/hr/terminations/`, `/legal/mergers/`).

### Why deferred

- Adding encryption would require key management (where to store the key).
- SQLite doesn't natively support transparent encryption; solutions like SQLCipher add a C dependency.
- The manifest is intended for local use only. If an attacker has access to the local filesystem, they already have access to the files themselves.
- The CertiSigma SDK's crypto module could be leveraged for envelope encryption, but this adds complexity with unclear benefit.

### Re-evaluate when

- Census is deployed on shared or networked filesystems
- A customer requires manifest encryption for compliance
- The SDK adds transparent envelope encryption support

---

## TD-004: Multiprocessing for large scans — CLOSED

**Category:** Performance
**Priority:** Low (P4)
**Deferred since:** v0.2.0
**Resolved in:** v0.9.0 (Phase 8)

### Resolution

Parallel hashing via `ProcessPoolExecutor` with `--workers N` was implemented in Phase 8 (v0.9.0). Both `census scan` and `census compare` support multi-core hashing with TOCTOU-safe stat capture and graceful error handling per worker. This item is closed.

---

## TD-005: Public repository preparation

**Category:** DevOps / Compliance
**Priority:** Medium (P3)
**Deferred since:** v1.8.1

### Description

The Census GitHub repository is currently private. Before making it public, several hygiene steps are required:

- SECRET scanning: verify no API keys, encryption keys, or credentials in git history
- `LICENSE` file: confirm MIT license is present and correct
- `CONTRIBUTING.md`: contributor guidelines, DCO/CLA policy
- CI badge: add build/test status badge to README
- Git history cleanup: ensure no sensitive data in past commits

### Why deferred

- The repository is private and accessible only to maintainers
- The CertiSigma main repository is also private
- There is no immediate business need to go public

### Re-evaluate when

- A decision is made to open-source Census
- External contributors are onboarded
- The CertiSigma main repository goes public

---

## TD-006: Automated census.html deployment

**Category:** DevOps
**Priority:** Low (P4)
**Deferred since:** v1.8.1

### Description

`docs/census.html` is currently deployed manually to `developers.certisigma.ch/census` by writing directly to the CertiSigma developers site directory. A CI step should automate this on release.

### Why deferred

- Deployment frequency is low (only on feature releases, not patches)
- The manual process is documented and takes <2 minutes
- Automating cross-repository deployment adds CI complexity (secrets, SSH, deploy keys)

### Re-evaluate when

- Deploy frequency exceeds once per week
- A second maintainer is onboarded who needs deploy access
- The developers site moves to a dedicated CI pipeline

---

## TD-007: Distribution packaging

**Category:** DevOps / Adoption
**Priority:** Medium (P3)
**Deferred since:** v1.10.0

### Description

Census is installed via `pip install certisigma-census`. For enterprise Linux environments where `pip` is restricted, native packaging would reduce adoption friction:

- **Man pages** — generate `man census` and `man census-scan` from Click help text (via `click-man` or custom script)
- **`.deb` / `.rpm`** — native packages via `fpm` or `nfpm`, bundled with systemd templates already in `docs/templates/`
- **Docker image** — `certisigma/census:latest` for ephemeral scanning (`docker run -v /data:/data certisigma/census scan /data`). Not infrastructure — Census remains a CLI tool.

### Why deferred

- `pip` covers all current deployment scenarios
- Man pages and native packages require build infrastructure and maintenance per distribution
- Docker image adds a container registry dependency

### Re-evaluate when

- Enterprise customer requests `.deb`/`.rpm` for deployment via configuration management (Ansible, Puppet)
- Census reaches >100 installations and onboarding friction becomes measurable

---

## TD-008: Signed PDF forensic reports

**Category:** Forensics / Compliance
**Priority:** Medium (P2)
**Deferred since:** v1.10.0

### Description

Current `census report` generates HTML/PDF that summarize evidence. A signed PDF — where the CertiSigma API provides an ECDSA signature over the report hash — would prove "this report was generated from attested data at time T". This has legal evidentiary value in jurisdictions that accept digital signatures (eIDAS, ZertES).

### Why deferred

- Requires a new backend endpoint (`POST /sign-document` or similar) that doesn't exist yet
- PDF signing libraries (endesive, pyHanko) add significant dependencies
- The current evidence bundle (ZIP with OTS proofs) already provides cryptographic proof, though less user-friendly

### Re-evaluate when

- Backend implements document signing endpoint
- A customer requires court-admissible reports (not just compliance)
- EU AI Act enforcement creates demand for certified AI governance reports

---

## TD-009: Application integrations

**Category:** Product / Adoption
**Priority:** Medium (P3)
**Deferred since:** v1.10.0

### Description

- **Nextcloud/ownCloud app** — PHP/Python plugin that triggers `census scan` on file upload, exposing attestation status in the file browser. Target audience: Swiss/European SMEs using Nextcloud as primary file server.
- **Web dashboard** (`census serve --port 8080`) — read-only web UI that visualizes manifest stats, integrity status, and attestation timeline. Useful for SOC/NOC teams. Lightweight: Flask/FastAPI single-file, no SPA framework.

### Why deferred

- Nextcloud app requires PHP development or a sidecar daemon, different from Census's Python toolchain
- Web dashboard is scope creep from CLI tool to web application
- Both require ongoing UI maintenance unrelated to core cryptographic functionality

### Re-evaluate when

- Market feedback from Swiss PMI sector indicates Nextcloud adoption friction
- SOC/MSSP customer requests dashboard for multi-client monitoring
- Census reaches commercial traction that justifies UI investment

---

**Author:** Ten Sigma Sagl
