🕵️ Framework OSINT Modulaire avec Claude Code

Un framework OSINT (Open Source Intelligence) moderne et modulaire conçu pour l'orchestration intelligente via Claude Code et le Model Context Protocol (MCP).

🎯 Vue d'ensemble

Ce framework implémente une architecture microservices complète pour la collecte, l'analyse et la corrélation d'informations OSINT. Chaque module fonctionne dans son propre conteneur Docker, orchestré par Claude via MCP pour une intelligence adaptative.

✨ Caractéristiques principales

• 🌐 Interface Web Moderne - Dashboard responsive avec monitoring temps réel
• 🤖 Orchestration Claude - Intégration native avec Claude Code via MCP
• 🐳 Architecture Docker - Modules isolés et scalables
• ⚡ Traitement asynchrone - Queues Redis pour la performance
• 🔐 Sécurité renforcée - XSS protection, CSP headers, authentification JWT
• 📊 Monitoring complet - Métriques Prometheus, logs structurés, alertes
• 🔄 Découverte dynamique - Registry automatique des modules
• 🛡️ Mode dégradé - Fonctionnement gracieux avec fallback mémoire

🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Claude Code   │    │  API Gateway    │    │ WebSocket Server│
│      (MCP)      │◄──►│   (FastAPI)     │◄──►│  (Temps réel)   │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Infrastructure Redis                         │
│              Cache, Queues, Pub/Sub, Métriques                │
└─────────────────────────────────────────────────────────────────┘
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Module DNS    │    │  Module GitHub  │    │ Module Shodan   │
│   (Container)   │    │   (Container)   │    │  (Container)    │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 ▼
                    ┌─────────────────────┐
                    │    PostgreSQL       │
                    │   (Métadonnées)     │
                    └─────────────────────┘

🚀 Démarrage rapide

Prérequis

• Docker & Docker Compose
• Python 3.11+
• Claude Desktop (pour l'intégration MCP)

Installation

1. Clonage et configuration

git clone <repository>
cd osint-framework
cp .env.example .env
# Éditez .env avec vos configurations

2. Démarrage complet

./scripts/start-framework.sh

3. Interface Web

# Lancer l'interface web
cd frontend
python3 -m venv venv
source venv/bin/activate  # Linux/Mac
pip install fastapi uvicorn aiohttp asyncpg redis pydantic python-multipart jinja2
python web_interface.py

4. Vérification

curl http://localhost:8080/health

🌐 Accès aux services

• Interface Web : http://localhost:8090 (Dashboard principal)
• API Gateway : http://localhost:8080 (API REST)
• MCP Server : http://localhost:8081 (Serveur de modules)

Configuration Claude Desktop

Ajoutez cette configuration à votre claude_desktop_config.json :

{
  "mcpServers": {
    "osint-framework": {
      "command": "python",
      "args": ["-m", "modules.mcp.server"],
      "cwd": "/path/to/osint-framework",
      "env": {
        "POSTGRES_HOST": "localhost",
        "REDIS_HOST": "localhost",
        "MCP_SERVER_PORT": "8081"
      }
    }
  }
}

🛠️ Utilisation

🌐 Interface Web (Recommandée)

L'interface web offre une expérience utilisateur complète :

Pages disponibles :

• Dashboard - Monitoring système temps réel, métriques, graphiques
• Investigation - Lancer des analyses OSINT interactives
• Modules - Gérer et configurer les modules actifs
• Historique - Consulter toutes les investigations passées
• Documentation - Guide complet d'utilisation

Comptes de démonstration :

• Admin : admin / osint2024
• Analyste : analyst / analyst123
• Démo : demo / demo

Avec Claude Code

Une fois configuré, vous pouvez utiliser Claude pour orchestrer les investigations :

Analyse le domaine example.com avec tous les modules disponibles

Claude utilisera automatiquement le framework via MCP pour :

1. Créer une nouvelle investigation
2. Lancer les modules appropriés (DNS, WHOIS, GitHub, etc.)
3. Collecter et corréler les résultats
4. Présenter un rapport consolidé

Via l'API REST

# Lancer une investigation
curl -X POST http://localhost:8080/api/v1/investigations \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Investigation example.com",
    "targets": [
      {"value": "example.com", "type": "domain"}
    ]
  }'

