​

GAIA Security Model

⚠️ Partially superseded by Agent UI v2 (agent-ui.mdx + agent-ui-agent-capabilities-plan.md §0). This doc’s localhost-trust framing (an unauthenticated loopback port is safe because only local processes reach it) no longer holds under v2: agents run as out-of-process sidecars that must authenticate on every leg — see §0.11 (per-spawn secret + per-agent-scoped callback token) and §0.24 (third-party trust root + egress containment). Read v2 §0 before relying on the localhost-only assumptions below.

Date: 2026-04-01 Status: Planning Milestones: v0.17.2, v0.18.2, v0.21.0, v0.23.0 Related issues: #94, #438, #447, #459, #461, #559 Prerequisites: None (security is cross-cutting)

​

1. Executive Summary

​

2. Threat Model

​

2.1 Attack Surface

​

2.2 Trust Boundaries

+-----------------------------------------------------------+
|  TRUSTED: Local User Session                              |
|  - Desktop UI (Electron IPC)                              |
|  - CLI (gaia chat, gaia-code)                             |
|  - Local filesystem                                       |
|                                                           |
|  +-----------------------------------------------------+ |
|  |  SEMI-TRUSTED: MCP Servers (localhost)               | |
|  |  - Playwright, Brave Search, Fetch                   | |
|  |  - User-configured servers from ~/.gaia/mcp.json     | |
|  |  - npm packages (verified via checksum)              | |
|  +-----------------------------------------------------+ |
|                                                           |
|  +-----------------------------------------------------+ |
|  |  UNTRUSTED: External Inputs                          | |
|  |  - Messaging adapters (Discord, Slack, Telegram)     | |
|  |  - Web content fetched via Fetch/Playwright          | |
|  |  - Third-party skills from marketplace               | |
|  |  - User-uploaded documents (PDF, DOCX)               | |
|  +-----------------------------------------------------+ |
+-----------------------------------------------------------+

​

3. Security Architecture Overview

​

3.1 Localhost-Only Communication

• The MCP bridge (src/gaia/mcp/mcp_bridge.py) and API server (src/gaia/api/) must reject non-loopback bind addresses unless --dangerous-allow-remote is explicitly passed (v0.23.0).
• The Windows installer and setup wizard should configure Windows Firewall to block inbound connections to GAIA ports.

​

3.2 Defense in Depth

Layer 1: Network isolation (localhost-only, no public ports)
    |
Layer 2: Tool classification (auto-approve / confirm / deny)
    |
Layer 3: Input validation (command whitelist, URL allowlist, sanitization)
    |
Layer 4: Execution sandboxing (subprocess isolation, timeout, resource limits)
    |
Layer 5: Audit trail (all tool executions logged to SQLite)
    |
Layer 6: Credential isolation (encrypted vault, never logged)

​

4. Tool Execution Guardrails

​

4.1 Tool Classification Tiers

​

4.2 MCP Tool Classification

# Proposed location: src/gaia/agents/base/security.py

MCP_AUTO_APPROVE = {
    # Playwright -- read-only browser operations
    "browser_navigate",
    "browser_snapshot",
    "browser_console_messages",
    "browser_network_requests",
    "browser_tabs",
    "browser_wait_for",
    "browser_evaluate",
    "browser_navigate_back",
    "browser_close",
    # Brave Search -- all operations are read-only
    "brave_web_search",
    "brave_local_search",
    # Fetch -- read-only HTTP
    "fetch",
}

MCP_ALWAYS_CONFIRM = {
    # Playwright -- write operations (mutate page state)
    "browser_click",
    "browser_fill_form",
    "browser_file_upload",
    "browser_type",
    "browser_select_option",
    "browser_press_key",
    "browser_drag",
    "browser_hover",
}

# Any MCP tool not in either set --> CONFIRM by default.
# Unknown tools from newly connected MCP servers always require confirmation
# until the user explicitly promotes them to auto-approve via config.

​

4.3 Confirmation Flow

1. Agent requests tool execution via SSE event.
2. UI displays a modal: tool name, arguments (truncated), risk tier.
3. User clicks “Allow” or “Deny”.
4. Result sent back via MCP bridge POST.
5. If denied, agent receives {"status": "denied", "reason": "user_rejected"} and must replan without that tool.

