Get comprehensive information about the MCP server configuration and environment.

This tool returns server metadata including version, transport protocol, operating system, and data directory location. Use this to:

• Verify server configuration

• Check server version for compatibility

• Confirm the platform before executing atomic tests

• Locate the atomic tests data directory

Args: ctx: MCP context (provided automatically by the framework)

Returns: ServerInfoOutput: Server information with the following fields: - name (str): Server name - always "Atomic Red Team MCP" - version (str): Installed package version (e.g., "1.2.3") Shows "dev" if running from source without installation - transport (str): MCP transport protocol being used Values: "stdio" (default), "sse", or "streamable-http" - os (str): Operating system platform Values: "Darwin" (macOS), "Linux", "Windows" Use this to verify test compatibility before execution - data_directory (str): Absolute path to atomic tests storage directory This is where atomic YAML files are stored Use this path when creating new atomic tests - execution_enabled (bool): Whether atomic test execution is enabled on this server

Examples: # Get server information info = server_info(ctx) print(f"Running version {info.version} on {info.os}")

# Check if remote server for execution
if info.transport == 'streamable-http':
    print("This is a remote MCP server")

# Get data directory for creating tests
data_dir = info.data_directory
print(f"Create new tests in: {data_dir}/T####/T####.yaml")

Use Cases: 1. Before executing tests: Check OS matches supported_platforms 2. Creating atomic tests: Use data_directory to know where to save files 3. Debugging: Verify configuration settings 4. Version compatibility: Ensure tools match server version

Notes: - This tool always succeeds and never raises exceptions - Information reflects the current runtime configuration - Transport and data_directory come from Settings (environment variables/.env) - OS is detected at runtime and cannot be changed

Download and reload atomic tests from the GitHub repository.

This tool forces a fresh download of all atomic tests from the configured GitHub repository, replacing any existing local copies. It then reloads all tests into memory, making them immediately available for querying and execution.

Use this tool when:

• You want to get the latest atomic tests from the repository

• Custom atomic tests were added to the data directory

• The atomic test database needs to be refreshed

• You suspect the loaded tests are out of sync with the repository

Args: ctx: MCP context (provided automatically by the framework) progress: Background task progress reporter (injected automatically)

Returns: RefreshAtomicsOutput: Structured output containing: - success (bool): Whether the refresh operation completed successfully - message (str): Human-readable message about the refresh operation - atomics_count (int): Number of atomic tests loaded after refresh - repository_url (str): GitHub repository URL that was used for refresh

Process: 1. Deletes existing atomic tests directory (if present) 2. Clones the GitHub repository (configured via ART_GITHUB_* settings) 3. Extracts the atomics directory from the repository 4. Parses all YAML files and validates them 5. Loads atomic tests into server memory 6. Makes tests immediately available to other tools

