admin / AirportCyberSimulator

# Airport Cyber Resilience Simulator

An interactive, kiosk-grade cyber-attack simulation for critical airport
infrastructure. A server-authoritative FastAPI engine steps through data-driven
attack playbooks — showing the **point and method of ingress**, timed **lateral
spread**, and the operational **trade-offs** of every defensive decision — while
an immersive dark command-center UI renders it at 60fps.

## Quick start (Docker)

```bash
docker compose up --build
# open http://localhost:8000
```

## Quick start (local)

```bash
cd backend
pip install -r requirements.txt
uvicorn main:app --host 0.0.0.0 --port 8000
# open http://localhost:8000
```

## Helper scripts

Wrappers around `docker compose` so you don't have to remember flags.

**Windows (PowerShell):**

```powershell
.\sim.ps1 up        # build + start in background  ->  http://localhost:8000
.\sim.ps1 logs      # tail logs
.\sim.ps1 status    # container + health state
.\sim.ps1 rebuild   # clean no-cache rebuild
.\sim.ps1 open      # open the kiosk in the browser
.\sim.ps1 down      # stop + remove
```

**macOS / Linux / WSL (make):**

```bash
make up        # build + start in background
make logs      # tail logs
make health    # show health status
make rebuild   # clean no-cache rebuild
make down      # stop + remove
```

## Architecture

| Layer          | Tech                                   | Responsibility                                            |
|----------------|----------------------------------------|-----------------------------------------------------------|
| Backend        | Python · FastAPI · WebSockets          | State machine, timed spread engine, mitigation trade-offs |
| Frontend       | HTML5 SVG · CSS · GSAP (vendored)      | Kiosk map, 60fps particle/halo animation, overlays        |
| Config layer   | JSON in `backend/data/`                | Nodes, links, playbooks, compliance — **no code changes** |

Everything is **data-driven**: to add a node, link, playbook or compliance
mapping, edit the JSON in `backend/data/` — the engine and UI adapt automatically.
`docker-compose.yml` mounts `backend/data` read-only so config edits hot-reload
without rebuilding the image.

## Data files

- `data/infrastructure.json` — 14 airport services, their positions, capacity
  weights, icons and interdependency links.
- `data/playbooks.json` — 5 attack scenarios, each with `ingress_point`,
  `ingress_method`, `ingress_icon` and a timed `spread_events` array.
- `data/compliance.json` — maps every node to an NCSC **CAF** objective/principle
  and a **UK Cyber Security and Resilience Bill** statutory duty.

## Simulation model

Live metrics: **Security Integrity (%)**, **Operational Capacity (%)**,
**Financial / Reputational Loss (£)**.

Mitigations (per compromised node):

| Option            | Effect on spread            | Node capacity | Cost profile              |
|-------------------|-----------------------------|---------------|---------------------------|
| A · ISOLATE NODE  | Severs links, stops instantly | → 0%        | High operational loss     |
| B · REDUCE TRAFFIC| Slows spread by 80%          | → 40%        | Moderate operational loss |
| C · STOP ATTACK   | 15s patch; fails if the next spread beats the timer | unchanged | Heavy financial penalty |

## Kiosk behaviour

- Fixed 1920×1080 stage, auto-scaled to any display.
- Idle 90s → auto-reset to the **Attract Loop**.
- Hover/tap any node for details, mitigation, and a **Regulatory Insights** tab.

## WebSocket protocol (`/ws`)

Client → server: `{action:"start", playbook_id}` · `{action:"mitigate", node, option}` · `{action:"reset"}`
Server → client: `sim_start`, `ingress`, `compromised`, `spread`, `spread_blocked`,
`mitigation`, `patch_start`, `patch_complete`, `metrics`, `sim_complete`, `reset`.