1. Agent prints tool name and arguments to console.
2. Prompt: Execute [tool_name]? (y/n/always):
3. “always” adds the tool to session-level auto-approve (not persisted).

​

4.4 Implementation: @tool Decorator Extension

# Extension to src/gaia/agents/base/tools.py

@tool(risk_tier="write")
def write_file(path: str, content: str) -> dict:
    """Write content to a file."""
    ...

@tool(risk_tier="read")
def read_file(path: str) -> dict:
    """Read a file and return its contents."""
    ...

​

5. MCP Security

​

5.1 Sandboxed Execution

​

5.2 Unknown Tool Default

1. GAIA calls tools/list on the server to discover available tools.
2. All discovered tools are classified as CONFIRM by default.
3. The user can promote individual tools to AUTO-APPROVE via the Settings UI.
4. Promoted tools are stored in ~/.gaia/config.json under mcp.trusted_tools.

{
  "mcp": {
    "trusted_tools": {
      "github": ["list_repos", "get_issue", "search_code"],
      "context7": ["resolve_library_id", "get_library_docs"]
    }
  }
}

​

5.3 npm Package Verification

1. Package name must be scoped (@modelcontextprotocol/server-* or @anthropic/*).
2. Package integrity is checked via npm’s --prefer-offline and lockfile hashes.
3. Unscoped packages display a warning: “This MCP server is from an unverified publisher. Proceed?”
4. A future AMD Verified badge (v0.24.0) will indicate code-signed packages.

​

6. Audit Trail

​

6.1 What is Logged

​

6.2 Storage

# Location: ~/.gaia/audit.db

CREATE TABLE tool_executions (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    timestamp TEXT NOT NULL DEFAULT (datetime('now')),
    session_id TEXT NOT NULL,
    tool_name TEXT NOT NULL,
    tool_source TEXT NOT NULL,
    risk_tier TEXT NOT NULL,
    arguments TEXT,          -- JSON, secrets redacted
    result_status TEXT NOT NULL,
    result_summary TEXT,
    user_confirmed INTEGER DEFAULT 0,
    duration_ms INTEGER,
    input_channel TEXT NOT NULL DEFAULT 'cli'
);

CREATE INDEX idx_tool_executions_session ON tool_executions(session_id);
CREATE INDEX idx_tool_executions_timestamp ON tool_executions(timestamp);
CREATE INDEX idx_tool_executions_tool ON tool_executions(tool_name);

​

6.3 UI Integration

• Filterable by session, tool, risk tier, date range.
• Exportable as CSV or JSON.
• Destructive/denied actions are highlighted.

gaia audit list                    # Last 50 entries
gaia audit list --tool write_file  # Filter by tool
gaia audit list --risk destructive # Filter by risk tier
gaia audit export --format json    # Export full audit log

​

6.4 Secret Redaction

• Any value matching a known credential pattern (API keys, tokens, passwords) is replaced with [REDACTED].
• Fields named password, token, secret, api_key, auth, credential are always redacted regardless of value.
• The redaction function lives in src/gaia/agents/base/security.py.

​

7. Credential Management

​

7.1 Current State (Insecure)

• ATLASSIAN_SITE_URL, ATLASSIAN_EMAIL, ATLASSIAN_API_TOKEN (Jira)
• GITHUB_TOKEN (GitHub MCP)
• BRAVE_API_KEY (Brave Search MCP)
• PERPLEXITY_API_KEY (web search fallback)
• DISCORD_BOT_TOKEN, SLACK_BOT_TOKEN, TELEGRAM_BOT_TOKEN (messaging)

​

7.2 Target: Encrypted Credential Vault

# Location: src/gaia/security/credential_vault.py

class CredentialVault:
    """Encrypted credential storage for GAIA."""

    def __init__(self, path: str = "~/.gaia/credentials.db"):
        ...

    def store(self, service: str, key: str, value: str) -> None:
        """Encrypt and store a credential."""
        ...

    def retrieve(self, service: str, key: str) -> str:
        """Retrieve and decrypt a credential."""
        ...

    def delete(self, service: str, key: str) -> None:
        """Remove a credential."""
        ...

    def list_services(self) -> List[str]:
        """List services with stored credentials (not the values)."""
        ...

​

7.3 Migration Path

1. v0.18.2: Introduce CredentialVault class, support both env vars and vault.
2. v0.21.0: UI for managing credentials (add/remove/rotate).
3. v0.23.0: Deprecate env var credentials with warning; vault is primary.
4. v0.24.0: Env var credentials removed from documentation.

​

7.4 Logging Rules

• Credentials MUST NEVER appear in log output, audit trail, error messages, or crash reports.
• The format_execution_trace function in src/gaia/agents/base/errors.py must scrub tool arguments before formatting.
• MCP server configs with env keys containing TOKEN, KEY, SECRET, PASSWORD, or CREDENTIAL must mask values in all debug output.

​

8. Browser Security

​

8.1 URL Allowlist

{
  "browser_security": {
    "mode": "allowlist",
    "allowed_domains": [
      "*.google.com",
      "*.github.com",
      "*.stackoverflow.com",
      "*.wikipedia.org",
      "*.python.org",
      "*.npmjs.com",
      "*.docs.rs",
      "*.developer.mozilla.org"
    ],
    "blocked_domains": [
      "*.onion",
      "localhost",
      "127.0.0.1",
      "0.0.0.0",
      "*.local"
    ],
    "max_concurrent_tabs": 3,
    "navigation_timeout_ms": 30000,
    "allow_downloads": false,
    "allow_file_protocol": false
  }
}

​

8.2 Domain Restriction Enforcement

1. Parse the target URL.
2. Check domain against allowed_domains (glob matching).
3. Check domain against blocked_domains (always takes precedence).
4. If domain is not in either list, prompt user for confirmation.
5. file://, javascript:, data: protocols are always blocked.

​

8.3 Content Security

• Pages that attempt to open new windows or popups are blocked.
• JavaScript alert(), confirm(), prompt() dialogs are auto-dismissed.
• Downloaded files are quarantined to ~/.gaia/downloads/ and never auto-executed.
• Cookie and localStorage data is isolated per session (no persistence across agent restarts).

​

9. Desktop Control Security

​

9.1 Opt-In Model

# CLI opt-in
gaia config set desktop_control.enabled true

# Or via Electron UI: Settings > Security > Desktop Control > Enable

​

9.2 Permission Tiers

​

9.3 Screenshot Permissions

• Screenshots are stored in ~/.gaia/screenshots/ with session-scoped filenames.
• Screenshots are auto-deleted after session ends (configurable retention).
• Screenshots are never sent to external services (processed locally via VLM).
• The Electron UI displays a persistent indicator when screenshot capture is active.

​

9.4 Safety Constraints

• Desktop control actions execute with a minimum 500ms delay between actions (prevents runaway automation).
• A global kill switch: pressing Escape three times rapidly cancels all pending desktop control actions.
• Desktop control is not available over messaging adapters (CLI and desktop UI only).
• CUA sessions are time-bounded (default: 5 minutes, configurable).

​

10. Dangerous Mode

​

10.1 Purpose

​

10.2 Activation

# CLI activation -- requires typing the full flag
gaia chat --dangerous-mode

# Confirmation prompt (cannot be suppressed)
# WARNING: Dangerous mode bypasses all tool confirmation gates.
# All tool executions will proceed without asking for approval.
# Audit logging remains active.
#
# Type "I understand the risks" to continue:

• Enabled via config file (must be per-session, explicit).
• Activated over messaging adapters (Discord, Slack, Telegram).
• Activated via the API server (only CLI and desktop UI).
• Combined with desktop control permissions (CUA always requires confirmation).

​

10.3 What Changes in Dangerous Mode

​

10.4 Visual Indicators

• CLI: Red banner [DANGEROUS MODE] in prompt.
• Desktop UI: Red border on chat window, persistent warning badge.
• Audit log: All entries during dangerous mode are tagged dangerous_mode: true.

​

11. Skill/Plugin Security

• Skills declare permissions in YAML frontmatter using domain-scoped syntax (filesystem:read, network:write, etc.)
• Three security tiers: AMD Verified, Community Reviewed, Experimental
• Skills run in isolated context with restricted _TOOL_REGISTRY access
• Dedicated working directory per skill: ~/.gaia/skills/<skill_name>/
• Code signing infrastructure planned for v0.24.0 (#462-#465)

​

12. Messaging Security

​

12.1 Threat: Untrusted Input

​

12.2 Restricted Default Tool Set

MESSAGING_ALLOWED_TOOLS = {
    # Read-only tools only
    "search_web",
    "brave_web_search",
    "brave_local_search",
    "fetch",
    "read_file",          # Read-only, within allowed paths
    "search_documents",   # RAG search
    "list_documents",     # RAG listing
}

MESSAGING_DENIED_TOOLS = {
    # Never available over messaging
    "write_file",
    "delete_file",
    "run_cli_command",
    "browser_click",
    "browser_fill_form",
    "browser_type",
    # All desktop control tools
    "screenshot",
    "mouse_click",
    "keyboard_type",
}

​

12.3 Input Sanitization

1. Length limit: Messages exceeding 4,000 characters are truncated.
2. Injection filtering: Known prompt injection patterns are detected and blocked (e.g., “ignore previous instructions”, “system prompt:”, role-switching attempts).
3. PII filtering: Outbound responses are scanned for potential PII leakage (email addresses, phone numbers, SSNs). Detected PII is replaced with [PII REDACTED] in responses sent back to the messaging platform.
4. Rate limiting: Per-user, per-channel, and global rate limits (see messaging-integrations-plan.mdx Section 7 for configuration).

​

12.4 Identity Isolation

• Sessions are keyed by (platform, user_id, channel_id).
• No cross-session data leakage.
• Sessions have a configurable TTL (default: 24 hours).
• Session history is stored in ~/.gaia/messaging/sessions.db, separate from the main audit log.

​

13. Pickle Deserialization Vulnerability — Mitigated in v0.17.2

​

13.1 Historical Vulnerability

​

13.2 What v0.17.2 shipped

​

13.3 Future hardening (tracked as follow-up)

1. Immediate (v0.17.2): Replace pickle.dump/pickle.load with json for the cache data structure. The cached data (chunks, full_text, metadata) is JSON-serializable.
2. If JSON is insufficient (e.g., numpy arrays in embeddings): Use numpy.save/numpy.load with allow_pickle=False for embedding vectors, and JSON for metadata.
3. Cache integrity: Add HMAC-SHA256 verification to cache files. The HMAC key is derived from the file content hash, ensuring tampered caches are rejected.

# Before (vulnerable):
with open(cache_path, "rb") as f:
    cached_data = pickle.load(f)

# After (safe):
with open(cache_path, "r") as f:
    cached_data = json.load(f)
# Verify HMAC before using cached_data

4. Migration: Existing .pkl cache files are invalidated on upgrade. Users will see a one-time re-indexing of their documents.

​

14. Phased Rollout

​

Phase 1: v0.17.2 — Critical Fixes

​

Phase 2: v0.18.2 — Foundation Guardrails

​

Phase 3: v0.21.0 — Browser and Desktop

​

Phase 4: v0.23.0 — Autonomous Execution

​

Phase 5: v0.24.0 — Marketplace Security

​

15. GitHub Issue Cross-References

​

16. Existing Security Measures

​

17. Open Questions

1. Credential vault key management: Should the vault encryption key be hardware-backed (TPM/fTPM on AMD platforms) or software-derived (DPAPI/Keychain)? TPM provides stronger security but adds platform-specific complexity.
2. Prompt injection detection: What detection model should be used? Options range from regex heuristics to a dedicated classifier model. The classifier approach is more robust but adds latency and model dependency.
3. Skill sandboxing depth: Should skills run in a separate Python subprocess (strong isolation, high overhead) or in-process with restricted globals (weaker isolation, low overhead)?
4. Audit log retention: What is the default retention period? Options: 30 days, 90 days, unlimited. Unlimited is safest for compliance but grows the database.
5. Browser allowlist management: Should the default allowlist be permissive (allow all, block known-bad) or restrictive (block all, allow known-good)? The current proposal is restrictive, which is safer but may frustrate users who browse diverse sites.