Security Configuration Guide

December 12, 2025 · View on GitHub

Table of Contents

Overview

The MCP ACS Process Server implements defense-in-depth security with multiple layers of validation to ensure AI agents can only perform authorized operations within strict boundaries. This guide explains how to configure security policies for your deployment.

Security Architecture

Six Layers of Validation

Every process launch request goes through six security layers:

  1. Executable Resolution - Verify executable exists and is accessible
  2. Dangerous Executable Check - Block known dangerous commands (sudo, rm, dd, etc.)
  3. Shell Interpreter Check - Optionally block shell access (bash, sh, cmd.exe, etc.)
  4. Privilege Check - Block setuid/setgid executables (Unix) or admin tools (Windows)
  5. Allowlist Check - Only permit explicitly allowed executables
  6. Argument Validation - Prevent command injection via arguments

Defense-in-Depth Principles

  • Fail Secure: If any validation layer fails, the operation is rejected
  • Least Privilege: Processes run with minimal permissions
  • Audit Everything: All operations are logged for forensics
  • No Bypass: Security checks cannot be disabled or bypassed at runtime

Configuration Options

Complete Configuration Schema

{
  // === EXECUTABLE CONTROL ===
  "allowedExecutables": ["node", "python3", "git"],
  "blockSetuidExecutables": true,
  "blockShellInterpreters": true,
  "additionalBlockedExecutables": [],

  // === ARGUMENT CONTROL ===
  "maxArgumentCount": 100,
  "maxArgumentLength": 4096,
  "blockedArgumentPatterns": [],

  // === ENVIRONMENT CONTROL ===
  "additionalBlockedEnvVars": [],
  "allowedEnvVars": [],
  "maxEnvVarCount": 100,

  // === WORKING DIRECTORY CONTROL ===
  "allowedWorkingDirectories": [],
  "blockedWorkingDirectories": [],

  // === RESOURCE LIMITS ===
  "defaultResourceLimits": {
    "maxCpuPercent": 80,
    "maxMemoryMB": 1024,
    "maxFileDescriptors": 1024,
    "maxCpuTime": 300,
    "maxProcesses": 10
  },
  "maximumResourceLimits": {
    "maxCpuPercent": 100,
    "maxMemoryMB": 4096,
    "maxFileDescriptors": 2048,
    "maxCpuTime": 3600,
    "maxProcesses": 50
  },
  "strictResourceEnforcement": true,

  // === PROCESS LIMITS ===
  "maxConcurrentProcesses": 10,
  "maxConcurrentProcessesPerAgent": 5,
  "maxProcessLifetime": 3600,
  "maxTotalProcesses": 1000,

  // === RATE LIMITING ===
  "maxLaunchesPerMinute": 10,
  "maxLaunchesPerHour": 100,
  "rateLimitCooldownSeconds": 60,

  // === TERMINATION CONTROL ===
  "allowProcessTermination": true,
  "allowGroupTermination": true,
  "allowForcedTermination": false,
  "requireTerminationConfirmation": false,

  // === I/O CONTROL ===
  "allowStdinInput": true,
  "allowOutputCapture": true,
  "maxOutputBufferSize": 10485760,
  "blockBinaryStdin": false,

  // === AUDIT & MONITORING ===
  "enableAuditLog": true,
  "auditLogPath": "./audit.log",
  "auditLogLevel": "info",
  "enableSecurityAlerts": false,
  "securityAlertWebhook": "",

  // === CONFIRMATION & APPROVAL ===
  "requireConfirmation": false,
  "requireConfirmationFor": [],
  "autoApproveAfterCount": 0
}

Executable Allowlist

Overview

The executable allowlist is the most critical security control. Only executables in this list can be launched by AI agents.

Configuration

{
  "allowedExecutables": [
    "node", // Basename (searches PATH)
    "/usr/bin/python3", // Absolute path
    "/usr/local/bin/*", // Glob pattern
    "npm",
    "git"
  ]
}

Allowlist Formats

  1. Basename: "node" - Matches any node executable in PATH
  2. Absolute Path: "/usr/bin/python3" - Exact path match
  3. Glob Pattern: "/usr/bin/*" - Pattern matching using minimatch

Hardcoded Dangerous Executables (ALWAYS Blocked)

These executables are always blocked regardless of allowlist configuration:

