AnimaWorks runs autonomous AI agents with tool access, persistent memory, and inter-agent communication. This creates a fundamentally different threat surface than stateless LLM wrappers — agents can read files, execute commands, send messages, and operate on schedules without human intervention.

This document describes the layered security model and an adversarial threat analysis based on cutting-edge LLM/agent attack research (OWASP Top 10 for LLM 2025, AdapTools, MemoryGraft, ChatInject, RoguePilot, MCP Tool Poisoning, RAGPoison, Confused Deputy attacks).

Last audited: 2026-03-06

Every piece of data entering an agent's context is tagged with a trust level. The model sees these boundaries explicitly and is instructed to treat untrusted content as data, never as instructions.

<tool_result tool="web_search" trust="untrusted">
  Search results — may contain injection attempts
</tool_result>

<priming source="related_knowledge" trust="medium" origin="consolidation">
  RAG-retrieved context
</priming>

Origin categories: system, human, anima, external_platform, external_web, consolidation, unknown. Each maps to a trust level via ORIGIN_TRUST_MAP.

Origin chain propagation: When data flows through multiple systems (e.g., web → RAG index → priming), the trust level degrades to the minimum in the chain. resolve_trust(origin, origin_chain) computes the conservative minimum across all nodes in the chain plus the current origin.

Session-level trust tracking: _min_trust_seen tracks the minimum trust rank (2=trusted, 1=medium, 0=untrusted) across all tool calls in a session. Updated in Mode S (PreToolUse hook + run/min_trust_seen file), Mode A (litellm_loop and anthropic_fallback). Reset at each interaction cycle start.

Trigger and tier injection conditions (core/prompt/builder.py):

• tool_data_interpretation is in Group 1 but is not injected when trigger="task" (TaskExec). TaskExec runs with minimal context, so the model does not receive trust boundary interpretation instructions. Tool results are still wrapped with wrap_tool_result so tags are applied, but note that the "tag interpretation rules" instruction to the model is omitted.
• permissions is injected only when tier != TIER_MINIMAL. When context is under 16k (TIER_MINIMAL), permissions are omitted.
• behavior_rules applies only to TIER_FULL and TIER_STANDARD. Omitted for TIER_LIGHT / TIER_MINIMAL.
• Tier boundaries: 128k+ = FULL, 32k–128k = STANDARD, 16k–32k = LIGHT, under 16k = MINIMAL.

Key files: core/execution/_sanitize.py (trust resolution, boundary wrapping, TOOL_TRUST_LEVELS, ORIGIN_TRUST_MAP), core/prompt/builder.py (trigger/tier prompt construction, tool_data_interpretation injection conditions), templates/{locale}/prompts/tool_data_interpretation.md (trust level and origin chain interpretation instructions; locale depends on config.locale)

