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

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

File: src/security/network-policy.ts

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

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

The isBlockedPrivateOrLinkLocalIp() function blocks access to:

File: src/runtime/custom-actions.ts (isBlockedUrl())

After hostname validation, the isBlockedUrl() function performs DNS resolution (via node:dns/promises lookup) and checks every resolved IP address against the blocklist using isBlockedPrivateOrLinkLocalIp() from network-policy.ts. This prevents DNS rebinding and split-horizon DNS attacks where a hostname resolves to a private IP.

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

See src/security/network-policy.test.ts for comprehensive tests including IPv4, IPv6, mapped addresses, and edge cases.

File: src/api/server.ts (line ~812)

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:

• 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)
• ELECTRON_RUN_AS_NODE — escape Electron sandbox
• NODE_PATH — module resolution override

• 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

• MILADY_API_TOKEN — API authentication
• MILADY_WALLET_EXPORT_TOKEN — wallet private key export
• MILADY_TERMINAL_RUN_TOKEN — shell command execution
• HYPERSCAPE_AUTH_TOKEN — cloud service auth

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

• PATH, HOME, SHELL — system path manipulation

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

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

The shell execution endpoint applies multiple constraints:

• Token authentication — requires MILADY_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

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.

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.

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.

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

File: apps/app/electron/src/native/desktop.ts

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

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

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

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

• MILADY_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

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

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.

File: src/api/server.ts

The isBlockedObjectKey() function (line ~2835) 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).

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

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