CyberAttack-PLL / pll_cyber /attacks.py
krishuggingface's picture
Claude Opus 5.5
v2: physically correct SRF-PLL, realistic attacks, exploit-proof graders
c282634
Raw History Blame Contribute Delete
4.07 kB
"""
False Data Injection (FDI) attacks on the PLL's voltage-measurement channel.
The attacker sits between the voltage transducers / ADC and the controller
(compromised sensor firmware, a man-in-the-middle on the sampled-values bus,
or malware on the control board) and rewrites the samples the PLL sees.
1 sinusoidal — interharmonic injection on one phase: excites a
persistent oscillation in the PLL frequency estimate
2 ramp — slowly growing DC bias on one phase (sensor-offset
style): a 50 Hz ripple in vq that grows over time
3 pulse — step bias on one phase for a short burst
4 phase_spoofing — coordinated, balanced manipulation of all three
phases that rotates the measured voltage vector by a
slowly accelerating angle δ(t). The PLL tracks the
spoofed angle perfectly (vq stays ≈ 0) so classic
residual detectors are blind, while the inverter
drifts out of synchronism with the real grid. Its
only local footprint is a small frequency deviation
that is indistinguishable from a natural grid
frequency event — unless it is cross-checked against
a trusted reference (the PMU stream).
Types 1–3 are "loud but harmless-ish"; type 4 is quiet and destructive.
"""
from __future__ import annotations
import math
from dataclasses import asdict, dataclass, field
from typing import Any, Dict, Optional
import numpy as np
from .pll import TWO_PI
ATTACK_TYPES: Dict[int, str] = {
0: "none",
1: "sinusoidal",
2: "ramp",
3: "pulse",
4: "phase_spoofing",
}
ATTACK_IDS: Dict[str, int] = {v: k for k, v in ATTACK_TYPES.items()}
@dataclass
class AttackSpec:
kind: str = "none"
t_start: float = math.inf
params: Dict[str, float] = field(default_factory=dict)
@property
def type_id(self) -> int:
return ATTACK_IDS[self.kind]
@property
def present(self) -> bool:
return self.kind != "none"
def to_dict(self) -> Dict[str, Any]:
d = asdict(self)
d["type_id"] = self.type_id
if not math.isfinite(d["t_start"]):
d["t_start"] = None
return d
class Attack:
"""Evaluates an AttackSpec on a block of sample times."""
def __init__(self, spec: AttackSpec):
self.spec = spec
def angle_offset(self, t: np.ndarray) -> Optional[np.ndarray]:
"""Spoofed angle δ(t) in rad added to all three measured phases, or None."""
s = self.spec
if s.kind != "phase_spoofing":
return None
tau = np.clip(t - s.t_start, 0.0, None)
r, df_max, sign = s.params["rocof_hz_s"], s.params["max_offset_hz"], s.params["direction"]
t_sat = df_max / r
# Frequency offset ramps at r until df_max, then holds; δ = 2π ∫ Δf dτ
ramp_part = 0.5 * r * np.minimum(tau, t_sat) ** 2
hold_part = df_max * np.clip(tau - t_sat, 0.0, None)
return sign * TWO_PI * (ramp_part + hold_part)
def additive(self, t: np.ndarray) -> Optional[np.ndarray]:
"""Additive injection, shape (3, n), or None."""
s = self.spec
if s.kind in ("none", "phase_spoofing"):
return None
tau = t - s.t_start
active = tau >= 0.0
if not active.any():
return None
sig = np.zeros_like(t)
p = s.params
if s.kind == "sinusoidal":
sig = np.where(active, p["amplitude_pu"] * np.sin(TWO_PI * p["freq_hz"] * tau + p["phase"]), 0.0)
elif s.kind == "ramp":
sig = np.where(active, np.clip(p["rate_pu_s"] * tau, -p["cap_pu"], p["cap_pu"]), 0.0)
elif s.kind == "pulse":
sig = np.where(active & (tau < p["duration_s"]), p["magnitude_pu"], 0.0)
out = np.zeros((3, t.size))
out[int(p["phase_index"])] = sig
return out