Apppublic

Unkerien/PLL-Sensor-Cyber-Guard

sourceHugging Facemitupdated 6mo agoView on Hugging Face

0likes

App README

PLL-Sensor-Cyber-Guard-v1

Meta OpenEnv 2026 Hackathon — Cyber-Physical Security for Phase-Locked Loop Sensors

Motivation: Protecting the Power Grid from Signal Sabotage

Phase-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.

This 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.

Environment Overview

Property	Value
Protocol	`openenv-2026-sync`
Port	`7860`
Observation Space	`Box` — continuous PLL signals
Action Space	`Discrete` — `none`, `step_attack`, `freq_ramp`, `stealthy_fdi`
Episode Length	100 steps
Sync Fields	`player_id` + `session_id` (mandatory)

PLL Physics

A discrete-time 2nd-order PLL state-space model:

$$\mathbf{x}[k+1] = Ad \, \mathbf{x}[k] + Bd \, \mathbf{u}[k] + \mathbf{w}[k]$$

where $\mathbf{x} = [\phie, \Delta f]^ op$ (phase error and frequency error), $\omegan = 2\pi \cdot 50$ rad/s, $\zeta = 0.707$, and $\mathbf{w} \sim \mathcal{N}(0, \sigma^2 I)$ with $\sigma = 0.02$.

Attack Tasks

Task	Difficulty	Attack	Description
`task_1`	🟢 Easy	Step Attack	Sudden +2.0 rad spike in phase error at a random step
`task_2`	🟡 Medium	Frequency Ramp	Gradual +0.1 Hz/sec frequency offset starting at a random step
`task_3`	🔴 Hard	Stealthy FDI	False Data Injection within 1σ of noise — subtle long-term drift

Reward Formula

$$R = (A imes Success) - (eta imes Latency) - (F imes FalsePositive)$$

Symbol	Meaning	Value
$A$	Success weight	1.0 (correct type), 0.5 (detected but wrong type)
$eta$	Latency penalty coefficient	0.3
$Latency$	Normalised detection delay	$(t{detect} - t{attack}) / T_{max}$
$F$	False-positive penalty	0.2 per false alarm

API Endpoints

`POST /reset`

json

{
  "player_id": "agent-1",
  "session_id": "sess-abc",
  "task_id": "task_1"
}

Returns a PLLObservation with the initial PLL state.

`POST /step`

json

{
  "player_id": "agent-1",
  "session_id": "sess-abc",
  "action": {
    "action_id": 1,
    "classification": {
      "attack_detected": true,
      "attack_type": "step_attack",
      "confidence": 0.95
    }
  }
}

Returns the next PLLObservation. At episode end (done: true), the response includes score, reward, and feedback.

`GET /state`

Returns the full PLLState snapshot.

`GET /health`

json

{"status": "ok", "environment": "PLL-Sensor-Cyber-Guard-v1"}

Quickstart

bash

# Install dependencies
pip install -r requirements.txt

# Launch environment
uvicorn app:app --host 0.0.0.0 --port 7860

# Run baseline agent (threshold fallback)
python baseline_inference.py

# Run with Llama-3.1-8B (requires HF token)
export HF_READ_TOKEN="hf_..."
python baseline_inference.py

Docker

bash

docker build -t pll-cyber-guard .
docker run -p 7860:7860 pll-cyber-guard

File Structure

├── models.py              # Pydantic v2 schemas
├── environment.py         # PLL physics + 3 attack tasks + grader
├── app.py                 # FastAPI server (port 7860)
├── openenv.yaml           # OpenEnv manifest
├── baseline_inference.py  # Llama-3.1-8B baseline agent
├── Dockerfile             # HF Spaces deployment
├── requirements.txt       # Python dependencies
└── README.md              # This file

License

MIT