Unix/Linux/macOS

  • sudo, su, doas - Privilege escalation
  • chmod, chown, chgrp - Permission modification
  • rm, rmdir - File deletion
  • dd - Disk operations
  • mkfs, fdisk, parted - Filesystem operations
  • iptables, nft - Firewall configuration
  • systemctl, service - Service management
  • reboot, shutdown, halt - System control

Windows

  • runas.exe - Privilege escalation
  • psexec.exe, psexec64.exe - Remote execution
  • del.exe, erase.exe - File deletion
  • format.com, diskpart.exe - Disk operations
  • bcdedit.exe - Boot configuration
  • reg.exe, regedit.exe - Registry modification
  • sc.exe - Service control
  • net.exe, netsh.exe - Network configuration
  • wmic.exe - WMI operations
  • msiexec.exe - Installer execution
  • taskkill.exe - Process termination
  • shutdown.exe - System control

Shell Interpreter Blocking

When blockShellInterpreters: true, these are blocked:

  • Unix/Linux/macOS: bash, sh, zsh, fish, csh, tcsh, ksh
  • Windows: cmd.exe, powershell.exe, pwsh.exe

Recommendation: Keep this enabled unless you have a specific need for shell access.

Setuid/Setgid Blocking

When blockSetuidExecutables: true, any executable with setuid or setgid bits is blocked.

Recommendation: Keep this enabled to prevent privilege escalation.

Resource Limits

Default Resource Limits

Applied to all processes unless overridden:

{
  "defaultResourceLimits": {
    "maxCpuPercent": 80, // Maximum CPU usage (0-100)
    "maxMemoryMB": 1024, // Maximum memory in MB
    "maxFileDescriptors": 1024, // Maximum open files
    "maxCpuTime": 300, // Maximum CPU time in seconds
    "maxProcesses": 10 // Maximum processes in tree
  }
}

Maximum Resource Limits

Hard limits that cannot be exceeded even if requested:

{
  "maximumResourceLimits": {
    "maxCpuPercent": 100,
    "maxMemoryMB": 4096,
    "maxFileDescriptors": 2048,
    "maxCpuTime": 3600,
    "maxProcesses": 50
  }
}

Strict Enforcement

{
  "strictResourceEnforcement": true
}

When enabled, processes are terminated immediately upon exceeding limits. When disabled, processes get a grace period.

Process Limits

{
  "maxConcurrentProcesses": 10, // Total across all agents
  "maxConcurrentProcessesPerAgent": 5, // Per agent limit
  "maxProcessLifetime": 3600, // Maximum lifetime in seconds
  "maxTotalProcesses": 1000 // Lifetime of server
}

Working Directory Restrictions

Allowed Directories

Restrict processes to specific directories:

{
  "allowedWorkingDirectories": ["/home/user/projects", "/tmp/workspace"]
}

When set, processes can only run in these directories or their subdirectories.

Blocked Directories

Explicitly block certain directories:

{
  "blockedWorkingDirectories": ["/etc", "/root", "/var/lib"]
}

Blocked directories take precedence over allowed directories.

Recommendation

For maximum security, use allowedWorkingDirectories to create a sandbox:

{
  "allowedWorkingDirectories": ["/home/aiagent/workspace"]
}

What AI Agents CANNOT Do

AI agents are strictly prevented from:

System Operations

  • ❌ Launching executables not in the allowlist
  • ❌ Launching shell interpreters (if blocked)
  • ❌ Launching dangerous system commands (sudo, rm, dd, etc.)
  • ❌ Launching setuid/setgid executables
  • ❌ Escalating privileges
  • ❌ Modifying system configuration
  • ❌ Rebooting or shutting down the system

File Operations

  • ❌ Deleting files directly (rm, del)
  • ❌ Modifying file permissions (chmod, chown)
  • ❌ Accessing arbitrary directories (if restricted)
  • ❌ Performing disk operations (dd, format)

Environment Manipulation

  • ❌ Modifying PATH environment variable
  • ❌ Setting LD_PRELOAD or DYLD_INSERT_LIBRARIES
  • ❌ Manipulating other dangerous environment variables

Process Operations

  • ❌ Sending signals to processes they didn't create
  • ❌ Terminating system processes
  • ❌ Bypassing resource limits
  • ❌ Launching unlimited concurrent processes
  • ❌ Keeping processes running indefinitely

