# Cyber Forensics Test Lab — Unified Component Brief

Build a NEW top-level component at `/home/user/workspace/sentinel/forensics_lab_unified/`
that ties the existing SENTINEL modules into ONE documented, working pipeline with a
single dashboard. This is the founder's central vision: **any attack on a phone,
email, link, or server is pulled into a trap, given bait, analyzed, documented, and
tokenized-tracked straight to law enforcement / government.**

## READ FIRST
- `/home/user/workspace/sentinel/shared/BRIEF.md` — design system + ABSOLUTE LEGAL GUARDRAILS. Obey every guardrail. Track-back, never hack-back. Synthetic data only. Nothing touches a machine we don't own. No live malware execution — simulated analysis only. Bind to 127.0.0.1.

## The pipeline this component must implement (end to end, one flow)
1. **Ingress / Attack surfaces** — a decoy inbox that receives three kinds of lures on OUR OWN decoy infrastructure:
   - **Decoy EMAIL** messages (fake but realistic-looking)
   - **Decoy SMS / text messages**
   - **Decoy malicious LINKS** (tokenized; clicking beacons home)
   Each surface represents an "individual attack" that could hit a phone, email, or server.
2. **Sandbox trap** — every incoming hostile artifact is routed into an isolated sandbox (SIMULATED containment; never executes real payloads). It is held, never allowed to touch anything real.
3. **Bait / deception** — the trap serves the attacker fake-but-real-looking assets they'd want to steal: fake credentials, fake API keys, fake customer records, decoy "servers" and files. All watermarked + tokenized so any exfil is trackable.
4. **Forensics documentation** — the forensics lab analyzes each captured artifact: classifies it, extracts indicators (hashes, patterns), writes a documented case file, and checks "is there a cure / signature" (look up against the fragment catalog; add new signatures). This happens BEFORE anything is packaged to leave.
5. **Tokenized track-back** — mint tokenized trackers (HMAC-signed, tamper-evident) bound to each case. These are the "trackers sent back" — passive beacons only; they identify the artifact and case, never attack anyone.
6. **Law-enforcement / government handoff** — package a chain-of-custody evidence bundle (JSON + human-readable TXT + integrity SHA-256 hash) into an `outbox/`, addressed to FBI IC3 / CISA. Government tier gets its own isolated version of the report stream.

## Reuse, don't reinvent
Import / adapt from existing modules where possible:
- `honeypot/canary_token.py`, `honeypot/forensics_lab.py`, `honeypot/quarantine.py`, `honeypot/fragment_catalog.py`, `honeypot/evidence_report.py`, `honeypot/db.py`
- `ransom_trace/` (tokenized "trace not touch" pattern for the tracker mint)
- `packet_layer/token_mint.py` (HMAC token minting pattern)
You may copy the needed logic into the new component so it runs standalone.

## Branding (IMPORTANT — founder-approved names)
- The **phishing / link + email + SMS scanner** piece is branded **"PhishBot 3.0"**. It scans incoming lures, flags them, and sanitizes dangerous links into safe tokenized ones.
- The **network-defense / deception grid** piece (the trap + decoy servers + isolation) is branded **"VigilantGuard"**.
- The overall component is the **"Cyber Forensics Test Lab"** inside the SENTINEL platform.
- Show these names in the dashboard UI and code comments/READMEs.

## Deliverables
- A Flask app `lab_server.py` on `127.0.0.1:5060` with a single dark black-and-teal dashboard (design system from BRIEF.md) showing: incoming lures (email/SMS/links) → sandbox holds → bait served → forensics case files → minted trackers → outbox handoffs. Live-ish counters and a case table.
- Routes: `POST /ingest` (submit a lure), `POST /analyze` (run forensics on a held artifact), `GET /api/cases`, `GET /api/trackers`, `GET /api/outbox`, plus the dashboard at `/`.
- `demo_seed.py` — seeds a realistic synthetic run: several email lures, SMS lures, and link lures across the three tiers (Family / Business / Government), so opening the dashboard shows a full populated pipeline.
- `pipeline.py` — the orchestrator that runs ingress→trap→bait→forensics→tracker→outbox for one artifact.
- `phishbot.py` (PhishBot 3.0 scanner) and `vigilantguard.py` (VigilantGuard deception/isolation) modules.
- `requirements.txt`, `README.md` (what it is, the pipeline, run steps, legal guardrails), `BUILD_NOTES.md`.
- `verify_run.py` — runs the full pipeline headless and asserts each stage produced output; prints a PASS summary.

## Run contract (must work exactly like this)
```
cd /home/user/workspace/sentinel/forensics_lab_unified
pip install -r requirements.txt
python demo_seed.py
python verify_run.py     # must print PASS for every stage
python lab_server.py     # dashboard at http://127.0.0.1:5060
```

## Guardrails restated (do not violate)
- No hack-back. No reaching out to any external system. Trackers are passive tokens only.
- No real malware execution. Sandbox is simulated containment.
- All data synthetic. Fake credentials are obviously fake / documentation-range only.
- Bind 127.0.0.1. Local-first. No telemetry.
- Everything must ACTUALLY RUN. This is real, not a mock. verify_run.py must pass.
