Threat Model

This document describes the security assumptions for Aegis as a local-first supervised agent harness. It names the supported operating modes, the assets Aegis protects, the trust boundaries in the current architecture, and the modes that are intentionally out of scope until separate hardening work is completed.

Supported Modes

Mode	Status	Assumptions	Required controls
Local workstation	Supported default	One operator runs Aegis on their own machine. The dashboard and API bind to `127.0.0.1` or `localhost`. Local OS account access is trusted.	Localhost bind, browser-origin mutation boundary, explicit approvals, local secret registry, filesystem containment, audit artifacts.
Private-network host	Supported with caution	The operator intentionally binds beyond localhost for access from trusted devices on a private network. The network is not hostile.	`AGENT_HARNESS_TOKEN`, private network boundary, protected host account, reviewed connector/provider credentials, backup and audit discipline.
Headless-agent client	Supported as scoped access	A non-human agent can inspect allowed state and add steering input, but cannot approve human-owned decisions or read operator-owned secret metadata.	`AGENT_HARNESS_AGENT_TOKEN`, operation-class scope checks, no approval endpoints, no secret metadata/status access.
Public internet service	Unsupported	Arbitrary remote users, hostile browsers, credential stuffing, internet scanning, DDoS, tenant isolation, and public session management are expected.	Requires a separate product track before use: hardened auth, TLS/reverse proxy, CSRF/session design, RBAC, rate limiting, secret manager, deployment isolation, monitoring, backup/restore operations.
Multi-tenant SaaS	Unsupported	Multiple organizations, shared infrastructure, delegated approvals, tenant data isolation, and administrative role separation are expected.	Requires a separate architecture. Do not infer this from the local/private-network harness.

Protected Assets

Asset	Examples	Primary controls
Local project files	Source code, docs, configuration, generated patches.	Repo/workspace path containment, approval-gated repo writes, verifier commands, symlink escape tests.
Run artifacts and audit history	Goals, traces, context packets, patch bundles, reports, evidence, replay packets.	Run workspaces, SQLite metadata, artifact hashes, audit/replay exports, retention roadmap.
Raw secrets and credentials	Provider API keys, OAuth refresh tokens, webhook secrets, connector credentials.	Local secret material store, redacted metadata, scoped API access, bounded subprocess environments.
Approval authority	Repo writes, external writes, delivery gates, high-risk action classes.	Human-owned approval checkpoints, idempotency guards, evidence/hash review requirements.
Model prompts and context	User requests, memory records, project context, task-session packets, provider inputs.	Context packet provenance, model routing visibility, local-first provider options, audit traces.
External accounts and connectors	Gmail, Google Calendar, GitHub, Plaid, Slack, OAuth-backed APIs.	Connector scopes, typed operations, OAuth approval previews for generic writes, receipts, policy classes.
Local Aegis state	Runs, jobs, tasks, automations, provider health, capabilities, memory records.	SQLite transactions, job claiming, startup requeue, schema migrations, API contract validation.

Actors

Actor	Trust level	Notes
Operator	Trusted human owner	Can approve high-risk work, configure providers/connectors, inspect secrets metadata, and manage local state.
Coordinator model	Untrusted assistant	Can propose, route, summarize, and request tools. It cannot be treated as approval authority for human-owned work.
Specialist agent/model	Untrusted worker	Executes bounded task contracts with explicit tool allowlists and verifier/approval gates.
Headless agent client	Partially trusted automation	Can read/steer through scoped token operations only. It cannot approve, mutate operator-owned config, or read secret metadata.
Local browser page	Potentially hostile	A malicious page in the operator browser may attempt cross-site localhost mutations. Browser-origin mutation checks are required.
Local process	Potentially hostile outside Aegis	Other local processes may attempt API calls or file access. Local OS account compromise is outside the default threat model.
External provider/connector	Outside trust boundary	Aegis sends data only when configured and policy allows it. Provider responses are not trusted as authority.
Internet attacker	Unsupported-mode adversary	Public exposure is not an accepted default. Do not rely on local-private controls for internet-facing deployment.

Trust Boundaries

