docs/SECURITY.md

# Sofia Engine Security Architecture & Threat Model

Sofia Engine is designed under the assumption that edge and industrial environments operate under adversarial and untrusted network conditions.

---

## 1. Core Security Invariants

1. **Default DENY Posture**:
   The `PolicyEngine` rejects all incoming actuation commands by default. An explicit, cryptographically authenticated rule must permit execution.
2. **Replay Protection**:
   All commands require a unique Nonce, monotonic Sequence Number, and Time-To-Live (TTL). Replayed commands or expired timestamps are immediately rejected.
3. **LLM Actuation Firewall**:
   External AI models (e.g. OpenAI, Anthropic, NVIDIA NIM, local LLMs) are strictly categorized as **Advisory Copilots**. Under no circumstance can an LLM directly trigger an edge actuator or override safety interlocks.
4. **Zero-Pickle Artifacts**:
   Sofia models are serialized exclusively as JSON manifests + NPZ/safetensors weight archives with SHA-256 parameter hashing. Arbitrary Python pickle files are strictly rejected.
5. **Secret Scrubbing**:
   All tokens, API keys, credentials, and sensitive headers are redacted from debug logs and telemetry exports using pattern-matched redaction filters.

---

## 2. Threat Mitigations

| Threat | Impact | Sofia Runtime Mitigation |
| :--- | :--- | :--- |
| **Command Injection / Replay** | Unauthorized machine actuation | `ReplayGuard` with Nonce cache, monotonic timestamp validation, and TTL eviction |
| **Model Tampering** | Adversarial parameter alteration | Mandatory SHA-256 parameter hash verification in `ModelManifest` prior to loading |
| **Sensor Saturation / Clipping** | Corrupted diagnostic assessment | `DataQuality.SATURATED` flag automatically attenuates diagnostic confidence to $\le 0.20$ |
| **Memory Exhaustion** | Gateway denial-of-service | Static capacity ceilings ($\le 65536$ frame size, fixed circular buffers, zero dynamic allocation in C99) |
| **Hostile Telemetry Metadata** | Buffer overflow or script injection | Strict identifier sanitization (`^[a-zA-Z0-9_\-\.]{1,64}$`) on all channels and device IDs |