# 13 — Security, privacy and threat model

## Security posture

DevRunbook processes development instructions, repository metadata, source snippets, integration tokens and generated artifacts. Even without direct code execution, it is a high-trust developer tool and must assume imported content can be malicious.

## Assets

- user accounts and sessions;
- Gitea access tokens;
- repository identities and metadata;
- source snippets and profile evidence;
- private playbooks;
- generated prompts and Run Packs;
- audit logs;
- encryption keys;
- future execution results.

## Trust boundaries

- browser to application;
- web process to PostgreSQL;
- worker to PostgreSQL and artifact storage;
- application to Gitea;
- package archive to importer;
- repository content to normalization engine;
- rendered prompt to external Codex workflow;
- host filesystem to container volumes.

## Primary threats and controls

### Prompt injection through repository content

Threat: README, issue text or source comments instruct the agent to ignore higher-level rules or expose secrets.

Controls:

- repository content is untrusted evidence;
- raw snippets are fenced and labeled;
- evidence cannot render inside platform policy blocks;
- prefer normalized facts;
- strict size and path allowlists;
- provenance visible to user;
- prompt-lint rule detects policy phrases in evidence placement.

### Malicious Playbook Package

Threat: template accesses secrets, escapes paths, includes scripts or creates misleading safety claims.

Controls:

- restricted schema and template context;
- no arbitrary template helpers or code evaluation;
- symlink rejection;
- archive traversal protection;
- scripts not executed or imported as active behavior in MVP;
- platform guardrails outrank package content;
- source and lifecycle labels;
- size and file-count limits.

### Token theft

Threat: Gitea token leaks through logs, database dumps, UI or generated output.

Controls:

- encrypted at rest with versioned key;
- plaintext accepted only over secure request path and discarded;
- token never returned after save;
- logs redact authorization and token patterns;
- generated output context has no secret access;
- rotation workflow;
- minimal permissions;
- optional external secret-provider adapter later.

### SSRF and internal network access

Threat: attacker configures a Gitea URL pointing at metadata or internal services.

Controls:

- URL scheme and host validation;
- resolve all addresses and enforce operator network policy;
- block loopback, link-local and metadata ranges by default;
- explicit configuration for intended private Gitea hosts;
- DNS re-check after redirects;
- no auth header across host changes;
- timeout, redirect and response-size limits.

### ZIP Slip and filesystem escape

Threat: imported/exported package paths write outside the intended directory.

Controls:

- normalize paths and reject absolute paths, `..`, device names and NUL bytes;
- reject symlinks and hardlinks;
- generate from in-memory manifest, not user-controlled path concatenation;
- use opaque storage keys;
- test Windows and POSIX edge cases.

### Broken authorization

Threat: a user accesses another workspace's playbook, run, artifact or integration.

Controls:

- authorization enforced in application use cases, not UI only;
- every resource query scoped by workspace membership;
- opaque IDs are not authorization;
- artifact downloads use short-lived authorized routes;
- cross-workspace integration references rejected;
- authorization integration tests.

### Cross-site scripting

Threat: playbook or repository Markdown executes scripts in the browser.

Controls:

- sanitize rendered Markdown;
- no raw HTML by default;
- strict Content Security Policy;
- escape code and template content;
- sandbox any future rich preview;
- test malicious fixtures.

### Denial of service

Threat: huge archives, files, prompts, regexes or repeated sync jobs exhaust resources.

Controls:

- file, archive, field and total prompt limits;
- streaming archive inspection with expanded-size cap;
- bounded concurrency;
- job leases and rate limits;
- pagination and timeouts;
- safe regex policy;
- per-workspace quotas configurable later.

### Data remanence

Threat: deleted repository or token remains in artifacts, logs or backups.

Controls:

- retention policy and deletion jobs;
- secrets excluded from artifacts by design;
- backup documentation states what remains;
- user-visible deletion consequences;
- encrypted secret deletion and key rotation;
- log retention kept short.

## Authentication and sessions

- select a maintained authentication implementation in Milestone 0;
- password hashing with current recommended parameters;
- secure, HTTP-only, same-site cookies;
- CSRF protection for state-changing operations;
- session revocation and password reset;
- rate limiting on authentication endpoints;
- optional OIDC after MVP without redesigning workspace ownership.

## Encryption key management

- application master key supplied outside the database;
- versioned envelope format for stored integration secrets;
- rotation supports decrypt-old/encrypt-new;
- readiness warns on missing old key versions;
- keys never included in application backup archives by default;
- recovery instructions explain key dependency honestly.

## Logging policy

Do log:

- request ID, route, status, duration;
- job ID, stage and safe error code;
- integration ID, not token;
- playbook ID/version and digest;
- run ID and artifact metadata;
- security-relevant actions.

Do not log:

- authorization headers;
- cookies or session tokens;
- plaintext secrets;
- complete repository files;
- full rendered prompt by default in operational logs;
- user passwords;
- archive contents.

## Security acceptance

- threat cases have automated tests where practical;
- dependency and secret scanning configured;
- no high or critical unresolved findings attributable to the product at release;
- CSP and security headers verified;
- archive and SSRF controls tested;
- authorization tests cover cross-workspace access;
- audit events exist for connection creation, token rotation, playbook publication, run generation and destructive deletion.