elizaos--eliza/packages/docs/security.md

title, sidebarTitle, description

title	sidebarTitle	description
Security architecture	Security	Security layers, hardening measures, and review notes for the Eliza codebase.

Security Architecture

This document describes the security architecture and hardening measures implemented in the Eliza codebase. It is intended for developers, auditors, and contributors who want to understand the defensive layers in place.

---

Table of Contents

1. SSRF Protection
2. Environment Variable Blocklist
3. SQL Injection Guards
4. Command Injection Defenses
5. Prototype Pollution Prevention
6. Plugin Installation Safety
7. Electrobun RPC Validation
8. Auth & Token Model
9. DNS Rebinding Protection
10. Configuration Injection Prevention

---

SSRF Protection

Canonical implementation: packages/core/src/network/ssrf.ts

All user-supplied URLs (e.g. knowledge ingestion, web fetches) are validated through a multi-layer SSRF defense:

URL Protocol Validation

Only http: and https: protocols are permitted. This blocks file:, ftp:, gopher:, data:, and other protocol-based attacks.

IP Address Blocklist

The isPrivateIpAddress() policy blocks access to:

Range	Purpose
0.0.0.0/8	"This" network
10.0.0.0/8	RFC 1918 private
127.0.0.0/8	Loopback
100.64.0.0/10	Carrier-grade NAT / shared address space
169.254.0.0/16	Link-local / cloud metadata
172.16.0.0/12	RFC 1918 private
192.168.0.0/16	RFC 1918 private
::	IPv6 unspecified
::1	IPv6 loopback
fc00::/7	IPv6 unique local
fec0::/10	Deprecated IPv6 site-local
fe80::/10	IPv6 link-local
ff00::/8	IPv6 multicast
::ffff: mapped	IPv4-mapped IPv6 addresses (decoded and rechecked)

DNS Resolution Verification

File: packages/core/src/network/ssrf.ts (fetchWithSsrfGuard())

After hostname validation, guarded fetch resolves and checks every resolved IP address, then pins the connection to the approved address. Redirects are revalidated. This prevents DNS rebinding and split-horizon DNS attacks where a hostname resolves to a private IP.

Hostname Blocklist

Literal hostnames like localhost, metadata.google.internal, and cloud metadata service hostnames are explicitly blocked.

Test Coverage

See packages/core/src/network/ssrf.test.ts for IPv4, IPv6, mapped/non-canonical addresses, DNS pinning, and edge cases.

---

Environment Variable Blocklist

File: src/api/server.ts

The BLOCKED_ENV_KEYS set prevents the API from writing to security-sensitive environment variables via PUT /api/env. Without this, an attacker with API access could:

System Injection Vectors (blocked)

• LD_PRELOAD, LD_LIBRARY_PATH — shared library injection (Linux)
• DYLD_INSERT_LIBRARIES, DYLD_LIBRARY_PATH — dylib injection (macOS)
• NODE_OPTIONS — arbitrary Node.js flags (e.g. --require for code injection)
• NODE_PATH — module resolution override

TLS/Proxy Hijack (blocked)

• NODE_TLS_REJECT_UNAUTHORIZED — setting to "0" disables all certificate verification, enabling MITM of API key traffic
• HTTP_PROXY, HTTPS_PROXY, ALL_PROXY — redirects all traffic through attacker proxy
• SSL_CERT_FILE, SSL_CERT_DIR, CURL_CA_BUNDLE, NODE_EXTRA_CA_CERTS — trust rogue CAs

Privilege Escalation Tokens (blocked)

• ELIZA_API_TOKEN — API authentication
• ELIZA_WALLET_EXPORT_TOKEN — wallet private key export
• ELIZA_TERMINAL_RUN_TOKEN — shell command execution

Sensitive Credentials (blocked)

• EVM_PRIVATE_KEY, SOLANA_PRIVATE_KEY — wallet private keys
• GITHUB_TOKEN — source code access
• DATABASE_URL, POSTGRES_URL — database connection strings

System Paths (blocked)

• PATH, HOME, SHELL — system path manipulation

---

SQL Injection Guards

File: src/api/database.ts

The database API enforces read-only query execution with multiple layers:

