rosett-ai 1.3.3

data/doc/THREAT_MODEL.md

@@ -0,0 +1,230 @@
+# Rosett-AI Threat Model
+
+## Overview
+
+This document defines the adversary model, trust boundaries, and threat
+scenarios for rosett-ai. It complements `conf/design/security.yml` (coding rules)
+and `conf/design/threat_model.yml` (design constraints) by mapping the
+concrete attack surface.
+
+Every security decision in rosett-ai traces back to a threat listed here.
+
+## Adversary Model
+
+| Adversary | Capability | Motivation |
+|-----------|-----------|------------|
+| **Malicious content pack author** | Publishes YAML/asset packs to community repositories | Data exfiltration, code execution on user systems |
+| **Compromised dependency** | Pushes malicious gem version to RubyGems.org | Supply chain attack, credential theft |
+| **Local attacker** | Has read access to user's filesystem (shared machine) | Secret extraction, configuration tampering |
+| **Hostile YAML input** | Crafts YAML files with deserialization payloads | Arbitrary object instantiation, DoS |
+| **D-Bus peer** | Sends crafted messages on session bus | Privilege escalation, command injection |
+| **Network MITM** | Intercepts HTTP traffic (content pack downloads) | Content substitution, credential interception |
+
+## Trust Boundaries
+
+```text
+                    +---------------------------+
+                    |      User's System        |
+                    |                           |
+  CLI args -------->|  +---------+              |
+  Env vars -------->|  |  rosett-ai   |              |
+                    |  |  core   |              |
+  YAML files ------>|  +----+----+              |
+  (behaviour,       |       |                   |
+   design, config)  |       v                   |
+                    |  +----+----+   +--------+ |
+                    |  | Compiler|-->| Output | |
+                    |  +---------+   | files  | |
+                    |                +--------+ |
+  Content packs --->|  +---------+              |
+  (untrusted)       |  | Content |              |
+                    |  | Loader  |              |
+                    |  +---------+              |
+                    |                           |
+  Engine gems ----->|  +---------+              |
+  (semi-trusted)    |  | Engine  |              |
+                    |  | Loader  |              |
+                    |  +---------+              |
+                    |                           |
+  D-Bus messages -->|  +---------+              |
+  (session bus)     |  | D-Bus   |              |
+                    |  | Service |              |
+                    |  +---------+              |
+                    +---------------------------+
+```
+
+### Boundary 1: CLI Arguments & Environment Variables
+
+**Input**: Command-line flags, subcommand names, `RAI_*` environment variables.
+
+**Validation**:
+
+- Thor parses and type-checks all CLI arguments
+- Environment variables read via `ENV.fetch` with safe defaults
+- No environment variable value is passed to shell commands without sanitisation
+- `RAI_ENGINE_PATH` entries are canonicalised before use
+
+**Threats**:
+
+- Command injection via crafted `--engine` or path arguments
+- Environment variable poisoning (`RAI_ENGINE_PATH` pointing to attacker-controlled gems)
+
+**Mitigations**:
+
+- Array-form `system()` calls (never string interpolation)
+- Path canonicalisation with `File.expand_path` + whitelist check
+- Engine paths validated against expected directory structure
+
+### Boundary 2: YAML Files (Behaviour, Design, Config)
+
+**Input**: User-authored YAML files in `conf/behaviour/`, `conf/design/`,
+`conf/claude_code/`, and project `.rosett-ai/` directories.
+
+**Validation**:
+
+- `YAML.safe_load` with explicit `permitted_classes: [Date]` only
+- Schema validation via `json_schemer` before processing
+- Bounded parsing: max 1 MB file size, 10 levels nesting, 1000 keys
+- Unicode NFC normalisation on identifiers
+
+**Threats**:
+
+- YAML deserialization attacks (arbitrary object instantiation)
+- Path traversal in output path fields (`../../etc/cron.d/`)
+- Oversized files causing memory exhaustion
+- Deeply nested structures causing stack overflow
+
+**Mitigations**:
+
+- `YAML.safe_load` blocks arbitrary object creation
+- Output paths canonicalised and checked against whitelist directories
+- File size, nesting depth, and key count limits enforced at parse time
+- Schema validation rejects unexpected fields
+
+### Boundary 3: Content Packs (Untrusted)
+
+**Input**: Community-authored content packs downloaded from repositories.
+
+**Validation**:
+
+- SHA-256 checksum verification against manifest before extraction
+- YAML files validated against schemas after extraction
+- No Ruby code execution from content packs (YAML + assets only)
+- Extraction to temporary directory; moved to final location only after validation
+
+**Threats**:
+
+- Malicious YAML embedded in content packs
+- Path traversal in archive entries (zip slip)
+- Tampered content (MITM during download)
+- Trojan content packs with hidden functionality
+
+**Mitigations**:
+
+- Checksum verification before extraction
+- Archive entry paths checked for traversal before extraction
+- Content packs cannot contain executable Ruby files
+- HTTPS-only download (HTTP auto-upgraded)
+- Schema validation on all YAML within packs
+
+### Boundary 4: Engine Gems (Semi-Trusted)
+
+**Input**: Engine gems installed via Bundler or system package manager.
+
+**Validation**:
+
+- Gemspec metadata validated against expected `RosettAiEngine::` namespace
+- Gems loaded via Zeitwerk (no arbitrary `require` paths)
+- `bundler-audit` checks for known CVEs in CI
+- `Gemfile.lock` pins exact versions with checksums
+
+**Threats**:
+
+- Supply chain attacks (compromised gem pushed to RubyGems.org)
+- Typosquatting (similarly-named malicious gems)
+- Native extension gems executing arbitrary C code
+
+**Mitigations**:
+
+- `Gemfile.lock` with pinned versions blocks automatic updates
+- `bundler-audit` runs in CI and blocks merge on findings
+- Engine discovery validates gem namespace pattern
+- Native extensions require explicit user acknowledgement (future)
+
+### Boundary 5: D-Bus Messages (Session Bus)
+
+**Input**: Method calls and signals on `be.neatnerds.rosettai` session bus service.
+
+**Validation**:
+
+- Method signatures validated by ruby-dbus type system
+- Unknown methods return `org.freedesktop.DBus.Error.UnknownMethod`
+- Argument types and counts checked before dispatch
+- Only session bus (no system bus exposure)
+
+**Threats**:
+
+- Malicious D-Bus client sending crafted method calls
+- Type confusion in D-Bus argument handling
+- Denial of service via rapid method call flooding
+
+**Mitigations**:
+
+- ruby-dbus enforces D-Bus type system (s, i, b, etc.)
+- Method handlers validate argument semantics beyond type
+- Session bus isolation (only user's session, no root access)
+- Rate limiting at D-Bus daemon level (system default)
+
+### Boundary 6: File System Output
+
+**Input**: Compiled output files, telemetry logs, backup archives.
+
+**Validation**:
+
+- Write-restricted to whitelisted directories:
+  `~/.claude/`, project `.claude/`, `~/.config/rosett-ai/`
+- Explicit file permissions: `0644` for files, `0755` for dirs, `0600` for secrets
+- Temporary files use `Tempfile.new` with cleanup in `ensure` blocks
+
+**Threats**:
+
+- Arbitrary file write via path traversal in compiled output
+- Symlink attacks (writing through symlinks to sensitive locations)
+- World-readable secrets files
+
+**Mitigations**:
+
+- Path canonicalisation (`File.expand_path`) + whitelist check
+- Symlinks not followed for output (canonical path must match whitelist)
+- Secret files created with `0600` permissions
+- Temp file cleanup guaranteed by `ensure` blocks
+
+## Supply Chain Risk Assessment
+
+| Dependency | Risk | Mitigation |
+|-----------|------|------------|
+| thor | Low | Widely used, well-maintained CLI framework |
+| rainbow | Low | Pure Ruby, no native extensions |
+| i18n | Low | Rails ecosystem dependency, actively maintained |
+| json_schemer | Medium | Parses external schemas; pinned version |
+| ruby-dbus | Medium | Native D-Bus bindings; pinned version |
+| zeitwerk | Low | Rails ecosystem autoloader |
+| jwt | Medium | Cryptographic operations; verify algorithm parameter |
+| ed25519 | Medium | Native extension; pinned + checksum verified |
+| bundler-audit | Low | Security tool itself; development dependency |
+| gitleaks | Low | Binary; development/CI dependency only |
+
+All runtime dependencies are locked in `Gemfile.lock` with exact versions.
+`bundler-audit` runs in CI to detect known CVEs.
+
+## Security Review Triggers
+
+The threat model must be reviewed when:
+
+1. A new external input channel is added
+2. A new engine integration is implemented
+3. A new network-facing feature is added
+4. Dependency versions are updated
+5. Trust assumptions change (e.g., content pack sources)
+
+See `doc/SECURITY_REVIEW_CHECKLIST.md` for the review process.