fatcousin forensics white paper
architecture, chain of custody, standards mapping, vendor-fidelity grading, and fixture replay design — written for investigators and counsel evaluating whether to trust browser-local output.
overview
fatcousin forensics is a catalog of browser-only analysis tools for digital incident response. each tool loads in the user's browser, reads files the investigator selects locally, and produces structured output — csv, json, timelines, hashes — without uploading those files to fatcousin or any third party.
the audience is investigators, in-house security teams, consultants, and counsel who need to triage exports quickly on a machine they control. it is not a managed IR service, not a SIEM, not a case management platform, and not a substitute for qualified legal advice.
outputs are aids to human judgment. they do not constitute expert conclusions, legal findings, or court-ready reports by themselves. every result requires verification against source material and your own methodology before use in litigation, regulatory filings, or executive decisions.
local-first architecture
processing happens entirely in the user's browser via JavaScript and Web Workers. when you open a tool and drop a file, the bytes stay on your device. fatcousin does not operate a backend that ingests evidence. there is no account, no session cookie that carries file content, and no API route that accepts uploads of user evidence.
you can verify this yourself. open DevTools → Network before running a tool. load an export and run analysis. you should see page assets and static resources only — not POST requests carrying your file. the VERIFY panel on proof and methodology pages monitors outbound requests after load and flags anything outside an allowlist (fonts, static assets, same-origin navigation).
heavy parsers (FFmpeg, ONNX, sql.js, large wasm bundles) load from the site's static origin or from Web Workers under /public/workers/. they still execute locally. the tradeoff: first load of a heavy tool can take seconds; subsequent runs use browser cache.
tool pages show a build SHA and manifest version in the footer when available. that lets you record which deployed build produced an output — important when comparing a run from today against a golden captured last month.
- no server-side processing of user files
- no evidence upload endpoint
- Web Workers for wasm/heavy libs — not server round-trips
- VERIFY panel + DevTools Network tab as independent checks
analysis-phase custody log model
investigators can attach tool runs to a case session stored in localStorage. a session records: tool slug, tool version, build SHA, timestamps, input filenames, SHA-256 hashes of inputs, optional SHA-256 hashes of outputs, structured engine findings (severity, type, detail, observables — Wave 17+), and free-text notes. input bytes are not stored by default — only hashes. investigators may opt in per run to embed input bytes in the session export.
exporting a session produces a .fc-case zip archive containing manifest.json, an append-only analysis-phase custody log (event list — not a per-event hash chain), optional Ed25519 signatures (signature.json), a manifest.sha256 sidecar, and embedded attachment bytes when the investigator chose to include them. corrections are new custody events, not edits to prior rows. the session manager also emits five client-side interop formats — universal csv, magnet axiom csv, stix 2.1 bundle, misp event json, and an autopsy 4.x ingest module — each carrying analysis-phase custody references back to the source .fc-case archive.
Ed25519 signing uses a key generated in the browser (Web Crypto). the private key never leaves the device. signing covers the custody log payload and the manifest bytes independently. verifiers can re-import the zip, run npm run forensics:verify-fc-case offline, and check manifest hash parity and signature validity — but signature proves integrity of what was exported, not that the underlying analysis was correct.
reproducibility: because engines are versioned and goldens are pinned in fixture packs, a third party can replay the same synthetic evidence through the same tool version and compare output hashes. live evidence will differ; the point is that the engine behavior is deterministic for a given version + input.
- .fc-case zip — manifest, custody log, optional signatures, optional embedded bytes
- SHA-256 of inputs and outputs captured by default
- structured findings[] on each run when engine output is available (Wave 17+)
- five interop exports from /forensics/sessions — csv, axiom, stix 2.1, misp, autopsy module
- tool version + build SHA stamped at capture time
- Ed25519 optional — device-local key, not a notary service
- offline verification — npm run forensics:verify-fc-case
sessions workbench · how to verify exports · examiner workflow · validation methodology · export formats · how to cite sessions
standards alignment
fatcousin does not claim certification under SWGDE, NIST, ISO, ACPO, or Daubert. the table below states what the architecture supports today, what is in progress, and what remains planned. see /forensics/standards for the full mapping and primary-source links.
- SWGDE digital evidence handling — satisfies: local examiner control, hash capture, exportable audit log. in progress: formal examiner workflow documentation. planned: third-party methodology review.
- NIST SP 800-86 — satisfies: collection without central ingestion, integrity hashing, reproducible tool behavior on fixtures. in progress: mapping each case-type playbook to 800-86 phases. planned: CFTT formal submission for flagship tools.
- ISO/IEC 27037 — satisfies: traceable handling steps in session custody log, no covert exfiltration path. in progress: explicit acquisition-procedure templates per case type. planned: ISO-oriented acquisition checklist export.
- ACPO Principle 3 (integrity) — satisfies: hash-before-analysis pattern in methodology guides, manifest sidecar on .fc-case export. in progress: signed-export UX hardening. planned: none beyond current architecture.
- RFC 3227 (evidence collection) — satisfies: ordering guidance in methodology (preserve before analyze), timestamp capture in sessions. in progress: RFC-aligned acquisition timestamps in panic-export PDF. planned: automated chain-of-custody PDF from sessions.
- Daubert / reliability factors — satisfies: published goldens, open fixture packs, versioned engines, known limitations on /forensics/scope, stix 2.1 bundle export with custody-log sha256 (`x_fatcousin_coc_hash`) and fixture-replay traceability for factor 3 (known error rate). in progress: formal error-rate publication per tool category. planned: independent replay attestations for flagship scenarios.
vendor-fidelity methodology
most forensic tools in the catalog parse vendor-specific exports — Okta system logs, M365 unified audit, WhatsApp databases, payroll CSV shapes, etc. each available tool can carry a vendor-fidelity.audit.json file describing how faithfully the engine maps vendor fields.
verdicts: faithful — engine parses the documented vendor schema fields with typed mapping; partial — core fields parse but long-tail vendor columns are best-effort; template-misfit — engine uses a generic EDR/log template and does not match the vendor schema (output may still be useful for triage but must not be treated as vendor-complete).
audits are machine-readable and regenerated in CI. the full ledger — every tool, verdict, recognized/missing field counts, recommended action, and case-type associations — is public at /forensics/vendor-fidelity/dataset as a downloadable CSV. we publish incomplete parsers because hiding them would be less honest.
start-here tools on case-type pages are ordered editorially. all 52 start-here parsers are faithful as of wave 15 (waves 11–15 depth pillar). the fleet long-tail still includes partial and template-misfit parsers — published honestly in the public dataset. a template-misfit tool in primary position shows a quiet fidelity footnote on the tool page.
- faithful / partial / template-misfit — three verdicts, public ledger
- start-here faithful: 52/52 case-type primary parsers (waves 11–15)
- full catalog ledger downloadable as csv — count drifts with ship velocity
- regenerate csv: npm run forensics:export-vendor-fidelity-dataset
fixture pack design
a fixture pack is a synthetic, replayable investigation: evidence files, a SHA-256 manifest, expected golden outputs per primary engine, and a proof page at /forensics/proof/<slug>. packs are fictional — inspired by real incident classes, not copies of live breaches. no real PII, no live IOCs.
there are 55 reference investigations (count from PROOF_SCENARIO_SLUGS — verify on /forensics/proof). each pack includes a deterministic build script (scripts/fixtures/build-<slug>.mjs or colocated generate.ts) seeded with a public string so anyone can regenerate byte-identical evidence.
goldens are committed JSON files under expected/*.golden.json. CI runs npm run check:flagship — it replays each golden through the fixture runner and compares output. if an engine changes intentionally, maintainers regenerate goldens with the capture script documented in the pack README.
flagship replays (e.g. ridgeline-transfer-exfil for MFT/exfil, cascade-idp-breach for IdP compromise) demonstrate end-to-end binder generation: load synthetic zip → run primary engines locally → assemble html case binder → zero upload.
- evidence/ + MANIFEST.sha256 + expected/*.golden.json
- npm run check:flagship — golden parity gate in CI
- proof page + TrustVerifyPanel + download evidence/goldens zips via API routes
all proof scenarios · ridgeline-transfer-exfil (MFT/exfil flagship) · cascade-idp-breach (IdP compromise flagship)
export formats and interoperability
the session manager (/forensics/sessions) emits five interop formats in addition to the native .fc-case archive. every format is generated client-side from the session manifest — no server, no upload. each carries chain-of-custody references so a downstream tool can trace any indicator back to the exact .fc-case archive that produced it.
the formats span the dfir / siem / threat-intel stack. universal csv is the works-everywhere fallback. magnet axiom + autopsy cover the credentialed-examiner platforms. stix 2.1 + misp cover enterprise siem (splunk es, sentinel, qradar, elastic, opencti) and threat-intel sharing.
the privacy promise is preserved: clicking any export button generates the file in your browser and downloads it locally. the export logic lives in lib/forensics/exports/ and never makes a network request with your session data. the autopsy module download is a static asset hosted by fatcousin.com (no session bytes transmitted).
daubert factor 3 (known or potential error rate) is addressed in every export by the chain-of-custody references. a stix bundle or misp event can always be traced back to a specific .fc-case archive, which can be replayed against the published goldens at /forensics/proof to verify deterministic engine behavior.
- universal csv (lib/forensics/exports/universalCsvExport.ts) — fatcousin-<id>-findings.csv — encase, x-ways, excel, siem
- magnet axiom csv (lib/forensics/exports/axiomExport.ts) — fatcousin-<id>-axiom.csv — via magnet ucag → axiom process custom artifact
- stix 2.1 bundle (lib/forensics/exports/stix21Export.ts) — fatcousin-<id>-stix21.json — splunk es, sentinel, qradar, elastic siem, opencti, axiom cyber. includes cisa core incident extension
- misp event (lib/forensics/exports/mispExport.ts) — fatcousin-<id>-misp.json — misp threat sharing platform. to_ids: false on every attribute (forensic triage, not active blocking intel)
- autopsy ingest module (docs/autopsy/fatcousin_import_module.py) — installs into autopsy 4.x python scripts dir; ingests .fc-case archives as TSK_INTERESTING_FILE_HIT artifacts
- structured findings — when a run is captured, engine output (severity, finding type/reason code, detail, extracted observables) is stored on `SessionRun.findings[]` in the .fc-case manifest. interop exports prefer this data; legacy archives without findings fall back to note-keyword severity and regex IOC extraction.
limitations and scope
browser memory and wasm limits cap file sizes — multi-gigabyte disk images and full mobile filesystem extractions are out of scope. tools document practical limits in their UI; exceeding them yields slow tabs or OOM, not silent truncation.
template-misfit and partial parsers remain in the catalog for triage velocity. they must not be cited as vendor-complete without reading the fidelity verdict.
local-first means no central case repository — if the investigator clears browser storage without exporting .fc-case, session data is gone. embedded input bytes survive export/re-import only; hash-only runs persist across reloads but cannot reconstruct bytes.
fatcousin does not provide 24/7 incident response, wire fraud recovery, victim advocacy, or legal representation. /forensics/help routes victims to crisis resources but is not a hotline.
for the exhaustive honest limits list — what we do not do, what outputs cannot prove, jurisdiction caveats — read /forensics/scope. that page is the binding scope statement; this white paper summarizes architecture and intent.