asl-mcp by kebabmane - MCP Server

Amazon Security Lake MCP Server

An MCP (Model Context Protocol) server for querying Amazon Security Lake data using AWS Athena. This server provides structured access to OCSF-normalized security data stored in Security Lake, enabling AI assistants and applications to search for IP addresses, GuardDuty findings, and explore available data sources.

Features

IP Address Search: Search for IP addresses across Security Lake data sources (source and destination)
GuardDuty Findings: Query GuardDuty security findings with filtering by ID, severity, and type
Data Source Discovery: List and analyze available Security Lake data sources and tables
OCSF Compliance: Built-in OCSF (Open Cybersecurity Schema Framework) schema validation
AWS Integration: Seamless integration with AWS Athena, S3, and IAM
Security-First: Input validation, query sanitization, and least-privilege access

Requirements

Python 3.10 or higher
AWS account with Amazon Security Lake configured
AWS credentials configured (IAM role, profile, or environment variables)
Access to AWS Athena and the Security Lake database

Installation

Option 1: Using pip (recommended)

pip install amazon-security-lake-mcp

Option 2: From source

git clone <repository-url>
cd amazon-security-lake-mcp
pip install -e .

Option 3: Using Docker

docker build -t amazon-security-lake-mcp .
docker run -it amazon-security-lake-mcp

Configuration

Automatic Resource Discovery (Recommended)

The MCP server can automatically discover your Security Lake resources! Simply configure your AWS credentials and the server will find:

Security Lake S3 buckets for Athena query results
Security Lake Glue database names
Appropriate IAM permissions and configurations

Minimal Configuration:

# Only AWS region is required for auto-discovery
export ASL_MCP_AWS_REGION="us-east-1"
export ASL_MCP_AWS_PROFILE="your-aws-profile"  # Optional if using default credentials

Test Discovery:

# After installation, test resource discovery
python -c "
from asl_mcp_server.aws.discovery import AWSResourceDiscovery
discovery = AWSResourceDiscovery('us-east-1')
print(discovery.get_discovery_summary())
"

Manual Configuration

If you prefer manual configuration or auto-discovery fails:

# Required
export ASL_MCP_ATHENA_OUTPUT_LOCATION="s3://your-athena-results-bucket/path/"

# Optional (with defaults)
export ASL_MCP_AWS_REGION="us-east-1"
export ASL_MCP_AWS_PROFILE="your-aws-profile"
export ASL_MCP_SECURITY_LAKE_DATABASE="amazon_security_lake_glue_db"
export ASL_MCP_ATHENA_WORKGROUP="primary"
export ASL_MCP_AUTO_DISCOVER_RESOURCES="false"  # Disable auto-discovery
export ASL_MCP_LOG_LEVEL="INFO"
export ASL_MCP_MAX_QUERY_RESULTS="1000"
export ASL_MCP_QUERY_TIMEOUT_SECONDS="300"

Configuration File

Create a .env file in your project directory:

# Minimal configuration (auto-discovery enabled)
ASL_MCP_AWS_REGION=us-east-1
ASL_MCP_AWS_PROFILE=security-lake-user

# Or full manual configuration
ASL_MCP_ATHENA_OUTPUT_LOCATION=s3://my-athena-results/
ASL_MCP_AWS_REGION=us-east-1
ASL_MCP_SECURITY_LAKE_DATABASE=amazon_security_lake_glue_db
ASL_MCP_AUTO_DISCOVER_RESOURCES=false
ASL_MCP_LOG_LEVEL=INFO

AWS Permissions

The MCP server requires the following AWS permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "athena:StartQueryExecution",
        "athena:GetQueryExecution",
        "athena:GetQueryResults",
        "athena:ListDataCatalogs",
        "athena:ListDatabases",
        "athena:ListTableMetadata"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:ListBucket",
        "s3:PutObject"
      ],
      "Resource": [
        "arn:aws:s3:::aws-security-data-lake-*",
        "arn:aws:s3:::aws-security-data-lake-*/*",
        "arn:aws:s3:::your-athena-results-bucket",
        "arn:aws:s3:::your-athena-results-bucket/*"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "glue:GetDatabase",
        "glue:GetTable",
        "glue:GetPartitions"
      ],
      "Resource": "*"
    }
  ]
}

Usage

Integrating with Claude Desktop

To use this MCP server with Claude Desktop, you need to configure it in Claude Desktop's settings.

Step 1: Install the MCP Server

Option A: Using pipx (Recommended for Claude Desktop)

# Install pipx if you don't have it
brew install pipx  # macOS
# or: pip install --user pipx  # Other systems

# Install the MCP server globally
pipx install amazon-security-lake-mcp

# Or install from source
git clone <repository-url>
cd amazon-security-lake-mcp
pipx install -e .

Option B: Using pip with virtual environment

# Create virtual environment
python3 -m venv asl-mcp-env
source asl-mcp-env/bin/activate  # Linux/macOS
# or: asl-mcp-env\Scripts\activate  # Windows

# Install the package
pip install amazon-security-lake-mcp

Find the installed command path:

# For pipx installation
which asl-mcp-server
# Typical output: /Users/username/.local/bin/asl-mcp-server

# For pip installation in venv
which asl-mcp-server  # (with venv activated)

Step 2: Configure Claude Desktop

Add the MCP server to your Claude Desktop configuration. The configuration file location depends on your operating system:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Option A: Using Full Path to Command (Recommended)

{
  "mcpServers": {
    "amazon-security-lake": {
      "command": "/Users/username/.local/bin/asl-mcp-server",
      "env": {
        "ASL_MCP_AWS_REGION": "us-east-1",
        "ASL_MCP_AWS_PROFILE": "your-aws-profile",
        "ASL_MCP_LOG_LEVEL": "INFO"
      }
    }
  }
}

Replace /Users/username/.local/bin/asl-mcp-server with the actual path from which asl-mcp-server

Option B: Using Python Module (Most Reliable)

{
  "mcpServers": {
    "amazon-security-lake": {
      "command": "/opt/homebrew/bin/python3",
      "args": ["-m", "asl_mcp_server.server"],
      "cwd": "/path/to/amazon-security-lake-mcp",
      "env": {
        "ASL_MCP_AWS_REGION": "us-east-1",
        "ASL_MCP_AWS_PROFILE": "your-aws-profile",
        "PYTHONPATH": "/path/to/amazon-security-lake-mcp/src",
        "ASL_MCP_LOG_LEVEL": "INFO"
      }
    }
  }
}

Option C: Using Python Path (if not installed globally)

{
  "mcpServers": {
    "amazon-security-lake": {
      "command": "python",
      "args": ["-m", "asl_mcp_server.server"],
      "cwd": "/path/to/amazon-security-lake-mcp",
      "env": {
        "ASL_MCP_AWS_REGION": "us-east-1",
        "ASL_MCP_AWS_PROFILE": "your-aws-profile"
      }
    }
  }
}

Step 3: Restart Claude Desktop

After saving the configuration file, restart Claude Desktop completely (quit and relaunch the application).

Step 4: Verify Connection

In Claude Desktop, you can now ask questions like:

"Can you discover my Security Lake resources?"
"Search for IP address 192.168.1.100 in my security data"
"Show me recent high-severity GuardDuty findings"
"What data sources are available in my Security Lake?"

Example Claude Desktop Conversation

User: Can you help me investigate security incidents in my AWS environment?

Claude: I can help you investigate security incidents using your Amazon Security Lake data! Let me start by discovering your Security Lake resources and then we can search for specific indicators.

[Claude uses the discover_aws_resources tool]

I found your Security Lake setup:
- Database: amazon_security_lake_glue_db_us_east_1
- Region: us-east-1
- Athena results: s3://aws-athena-query-results-123456789012-us-east-1/

What would you like to investigate? I can:
1. Search for specific IP addresses
2. Look up GuardDuty findings
3. Show available data sources
4. Search by time ranges or severity levels

User: Search for any activity related to IP address 203.0.113.45

Claude: [Uses search_ip_addresses tool to query Security Lake data]

I found 3 security events involving IP 203.0.113.45:
...

Advanced Claude Desktop Configuration

For production use, consider these additional configurations:

Environment-Specific Configuration:

{
  "mcpServers": {
    "security-lake-prod": {
      "command": "asl-mcp-server",
      "env": {
        "ASL_MCP_AWS_REGION": "us-east-1",
        "ASL_MCP_AWS_PROFILE": "prod-security-readonly",
        "ASL_MCP_MAX_QUERY_RESULTS": "500",
        "ASL_MCP_QUERY_TIMEOUT_SECONDS": "180"
      }
    },
    "security-lake-dev": {
      "command": "asl-mcp-server",
      "env": {
        "ASL_MCP_AWS_REGION": "us-west-2",
        "ASL_MCP_AWS_PROFILE": "dev-security",
        "ASL_MCP_LOG_LEVEL": "DEBUG"
      }
    }
  }
}

Starting the MCP Server (Standalone)

You can also run the server standalone for testing:

# Using the installed command
asl-mcp-server

# Or using Python module
python -m asl_mcp_server.server

Available Tools

1. Search IP Addresses

Search for IP addresses in Security Lake data:

{
  "tool": "search_ip_addresses",
  "arguments": {
    "ip_address": "192.168.1.100",
    "start_time": "2024-01-15T00:00:00Z",
    "end_time": "2024-01-15T23:59:59Z",
    "sources": ["guardduty", "cloudtrail"],
    "limit": 100
  }
}

Parameters:

ip_address (required): IP address to search for (IPv4 or IPv6)
start_time (optional): Start time in ISO format (default: 7 days ago)
end_time (optional): End time in ISO format (default: now)
sources (optional): Data sources to search (guardduty, cloudtrail, vpcflow, etc.)
limit (optional): Maximum results to return (default: 100, max: 1000)

2. Search GuardDuty Findings

Query GuardDuty security findings:

{
  "tool": "search_guardduty_findings",
  "arguments": {
    "finding_id": "12345abc-def0-1234-5678-90abcdef1234",
    "severity": "High",
    "finding_type": "Trojan:EC2/MaliciousIP",
    "start_time": "2024-01-15T00:00:00Z",
    "end_time": "2024-01-15T23:59:59Z",
    "limit": 50
  }
}

Parameters:

finding_id (optional): Specific GuardDuty finding ID
severity (optional): Severity level (Critical, High, Medium, Low, Informational)
finding_type (optional): Type of finding to search for
start_time (optional): Start time in ISO format (default: 7 days ago)
end_time (optional): End time in ISO format (default: now)
limit (optional): Maximum results to return (default: 100, max: 1000)

3. List Data Sources

Discover available Security Lake data sources:

{
  "tool": "list_data_sources",
  "arguments": {
    "include_schema": true
  }
}

Parameters:

include_schema (optional): Include detailed table schema information (default: false)

4. Discover AWS Resources

Automatically discover Security Lake resources in your AWS account:

{
  "tool": "discover_aws_resources",
  "arguments": {}
}

This tool scans your AWS account to find:

Security Lake S3 buckets and databases
Athena output locations
Configuration recommendations
Setup validation

5. Universal Security Search

Intelligent search across all available Security Lake data sources:

{
  "tool": "universal_security_search",
  "arguments": {
    "query_type": "findings",
    "filters": {
      "severity": "High",
      "start_time": "2024-01-15T00:00:00Z",
      "end_time": "2024-01-15T23:59:59Z"
    },
    "limit": 50
  }
}

Query Types:

findings: Search security findings (GuardDuty, Security Hub)
network: Search network activity (VPC Flow, DNS, Route53)
api_calls: Search API activity (CloudTrail)
ip_search: Search by IP address across all sources

Key Features:

Automatically adapts to available data sources
Supports both OCSF 1.0 and 2.0 schemas
Intelligent fallback (e.g., Security Hub for GuardDuty data)
Unified result format across different sources

6. Test Connection

Verify connectivity to AWS services:

{
  "tool": "test_connection",
  "arguments": {}
}

Response Format

All tools return responses in a consistent format:

{
  "success": true,
  "error": null,
  "results": [...],
  "metadata": {
    "query_info": {...},
    "summary": {...}
  },
  "count": 10
}

Example Response - IP Search

{
  "success": true,
  "results": [
    {
      "timestamp": "2024-01-15T10:30:00Z",
      "event_type": "Network Activity",
      "severity": "Medium",
      "ip_context": {
        "role": "source",
        "direction": "outbound"
      },
      "network_info": {
        "source_ip": "192.168.1.100",
        "destination_ip": "203.0.113.45",
        "source_port": 3456,
        "destination_port": 443
      },
      "aws_context": {
        "account_id": "123456789012",
        "region": "us-east-1"
      },
      "product_info": {
        "name": "VPC Flow Logs",
        "vendor": "AWS"
      }
    }
  ],
  "metadata": {
    "summary": {
      "total_events": 1,
      "most_common_event_type": "Network Activity",
      "highest_severity": "Medium"
    }
  },
  "count": 1
}

Development

Setting up Development Environment

# Clone the repository
git clone <repository-url>
cd amazon-security-lake-mcp

# Install development dependencies
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=asl_mcp_server --cov-report=html

# Run specific test categories
pytest -m unit        # Unit tests only
pytest -m integration # Integration tests only
pytest -m slow        # Long-running tests

Code Quality

# Format code
black src tests

# Lint code
ruff src tests

# Type checking
mypy src

Security Considerations

Input Validation

All IP addresses are validated before querying
Query parameters are sanitized to prevent injection attacks
Time ranges are validated for reasonableness

Access Control

Uses AWS IAM for authentication and authorization
Supports least-privilege access patterns
Query results are limited to prevent resource exhaustion

Data Protection

No sensitive data is logged
Query results can be filtered to remove sensitive information
Supports encryption in transit and at rest through AWS services

Troubleshooting

Common Issues

1. Command Not Found (ENOENT Error)

Error: spawn asl-mcp-server ENOENT

Solution: Claude Desktop cannot find the asl-mcp-server command. Use one of these fixes:

Fix A: Use Full Command Path

# Find the command location
which asl-mcp-server
# Output: /Users/username/.local/bin/asl-mcp-server

# Update Claude Desktop config with full path
{
  "mcpServers": {
    "amazon-security-lake": {
      "command": "/Users/username/.local/bin/asl-mcp-server",
      "env": { ... }
    }
  }
}

Fix B: Use Python Module (Most Reliable)

{
  "mcpServers": {
    "amazon-security-lake": {
      "command": "/opt/homebrew/bin/python3",
      "args": ["-m", "asl_mcp_server.server"],
      "cwd": "/path/to/amazon-security-lake-mcp",
      "env": {
        "PYTHONPATH": "/path/to/amazon-security-lake-mcp/src"
      }
    }
  }
}

2. AWS Credentials Not Found

Error: AWS credentials not configured

Solution: Configure AWS credentials using one of these methods:

Set AWS_PROFILE environment variable
Configure ~/.aws/credentials file
Use IAM roles (recommended for EC2/Lambda)
Set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables

2. Auto-Discovery Failed

Error: athena_output_location could not be auto-discovered and was not provided

Solution: Either enable manual configuration or create required resources:

Option A: Use Manual Configuration

export ASL_MCP_AUTO_DISCOVER_RESOURCES="false"
export ASL_MCP_ATHENA_OUTPUT_LOCATION="s3://your-bucket/athena-results/"
export ASL_MCP_SECURITY_LAKE_DATABASE="amazon_security_lake_glue_db"

Option B: Create Athena Results Bucket

# Create a bucket for Athena results
aws s3 mb s3://aws-athena-query-results-$(aws sts get-caller-identity --query Account --output text)-us-east-1

Option C: Run Discovery Tool Use the discover_aws_resources tool to see what's missing and get specific recommendations.

3. Security Lake Database Not Found

Error: Database 'amazon_security_lake_glue_db' is not available

Solution:

Verify Security Lake is enabled in your AWS account
Check that the database name is correct
Ensure you have permissions to access the Glue catalog

4. Query Timeout

Error: Query timeout after 300 seconds

Solution:

Increase ASL_MCP_QUERY_TIMEOUT_SECONDS
Use more specific time ranges to reduce data scanned
Add appropriate WHERE clauses to filter results

Performance Optimization

Use specific time ranges: Always specify start_time and end_time to leverage partitioning
Limit results: Use appropriate limit values to avoid large result sets
Filter by source: Specify sources parameter to query only relevant tables
Monitor costs: Large queries can incur significant Athena charges

Debugging

Enable debug logging:

export ASL_MCP_LOG_LEVEL=DEBUG

This will provide detailed information about:

Query construction and execution
AWS API calls
Result processing
Error details

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Add tests for new functionality
Ensure all tests pass (pytest)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the file for details.

Support

For issues and questions:

Open an issue on GitHub
Check the troubleshooting section above
Review AWS Security Lake documentation
Consult the OCSF specification

Related Projects

Changelog

v0.1.0 (Initial Release)

IP address search functionality
GuardDuty findings search
Data source discovery
OCSF schema validation
Comprehensive test suite
AWS integration with proper error handling