Security Bypasses

  • ❌ Executing command injection via arguments
  • ❌ Bypassing the allowlist
  • ❌ Disabling security checks
  • ❌ Modifying configuration at runtime

What AI Agents CAN Do

Within the configured allowlist and limits, AI agents can:

Process Management

  • ✅ Launch approved executables with arguments
  • ✅ Set safe environment variables
  • ✅ Specify working directory (within restrictions)
  • ✅ Set resource limits (within maximums)
  • ✅ Terminate processes they created
  • ✅ Create process groups
  • ✅ Manage process pipelines

I/O Operations

  • ✅ Capture stdout and stderr
  • ✅ Send stdin input
  • ✅ Retrieve buffered output
  • ✅ Handle binary data (if allowed)

Monitoring

  • ✅ Monitor CPU usage
  • ✅ Monitor memory usage
  • ✅ Monitor I/O statistics
  • ✅ Track process uptime
  • ✅ View historical resource data

Service Management

  • ✅ Start long-running services
  • ✅ Configure auto-restart
  • ✅ Set up health checks
  • ✅ Stop services they created

Advanced Features

  • ✅ Create process groups
  • ✅ Build process pipelines
  • ✅ Set timeout constraints
  • ✅ Query process status
  • ✅ List managed processes

Development Environment (Permissive)

For local development with trusted AI agents:

{
  "allowedExecutables": [
    "node",
    "npm",
    "yarn",
    "npx",
    "python3",
    "pip3",
    "pytest",
    "git",
    "make",
    "tsc",
    "jest"
  ],
  "defaultResourceLimits": {
    "maxCpuPercent": 90,
    "maxMemoryMB": 2048,
    "maxCpuTime": 600
  },
  "maxConcurrentProcesses": 20,
  "maxProcessLifetime": 7200,
  "blockShellInterpreters": false,
  "blockSetuidExecutables": true,
  "allowProcessTermination": true,
  "allowGroupTermination": true,
  "allowForcedTermination": true,
  "allowStdinInput": true,
  "allowOutputCapture": true,
  "enableAuditLog": true,
  "requireConfirmation": false
}

Production Environment (Restrictive)

For production with untrusted AI agents:

{
  "allowedExecutables": ["/usr/bin/node", "/usr/bin/python3"],
  "defaultResourceLimits": {
    "maxCpuPercent": 50,
    "maxMemoryMB": 512,
    "maxCpuTime": 300
  },
  "maximumResourceLimits": {
    "maxCpuPercent": 80,
    "maxMemoryMB": 1024,
    "maxCpuTime": 600
  },
  "maxConcurrentProcesses": 5,
  "maxConcurrentProcessesPerAgent": 2,
  "maxProcessLifetime": 1800,
  "maxLaunchesPerMinute": 5,
  "allowedWorkingDirectories": ["/var/lib/aiagent/workspace"],
  "blockShellInterpreters": true,
  "blockSetuidExecutables": true,
  "strictResourceEnforcement": true,
  "allowProcessTermination": true,
  "allowGroupTermination": false,
  "allowForcedTermination": false,
  "allowStdinInput": false,
  "allowOutputCapture": true,
  "enableAuditLog": true,
  "auditLogLevel": "info",
  "enableSecurityAlerts": true,
  "requireConfirmation": true
}

Testing Environment (Minimal)

For automated testing only:

{
  "allowedExecutables": ["jest", "pytest", "mocha", "npm"],
  "defaultResourceLimits": {
    "maxCpuPercent": 80,
    "maxMemoryMB": 1024,
    "maxCpuTime": 300
  },
  "maxConcurrentProcesses": 10,
  "maxProcessLifetime": 3600,
  "blockShellInterpreters": true,
  "blockSetuidExecutables": true,
  "allowProcessTermination": true,
  "allowGroupTermination": true,
  "allowForcedTermination": false,
  "allowStdinInput": true,
  "allowOutputCapture": true,
  "enableAuditLog": true,
  "requireConfirmation": false
}

Node.js Development

{
  "allowedExecutables": [
    "node",
    "npm",
    "yarn",
    "npx",
    "pnpm",
    "tsc",
    "jest",
    "eslint",
    "prettier"
  ],
  "defaultResourceLimits": {
    "maxCpuPercent": 80,
    "maxMemoryMB": 2048,
    "maxCpuTime": 600
  },
  "maxConcurrentProcesses": 15,
  "blockShellInterpreters": true,
  "blockSetuidExecutables": true,
  "allowProcessTermination": true,
  "allowGroupTermination": true,
  "allowForcedTermination": false,
  "allowStdinInput": true,
  "allowOutputCapture": true,
  "enableAuditLog": true
}

