Atomic Red Team MCP Server

A Model Context Protocol (MCP) server that provides access to Atomic Red Team adversary emulation tests. This server enables AI assistants to list, inspect, and execute security tests for defensive testing and purple team operations.

Features

• YAML Parsing: Direct parsing of Atomic Red Team YAML test definitions
• CLI Execution: Execute tests via PowerShell/Bash with timeout controls
• Security Controls:
  • Authorization required for execution
  • Blocked techniques (network exfiltration/C2)
  • Input sanitization against shell injection
  • Maximum timeout limits
• Comprehensive Tools:
  • List and filter tests by technique, tactic, or platform
  • View detailed test specifications
  • Check prerequisites
  • Execute tests with custom arguments
  • Run cleanup commands
  • Generate standalone scripts
  • Map techniques by MITRE ATT&CK tactics

Prerequisites

1. Atomic Red Team Repository

Clone the Atomic Red Team repository:

git clone https://github.com/redcanaryco/atomic-red-team.git

Set the environment variable to point to the repository:

# Linux/macOS
export ATOMIC_RED_TEAM_PATH=/path/to/atomic-red-team

# Windows (PowerShell)
$env:ATOMIC_RED_TEAM_PATH = "C:\path\to\atomic-red-team"

2. Runtime Requirements

• Bun: For running the server (or Node.js 18+)
• PowerShell Core: For Windows tests (cross-platform)
• Bash: For Linux/macOS tests

3. Install Dependencies

cd atomic-red-team
bun install

Installation

Build the server:

bun run build

Configure MCP Client

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "atomic-red-team": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/atomic-red-team/src/index.ts"],
      "env": {
        "ATOMIC_RED_TEAM_PATH": "/path/to/atomic-red-team"
      }
    }
  }
}

Tools

1. atomic_list_tests

List available Atomic Red Team tests with optional filtering.

Parameters:

• technique_id (optional): MITRE ATT&CK technique ID (e.g., T1059, T1059.001)
• tactic (optional): MITRE ATT&CK tactic filter (e.g., execution, persistence)
• platform (optional): Platform filter (linux, macos, windows)

Example:

{
  "technique_id": "T1059.001",
  "platform": "linux"
}

Response:

{
  "tests": [
    {
      "technique_id": "T1059.001",
      "technique_name": "Command and Scripting Interpreter: PowerShell",
      "test_index": 0,
      "test_name": "Mimikatz",
      "description": "Download and execute Mimikatz",
      "platforms": ["windows"],
      "executor_name": "powershell",
      "input_arguments": {
        "mimikatz_path": {
          "description": "Path to mimikatz.exe",
          "type": "path",
          "default": "$env:TEMP\\mimikatz.exe"
        }
      }
    }
  ],
  "total": 1
}

2. atomic_test_detail

Get detailed information about a specific test.

Parameters:

• technique_id (required): MITRE ATT&CK technique ID
• test_index (optional, default: 0): Test index within the technique

Example:

{
  "technique_id": "T1059.001",
  "test_index": 0
}

Response:

{
  "technique_id": "T1059.001",
  "technique_name": "Command and Scripting Interpreter: PowerShell",
  "test_index": 0,
  "test_name": "PowerShell Execute Command",
  "description": "Execute a PowerShell command",
  "platforms": ["windows"],
  "executor": {
    "name": "powershell",
    "command": "Write-Host 'Hello from Atomic Red Team'",
    "cleanup_command": null,
    "elevation_required": false
  },
  "input_arguments": [],
  "dependencies": []
}

3. atomic_prereq_check

Check if prerequisites for a test are met.

Parameters:

• technique_id (required): MITRE ATT&CK technique ID
• test_index (optional, default: 0): Test index
• timeout (optional, default: 60): Maximum execution time in seconds

Example:

{
  "technique_id": "T1059.001",
  "test_index": 0,
  "timeout": 60
}

Response:

{
  "technique_id": "T1059.001",
  "test_name": "PowerShell Execute Command",
  "prerequisites": [
    {
      "description": "PowerShell must be installed",
      "check_command": "powershell -Command 'exit 0'",
      "get_command": "Install PowerShell from https://github.com/PowerShell/PowerShell",
      "met": true
    }
  ],
  "all_met": true
}

4. atomic_run_test

Execute an Atomic Red Team test. REQUIRES AUTHORIZATION.

Security Notes:

• Blocked techniques: T1048, T1071, T1095, T1572, T1090, T1219 (network exfiltration/C2)
• Input arguments are sanitized against shell injection
• Maximum timeout: 300 seconds
• Requires explicit authorized: true parameter

Parameters:

• technique_id (required): MITRE ATT&CK technique ID
• test_index (optional, default: 0): Test index
• authorized (required): Must be true to execute
• input_args (optional): Override default input arguments
• timeout (optional, default: 60): Maximum execution time

Example:

{
  "technique_id": "T1059.001",
  "test_index": 0,
  "authorized": true,
  "input_args": {
    "message": "Custom test message"
  },
  "timeout": 60
}

Response:

{
  "technique_id": "T1059.001",
  "test_name": "PowerShell Execute Command",
  "executor": "powershell",
  "command_executed": "Write-Host 'Custom test message'",
  "output": "Custom test message\n",
  "exit_code": 0,
  "duration_ms": 234
}

5. atomic_cleanup