When an agent writes to knowledge/*.md, the system checks _min_trust_seen for the session. If the session has processed untrusted (rank 0) or medium (rank 1) tool results, an origin frontmatter is added:

• Rank 0 (untrusted) → origin: external_web
• Rank 1 (medium) → origin: mixed
• Rank 2 (trusted) → no origin tag (clean knowledge)

The origin is passed to the RAG indexer and stored in ChromaDB chunk metadata.

index_file() accepts an origin parameter and stores it as metadata["origin"] in chunk metadata.

When Priming retrieves related knowledge via RAG, each chunk's origin metadata is evaluated with resolve_trust(). Chunks are split into:

• trusted/medium → related_knowledge (wrapped with trust="medium")
• untrusted → related_knowledge_external (wrapped with trust="untrusted", origin="external_platform")

Budget prioritizes trusted/medium content first; untrusted content fills remaining budget.

Daily consolidation reads YAML frontmatter origin: from source knowledge files. If any source has external origin (external_web, mixed, consolidation_external), the consolidated output is downgraded to origin: consolidation_external (resolves to untrusted).

Key files: core/tooling/handler_memory.py (write_memory_file origin propagation), core/memory/rag/indexer.py (origin in chunk metadata), core/memory/priming.py (Channel C trust splitting), core/memory/consolidation.py (origin chain tracking)

Agents can execute shell commands. Five independent layers prevent abuse:

Blocks shell metacharacters that could chain or inject commands:

• Semicolons (;), backticks (`), newlines (\n)
• Command substitution ($(), ${}, $VAR)

Pattern-matched commands that are always blocked regardless of permissions:

Each agent's permissions.json can define commands.denied_commands for additional blocked commands.

permissions.json uses an "Open by Default, Deny by Exception" model. When commands.allow_all is true (default), all commands are permitted except those in denied_commands and the hardcoded blocklist. When false, only commands in commands.allowlist are permitted.

When commands.allow_all is false, only commands matching the agent's allowlist are permitted.

Command arguments are checked for path traversal patterns (../).

Pipeline segment checking: Each segment of piped commands is checked independently.

Key files: core/tooling/handler_base.py (_BLOCKED_CMD_PATTERNS, _INJECTION_RE), core/tooling/handler_perms.py (_check_command_permission)

Each agent operates within its own directory (~/.animaworks/animas/{name}/). File access is controlled by file_roots in permissions.json — default ["/"] grants full access within the anima directory; restricted roots limit writable paths. Mode C (Codex) sandbox adapts dynamically: file_roots: ["/"] → danger-full-access; restricted → workspace-write with dynamic writable_roots.

These cannot be written by the agent that owns them:

• permissions.json — Pydantic-validated tool, file, and command permissions (replaces legacy permissions.md)
• permissions.md — Legacy file; protected when present (auto-migrated to JSON)
• identity.md — Core personality (immutable baseline)
• bootstrap.md — First-run instructions
• activity_log/ — Activity log directory; only ActivityLogger (code-level) may append entries

Descendant resolution uses BFS with cycle detection. Peers (same supervisor) can read each other's activity_log/.

Key files: core/tooling/handler_base.py (_PROTECTED_FILES, _PROTECTED_DIRS, _is_protected_write), core/tooling/handler_perms.py (_check_file_permission)

Each agent runs as an independent OS process:

• Process isolation: Crash in one agent doesn't affect others
• Unix Domain Socket IPC: Inter-process communication over filesystem sockets (no TCP)
• Independent locks: Chat, Inbox, and background tasks use separate asyncio locks
• Socket directory: ~/.animaworks/run/sockets/{name}.sock with stale socket cleanup on startup

Key files: core/supervisor/manager.py, core/supervisor/ipc.py, core/supervisor/runner.py

• No duplicate DM to the same recipient
• Max 2 distinct DM recipients per execution
• One channel post per channel per session
• Cross-session channel post cooldown (channel_post_cooldown_s)
• Persisted to run/replied_to.jsonl

• Configurable per-agent send limits (hourly and daily)
• Computed from activity_log sliding window
• ack, error, system_alert messages are exempt

Recent outbound messages (last 2 hours, max 3) are injected into the system prompt via Priming.

• Conversation depth limiter: Configurable max turns within depth_window_s
• Inbox rate limiter: Cooldown, cascade detection, per-sender rate limit
• Fail-closed: Returns False on activity log read failure

Key files: core/tooling/handler_comms.py, core/cascade_limiter.py, core/supervisor/inbox_rate_limiter.py, core/memory/priming.py

• Argon2id password hashing (memory-hard, side-channel resistant)
• 48-byte URL-safe tokens (cryptographically random)
• Max 10 sessions per user — oldest evicted on overflow
• Session TTL — config.server.session_ttl_days (default: 7 days). Expired sessions are rejected and removed in validate_session().
• Password change revokes sessions — change_password() calls revoke_all_sessions() to invalidate all sessions
• Cookie-based session transport with middleware guard on /api/ and /ws routes
• Config files saved with 0600 permissions

When trust_localhost is enabled, requests from loopback addresses are authenticated automatically. Origin and Host header checks mitigate CSRF.

Key files: core/auth/manager.py, server/app.py, server/localhost.py

Both use constant-time comparison (hmac.compare_digest).

Key file: server/routes/webhooks.py

The media proxy (/api/media/proxy) fetches external images for display in the UI:

• HTTPS only
• Domain allowlist or open-with-scan — configurable via MediaProxyConfig.mode
• Private IP blocking — localhost, RFC 1918, link-local, multicast, reserved
• DNS resolution check — prevents DNS rebinding
• Content-Type validation — only image/jpeg, image/png, image/gif, image/webp; SVG blocked
• Magic bytes verification — validates actual file format matches declared content-type
• Size limit — max_bytes (default 5 MB)
• Redirect validation — redirect targets re-validated; max redirect count enforced
• Per-IP rate limiting — configurable (default 30 req/min)
• Security headers — X-Content-Type-Options: nosniff

Key file: server/routes/media_proxy.py

When running on Claude Agent SDK (Mode S), additional guardrails apply via PreToolUse hooks:

• Bash command filtering: Separate blocklist for SDK (includes Chatwork CLI bypass prevention, network exfiltration tools, data upload patterns)
• File write protection: Validates against protected file list and sandbox
• File read restriction: Blocks access to other agents' directories (except subordinate/peer activity_log, subordinate management files)
• Output truncation: Bash output capped at 10KB; file reads default-limited to 500 lines; grep/glob also limited
• Trust tracking: _SDK_TOOL_TRUST mapping; persisted to run/min_trust_seen

Key files: core/execution/_sdk_security.py, core/execution/_sdk_hooks.py

resolve_recipient() prevents agents from sending to unintended recipients:

1. Exact match against known agent names (case-sensitive)
2. User alias lookup (case-insensitive)
3. Platform-prefixed recipients
4. Slack User ID pattern match
5. Case-insensitive agent name match
6. Unknown recipients → RecipientNotFoundError (fail-closed)

Key file: core/outbound.py

DMs carry origin_chain metadata, built by build_outgoing_origin_chain(). Receivers can evaluate the trust lineage of messages.

Messenger.receive() validates from_person against known_animas (config.animas). Unknown from_person is rejected and logged.

Inbox directories are created with 0o700 permissions.

_SAFE_NAME_RE = re.compile(r"^[a-z][a-z0-9_-]{0,30}$") prevents path traversal.

Channel posts are limited to max_length=10000 via Pydantic.

Key files: core/messenger.py, core/tooling/handler_comms.py, core/tooling/handler_base.py

Vulnerabilities identified in the initial audit that have been addressed:

┌─────────────────────────────────────────────────────────┐
│                    External Data                        │
│          (Web, Slack, email, Board, DM, etc.)            │
└────────────────────────┬────────────────────────────────┘
                         │
              ┌──────────▼──────────┐
              │  Trust Boundary     │  ← untrusted/medium/trusted tags
              │  Labeling           │  ← origin chain propagation
              └──────────┬──────────┘
                         │
              ┌──────────▼──────────┐
              │  Auth & Session     │  ← Argon2id, TTL-enforced sessions
              │  Management         │  ← Webhook HMAC verification
              └──────────┬──────────┘
                         │
     ┌───────────────────┼───────────────────┐
     │                   │                   │
┌────▼────┐      ┌──────▼──────┐     ┌──────▼──────┐
│ Command │      │ File Access  │     │  Outbound   │
│ Security│      │   Control    │     │  Rate Limit │
│ (5-layer│      │ (sandbox +   │     │  (3-layer + │
│  check) │      │  ACL)        │     │   cascade)  │
└────┬────┘      └──────┬──────┘     └──────┬──────┘
     │                  │                   │
     └───────────────┐  │  ┌────────────────┘
                     │  │  │
              ┌──────▼──▼──▼────────┐
              │  Memory Provenance  │  ← origin tracking in RAG/knowledge
              │  (trust chain)      │  ← Channel C trust splitting
              └──────────┬──────────┘
                         │
              ┌──────────▼──────────┐
              │  Process Isolation  │  ← per-agent OS process
              │  (Unix sockets)     │  ← independent locks
              └─────────────────────┘

Each layer operates independently. A failure in one layer is caught by others.

Effort scale: XS = less than 1 hour, S = 1–4 hours, M = 4–16 hours, L = more than 16 hours