# 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

**Category:** Performance
**Priority:** Low (P4)
**Deferred since:** v0.2.0

### Description

For very large directories (>100K files), SHA-256 hashing is CPU-bound. Using `multiprocessing.Pool` to parallelize hashing across cores could reduce scan time by Nx where N is the core count.

### Why deferred

- For typical Census use cases (<50K files), single-threaded hashing with streamed I/O is fast enough.
- Multiprocessing adds complexity: manifest writes from multiple processes, progress bar synchronization, error handling across workers.
- Disk I/O is often the bottleneck, not CPU — parallelism helps less than expected on spinning disks.

### Re-evaluate when

- Backend implements §10 (Bulk Endpoints) — large-scale ingestion becomes a first-class workflow
- A customer reports scan times >30 minutes as a blocker
- Census adds a benchmark suite for profiling

---

**Author:** Ten Sigma Sagl