Execute cleanup commands after a test. REQUIRES AUTHORIZATION.

Parameters:

• technique_id (required): MITRE ATT&CK technique ID
• test_index (optional, default: 0): Test index
• authorized (required): Must be true to execute
• timeout (optional, default: 60): Maximum execution time

Example:

{
  "technique_id": "T1059.001",
  "test_index": 0,
  "authorized": true,
  "timeout": 60
}

Response:

{
  "technique_id": "T1059.001",
  "test_name": "PowerShell Execute Command",
  "cleanup_command": "Remove-Item $env:TEMP\\test.txt",
  "output": "Cleanup completed successfully\n",
  "success": true
}

6. atomic_technique_map

Build a map of techniques organized by MITRE ATT&CK tactics.

Parameters:

• tactic (optional): Filter by tactic (e.g., execution, persistence)
• platform (optional): Filter by platform (linux, macos, windows)

Example:

{
  "tactic": "execution",
  "platform": "linux"
}

Response:

{
  "tactics": [
    {
      "tactic": "execution",
      "techniques": [
        {
          "id": "T1059",
          "name": "Command and Scripting Interpreter",
          "test_count": 15,
          "platforms": ["linux", "macos", "windows"]
        },
        {
          "id": "T1059.004",
          "name": "Command and Scripting Interpreter: Unix Shell",
          "test_count": 8,
          "platforms": ["linux", "macos"]
        }
      ]
    }
  ],
  "total_techniques": 2,
  "total_tests": 23
}

7. atomic_generate_script

Generate a standalone executable script from a test.

Parameters:

• technique_id (required): MITRE ATT&CK technique ID
• test_index (optional, default: 0): Test index
• platform (required): Target platform (linux, macos, windows)
• input_args (optional): Override default input arguments

Example:

{
  "technique_id": "T1059.004",
  "test_index": 0,
  "platform": "linux",
  "input_args": {
    "filename": "/tmp/test.txt"
  }
}

Response:

{
  "technique_id": "T1059.004",
  "test_name": "Create and Execute Bash Script",
  "platform": "linux",
  "script_content": "#!/bin/bash\n# Atomic Red Team Test: Create and Execute Bash Script\n# Technique: T1059.004\n# Platform: linux\n\n# Input Arguments:\n# filename: /tmp/test.txt (File to create)\n\necho 'test' > /tmp/test.txt\ncat /tmp/test.txt",
  "script_type": "bash",
  "input_args_used": {
    "filename": "/tmp/test.txt"
  }
}

Security Considerations

Blocked Techniques

The following techniques are blocked by default due to network exfiltration/C2 risks:

• T1048: Exfiltration Over Alternative Protocol
• T1071: Application Layer Protocol (C2)
• T1095: Non-Application Layer Protocol (C2)
• T1572: Protocol Tunneling
• T1090: Proxy
• T1219: Remote Access Software

Input Validation

All input arguments are validated to prevent shell injection:

• Maximum length: 1024 characters per value
• Blocked characters: ;, &, |, `, $, (, ), {, }, [, ], <, >

Authorization

Execution and cleanup tools require explicit authorization via the authorized: true parameter. This prevents accidental execution of adversary emulation tests.

Timeouts

All command executions have configurable timeouts:

• Minimum: 10 seconds
• Maximum: 300 seconds (5 minutes)
• Default: 60 seconds

Architecture

atomic-red-team/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── schemas.ts            # Zod validation schemas
│   ├── security.ts           # Security validation functions
│   ├── cli-executor.ts       # Command execution utilities
│   └── tools/
│       ├── atomic-list-tests.ts
│       ├── atomic-test-detail.ts
│       ├── atomic-prereq-check.ts
│       ├── atomic-run-test.ts
│       ├── atomic-cleanup.ts
│       ├── atomic-technique-map.ts
│       └── atomic-generate-script.ts
├── package.json
├── tsconfig.json
└── README.md

Development

Build

bun run build

Run Locally

bun run start

Testing

The server can be tested using the MCP Inspector:

npx @modelcontextprotocol/inspector bun run src/index.ts

Environment Variables

• ATOMIC_RED_TEAM_PATH (required): Path to the Atomic Red Team repository

Use Cases

Purple Team Operations

• Execute adversary emulation tests in controlled environments
• Validate detection capabilities
• Test security controls

Security Research

• Explore MITRE ATT&CK techniques
• Understand attack patterns
• Generate test scripts for analysis

Training & Education

• Learn offensive security techniques
• Practice defensive detection
• Build security automation

Limitations

• Simple YAML Parser: Custom parser may not handle all YAML edge cases
• Platform Support: Requires appropriate executor (PowerShell/Bash) on host system
• No Validation: Tests are executed as-is without additional safety checks
• Network Tests Blocked: C2 and exfiltration techniques are disabled by default

Contributing

Contributions are welcome! Please ensure:

• All Zod schemas include .describe() documentation
• Security validations are maintained
• Tests are added for new features

License

This MCP server is provided as-is for educational and defensive security purposes. Use responsibly and only in authorized environments.

References

• Atomic Red Team
• MITRE ATT&CK
• Model Context Protocol

Disclaimer

WARNING: This tool executes adversary emulation tests that may:

• Modify system state
• Create/delete files
• Execute privileged commands
• Trigger security alerts

Only use in isolated, controlled environments with proper authorization. The authors are not responsible for misuse or damage caused by this software.