# BUILD NOTES — SENTINEL Honeypot + Forensics Lab + Track-Back

**Status:** Built and verified runnable. All routes, DB writes, beacons,
simulated analysis, and evidence generation tested end-to-end.

## What was built

A self-contained Python/Flask prototype under
`/home/user/workspace/sentinel/honeypot/`:

- **`honeypot_server.py`** — Flask decoy server on `127.0.0.1:8080`. Serves a
  convincing-but-clearly-labelled fake admin login (`/`, `/admin/login`) and a
  fake "data center" file portal (`/files`) listing watermarked bait. Logs
  every interaction — timestamp, source IP (honors `X-Forwarded-For`),
  user-agent, method, path, POSTed credentials, and all headers — into a
  SQLite `events` table. Extra routes: common probe traps (`/.env`,
  `/wp-login.php`, `/phpmyadmin`, `/.git/config`, `/api/v1/keys`) all logged and
  403'd; `/beacon/<token>` track-back callback; `/submit-sample` (simulated
  analysis); `/dashboard`; and `/api/summary|events|beacons|samples|evidence`
  plus `/api/build-evidence`.
- **`canary_token.py`** — Generates watermarked plain-text bait files
  (`passwords.xlsx`, `network_diagram.pdf`, `customer_db_backup.sql`,
  `master_keys.txt`), each embedding a unique `sntl-...` token + a
  `/beacon/<token>` callback URL, and registers tokens in the DB. The beacon
  endpoint records a track-back event (token id, time, reporting IP, UA,
  headers) when the bait is opened on the attacker's own machine. Returns an
  inert 1×1 GIF so a document's remote-image beacon renders harmlessly.
- **`forensics_lab.py`** — Simulated "microscope". Computes md5/sha1/sha256,
  guesses file type by magic bytes, measures size, extracts printable strings,
  and produces a synthetic verdict (Malicious / Suspicious / Low-Risk / Benign),
  threat score, family guess, and an attribution hint **explicitly labelled
  "INDICATIVE ONLY ... NOT proof"**. Never executes the sample — reads bytes
  only. Stores results in the `samples` table (the virus database).
- **`evidence_report.py`** — Assembles a chain-of-custody package from all
  logged events/beacons/samples, writes JSON + human-readable `.txt` to
  `outbox/`, SHA-256 hashes the body for integrity, records it in the
  `evidence` table, and states forwarding target as `outbox/` (simulated
  CISA / FBI IC3). Notice makes clear pursuit is done by law enforcement.
- **`dashboard.html`** — Dark security-console UI in the brief's palette
  (`#0D1117` / `#161B22` / accent `#20808D`, Space Grotesk / Inter / JetBrains
  Mono via CDN). Shows six KPIs, a live attacker-events table, beacons,
  microscope samples, and evidence packages, auto-refreshing every 4s, with a
  one-click "Build Chain-of-Custody Package" button and a prominent legal banner.
- **`db.py`** — Shared SQLite schema (`events`, `beacons`, `tokens`, `samples`,
  `evidence`) and connection helper. DB file: `events.db`.
- **`demo_seed.py`** — Inserts 40 synthetic attacker events (RFC 5737
  documentation IPs, realistic tool user-agents like sqlmap/Hydra/Nikto, decoy
  credential pairs), generates 4 bait files, fires 3 synthetic beacons, runs 5
  synthetic samples through the microscope, and builds one evidence package.

## How to run

```bash
pip install flask
cd /home/user/workspace/sentinel/honeypot
python demo_seed.py          # populate synthetic data (idempotent-ish; appends)
python honeypot_server.py    # then open http://127.0.0.1:8080/dashboard
```

## Verification performed

- `demo_seed.py` populated the DB: 40 events, 4 bait files + 3 beacons, 5
  samples, 1 evidence package (JSON + TXT in `outbox/`).
- Server starts cleanly on `127.0.0.1:8080`.
- `GET /` returns fake login with visible "DECOY / HONEYPOT" label; POST to
  `/admin/login` logs a `login_attempt` and returns "Invalid credentials".
- `GET /files` (200) lists all four bait files; `GET /files/master_keys.txt`
  returns the file including the `SENTINEL CANARY` watermark block.
- `GET /beacon/<valid-token>` returns HTTP 200 `image/gif` and inserts a beacon
  row (confirmed count increment).
- Probe path `/.env` returns 403 and logs a `probe` event.
- `/api/summary|events|beacons|samples|evidence` all return correct seeded JSON.
- `POST /submit-sample` on a suspicious-looking (but inert) blob returned
  `verdict=Malicious score=60`.
- `POST /api/build-evidence` produced a new case package with a SHA-256
  integrity hash.

## Legal guardrails honored (per shared/BRIEF.md)

- Purely passive/defensive: no code reaches out to, touches, or exfiltrates from
  any system not owned by the operator. Server binds to `127.0.0.1` only.
- Track-back is beacon/canary based — the attacker's machine reports to us.
- Malware analysis is simulated; samples are never executed.
- Attribution is indicative only; evidence is forwarded to law enforcement,
  which performs any pursuit. We collect and report.
- All demo data is synthetic; source IPs use RFC 5737 documentation ranges; no
  real PII.

## Notes / limitations

- Prototype persistence is SQLite; bait files are plain text (obviously safe)
  stand-ins for real content-free Office/PDF beacon documents.
- `demo_seed.py` appends each run; delete `events.db` (and `bait_files/`,
  `outbox/`, `demo_samples/`) to reset to empty.
- Only third-party dependency is Flask; everything else is Python stdlib.
