# BUILD NOTES — Cyber Forensics Test Lab (unified)

## What was built and why

A new top-level SENTINEL component at
`/home/user/workspace/sentinel/forensics_lab_unified/` that ties the existing
modules into **one documented, working pipeline with a single dashboard**, plus
a **Cyber Caller ID & Blocker** screening gateway.

It is **standalone**: rather than importing the sibling `honeypot/` package
(whose `db.py` binds a different SQLite file and a honeypot-specific schema), the
proven logic was **adapted/copied** into this component so it runs on its own
`lab.db` with a single `pip install` + run command. This matches the brief's
"you may copy the needed logic into the new component so it runs standalone."

### Reuse map (source → adapted here)

| Reused from | Adapted into | Notes |
|-------------|--------------|-------|
| `honeypot/forensics_lab.py` | `forensics.py` | Non-executing static analysis (hashes, strings, verdict, indicative attribution). |
| `honeypot/fragment_catalog.py` | `forensics.py` (`file_signature`) | Growing signature/"cure" catalog + KNOWN/NEW signature check. |
| `honeypot/canary_token.py` | `vigilantguard.py` (`serve_bait`) | Watermarked + canary-tokenized bait; beacon URL points at our own lab. |
| `honeypot/quarantine.py` (glovebox concept) | `vigilantguard.py` (`contain`) | Artifact sealed as INERT base64, `executed=0` invariant. |
| `honeypot/evidence_report.py` | `pipeline.py` (`build_evidence_bundle`) | Chain-of-custody JSON+TXT+SHA-256; adds isolated GOVERNMENT stream. |
| `packet_layer/token_mint.py` | `tracker_mint.py` and `caller_id.py` | HMAC-SHA256 signed, tamper-evident JWS-style envelope; verify-back. |
| `ransom_trace/` ("trace not touch") | `tracker_mint.py` framing | Passive identifiers only; no funds/hosts touched. |

## Branding (founder-approved)

- **PhishBot 3.0** — the phishing / email + SMS + link **scanner** (`phishbot.py`).
  Shown in the dashboard header tag, the "Ingest a lure" card badge, and the
  case table column. Comments/docstrings name it explicitly.
- **VigilantGuard** — the **deception & isolation** grid (`vigilantguard.py`):
  simulated sandbox trap, decoy servers, watermarked/tokenized bait. Shown in
  the header tag and pipeline strip; named in the chain-of-custody steps.
- **Cyber Caller ID & Blocker** — the typed-token screening gateway
  (`caller_id.py`), its own dashboard card + call-log table.

## Cyber Caller ID & Blocker — design decisions

- **Typed tokens are structurally distinct** by a visible prefix (`PSN-` /
  `BIZ-` / `GOV-`) *and* a `typ` header claim. Even before signature checking,
  the type is visible, so a wrong-type token is caught immediately.
- **Verify-back** looks the claimed entity up in the SQLite `registry`, compares
  the presented type to the entity's **registered** type, and verifies the HMAC
  with the **entity's own secret**. A forged token (unknown secret) fails the
  signature check; a wrong-type token fails the type check. Both are breaches.
- **Severity mapping:** type mismatch or forged signature → `ACTIVE_BREACH`
  ("actively breaching"); unknown caller / other invalidity → `SUSPICIOUS`
  ("attempting breach"); no token → `INFO`/`SCREENED` ("left a message");
  released → `INFO`/`ALLOWED` ("passed through" / fast lane).
- **Sandbox-copy-first:** every inbound connection creates a sandbox row for a
  **copy** (torn apart statically) while the original is held. Even a valid
  token cannot release a hostile copy — that path returns `DENIED` /
  `ACTIVE_BREACH`.
- **Instant rotation on breach:** `screen_call` auto-calls `rotate_token`, which
  cycles the tenant's registered type (person→business→government→…) and mints a
  fresh secret, invalidating any stolen/forged token. Logged in `rotations`.
- **Reputation memory:** `rep_score` rises on allow, falls on deny; crossing the
  quarantine threshold auto-seals an offender marker via VigilantGuard
  containment. High rep gets a "fast lane" status (still sandboxed).
- **Export to evidence:** `export_call_to_evidence` synthesizes an inert lure
  from the call record and runs the standard `pipeline.run_artifact`, so a
  caller record flows through forensics → tracker → outbox and back-links the
  resulting case to the call-log row.

## Legal guardrails — how each is enforced in code

- **No hack-back / no external egress:** no module opens an outbound socket.
  PhishBot never fetches a scanned URL; it only rewrites it to a `127.0.0.1`
  beacon. The server binds `127.0.0.1` only.
- **Passive trackers:** `tracker_mint.py` produces a signed identifier with a
  `kind: "passive-trackback"` claim and an explicit no-action notice; it carries
  no payload and performs no action. `/beacon/<token>` only records.
- **No malware execution:** `vigilantguard.contain` stores bytes as base64 with
  `executed=0` (asserted by `verify_run.py`); `forensics` only reads bytes.
- **Collect & report:** evidence bundles carry a legal notice stating pursuit is
  performed by law enforcement (FBI IC3 / CISA); attribution is INDICATIVE ONLY.
- **Synthetic data:** all senders use `.invalid`, keys are documentation-range
  (`AKIA0000FAKE...`), and caller secrets are locally generated demo secrets.

## Design system

Dark security-console: bg `#0D1117`, surface `#161B22`, border `#30363D`,
accent teal `#20808D`, text `#C9D1D9`, success `#6DAA45`, warning `#E8AF34`,
danger `#DD6974`. Fonts via CDN: Space Grotesk (headings), Inter (body),
JetBrains Mono (logs/mono). Call log and outbox streams are color-coded by
severity/stream. `dashboard_preview.png` is a rendered reference screenshot.

## Verification

`verify_run.py` resets `lab.db`, runs a GOVERNMENT-tier lure through the whole
pipeline, and asserts 12 stages, including:

1–8: ingress, PhishBot scan, sandbox (executed==0), bait, forensics+cure,
tracker (mints **and** re-verifies + rejects a tampered token), evidence bundle
(integrity hash recomputed and matched), government stream isolation.
9–12: caller-ID ALLOWED (valid token + clean copy + anchor), DENIED (forged
token), token ROTATION on breach (in-memory result + persisted `rotations`
row), and call-log persistence across ALLOWED/DENIED/SCREENED.

Latest run: **12/12 PASS**. The server boots on `127.0.0.1:5060` and answers
`200` on `/`, `/api/counts`, and `/api/calllog`.

## Known limitations / prototype scope

- Classification, attribution, and reverse-engineering notes are **heuristic
  simulations** for the prototype, explicitly labelled INDICATIVE — not a real
  detection/RE engine.
- The evidence "handoff" writes to a local `outbox/`; a production system would
  transmit over an authenticated channel to FBI IC3 / CISA.
- Flask's dev server is used (fine for a local, single-user prototype); a
  production deploy would front it with a WSGI server. It still binds
  `127.0.0.1` only.
- Per-entity/lab HMAC secrets are stored locally for the demo (`.tracker_secret`
  and `registry.secret_b64`); production would keep them in an HSM.