# Vérifier le statut
curl http://localhost:8080/api/v1/investigations/1/status

📋 Modules disponibles

Modules de base

Module	Description	Cibles supportées	API requise
DNS	Analyse DNS complète	domain	Non
WHOIS	Informations de domaine	domain, ip	Non
GitHub	Reconnaissance GitHub	username, email	Oui
Shodan	Scan d'infrastructure	ip, domain	Oui

Ajouter un module

1. Créer le répertoire

mkdir modules/osint/monmodule

2. Dockerfile du module

FROM osint/base:latest
LABEL osint.module.display_name="Mon Module"
LABEL osint.module.target_types='["domain"]'
# ... configuration spécifique

3. Enregistrement automatique Le Module Registry découvrira automatiquement le nouveau module au redémarrage.

🔧 Commandes utiles

# Gestion de l'infrastructure
make up              # Démarrer tous les services
make down            # Arrêter tous les services
make restart         # Redémarrer
make status          # Statut des services
make logs            # Voir les logs

# Développement
make test            # Lancer les tests
make lint            # Vérifier le code
make format          # Formater le code

# Nettoyage
make clean           # Nettoyer les containers
make clean-all       # Nettoyage complet (⚠️ supprime les données)

# Monitoring
make up-monitoring   # Démarrer Prometheus/Grafana
make ports           # Afficher les ports utilisés

📊 Monitoring

Prometheus & Grafana

make up-monitoring

• Prometheus: http://localhost:9090
• Grafana: http://localhost:3000 (admin/admin)

Métriques disponibles

• Nombre d'investigations par statut
• Performance des modules OSINT
• Métriques de l'API Gateway
• Santé des queues Redis

🔐 Sécurité

Authentification

Le framework utilise JWT pour l'authentification :

# Connexion (demo)
curl -X POST http://localhost:8080/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "demo", "password": "demo123"}'

Gestion des secrets

• Docker Secrets pour les clés API
• HashiCorp Vault (optionnel)
• Chiffrement Fernet pour les données sensibles

Isolation réseau

• Réseau interne pour les communications inter-services
• Réseau externe pour l'accès public
• Pas d'exposition directe des modules

🧪 Tests

# Tests unitaires
pytest tests/unit/

# Tests d'intégration
pytest tests/integration/

# Tests end-to-end
pytest tests/e2e/

# Tests avec Docker
make test-docker

📚 Documentation API

• Swagger UI: http://localhost:8080/docs
• ReDoc: http://localhost:8080/redoc

🤝 Contribution

1. Fork le projet
2. Créer une branche (git checkout -b feature/nouvelle-fonctionnalite)
3. Commit (git commit -am 'Ajout nouvelle fonctionnalité')
4. Push (git push origin feature/nouvelle-fonctionnalite)
5. Pull Request

Standards de code

• Black pour le formatage
• Ruff pour le linting
• MyPy pour le type checking
• Tests obligatoires pour les nouvelles fonctionnalités

🔍 Dépannage

Problèmes courants

Services non accessibles

make health  # Vérifier la santé des services
make logs    # Examiner les logs

Problèmes de base de données

make db-shell     # Accès PostgreSQL
make db-migrate   # Relancer les migrations

Problèmes Docker

docker system prune -f  # Nettoyer Docker
make build              # Reconstruire les images

Logs structurés

Tous les logs sont en JSON structuré pour faciliter l'analyse :

make logs | jq '.level == "ERROR"'  # Filtrer les erreurs

📖 Ressources

• Documentation MCP
• FastAPI Documentation
• Docker Compose Reference
• OSINT Best Practices

📄 Licence

MIT License - voir le fichier LICENSE pour plus de détails.

🙏 Remerciements

• Anthropic pour Claude Code et MCP
• FastAPI pour le framework web
• Docker pour la containerisation
• La communauté OSINT pour l'inspiration

---

🚀 Le framework est prêt pour l'orchestration intelligente via Claude Code !