overmind-mcp
Version:
Orchestrateur universel agents IA multi-modeles via MCP. Inclut le protocole 'Custom-Nickname' pour identifier vos agents avec des surnoms originaux (The Chaos Prophet, Shadow Sniper, etc.), l'isolation mémoire (Private Memory Context) et le support pour
352 lines (288 loc) • 14.9 kB
Markdown
# 🛡️ PLAN SÉCURITÉ OVERMIND — Guérison Complète
> **Date** : 28 Mai 2026
> **Auteur** : Sniper Analyste Financier (via audit Discord)
> **Relecteur** : sley_73350 (validation en cours)
> **Version** : 1.0 — Brouillon pour validation
## 🔍 ÉTAT DES LIEUX — Diagnostic Critique
### Surface d'attaque actuelle
```
╔═══════════════════════════════════════════════════════════════════════════╗
║ TRANSPORT │ PROTOCOLE │ POINT D'ENTRÉE │ AUTH? │ PORT ║
╠═══════════════════════════════════════════════════════════════════════════╣
║ STDIO │ JSON-RPC 2.0 │ stdin → stdout │ ❌ │ N/A ║
║ HTTP Stream │ JSON-RPC 2.0 │ POST /mcp │ ❌ │ 3099 ║
║ HTTP Stream │ SSE │ POST /mcp (stream) │ ❌ │ 3099 ║
║ HTTP Stream │ REST │ GET /health │ ❌ │ 3099 ║
║ HTTPS (SSL) │ JSON-RPC 2.0 │ POST /mcp │ ❌ │ 3099 ║
║ HTTPS (SSL) │ SSE │ POST /mcp (stream) │ ❌ │ 3099 ║
╚═══════════════════════════════════════════════════════════════════════════╝
🔐 CONSTAT : TOUS les endpoints sont OUVERTS — 0 authentification côté serveur
```
### 14 Outils MCP exposés sans protection
```
# │ TOOL │ RISQUE
───┼─────────────────────────┼──────────
01 │ run_agent │ 🔴 CRITIQUE
02 │ run_agents_parallel │ 🔴 CRITIQUE
03 │ create_agent │ 🟠 ÉLEVÉ
04 │ delete_agent │ 🟠 ÉLEVÉ
05 │ update_agent_config │ 🔴 CRITIQUE
06 │ list_agents │ 🟡 MOYEN
07 │ get_agent_configs │ 🔴 CRITIQUE (fuites clés API)
08 │ create_prompt │ 🟡 MOYEN
09 │ edit_prompt │ 🟡 MOYEN
10 │ memory_search │ 🟡 MOYEN
11 │ memory_store │ 🟡 MOYEN
12 │ memory_runs │ 🟢 FAIBLE
13 │ config_example │ 🟢 FAIBLE
14 │ agent_control │ 🔴 CRITIQUE (kill process)
```
### Modules bibliothèque — Couverture Bearer
```
MODULE │ TYPE │ ENVOIE BEARER │ REÇOIT/VERIFY │ STATUS
────────────────────────┼─────────┼───────────────┼───────────────┼───────
overmind-client.ts │ Client │ ✅ OUI │ N/A │ ✅ OK
cli.ts (serveur) │ Serveur │ N/A │ ❌ NON │ 🔴 GAP
server.ts (FastMCP) │ Serveur │ N/A │ ❌ NON │ 🔴 GAP
run_agent.ts │ Tool │ N/A │ ❌ NON │ 🔴 GAP
run_agents_parallel.ts │ Tool │ N/A │ ❌ NON │ 🔴 GAP
create_agent.ts │ Tool │ N/A │ ❌ NON │ 🔴 GAP
manage_agents.ts │ Tool │ N/A │ ❌ NON │ 🔴 GAP
memory_store.ts │ Tool │ N/A │ ❌ NON │ 🔴 GAP
memory_search.ts │ Tool │ N/A │ ❌ NON │ 🔴 GAP
agent_control.ts │ Tool │ N/A │ ❌ NON │ 🔴 GAP
config.ts │ Config │ N/A │ ❌ NON │ 🟡
processRegistry.ts │ Runtime │ N/A │ ❌ NON │ 🔴 GAP
```
## 🏗️ ARCHITECTURE CIBLE — Après Guérison
```
🔐 MIDDLEWARE AUTH ACTIF 🔐
┌──────────┐ Bearer ┌──────────────┐ ┌────────────┐
│ Client │ ──────────▶ │ FastMCP │───▶│ 14 Tools │
│ (TS/JS) │ Header ✓ │ v4.0.1 │ │ MCP │
│ │ │ ✅ CHECK ✓ │ │ (protégés)│
└──────────┘ └──────┬───────┘ └────────────┘
│
┌────────────┴────────────┐
│ Transports sécurisés │
├─────────────────────────┤
│ stdio (pipe local) │
│ httpStream (port 3099) │
│ endpoint: /mcp │
│ ✅ Bearer: REQUIRED │
│ stateless: true │
│ SSL: ACTIF │
└─────────────────────────┘
```
## 📋 PLAN D'IMPLÉMENTATION — 5 Phases
### PHASE 1 — Middleware Serveur Bearer (PRIORITÉ MAX)
**Objectif** : Bloquer tout accès non authentifié sur HTTP/RPC
**Fichier cible** : `src/cli.ts` + `src/server.ts`
**Tâches** :
- [ ] Créer `src/lib/bearerMiddleware.ts`
- Fonction `verifyBearer(request): boolean`
- Lecture `OVERMIND_AUTH` depuis `.env`
- Comparaison via `crypto.timingSafeEqual()` (anti timing attack)
- Retourner 401 + message JSON si token absent/invalide
- [ ] Injecter le middleware dans FastMCP httpStream
- Hook AVANT `server.start()`
- Exempter UNIQUEMENT `GET /health` (monitoring)
- Bloquer tout le reste si token absent
- [ ] Logger chaque accès (audit trail)
- IP source, timestamp, tool appelé, résultat auth
**Code de référence** :
```typescript
// src/lib/bearerMiddleware.ts
import crypto from 'crypto';
export function verifyBearer(authHeader: string | undefined): boolean {
const expected = process.env.OVERMIND_AUTH;
if (!expected) {
console.warn('[AUTH] ⚠️ OVERMIND_AUTH non défini — accès refusé par défaut');
return false;
}
if (!authHeader?.startsWith('Bearer ')) return false;
const token = authHeader.slice(7);
const expectedBuf = Buffer.from(expected);
const tokenBuf = Buffer.from(token);
if (tokenBuf.length !== expectedBuf.length) return false;
return crypto.timingSafeEqual(tokenBuf, expectedBuf);
}
```
**Validation** :
- [ ] Tester sans token → 401
- [ ] Tester avec mauvais token → 401
- [ ] Tester avec bon token → 200
- [ ] GET /health sans token → 200 (exempté)
---
### PHASE 2 — Intégration dans tous les modules de la bibliothèque
**Objectif** : Chaque module serveur vérifie le Bearer
**Fichiers cibles** :
- `src/cli.ts` (serveur principal)
- `src/server.ts` (FastMCP)
- Chaque tool MCP (run_agent, memory_store, etc.)
**Tâches** :
- [ ] Importer `verifyBearer` dans chaque point d'entrée serveur
- [ ] Ajouter un wrapper `withAuth(toolHandler)` qui :
1. Extrait le header Authorization du contexte MCP
2. Vérifie via `verifyBearer()`
3. Si échec → retourne erreur MCP avec code d'auth
4. Si succès → exécute le tool normalement
- [ ] Valider que les 14 tools sont couverts
**Code de référence** :
```typescript
// src/lib/withAuth.ts
import { verifyBearer } from './bearerMiddleware';
export function withAuth(handler: Function) {
return async (args: any, context: any) => {
const authHeader = context?.request?.headers?.authorization;
if (!verifyBearer(authHeader)) {
throw new Error('[AUTH] ❌ Accès refusé — Bearer token invalide');
}
return handler(args, context);
};
}
```
### PHASE 3 — Propagation aux configs agents (.mcp.json)
**Objectif** : Chaque agent injecte le Bearer dans ses appels
**Tâches** :
- [ ] Vérifier que `overmind-client.ts` envoie bien le Bearer ✅ (déjà fait)
- [ ] Mettre à jour les templates `.mcp.json` des agents
- Ajouter `Authorization: Bearer ${OVERMIND_AUTH}` dans les headers
- [ ] Scripts externes → utiliser `OVERMIND_AUTH` depuis `.env`
- [ ] Documenter la variable dans le README Overmind
**Exemple .mcp.json** :
```json
{
"mcpServers": {
"overmind": {
"url": "http://localhost:3099/mcp",
"headers": {
"Authorization": "Bearer ${OVERMIND_AUTH}"
}
}
}
}
```
### PHASE 4 — SSL/TLS + Durcissement Réseau
**Objectif** : Chiffrer les communications + réduire la surface
**Tâches** :
- [ ] Activer SSL sur le port 3099 (HTTPS)
- Générer certificat auto-signé ou Let's Encrypt
- Configurer dans FastMCP httpStream
- [ ] Restreindre le bind à `localhost` uniquement (sauf besoin externe)
- [ ] Ajouter rate-limiting sur les endpoints
- Max 100 req/min par IP
- Ban temporaire après 5 échecs d'auth consécutifs
- [ ] CORS restrictif (si besoin)
- [ ] Firewall : bloquer le port 3099 à l'extérieur sauf reverse proxy
### PHASE 5 — Audit Trail & Monitoring
**Objectif** : Traçabilité complète des accès
**Tâches** :
- [ ] Logger chaque requête MCP :
- Timestamp ISO 8601
- IP source
- Tool appelé
- Résultat auth (success/fail)
- Agent demandeur
- [ ] Stocker les logs dans PostgreSQL (table `audit_log`)
```sql
CREATE TABLE audit_log (
id SERIAL PRIMARY KEY,
timestamp TIMESTAMPTZ DEFAULT NOW(),
ip VARCHAR(45),
tool VARCHAR(100),
agent VARCHAR(100),
auth_result BOOLEAN,
details JSONB
);
```
- [ ] Alertes Discord automatiques :
- 3 échecs d'auth consécutifs → alerte embed
- Tool critique appelé → notification
- [ ] Dashboard simple (endpoint `/audit/stats`)
## 🧪 PLAN DE TEST — Validation par Phase
### Tests Phase 1 (Middleware)
```
TEST │ DESCRIPTION │ RÉSULTAT ATTENDU
─────┼────────────────────────────────┼──────────────────
T1.1 │ curl POST /mcp sans header │ 401 Unauthorized
T1.2 │ curl POST /mcp mauvais token │ 401 Unauthorized
T1.3 │ curl POST /mcp bon token │ 200 OK
T1.4 │ curl GET /health sans token │ 200 OK (exempté)
T1.5 │ curl GET /health mauvais token │ 200 OK (exempté)
T1.6 │ Token vide │ 401 Unauthorized
T1.7 │ OVERMIND_AUTH non défini │ 500 / 403
```
### Tests Phase 2 (Couverture modules)
```
TEST │ DESCRIPTION │ RÉSULTAT ATTENDU
─────┼───────────────────────────────────────┼──────────────────
T2.1 │ Appeler run_agent sans Bearer │ Erreur MCP auth
T2.2 │ Appeler run_agent avec Bearer │ Exécution normale
T2.3 │ Appeler memory_search sans Bearer │ Erreur MCP auth
T2.4 │ Appeler agent_control sans Bearer │ Erreur MCP auth
T2.5 │ Vérifier les 14 tools couverts │ 14/14 ✅
```
### Tests Phase 3 (Propagation)
```
TEST │ DESCRIPTION │ RÉSULTAT ATTENDU
─────┼──────────────────────────────────────────┼──────────────────
T3.1 │ Agent Claude appelle overmind sans Bearer │ Connexion refusée
T3.2 │ Agent Kilo appelle overmind avec Bearer │ Connexion OK
T3.3 │ Script externe sans OVERMIND_AUTH │ Échec auth
T3.4 │ Script externe avec OVERMIND_AUTH │ Succès
```
### Tests Phase 4 (SSL + Durcissement)
```
TEST │ DESCRIPTION │ RÉSULTAT ATTENDU
─────┼──────────────────────────────────────────┼──────────────────
T4.1 │ Accès HTTP (non SSL) │ Connexion refusée
T4.2 │ Accès HTTPS avec cert valide │ 200 OK
T4.3 │ Rate limit : 100+ req/min │ 429 Too Many
T4.4 │ 5 échecs auth consécutifs │ Ban temporaire
T4.5 │ Bind localhost uniquement │ Pas d'accès externe
```
### Tests Phase 5 (Audit)
```
TEST │ DESCRIPTION │ RÉSULTAT ATTENDU
─────┼──────────────────────────────────────────┼──────────────────
T5.1 │ Appel tool → vérifier log PostgreSQL │ Entrée présente
T5.2 │ Échec auth → vérifier log │ Entrée avec auth_result=false
T5.3 │ 3 échecs consécutifs → alerte Discord │ Embed envoyé
T5.4 │ GET /audit/stats │ JSON statistiques
```
## 📊 PRIORISATION & EFFORT
```
PHASE │ PRIORITÉ │ EFFORT │ IMPACT │ DÉPENDANCE
──────┼─────────────┼───────────┼────────────┼────────────
1 │ 🔴 CRITIQUE │ 🟡 Moyen │ 🟢 MAX │ Aucune
2 │ 🟠 ÉLEVÉ │ 🟡 Moyen │ 🟢 ÉLEVÉ │ Phase 1
3 │ 🟡 MOYEN │ 🟢 Faible │ 🟡 MOYEN │ Phase 1
4 │ 🟡 MOYEN │ 🔴 ÉLEVÉ │ 🟢 ÉLEVÉ │ Phase 1
5 │ 🟢 FAIBLE │ 🟡 Moyen │ 🟡 MOYEN │ Phase 1+2
```
**Recommandation** : Phase 1 immédiate → Phase 2 le même jour → Phase 3 le lendemain → Phase 4-5 dans la semaine
## 🔑 LIVRABLES
1. `src/lib/bearerMiddleware.ts` — Middleware de vérification Bearer
2. `src/lib/withAuth.ts` — Wrapper pour les handlers MCP
3. `.env` — Ajout de `OVERMIND_AUTH=<token_sécurisé>`
4. `audit_log` table PostgreSQL — Traçabilité
5. Documentation mise à jour — README + SECURITY.md
## ⚠️ POINTS D'ATTENTION (Sley à vérifier)
- Le Bearer middleware doit-il être dans `cli.ts` OU dans un hook FastMCP ?
- FastMCP v4.0.1 supporte-t-il un middleware natif ou faut-il un workaround Express ?
- STDIO doit-il aussi être protégé ou est-il trusted par design (local pipe) ?
- Le token doit-il être rotatif ou statique ?
- Faut-il un système de scopes (admin vs lecture seule) ?
*📝 Document en attente de validation par sley_73350*