Security Architecture

Overview

Security-first design with 7 defense layers:

1. Input Validation - Zod schemas at all boundaries
2. Secrets Vault - Never expose API keys or tokens
3. Rate Limiting - Token bucket per tool
4. Memory Bounds - Context pruning, history caps
5. Path Safety - Normalized paths, directory jails
6. Timeout Protection - TimeoutGuard for async operations
7. Byzantine Detection - WeightedVoting pattern detection (exported, not on the consensus_vote path — see Threat Model)

Authentication & Access Control

The MCP server ships one transport, StdioServerTransport (src/cli-server.ts, src/mcp/server.ts). It communicates with the parent process only — no network listener, so no other process can reach it. Process isolation is the access control; no authentication runs on this path.

There is no REST API mode. Earlier versions of this section described an api.enabled: true config key and an auto-generated ~/.nexus-agents/auth/rest-api-key; neither is implemented. AppConfigSchema (src/config/schemas.ts) has no api key, no source file references rest-api-key, and nothing under src/ opens an HTTP listener. An api: block in nexus-agents.yaml is not read by any code.

Token-Based Authentication (Issue #739)

The AuthHandler middleware (src/mcp/middleware/auth-handler.ts) and its token CLI are implemented; enforcement is not. No server code path calls AuthHandler.authenticate(), and no HTTP endpoint exists to present a token to (see MCP Middleware Security below).

Token management CLI commands:

nexus-agents auth init          # Generate new auth token
nexus-agents auth show          # Show token status (file path, permissions)
nexus-agents auth rotate        # Rotate token (invalidate old, generate new)
nexus-agents auth init --force  # Regenerate token (overwrite existing)

Security properties:

• Tokens are 64-character hex strings (32 bytes of crypto.randomBytes)
• Stored at ~/.nexus-agents/auth/server-token with 0600 permissions (owner read/write only)
• Directory created with 0700 permissions
• Timing-safe comparison (crypto.timingSafeEqual) prevents timing attacks
• Token shown only once on generation (not recoverable — rotate if lost)

Enabling authentication:

# nexus-agents.yaml
security:
  auth:
    enabled: true
    method: token # Only supported authentication method
    tokenHeader: Authorization # Header name for Bearer token
    tokenFile: ~/.nexus-agents/auth/server-token # Token storage path

Since 10.0, security.auth.method accepts only token. OAuth2 was never implemented; earlier versions accepted oauth2 but performed bearer-token checks. If your config sets security.auth.method: oauth2, change it to security.auth.method: token before upgrading. Otherwise config loading fails with migration guidance (#5681).

Or via environment variables:

export NEXUS_AUTH_ENABLED=true
nexus-agents --mode=server

Client usage: none today. Setting NEXUS_AUTH_ENABLED=true generates and logs the token file path at startup, but there is no listener that accepts an Authorization header, so no client can use the token.

Threat Model

Byzantine Failures is not on the live vote path. WeightedVoting (src/consensus/weighted-voting.ts) is exported from consensus/index.ts along with its factory createWeightedVoting, but neither has a non-test caller, and ConsensusEngine (src/consensus/engine.ts) — what consensus_vote runs — does not reference it. The class implements two of the four documented patterns (contrarian, collusion) and returns false without evaluating when fewer than 3 votes are present. See CONSENSUS_PROTOCOLS.md.

Reference: OWASP LLM Top 10 (LLM01: Prompt Injection)

MCP Middleware Security

Locally registered MCP tools are wrapped in a middleware pipeline by createSecureHandler (src/mcp/middleware/secure-handler.ts). Coverage is per-tool opt-in, not a transport chokepoint: each tool’s registration calls createSecureHandler itself, and a registration that does not is not covered. Upstream MCP proxy tools — registered by initUpstreamServers (src/cli-server-tools.ts) with a raw passthrough handler when the gateway lists upstream servers — receive none of the layers below; the server logs this at startup as upstreamProxiesUncovered: true. The registerTool() interception proxies (mcp/gateway/gateway-server-proxy.ts, mcp/tools/annotation-proxy.ts, mcp/tools/tool-observability-proxy.ts) add annotations, gateway dispatch and metrics; they do not add security layers.

Three rows need qualification:

• Policy Firewall. defaultConfig.security.policy.policyMode is enforce, but it is not read for the effective mode: stagePolicyFirewallForRollout (src/mcp/middleware/policy-registry.ts), called from cli-server-tools.ts at startup, sets the firewall to warn unless NEXUS_MCP_POLICY_ENFORCE=1 (#6431), in which case it runs enforce. In warn every rule is evaluated and every would-be denial is logged, none is applied. The startup record (cli-server-audit.ts) names the effective mode and its reason — policyMode: enforce (NEXUS_MCP_POLICY_ENFORCE) or warn (rollout default) — rather than the config value. Whether enforce becomes the default is #4988. The execution mode every call is evaluated under is security.policy.defaultMode, read-write by default since #6431 (read-only is an operator lock that forbids every manifest-classified mutation tool); the policy registry carries it to every secure handler.

• Authentication. AuthHandler is constructed at startup (cli-server-auth.ts) and can generate a token, but no server code path calls AuthHandler.authenticate() (grep -rn "\.authenticate(" src --exclude=*.test.ts returns nothing). On the stdio transport, process isolation is the access control (see Authentication & Access Control above); the token is never checked.

• Audit logging is opt-in. initializeAuditLogger (cli-server-audit.ts) returns null unless security.audit.enabled === true, and defaultConfig.security (config/schemas.ts) has no audit key, so a default install writes no audit log. Startup reports the absence (#4996).

CORS, security headers and request body-size limits are not implemented: the only transport is StdioServerTransport, and src/mcp/middleware/ contains no HTTP middleware. Earlier versions of this table listed them.

Configuration

Values marked default are what ships; the audit block is absent by default and must be added to enable audit logging.

security:
  policy:
    policyMode: enforce # default, but not read: NEXUS_MCP_POLICY_ENFORCE decides (see above); enforce | warn
    defaultMode: read-write # default; read-only is the operator's mutation lock (#6431)

  rateLimit:
    enabled: true # default
    requestsPerMinute: 60 # default

  audit: # not present by default — add this block to turn audit logging on
    enabled: true
    logDir: .nexus-agents/audit # per-repo (epic #2872); cross-repo override: ~/.nexus-agents/audit
    minSeverity: info # info | warning | critical
    enableHashChain: false # Tamper-evident log chain
    maxFileSizeBytes: 10485760
    maxFiles: 10

Sandbox Execution

All agent-executed code runs through the sandbox system.

Execution Modes

Real isolation: out-of-process via OpenCode sandbox bootstrap (#2500)

Nexus-agents is sandbox-compatible, not a sandbox-builder. The in-process Docker / Deno executors were deleted in #2551 — they were dead code masquerading as security boundary. For real isolation, set the NEXUS_SANDBOX environment variable and run nexus-agents inside an OpenCode-managed Docker sandbox; see docs/guides/SANDBOXED-USAGE.md.

The container and deno modes are kept in the SandboxMode config union so existing config files don’t fail validation, but the factory resolves both to policy mode at runtime with a warning. New deployments wanting container-level isolation should use the OpenCode bootstrap.

Command Classification

Resource Limits

Environment Sanitization

Variables blocked from execution context:

const BLOCKED_PREFIXES = [
  'API_',
  'TOKEN_',
  'SECRET_',
  'KEY_',
  'PASSWORD_',
  'CREDENTIAL_',
  'AWS_',
  'AZURE_',
  'GCP_',
  'ANTHROPIC_',
  'OPENAI_',
  'GOOGLE_AI_',
];

function sanitizeEnv(env: Record<string, string>): Record<string, string> {
  return Object.fromEntries(
    Object.entries(env).filter(
      ([key]) => !BLOCKED_PREFIXES.some((prefix) => key.startsWith(prefix))
    )
  );
}

Secrets Vault Pattern

class SecretsVault {
  private readonly secrets: Map<string, string>;

  get(key: string): string | undefined {
    // Audit log access
    return this.secrets.get(key);
  }

  // Sanitize before any output
  sanitize(text: string): string {
    for (const secret of this.secrets.values()) {
      text = text.replaceAll(secret, '[REDACTED]');
    }
    return text;
  }
}

Usage Rules

1. Never log secrets - Use sanitize() before any logging
2. Never return secrets - Sanitize all tool outputs
3. Audit access - Log when secrets are accessed
4. Rotate regularly - Support key rotation without restart

Input Validation Pipeline

const validateInput = (input: unknown): Result<ValidInput, ValidationError> => {
  // 1. Schema validation (Zod)
  const parsed = InputSchema.safeParse(input);
  if (!parsed.success) return { ok: false, error: parsed.error };

  // 2. Business rule validation
  if (parsed.data.value < 0) {
    return { ok: false, error: new ValidationError('Value must be positive') };
  }

  // 3. Security checks (path traversal, injection, etc.)
  const sanitized = sanitizeInput(parsed.data);

  return { ok: true, value: sanitized };
};

Path Traversal Prevention

function validatePath(userPath: string, allowedRoot: string): Result<string, SecurityError> {
  const resolved = path.resolve(allowedRoot, userPath);
  if (!resolved.startsWith(allowedRoot)) {
    return { ok: false, error: new SecurityError('Path traversal detected') };
  }
  return { ok: true, value: resolved };
}

Directory Jail

All file operations are restricted to:

• Current working directory
• Explicitly allowed paths in config
• Temporary directories with cleanup

ReDoS Prevention

// NEVER do this - user-provided regex
const pattern = new RegExp(userInput); // DANGEROUS!

// ALWAYS do this - static patterns only
const VALID_PATTERN = /^[a-zA-Z0-9_-]+$/; // Static, safe pattern

// Validate against known-safe patterns
function validateIdentifier(input: string): boolean {
  return VALID_PATTERN.test(input);
}

CVE-2026-0621 Mitigation

TimeoutGuard for all async operations:

const result = await TimeoutGuard.execute(async () => await mcpTool.execute(args), {
  timeout: 30000,
  name: 'mcp-tool-call',
});

Rate Limiting

Token bucket per tool:

const rateLimiter = new TokenBucket({
  capacity: 100, // Max burst
  refillRate: 10, // Tokens per second
});

async function executeWithRateLimit<T>(fn: () => Promise<T>, cost: number = 1): Promise<T> {
  if (!rateLimiter.consume(cost)) {
    throw new RateLimitError('Rate limit exceeded');
  }
  return fn();
}

Per-Tool Limits

Sanitization Pipeline

All output passes through sanitization:

// Standard sanitization
const sanitized = logger.sanitize(text);
// API keys, tokens, passwords -> [REDACTED]

// Patterns matched
const REDACT_PATTERNS = [
  /sk-[a-zA-Z0-9]{48}/g, // Anthropic API keys
  /sk-[a-zA-Z0-9-_]{43}/g, // OpenAI API keys
  /ghp_[a-zA-Z0-9]{36}/g, // GitHub tokens
  /password["']?\s*[:=]\s*["']?[^"'\s]+/gi, // Password values
];

Security Audit Logging

Audit events are written as SIEM-compatible JSON-L to <repo>/.nexus-agents/audit/ by default — audit/ is per-repo state (epic #2872). Configurable via the audit.logDir config field or NEXUS_DATA_DIR.

Event Types

Enabling Audit Logging

security:
  audit:
    enabled: true
    minSeverity: info
    enableHashChain: true # Optional tamper-evident chain

Each event includes: timestamp, actor, tool name, request ID, duration, and outcome. With enableHashChain: true, events include a SHA-256 hash chain for tamper detection.

Configuration

security:
  sandbox:
    mode: policy # none | policy | container
    fallbackMode: none # Fallback if container unavailable
    resourceLimits:
      memory: 512m
      cpu: 2
      timeout: 300s
      maxProcesses: 10

  allowedPaths: [./] # Directory jail

  policy:
    policyMode: enforce # enforce | warn (not read for the effective mode; NEXUS_MCP_POLICY_ENFORCE decides)
    defaultMode: read-write # read-only | read-write (default read-write since #6431)

  rateLimit:
    enabled: true
    requestsPerMinute: 60

  audit:
    enabled: false # Set to true for structured audit logging
    logDir: .nexus-agents/audit # per-repo (epic #2872); cross-repo override: ~/.nexus-agents/audit
    minSeverity: info # info | warning | critical
    enableHashChain: false # Tamper-evident hash chain
    maxFileSizeBytes: 10485760 # 10 MB per log file
    maxFiles: 10 # Log rotation file count

Security Checklist

Before any code change:

• ☐Not done: No secrets in code, logs, or outputs
• ☐Not done: Input validation at all boundaries
• ☐Not done: Path traversal prevention on file ops
• ☐Not done: No user-provided RegExp (use static patterns)
• ☐Not done: Rate limiting on public interfaces
• ☐Not done: Memory bounds on collections
• ☐Not done: Timeout on external calls
• ☐Not done: Sanitization on all outputs

Agent-SafetyBench Evaluation

Comprehensive safety category taxonomy for agent evaluation (arXiv:2412.14470).

Safety Categories

Expected Outcomes

Usage

import { SAFETY_CATEGORIES, getSafetyTaxonomySummary } from 'nexus-agents';

// Get all categories
for (const category of SAFETY_CATEGORIES) {
  console.log(`${category.id}: ${category.defaultRiskLevel}`);
}

// Get summary statistics
const summary = getSafetyTaxonomySummary();
// { totalCategories: 10, totalCriteria: 42, ... }

Source Files

Penetration Testing

113 security tests covering:

• Container escape prevention
• Capability restrictions
• Network isolation
• Filesystem isolation
• Privilege escalation prevention
• Command injection prevention
• Environment variable sanitization
• CVE regression tests

Run with:

pnpm test src/security/sandbox-pentest.test.ts

Related Documents

• Consensus Protocols: CONSENSUS_PROTOCOLS.md (Byzantine detection)
• Routing System: ROUTING_SYSTEM.md (Budget limits)
• Full Architecture: ARCHITECTURE.md
• Coding Standards: CODING_STANDARDS.md