Unkerien/PLL-Sensor-Cyber-Guard

1---2title: PLL-Sensor-Cyber-Guard-v13emoji: 🔒⚡4colorFrom: indigo5colorTo: red6sdk: docker7pinned: false8tags:9  - openenv10license: mit11---12 13# PLL-Sensor-Cyber-Guard-v114 15> **Meta OpenEnv 2026 Hackathon** — Cyber-Physical Security for Phase-Locked Loop Sensors16 17## Motivation: Protecting the Power Grid from Signal Sabotage18 19Phase-Locked Loops (PLLs) are at the heart of every modern power-grid inverter and synchrophasor measurement unit.  They synchronise distributed generators, solar farms, and HVDC links to the utility-frequency reference.  A compromised PLL sensor — through **False Data Injection**, **frequency spoofing**, or **step attacks** — can destabilise voltage regulation, cause protective relays to trip, and cascade into wide-area blackouts.20 21This environment challenges AI agents to act as real-time **intrusion-detection systems** that monitor raw PLL telemetry and classify cyber-attacks before they propagate through the grid.22 23## Environment Overview24 25| Property | Value |26|---|---|27| **Protocol** | `openenv-2026-sync` |28| **Port** | `7860` |29| **Observation Space** | `Box` — continuous PLL signals |30| **Action Space** | `Discrete` — `none`, `step_attack`, `freq_ramp`, `stealthy_fdi` |31| **Episode Length** | 100 steps |32| **Sync Fields** | `player_id` + `session_id` (mandatory) |33 34### PLL Physics35 36A discrete-time **2nd-order PLL** state-space model:37 38$$\mathbf{x}[k+1] = A_d \, \mathbf{x}[k] + B_d \, \mathbf{u}[k] + \mathbf{w}[k]$$39 40where $\mathbf{x} = [\phi_e, \Delta f]^	op$ (phase error and frequency error), $\omega_n = 2\pi \cdot 50$ rad/s, $\zeta = 0.707$, and $\mathbf{w} \sim \mathcal{N}(0, \sigma^2 I)$ with $\sigma = 0.02$.41 42## Attack Tasks43 44| Task | Difficulty | Attack | Description |45|---|---|---|---|46| `task_1` | 🟢 Easy | **Step Attack** | Sudden +2.0 rad spike in phase error at a random step |47| `task_2` | 🟡 Medium | **Frequency Ramp** | Gradual +0.1 Hz/sec frequency offset starting at a random step |48| `task_3` | 🔴 Hard | **Stealthy FDI** | False Data Injection within 1σ of noise — subtle long-term drift |49 50## Reward Formula51 52$$R = (A 	imes Success) - (eta 	imes Latency) - (F 	imes FalsePositive)$$53 54| Symbol | Meaning | Value |55|---|---|---|56| $A$ | Success weight | 1.0 (correct type), 0.5 (detected but wrong type) |57| $eta$ | Latency penalty coefficient | 0.3 |58| $Latency$ | Normalised detection delay | $(t_{detect} - t_{attack}) / T_{max}$ |59| $F$ | False-positive penalty | 0.2 per false alarm |60 61## API Endpoints62 63### `POST /reset`64 65```json66{67  "player_id": "agent-1",68  "session_id": "sess-abc",69  "task_id": "task_1"70}71```72 73Returns a `PLLObservation` with the initial PLL state.74 75### `POST /step`76 77```json78{79  "player_id": "agent-1",80  "session_id": "sess-abc",81  "action": {82    "action_id": 1,83    "classification": {84      "attack_detected": true,85      "attack_type": "step_attack",86      "confidence": 0.9587    }88  }89}90```91 92Returns the next `PLLObservation`.  At episode end (`done: true`), the response includes `score`, `reward`, and `feedback`.93 94### `GET /state`95 96Returns the full `PLLState` snapshot.97 98### `GET /health`99 100```json101{"status": "ok", "environment": "PLL-Sensor-Cyber-Guard-v1"}102```103 104## Quickstart105 106```bash107# Install dependencies108pip install -r requirements.txt109 110# Launch environment111uvicorn app:app --host 0.0.0.0 --port 7860112 113# Run baseline agent (threshold fallback)114python baseline_inference.py115 116# Run with Llama-3.1-8B (requires HF token)117export HF_READ_TOKEN="hf_..."118python baseline_inference.py119```120 121## Docker122 123```bash124docker build -t pll-cyber-guard .125docker run -p 7860:7860 pll-cyber-guard126```127 128## File Structure129 130```131├── models.py              # Pydantic v2 schemas132├── environment.py         # PLL physics + 3 attack tasks + grader133├── app.py                 # FastAPI server (port 7860)134├── openenv.yaml           # OpenEnv manifest135├── baseline_inference.py  # Llama-3.1-8B baseline agent136├── Dockerfile             # HF Spaces deployment137├── requirements.txt       # Python dependencies138└── README.md              # This file139```140 141## License142 143MIT144 145