Configuration: The repository location is controlled by environment variables: - ART_GITHUB_URL: Base GitHub URL (default: https://github.com) - ART_GITHUB_USER: User/organization (default: redcanaryco) - ART_GITHUB_REPO: Repository name (default: atomic-red-team) - ART_DATA_DIR: Local storage path (default: ./atomics)

Examples: # Refresh from default repository refresh_atomics(ctx)

# After setting custom repo in .env:
# ART_GITHUB_USER=your-org
# ART_GITHUB_REPO=custom-atomics
refresh_atomics(ctx)

Notes: - This operation may take 30-60 seconds depending on network speed - Runs as a background task — the client receives a task ID immediately and can poll for completion - Requires internet connectivity to GitHub - Overwrites any local modifications to atomic tests - The repository is cloned with depth=1 for efficiency (only latest commit) - Failed YAML files are logged but don't stop the overall refresh

Search and filter atomic tests across the repository.

This tool searches through all atomic tests and returns matches based on your criteria. You can search by free-text query, or filter by specific attributes like technique ID, GUID, or platform. Results are paginated — use the returned next_cursor to fetch subsequent pages.

Args: query: Free-text search term to match against all atomic test fields including name, description, commands, and input arguments. Supports multi-word queries where all words must match (AND logic). Examples: "powershell registry", "credential access", "T1059"

guid: Filter by exact atomic test GUID (UUID format).
      Example: "a8c41029-8d2a-4661-ab83-e5104c1cb667"
      Use this when you know the specific test you want to retrieve.

technique_id: Filter by MITRE ATT&CK technique ID. Must follow the format
              T#### or T####.### (e.g., T1059, T1059.001).
              Example: "T1059.001" for PowerShell technique
              Returns all atomic tests associated with this technique.

technique_name: Filter by technique name (case-insensitive partial match).
                Example: "Command and Scripting Interpreter"
                Useful when you know the technique name but not the ID.

supported_platforms: Filter by platform (case-insensitive partial match).
                    Valid platforms: windows, linux, macos, office-365, azure-ad,
                    google-workspace, saas, iaas, containers, iaas:aws, iaas:azure,
                    iaas:gcp, esxi
                    Example: "windows", "linux", "macos"

cursor: Opaque pagination cursor returned by a previous call as `next_cursor`.
        Omit or pass null to start from the first page.

limit: Maximum number of results to return per page (1–200, default 50).

Returns: QueryAtomicsOutput: Structured output containing: - total_results: Total number of matching atomic tests - atomics: List of matching atomic tests for this page - next_cursor: Opaque cursor for the next page, or null if last page - query_metadata: Information about applied filters

Raises: ValueError: If query is empty without any filters ValueError: If query exceeds 1000 characters ValueError: If technique_id format is invalid (must be T#### or T####.###) ValueError: If limit is outside the range 1–200 ValueError: If cursor is malformed

Get the JSON schema that defines the structure and requirements for atomic tests.

This schema provides the complete specification for creating valid atomic tests. It defines all fields (required and optional), data types, validation rules, and constraints. Use this as a reference when creating or modifying atomic tests to ensure they meet quality standards.

The schema follows the Atomic Red Team YAML format and is automatically generated from the Pydantic models, ensuring it's always in sync with validation rules.

Returns: dict: JSON Schema (Draft 7) containing: - definitions: Nested object definitions (Executor, Dependency, etc.) - properties: Field definitions with types and constraints - required: List of mandatory fields - additionalProperties: Whether extra fields are allowed - field descriptions: Human-readable explanations for each field

Schema Structure: The schema defines these main sections: - name: Test name (required, min 1 character) - description: Test explanation (required, min 1 character) - supported_platforms: Platform list (required, min 1 platform) - executor: Execution method (required, CommandExecutor or ManualExecutor) - input_arguments: Parameterized inputs (optional, dict) - dependencies: Prerequisites (optional, list) - dependency_executor_name: Executor for dependencies (optional) - auto_generated_guid: Unique ID (optional, auto-generated)

Examples: # Get the schema schema = get_validation_schema()

# Check required fields
required_fields = schema['required']
print(f"Required fields: {required_fields}")

# View field definitions
properties = schema['properties']
print(f"Available fields: {list(properties.keys())}")

# Check platform options
platform_enum = schema['definitions']['Platform']['enum']
print(f"Valid platforms: {platform_enum}")

Common Use Cases: 1. Creating new tests: Reference required fields and formats 2. Understanding validation: See what rules will be enforced 3. Tool development: Use schema for code generation 4. Documentation: Generate field descriptions automatically

Notes: - Schema is generated from Pydantic models at runtime - Always reflects current validation rules - Includes custom validators and constraints - Follows JSON Schema Draft 7 specification - Can be used with JSON Schema validators in any language - Do not add comments to the created atomic test

Validate an atomic test YAML string against the official Atomic Red Team schema.

This tool checks if your atomic test follows the correct structure and includes all required fields. Use this before finalizing any atomic test to ensure it meets the quality standards and can be properly parsed by Atomic Red Team tools.

The validator performs two levels of checks:

1. Structural validation: Ensures all required fields are present and properly typed

2. Best practice warnings: Flags common issues that should be addressed

Args: yaml_string: The complete YAML string of the atomic test to validate. Should include all fields like name, description, supported_platforms, executor, etc. as defined in the schema.

Returns: ValidationOutput: Structured validation result containing: - valid (bool): Whether the atomic test passes validation - message (str): Human-readable success/error message with warnings prominently displayed - atomic_name (str): Name of the atomic test (only if valid) - supported_platforms (list): Platforms the test supports (only if valid) - warnings (list): List of warning messages for best practice violations (only if present) - error (str): Detailed error message (only if invalid)

Validation Warnings: The tool will flag these common issues with ⚠️ warnings: - Presence of 'auto_generated_guid' field (should be auto-generated, not manually set) - Use of echo/print/Write-Host commands (discouraged in test commands)

Warnings do not cause validation to fail, but should be addressed before finalizing.

Examples: # Valid atomic test yaml_str = ''' name: Test PowerShell Execution description: Execute a PowerShell command supported_platforms: - windows executor: name: powershell command: Get-Process ''' result = validate_atomic(yaml_str, ctx) # result.valid == True, result.message contains success message

# Test with warnings (still valid but needs improvement)
yaml_str = '''
name: Test with Echo
description: Test with echo command
supported_platforms:
  - linux
executor:
  name: bash
  command: echo "Hello World"
'''
result = validate_atomic(yaml_str, ctx)
# result.valid == True, result.warnings contains warning messages

# Invalid atomic test (missing required field)
yaml_str = '''
name: Incomplete Test
description: Missing supported_platforms
executor:
  name: bash
  command: ls
'''
result = validate_atomic(yaml_str, ctx)
# result.valid == False, result.error contains error message

Raises: No exceptions are raised - all errors are returned in the ValidationOutput model.

Notes: - Always check the 'valid' field before using the atomic test - Address all warnings even if validation succeeds - Warnings are displayed with ⚠️ emoji for visibility - The 'message' field contains formatted text with warnings prominently shown

Generate an atomic test for a MITRE ATT&CK technique using AI assistance.

Uses the MCP client's LLM to draft an atomic test YAML for the given technique and platform, then validates it automatically. If the generated test has errors or warnings, re-samples up to 3 times to fix them before returning.

Args: technique_id: MITRE ATT&CK technique ID (e.g., "T1059.001"). Used to focus the generated test on the correct technique.

platform: Target platform for the test. Valid values: windows, linux, macos.
          Defaults to "linux".

description: Optional free-text description of what the test should do or
             demonstrate. Leave blank to let the AI determine the best approach
             for the technique.

Returns: GenerateAtomicOutput: Result containing: - valid (bool): Whether the final test passes schema validation - message (str): Success or error message - atomic_name (str): Name of the generated test (if valid) - supported_platforms (list): Platforms declared in the test (if valid) - yaml (str): Generated YAML content (if valid) - warnings (list): Best-practice warnings to address (if any) - error (str): Validation error details (if invalid)

Notes: - Requires the MCP client to support server-side sampling - If the client doesn't support sampling, returns an error - The generated YAML is validated but NOT saved automatically - Use server_info to find where to save validated tests - Always review generated tests before use in production environments