# SENTINEL Gateway — "Filter Before It Hits You"

An inbound-message filter that **detonates suspicious links and attachments in a
purely SIMULATED sandbox** before forwarding a cleaned, *tokenized* version of
the message to the user.

Part of the SENTINEL Track-Back Defense Platform (Tier 1 Individual/Family →
Tier 2 Business → Tier 3 Government). See `../shared/BRIEF.md`.

---

## The idea (founder's tokenization analogy)

> Like a **virtual/burner card number** that absorbs fraud risk before it ever
> touches your real bank account, this gateway inserts a disposable **token**
> between the attacker and you.

Risky links never reach your inbox directly. They are swapped for a safe
tokenized placeholder URL (e.g. `https://gateway.sentinel.local/t/9f3ac21b7de0`)
that would route back through the gateway on click. The threat is absorbed at
the gateway, not on your device.

```
 ✉ Inbound            ⛨ Gateway                      ✔ You
 attacker message  →  simulate detonation + tokenize → cleaned, safe message
```

---

## Safety guarantees (non-negotiable)

- **Nothing is ever fetched, opened, or executed.** There is zero network egress
  in this codebase. Search it — there is no `requests.get`, no `urlopen` of a
  scanned link, no `subprocess` that runs a file.
- **"Sandbox detonation" is 100% synthetic.** Verdicts are derived from local
  heuristics and a deterministic hash of the artifact string. The response always
  carries `"real_execution": false`.
- **All demo data is fictional** — reserved/example/.local domains, no real PII,
  no real malware.

---

## Install & run

```bash
cd sentinel/gateway
pip install -r requirements.txt        # just Flask

python gateway.py                      # serves http://127.0.0.1:5001
```

In a second terminal, load synthetic messages:

```bash
python demo_seed.py                    # posts to the running server
# or, without a server running:
python demo_seed.py --offline          # writes straight to gateway.db
```

Then open **http://127.0.0.1:5001/** for the dark-console dashboard.

---

## API

### `POST /scan`
Request body:
```json
{
  "from": "support@gmail-example.com",
  "subject": "URGENT: verify your account",
  "body": "Click here: http://paypal.verify-account.ru/login",
  "links": ["http://paypal.verify-account.ru/login"],
  "attachments": ["invoice.pdf.exe"]
}
```
Response (abridged):
```json
{
  "verdict": "malicious",
  "score": 14,
  "reasons": ["Urgency / credential keywords: urgent, verify", "..."],
  "link_analysis": [{ "sandbox": { "state": "malicious", "real_execution": false } }],
  "attachment_analysis": [ ... ],
  "sanitized": {
    "subject": "[SENTINEL: SUSPICIOUS] URGENT: verify your account",
    "body": "Click here: https://gateway.sentinel.local/t/9f3ac21b7de0",
    "attachments": [{ "name": "invoice.pdf.exe", "quarantined": true }],
    "gateway_banner": "SENTINEL Gateway: BLOCKED — malicious content detected."
  },
  "disclaimer": "Sandbox detonation is SIMULATED. No link or attachment was fetched..."
}
```

Other endpoints (used by the dashboard): `GET /api/scans`, `GET /api/scan/<id>`,
`GET /api/stats`.

---

## How scoring works (heuristics only)

| Signal | Example | Weight |
|---|---|---|
| Urgency / credential keywords | *urgent, verify, lockout, gift card* | up to +4 |
| Look-alike / homoglyph brand domain | `paypal.verify-account.ru`, `micros0ft.com` | +5 (link) / +4 (sender) |
| URL shortener | `bit.ly`, `tinyurl.com` | +3 |
| Raw-IP or `@`-redirect link | `http://...@192.168.44.9/pay` | +3 |
| Risky / macro-capable extension | `.exe .js .scr .docm` | +5 |
| Double-extension disguise | `invoice.pdf.exe` | +4 |
| Free-mail sender impersonating an institution | gmail sender + "bank" | +2 |

Totals map to verdict: `>= 7` malicious, `>= 3` suspicious, else clean.

---

## Files

| File | Purpose |
|---|---|
| `gateway.py` | Flask API, heuristics, simulated sandbox, SQLite logging |
| `templates/dashboard.html` | Dark security-console dashboard |
| `demo_seed.py` | Synthetic inbound messages |
| `requirements.txt` | Dependencies (Flask) |
| `gateway.db` | SQLite scan log (created on first run) |
| `BUILD_NOTES.md` | Design decisions & safety review |
