rosett-ai 1.3.3 → 1.5.9

data/doc/THREAT_MODEL.md

@@ -1,230 +0,0 @@
-# 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.