Boundary	Current control	Primary source owner	Regression coverage
Local API bind	Defaults to localhost; token required beyond localhost.	`src/api/config.ts`, `src/api/server-helpers.ts`	`tests/api-browser-boundary.test.ts`, `tests/control-plane-api.test.ts`
Browser-origin mutations	Browser unsafe requests require localhost host/origin proof and local UI header.	`src/api/server-helpers.ts`	`tests/api-browser-boundary.test.ts`
Operator vs agent tokens	Agent token gets readable/steering classes only; human/operator-only operations are denied.	`src/api/server-helpers.ts`, `src/shared/contracts.ts`	`tests/control-plane-api.test.ts`
Tool permission allowlists	Compound tools require every required token unless explicit alternatives are modeled.	`src/task-runtime/index.ts`, `src/tools/index.ts`	`tests/runtime-policy-service.test.ts`, `tests/runtime-isolation-policy.test.ts`
Policy classes	Repo writes, external writes, and high-risk actions are blocked or approval-gated.	`src/policy/index.ts`, `src/task-runtime/index.ts`	`tests/runtime-policy-service.test.ts`, `tests/approval-checkpoints.test.ts`
Human approvals	Checkpoints are evidence-bound and single-decision. Repo-write approvals bind hashes and paths.	`src/orchestrator/service.ts`, `src/db/database.ts`	`tests/approval-checkpoints.test.ts`, `tests/coding-approval-verification.test.ts`, `tests/transaction-boundaries.test.ts`
Repo filesystem access	Repo tools use containment checks and reject symlink/sibling-prefix escapes.	`src/shared/fs.ts`, `src/tools/index.ts`	`tests/workspace-containment.test.ts`, `tests/verifier-bounds.test.ts`
Workspace artifacts	Workspace reads/writes stay inside run workspace and skip symlink entries.	`src/workspace/index.ts`	`tests/workspace-containment.test.ts`
Host subprocess execution	Verifier commands use argv arrays, bounded env, output caps, timeouts, and process cleanup.	`src/verifiers/index.ts`	`tests/verifier-bounds.test.ts`
Model-provider CLI execution	Provider CLIs receive bounded environment plus explicit credentials only.	`src/model-runtime/index.ts`, `src/shared/subprocess-env.ts`	`tests/model-provider-env.test.ts`, `tests/provider-smoke-env.test.ts`
Generic OAuth writes	Unsafe generic OAuth methods require matching approval preview before token or network access.	`src/connectors/oauth-api-tools.ts`, `src/task-runtime/index.ts`	`tests/oauth-connectors.test.ts`, `tests/runtime-policy-service.test.ts`, `tests/workflow-test-runs.test.ts`
Source intake	Archives are quarantined, path traversal is rejected, manifests capture risky source traits.	`src/source-intake/index.ts`	`tests/source-intake.test.ts`
Container sandbox	Docker sandbox has resource/network/artifact policy metadata and no host Docker socket mount.	`src/sandbox-runner/index.ts`	`tests/sandbox-runner.test.ts`
Runtime persistence	Core state transitions use transactions where implemented; jobs are atomically claimed.	`src/db/database.ts`, `src/orchestrator/service.ts`	`tests/transaction-boundaries.test.ts`, `tests/job-claiming.test.ts`

The Source Map lists the code ownership for these boundaries.

Explicit Non-Goals

Aegis does not currently claim to protect against:

an attacker who controls the operator’s OS account;
a malicious browser extension with access to local pages and credentials;
untrusted users sharing the same Aegis instance;
internet-scale request flooding or credential stuffing;
tenant isolation, delegated approvals, or enterprise RBAC;
hardened at-rest encryption through an enterprise secret manager;
compromise of a configured model provider or OAuth provider;
arbitrary code execution in third-party tools that the operator deliberately installs and runs outside Aegis.

Some of these can be reduced by future work, but they are not part of the default local-first guarantee today.

Abuse Cases To Keep Tested

Boundary-sensitive changes should preserve negative tests for these cases:

broad category tokens such as external-write do not unlock connector-specific tools;
repo paths cannot escape through sibling prefixes or symlinks;
browser-originated cross-site requests cannot mutate local API state;
scoped agent tokens cannot approve, dismiss, mutate operator-owned configuration, or read secret metadata;
repo-write approval cannot apply a different file, content hash, or stale before-hash;
generic OAuth writes cannot request approval or token access without a matching approval preview;
model-provider subprocesses do not inherit ambient shell secrets;
verifier timeouts stop child process groups and cap captured output;
restore verification opens candidate databases read-only.

Future Hardening Tracks

These tracks should be explicit product decisions, not accidental assumptions:

public HTTPS deployment profile with reverse proxy, TLS, session design, CSRF strategy, rate limits, and monitoring;
multi-operator approval delegation and RBAC;
external secret manager or OS keychain integration;
artifact retention classes and integrity-aware cleanup;
runtime isolation enforcement for tools, connectors, and network egress;
connector enablement checklists for purchases, trades, tax, device/network actions, and self-extension;
stronger transaction/compensation handling for operations that span SQLite plus filesystem artifacts.

Until those tracks land, keep Aegis positioned as a serious local/private-network harness with explicit supervision and auditability.