Python Development

{
  "allowedExecutables": [
    "python3",
    "pip3",
    "pytest",
    "black",
    "flake8",
    "mypy",
    "pylint"
  ],
  "defaultResourceLimits": {
    "maxCpuPercent": 80,
    "maxMemoryMB": 2048,
    "maxCpuTime": 600
  },
  "maxConcurrentProcesses": 15,
  "blockShellInterpreters": true,
  "blockSetuidExecutables": true,
  "allowProcessTermination": true,
  "allowGroupTermination": true,
  "allowForcedTermination": false,
  "allowStdinInput": true,
  "allowOutputCapture": true,
  "enableAuditLog": true
}

Cross-Platform Security

Unix/Linux Security

Blocked Environment Variables:

  • LD_PRELOAD, LD_LIBRARY_PATH - Library injection
  • PATH - Path manipulation
  • PYTHONPATH, NODE_PATH, PERL5LIB, RUBYLIB - Language paths

Additional Checks:

  • Setuid/setgid executable detection
  • File permission validation
  • Process capability checks

Windows Security

Blocked Environment Variables:

  • Path, PATH - Path manipulation (case-insensitive)
  • PATHEXT - Executable extension manipulation
  • COMSPEC - Command interpreter manipulation

Additional Checks:

  • Windows path separator handling (\ and /)
  • Case-insensitive executable matching
  • UAC elevation detection

macOS Security

Blocked Environment Variables:

  • DYLD_INSERT_LIBRARIES, DYLD_LIBRARY_PATH - Dynamic library injection
  • All Unix/Linux blocked variables

Additional Checks:

  • Setuid/setgid executable detection
  • macOS-specific library injection prevention
  • Gatekeeper validation

Advanced Security Features

Rate Limiting

Prevent abuse by limiting process launches:

{
  "maxLaunchesPerMinute": 10,
  "maxLaunchesPerHour": 100,
  "rateLimitCooldownSeconds": 60
}

Argument Validation

Additional argument security:

{
  "maxArgumentCount": 100,
  "maxArgumentLength": 4096,
  "blockedArgumentPatterns": [".*\\$\\(.*\\).*", ".*`.*`.*", ".*\\|.*", ".*;.*"]
}

Environment Variable Control

Fine-grained environment control:

{
  "allowedEnvVars": ["NODE_ENV", "DEBUG", "LOG_LEVEL"],
  "additionalBlockedEnvVars": ["AWS_SECRET_ACCESS_KEY", "DATABASE_PASSWORD"],
  "maxEnvVarCount": 50
}

Audit Logging

Configuration

{
  "enableAuditLog": true,
  "auditLogPath": "./audit.log",
  "auditLogLevel": "info"
}

Log Levels

  • error: Only security violations and errors
  • warn: Warnings and above
  • info: Normal operations (recommended)
  • debug: Detailed debugging information

Log Format

{
  "timestamp": "2024-01-15T10:30:45.123Z",
  "level": "AUDIT",
  "operation": "process_start",
  "executable": "node",
  "pid": 12345,
  "result": "success"
}

Security Violations

{
  "timestamp": "2024-01-15T10:30:45.123Z",
  "level": "SECURITY_VIOLATION",
  "type": "not_in_allowlist",
  "details": ["bash", "/bin/bash"]
}

Best Practices

1. Start Restrictive

Begin with a minimal allowlist and add executables as needed.

2. Use Absolute Paths in Production

Prefer absolute paths over basenames for better security.

3. Enable All Security Features

Enable shell blocking, setuid blocking, and strict enforcement.

4. Set Conservative Resource Limits

Start with low limits and increase as needed.

5. Restrict Working Directories

Use allowedWorkingDirectories to create a sandbox.

6. Monitor Audit Logs

Regularly review logs for security violations and unusual patterns.

7. Use Rate Limiting

Prevent abuse with rate limits on process launches.

8. Test Configuration

Test your configuration thoroughly before deployment.

9. Regular Updates

Review and update allowlist and limits regularly.

10. Defense in Depth

Use multiple security layers together.

Support

For security issues or questions: