Serveur Amazon Security Lake MCP

Un serveur MCP (Model Context Protocol) pour interroger les données Amazon Security Lake à l'aide d'AWS Athena. Ce serveur fournit un accès structuré aux données de sécurité normalisées OCSF stockées dans Security Lake, permettant aux assistants et applications d'IA de rechercher des adresses IP, des résultats GuardDuty et d'explorer les sources de données disponibles.

Fonctionnalités

• Recherche d'adresses IP: Recherche d'adresses IP dans l'ensemble des sources de données de Security Lake (source et destination)
• Constatations GuardDuty: Interroger les résultats de sécurité GuardDuty avec un filtrage par ID, gravité et type
• Découverte des sources de données: Liste et analyse des sources de données et des tables disponibles dans Security Lake
• Conformité OCSF: Validation intégrée du schéma OCSF (Open Cybersecurity Schema Framework)
• Intégration AWS: Intégration transparente avec AWS Athena, S3 et IAM
• Sécurité d'abord: validation des entrées, assainissement des requêtes et accès au moindre privilège

Conditions requises

• Python 3.10 ou supérieur
• Compte AWS avec Amazon Security Lake configuré
• Configuration des informations d'identification AWS (rôle IAM, profil ou variables d'environnement)
• Accès à AWS Athena et à la base de données Security Lake

Installation de l'application

Option 1 : Utilisation de pip (recommandée)

pip install amazon-security-lake-mcp

Option 2 : À partir des sources

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

Option 3 : En utilisant Docker

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

Configuration

Découverte automatique des ressources (recommandé)

Le serveur MCP peut découvrir automatiquement vos ressources Security Lake ! Configurez simplement vos informations d'identification AWS et le serveur trouvera :

• Les buckets S3 de Security Lake pour les résultats des requêtes Athena
• Les noms des bases de données Security Lake Glue
• Les autorisations et configurations IAM appropriées

Configuration minimale :

# Seule la région AWS est requise pour la découverte automatique export ASL_MCP_AWS_REGION="us-east-1" export ASL_MCP_AWS_PROFILE="your-aws-profile" # Facultatif si vous utilisez les informations d'identification par défaut

Tester la découverte :

# Après l'installation, tester la découverte des ressources python -c " from asl_mcp_server.aws.discovery import AWSResourceDiscovery discovery = AWSResourceDiscovery('us-east-1') print(discovery.get_discovery_summary()) "

Configuration manuelle

Si vous préférez une configuration manuelle ou si la découverte automatique échoue :

# Requis export ASL_MCP_ATHENA_OUTPUT_LOCATION="s3 ://votre-athena-results-bucket/path/" # Facultatif (avec valeurs par défaut) export ASL_MCP_AWS_REGION="us-east-1" export ASL_MCP_AWS_PROFILE="votre-profil-aws-profil" export ASL_MCP_SECURITY_LAKE_DATABASE="amazon_security_lake_glue_db" export ASL_MCP_ATHENA_WORKGROUP="primary" export ASL_MCP_AUTO_DISCOVER_RESOURCES="false" # Désactiver la découverte auto-auto export ASL_MCP_LOG_LEVEL="INFO" export ASL_MCP_MAX_QUERY_RESULTS="1000" export ASL_MCP_QUERY_TIMEOUT_SECONDS="300"

Fichier de configuration

Créez un fichier .env dans le répertoire de votre projet :

# Configuration minimale (découverte automatique activée) ASL_MCP_AWS_REGION=us-east-1 ASL_MCP_AWS_PROFILE=security-lake-user # Ou configuration manuelle complète 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

Autorisations AWS

Le serveur MCP nécessite les autorisations AWS suivantes :

{"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" : "*" } ] }

Utilisation

Intégration avec Claude Desktop

Pour utiliser ce serveur MCP avec Claude Desktop, vous devez le configurer dans les paramètres de Claude Desktop.

Etape 1 : Installer le serveur MCP

Option A : Utiliser pipx (Recommandé pour Claude Desktop)

# Installer pipx si vous ne l'avez pas brew install pipx # macOS # ou : pip install --user pipx # Autres systèmes # Installer le serveur MCP globalement pipx install amazon-security-lake-mcp # Ou installer à partir des sources git clone <repository-url> cd amazon-security-lake-mcp pipx install -e

Option B : Utiliser pip avec un environnement virtuel

# Créer un environnement virtuel python3 -m venv asl-mcp-env source asl-mcp-env/bin/activate # Linux/macOS # ou : asl-mcp-env\Scripts\activate # Windows # Installer le paquet pip install amazon-security-lake-mcp

Trouver le chemin de commande installé :

# Pour l'installation de pipx qui asl-mcp-server # Sortie typique : /Users/nom d'utilisateur/.local/bin/asl-mcp-server # Pour l'installation de pip dans venv which asl-mcp-server # (avec venv activé)

Etape 2 : Configurer Claude Desktop

Ajoutez le serveur MCP à votre configuration Claude Desktop. L'emplacement du fichier de configuration dépend de votre système d'exploitation :

• macOS: ~/Bibliothèque/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claudeclaude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Option A : Utiliser le chemin complet de la commande (recommandé)

{ "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" } } }

Remplacez /Users/nom d'utilisateur/.local/bin/asl-mcp-server par le chemin d'accès à partir duquel asl-mcp-server a été exécuté

Option B : Utilisation du module Python (la plus fiable)

{"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 : Utilisation du chemin Python (s'il n'est pas installé globalement)

{ "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" } } }

Étape 3 : Redémarrer Claude Desktop

Après avoir enregistré le fichier de configuration, redémarrez complètement Claude Desktop (quittez et relancez l'application).

Étape 4 : Vérification de la connexion

Dans Claude Desktop, vous pouvez maintenant poser des questions telles que :

• "Pouvez-vous découvrir les ressources de mon lac de sécurité ?"
• "Recherchez l'adresse IP 192.168.1.100 dans mes données de sécurité
• "Montrez-moi les récentes découvertes GuardDuty de haute sévérité"
• "Quelles sont les sources de données disponibles dans mon lac de sécurité ?

Exemple de conversation sur le bureau de Claude

Utilisateur : Pouvez-vous m'aider à enquêter sur les incidents de sécurité dans mon environnement AWS ? Claude : Je peux vous aider à enquêter sur les incidents de sécurité en utilisant vos données Amazon Security Lake ! Laissez-moi commencer par découvrir vos ressources Security Lake, puis nous pourrons rechercher des indicateurs spécifiques [Claude utilise l'outil discover_aws_resources] J'ai trouvé votre configuration Security Lake : - Base de données : amazon_security_lake_glue_db_us_east_1 - Région : us-east-1 - Résultats Athena : s3://aws-athena-query-results-123456789012-us-east-1/ Qu'aimeriez-vous investiguer ? Je peux : 1. Rechercher des adresses IP spécifiques 2. Rechercher les résultats de GuardDuty 3. Afficher les sources de données disponibles 4. Rechercher par plages horaires ou niveaux de gravité Utilisateur : Rechercher toute activité liée à l'adresse IP 203.0.113.45 Claude : [Utilise l'outil search_ip_addresses pour interroger les données du lac de sécurité] J'ai trouvé 3 événements de sécurité impliquant l'adresse IP 203.0.113.45 : ..

Configuration avancée de Claude Desktop

Pour une utilisation en production, envisagez ces configurations supplémentaires :

Configuration spécifique à l'environnement :

{ "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" } } }

Démarrage du serveur MCP (autonome)

Vous pouvez également lancer le serveur en mode autonome pour le tester :

# En utilisant la commande installée asl-mcp-server # Ou en utilisant le module Python python -m asl_mcp_server.server

Outils disponibles

1. Recherche d'adresses IP

Recherche d'adresses IP dans les données de Security Lake :

{"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 } }

Paramètres :

• ip_address (obligatoire) : Adresse IP à rechercher (IPv4 ou IPv6)
• start_time (optionnel) : Heure de début au format ISO (par défaut : il y a 7 jours)
• end_time (facultatif) : Heure de fin au format ISO (par défaut : maintenant)
• sources (optionnel) : Sources de données à rechercher (guardduty, cloudtrail, vpcflow, etc.)
• limit (optionnel) : Nombre maximum de résultats à retourner (default : 100, max : 1000)

2. Rechercher les résultats de GuardDuty

Interroger les résultats de sécurité de GuardDuty :

{"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 } }

Paramètres :

• finding_id (optionnel) : L'identifiant spécifique de l'enquête GuardDuty
• severity (optionnel) : Niveau de gravité (critique, élevé, moyen, faible, informatif)
• finding_type (optionnel) : Type de résultat à rechercher
• start_time (optionnel) : Heure de début au format ISO (par défaut : il y a 7 jours)
• end_time (optionnel) : Heure de fin au format ISO (par défaut : maintenant)
• limit (optionnel) : Nombre maximal de résultats à renvoyer (par défaut : 100, max : 1000)

3. Liste des sources de données

Découvrez les sources de données Security Lake disponibles :

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

Paramètres :

• include_schema (facultatif) : Inclut des informations détaillées sur le schéma de la table (par défaut : false)

4. Découvrir les ressources AWS

Découvrez automatiquement les ressources Security Lake dans votre compte AWS :

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

Cet outil analyse votre compte AWS pour trouver :

• Les buckets S3 et les bases de données de Security Lake
• Les emplacements de sortie d'Athena
• Recommandations de configuration
• Validation de la configuration

5. Recherche universelle de sécurité

Recherche intelligente dans toutes les sources de données Security Lake disponibles :

{"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 } }

Types de requêtes :

• résultats: Recherche de résultats de sécurité (GuardDuty, Security Hub)
• network: Recherche de l'activité du réseau (VPC Flow, DNS, Route53)
• api_calls: Recherche de l'activité API (CloudTrail)
• ip_search: Recherche par adresse IP dans toutes les sources

Caractéristiques principales :

• S'adapte automatiquement aux sources de données disponibles
• Prend en charge les schémas OCSF 1.0 et 2.0
• Repli intelligent (par exemple, Security Hub pour les données GuardDuty)
• Format de résultat unifié entre les différentes sources

6. Test de connexion

Vérifier la connectivité aux services AWS :

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

Format des réponses

Tous les outils renvoient des réponses dans un format cohérent :

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

Exemple de réponse - Recherche IP

{ "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" : "Activité réseau", "highest_severity" : "Medium" } }, "count" : 1 }

Développement

Mise en place de l'environnement de développement

# Cloner le dépôt git clone <repository-url> cd amazon-security-lake-mcp # Installer les dépendances de développement pip install -e ".[dev]" # Installer les hooks pre-commit pre-commit install

Exécution des tests

# Exécuter tous les tests pytest # Exécuter avec couverture pytest --cov=asl_mcp_server --cov-report=html # Exécuter des catégories de tests spécifiques pytest -m unit # Tests unitaires uniquement pytest -m integration # Tests d'intégration uniquement pytest -m slow # Tests à longue durée d'exécution

Qualité du code

# Format code black src tests # Lint code ruff src tests # Type checking mypy src

Considérations de sécurité

Validation des entrées

• Toutes les adresses IP sont validées avant l'interrogation
• Les paramètres de la requête sont nettoyés pour éviter les attaques par injection
• Les plages de temps sont validées pour être raisonnables

Contrôle d'accès

• Utilise AWS IAM pour l'authentification et l'autorisation
• Prise en charge des modèles d'accès avec le moins de privilèges possible
• Les résultats des requêtes sont limités afin d'éviter l'épuisement des ressources

Protection des données

• Aucune donnée sensible n'est enregistrée
• Les résultats des requêtes peuvent être filtrés pour supprimer les informations sensibles
• Prise en charge du cryptage en transit et au repos via les services AWS

Résolution des problèmes

Problèmes courants

1. Commande introuvable (erreur ENOENT)

Erreur : spawn asl-mcp-server ENOENT

Solution : Claude Desktop ne trouve pas la commande asl-mcp-server. Utilisez l'une des solutions suivantes :

Correction A : Use Full Command Path

# Trouver l'emplacement de la commande que asl-mcp-server # Sortie : /Users/username/.local/bin/asl-mcp-server # Mettre à jour la configuration de Claude Desktop avec le chemin complet { "mcpServers" : { "amazon-security-lake" : { "command" : "/Users/username/.local/bin/asl-mcp-server", "env" : { ... } } } }

Solution B : Utiliser le module Python (le plus fiable)

{ "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. Les informations d'identification AWS sont introuvables

Erreur : Les informations d'identification AWS ne sont pas configurées

Solution : Configurez les informations d'identification AWS à l'aide de l'une des méthodes suivantes :

• Définir la variable d'environnement AWS_PROFILE
• Configurer le fichier ~/.aws/credentials
• Utiliser les rôles IAM (recommandé pour EC2/Lambda)
• Définir les variables d'environnement AWS_ACCESS_KEY_ID et AWS_SECRET_ACCESS_KEY

2. Échec de la découverte automatique

Erreur : athena_output_location n'a pas pu être découvert automatiquement et n'a pas été fourni

Solution : Activez la configuration manuelle ou créez les ressources nécessaires :

Option A : Utiliser la configuration manuelle

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

Option B : Création d'une base de données pour les résultats d'Athena

# Créer un bucket pour les résultats d'Athena aws s3 mb s3://aws-athena-query-results-$(aws sts get-caller-identity --query Account --output text)-us-east-1

Option C : Exécuter l'outil de découverteUtilisez l'outil discover_aws_resources pour voir ce qui manque et obtenir des recommandations spécifiques.

3. Base de données Security Lake introuvable

Erreur : La base de données 'amazon_security_lake_glue_db' n'est pas disponible

Solution :

• Vérifiez que Security Lake est activé dans votre compte AWS
• Vérifiez que le nom de la base de données est correct
• Vérifiez que vous disposez des autorisations nécessaires pour accéder au catalogue Glue

4. Délai d'attente de la requête

Erreur : Query timeout après 300 secondes

Solution :

• Augmenter ASL_MCP_QUERY_TIMEOUT_SECONDS
• Utiliser des plages de temps plus spécifiques pour réduire le balayage des données
• Ajouter des clauses WHERE appropriées pour filtrer les résultats

Optimisation des performances

1. Utilisez des plages de temps spécifiques: Toujours spécifier l'heure de début et l'heure de fin pour tirer parti du partitionnement
2. Limitez les résultats: Utilisez des valeurs limites appropriées pour éviter les ensembles de résultats trop volumineux
3. Filtrer par source: Spécifiez le paramètre sources pour n'interroger que les tables pertinentes
4. Surveiller les coûts: Les requêtes volumineuses peuvent entraîner des frais importants pour Athena

Débogage

Activez la journalisation de débogage :

export ASL_MCP_LOG_LEVEL=DEBUG

Cela fournira des informations détaillées sur

• La construction et l'exécution de la requête
• Les appels à l'API AWS
• Traitement des résultats
• Détails des erreurs

Contribuer

1. Ouvrir le référentiel (Fork)
2. Créez une branche de fonctionnalités(git checkout -b feature/amazing-feature)
3. Effectuez vos modifications
4. Ajouter des tests pour les nouvelles fonctionnalités
5. S'assurer que tous les tests passent(pytest)
6. Validez vos modifications(git commit -m 'Add amazing feature')
7. Pousser vers la branche(git push origin feature/amazing-feature)
8. Ouvrir une demande de retrait (Pull Request)

Licence

Ce projet est sous licence MIT - voir le fichier LICENSE pour plus de détails.

Support

Pour les problèmes et les questions :

• Ouvrir un problème sur GitHub
• Consultez la section de dépannage ci-dessus
• Examinez la documentation d'AWS Security Lake
• Consulter la spécification OCSF

Projets connexes

• Documentation AWS Security Lake
• Schéma OCSF
• Protocole de contexte de modèle
• FastMCP

Changelog

v0.1.0 (version initiale)

• Fonctionnalité de recherche d'adresses IP
• Recherche de résultats de GuardDuty
• Recherche de sources de données
• Validation du schéma OCSF
• Suite de tests complète
• Intégration AWS avec traitement approprié des erreurs