1. Mutation keyword detection — Blocks INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, TRUNCATE, REPLACE, ATTACH, DETACH, PRAGMA (write-mode)
2. Dangerous function detection — Blocks PostgreSQL-specific functions that could escape the query sandbox:
   • File I/O: pg_read_file, pg_write_file, pg_stat_file, pg_ls_dir, lo_import, lo_export
   • Sequence/state mutation: nextval, setval
   • Denial of service: pg_sleep, pg_sleep_for, pg_sleep_until
   • Backend control: pg_terminate_backend, pg_cancel_backend, pg_reload_conf, set_config
   • Advisory locks: pg_advisory_lock, pg_advisory_unlock, and variants
3. Read-only mode — Queries execute in read-only mode as a defense-in-depth measure

---

Command Injection Defenses

Terminal Run Endpoint

File: src/api/server.ts (/api/terminal/run)

The shell execution endpoint applies multiple constraints:

• Token authentication — requires ELIZA_TERMINAL_RUN_TOKEN
• Length limit — commands are capped at a maximum character length
• Control character rejection — newlines, carriage returns, and other control characters are blocked to prevent command chaining
• Rate limiting — concurrent shell executions are bounded

Sandbox Routes

File: src/api/sandbox-routes.ts

The runCommand() helper uses execFileSync with argument arrays, preventing shell metacharacter injection for general command execution. Note that execSync is also used elsewhere in the file for platform-specific operations (PowerShell commands, osascript, wmctrl/xdotool, audio recording, Docker). Variables used in commands are bounded integers or server-generated paths, never raw user input.

Custom Actions

File: src/runtime/custom-actions.ts

Shell and code execution handlers are gated behind explicit configuration flags. The VM sandbox uses vm.runInNewContext with a restricted global scope.

---

Prototype Pollution Prevention

File: src/api/server.ts

Object property manipulation endpoints explicitly block dangerous keys:

• __proto__
• constructor
• prototype

This prevents prototype pollution attacks that could modify the behavior of all JavaScript objects in the runtime.

---

Plugin Installation Safety

Files: src/services/plugin-installer.ts, src/services/plugin-eject.ts, src/services/core-eject.ts

All npm install and bun install calls include the --ignore-scripts flag to prevent:

• Postinstall RCE from malicious packages
• Lifecycle script execution during dependency installation
• Supply chain attacks via compromised npm packages

---

Electrobun RPC Validation

File: packages/app-core/platforms/electrobun/src/native/desktop.ts

shell.openExternal Validation

URLs passed to shell.openExternal are validated to only allow http: and https: schemes. This prevents:

• file: scheme abuse (reading local files)
• javascript: scheme execution
• Custom protocol handler attacks

shell.showItemInFolder Validation

File paths are validated to prevent path traversal and ensure they point to legitimate filesystem locations.

Context Menu

The "Open Link in Browser" context menu option routes through the same validated openExternal helper, preventing bypass via right-click.

---

Auth & Token Model

API Token

• ELIZA_API_TOKEN — Required for authenticated API access when set
• Token is checked on every request in the middleware chain

Wallet Export Token

• ELIZA_WALLET_EXPORT_TOKEN — Required to export private keys via /api/wallet/export
• Separate from the API token as an additional layer of defense
• Private keys are masked in all other API responses

Terminal Run Token

• ELIZA_TERMINAL_RUN_TOKEN — Required to execute shell commands via /api/terminal/run
• Separate from API token to prevent accidental shell access

---

DNS Rebinding Protection

File: src/api/server.ts

Host header validation prevents DNS rebinding attacks where an attacker's domain resolves to 127.0.0.1 and bypasses same-origin policy. The server validates the Host header against expected values.

---

Configuration Injection Prevention

File: src/api/server.ts

$include Directive Blocking

The isBlockedObjectKey() function blocks dangerous property keys including $include directives across all object property manipulation endpoints — not just config writes. This prevents including arbitrary files from the filesystem into any object, potentially leaking secrets or overriding security settings. The same guard also blocks __proto__, constructor, and prototype (see Prototype Pollution Prevention).

Top-Level Key Allowlist

Only known top-level configuration keys are accepted (CONFIG_WRITE_ALLOWED_TOP_KEYS). This prevents injection of arbitrary configuration properties.

---

Reporting Security Issues

If you discover a security vulnerability, please report it responsibly through a private channel — do not open a public GitHub issue, as this risks 0-day disclosure. Use one of:

• GitHub private vulnerability reporting via the repository's Security tab
• Direct contact with the maintainers