npm package: @modular-intelligence/atomic-red-team
Description: MCP server for Atomic Red Team adversary emulation tests
Latest version: 1.0.2

# Atomic Red Team MCP Server

A Model Context Protocol (MCP) server that provides access to [Atomic Red Team](https://github.com/redcanaryco/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:

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

Set the environment variable to point to the repository:

```bash
# 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

```bash
cd atomic-red-team
bun install
```

## Installation

### Build the server:

```bash
bun run build
```

### Configure MCP Client

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

```json
{
  "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:**
```json
{
  "technique_id": "T1059.001",
  "platform": "linux"
}
```

**Response:**
```json
{
  "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:**
```json
{
  "technique_id": "T1059.001",
  "test_index": 0
}
```

**Response:**
```json
{
  "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:**
```json
{
  "technique_id": "T1059.001",
  "test_index": 0,
  "timeout": 60
}
```

**Response:**
```json
{
  "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:**
```json
{
  "technique_id": "T1059.001",
  "test_index": 0,
  "authorized": true,
  "input_args": {
    "message": "Custom test message"
  },
  "timeout": 60
}
```

**Response:**
```json
{
  "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:**
```json
{
  "technique_id": "T1059.001",
  "test_index": 0,
  "authorized": true,
  "timeout": 60
}
```

**Response:**
```json
{
  "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:**
```json
{
  "tactic": "execution",
  "platform": "linux"
}
```

**Response:**
```json
{
  "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:**
```json
{
  "technique_id": "T1059.004",
  "test_index": 0,
  "platform": "linux",
  "input_args": {
    "filename": "/tmp/test.txt"
  }
}
```

**Response:**
```json
{
  "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

```bash
bun run build
```

### Run Locally

```bash
bun run start
```

### Testing

The server can be tested using the MCP Inspector:

```bash
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](https://github.com/redcanaryco/atomic-red-team)
- [MITRE ATT&CK](https://attack.mitre.org/)
- [Model Context Protocol](https://modelcontextprotocol.io/)

## 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.