CONTEXT
The work started here.
A private, local-only investigation workflow was developed around a sensitive real case.
BUILD
What was built.
A local-only investigation pipeline built in five days to help a friend being stalked. It organizes open-source intelligence to evidence standards: provenance manifests on every finding, fail-closed network defaults, attribution scoring with negative controls. The output is a report a detective can act on. 140 commits, ~22,000 lines, 44% of it tests.
PROJECT DESIGN
How it was shaped.
The design document was audited against the actual tools it would orchestrate before any code existed. That audit found five build-breaking errors and three architectural defects, and every finding became an enforced rule, not a recommendation. Validation was the live case itself: the first real run happened four and a half hours after the first commit, and 24 runs over five days drove every redesign.
SECURITY & OPS
The operating decisions.
- Chain of custody as code: every tool run writes an append-only manifest — exact version, full command line, operator, UTC timestamps, output hash — and finished outputs are made OS-level immutable.
- Capabilities that could tip off a subject are dual-gated: the riskiest tool runs only if two settings flip, and the skip reason is recorded so the report shows why.
- Egress control is enforced per tool wrapper and fails closed: if the proxy is enabled but unconfigured, the pipeline refuses to connect rather than going direct.
- Breach-check passwords are HMAC-hashed on receipt with a per-case ephemeral key that never persists beyond the run.
- False attribution is engineered against: existence confidence and attribution strength are scored separately, with negative graph weights for mismatched evidence.
BUILDER NOTES
What the build taught.
- Every OSINT tool runs in its own isolated environment and the orchestrator only shells out to binaries — conflicting dependency pins were an audit finding, not a hypothetical.
- Stage-two runtime had a numeric SLO (under 15 minutes), hit by tuning to six scanner batches, 80 concurrent validators, and 25 avatar workers.
- Every wrapper logs command line, exit code, parse counts, and data freshness — silent tool failures were the postmortem's biggest finding.
- The design doc was audited against the actual tools it would orchestrate before any code was written; each finding became an enforced rule, catching five install-breaking errors early.
LESSONS
What changed afterward.
- “Confidence” has to mean attribution, not tool health. The first question is whether an account actually belongs to the subject, and conflating that with whether a tool ran cleanly flooded the early results with false positives — exactly what a report headed to law enforcement can't carry.
- Victim safety precedes investigation, structurally: the hardening playbook for the person at risk runs before any investigative stage can.
- Restraint can be architecture. Nothing behind a login is touched; instead the pipeline generates guidance on what law enforcement should subpoena. And anything that could tip off the subject is off by default, its use recorded in the case manifest, so the restraint is auditable.
- Wrapping an unmaintained open-source tool means becoming its maintainer: one tool needed six fixes in 36 hours.
THE GATE THAT HELD
Safety precedes investigation.
The hardening playbook runs before investigative stages, and activity that could alert a subject remains off by default and recorded when used.
CONTROL
The constraint that held.
Provenance manifests, fail-closed network defaults, negative controls, and no login-protected access constrain the workflow.
EVIDENCE
Where to inspect it next.
- Chain of custody as code: every tool run writes an append-only manifest — exact version, full command line, operator, UTC timestamps, output hash — and finished outputs are made OS-level immutable.
- Capabilities that could tip off a subject are dual-gated: the riskiest tool runs only if two settings flip, and the skip reason is recorded so the report shows why.
- Egress control is enforced per tool wrapper and fails closed: if the proxy is enabled but unconfigured, the pipeline refuses to connect rather than going direct.
- Breach-check passwords are HMAC-hashed on receipt with a per-case ephemeral key that never persists beyond the run.
- False attribution is engineered against: existence confidence and attribution strength are scored separately, with negative graph weights for mismatched evidence.
CARRIED FORWARD
What survived the project.
The audit-the-design-before-building gate, and the fail-closed posture that refuses rather than warns. The repository itself stays private, permanently: it holds a real case.
WRITING