
Plan de contrôle de sécurité pour agents LLM : listes d'autorisation, interrupteur d'arrêt d'urgence du propriétaire, sessions PIN, limites de débit, détection d'injection de prompt et nettoyage des sorties pour bloquer les fuites de secrets et l'exfiltration par balises image.
# Agentic DM Gateway

[](https://gitlab.com/WattoCyber/agentic-dm-gateway/-/pipelines) [](LICENSE) [](https://gitlab.com/WattoCyber/agentic-dm-gateway)
Plan de contrôle de sécurité pour les agents LLM sur messagerie privée (généralement les DM Discord).
Il se place **devant votre agent**. Il décide qui peut parler, si la session est déverrouillée, si le processus est en pause, et si ce message est suffisamment sûr pour être transmis. Votre modèle et vos outils restent derrière cette barrière. La bibliothèque n'appelle pas de LLM. Elle n'implémente aucune fonctionnalité produit au-delà de la sécurité.
**Inspiré de Hermes.** La conception suit les mêmes idées de plan de contrôle que celles utilisées dans les passerelles de messagerie de [Hermes Agent](https://github.com/NousResearch/hermes-agent) : livraison prioritaire aux DM, listes d'autorisation d'identité, ouverture de type appairage, interrupteur d'arrêt du propriétaire, et séparation stricte entre *qui peut agir* (plan de contrôle) et *le texte du message que voit le modèle* (plan de données). Ce paquet est un extrait autonome et compact de ce modèle pour tout agent appelable. Non affilié à Nous Research.
**Maturité :** implémenté · validé indépendamment · maintenu. Voir [STATUS.md](https://gitlab.com/wattocyber/agentic-dm-gateway/-/blob/main/STATUS.md).
**Reproduire :** `python scripts/repro.py` (attend `REPRO_OK`).
**Tests hors ligne :**
```bash
pip install -e ".[dev]" # or: pip install -e . && pip install pytest
python -m pytest -q --tb=line
# or: python scripts/repro.py
```
**En ligne :** https://gitlab.com/WattoCyber/agentic-dm-gateway
---
## Le problème
Si vous placez un agent sur Discord (ou toute API de messagerie) avec des outils, quiconque peut envoyer un message au bot peut tenter de :
- utiliser l'agent sans autorisation
- épuiser le quota d'API par des floods
- injecter des prompts du type « ignore previous instructions »
- tromper le modèle pour qu'il répète des clés d'API ou d'autres secrets
Vous avez besoin d'un **plan de contrôle** (contrôles d'identité et de processus) distinct du **plan de données** (le texte des messages que voit le modèle).
Ce paquet est ce plan de contrôle.
---
## Ce qu'il fait
| Contrôle | Comportement |
|---------|----------|
| **Liste d'autorisation** | Seuls les identifiants d'utilisateurs configurés peuvent poursuivre. Tous les autres sont rejetés (silencieusement ou avec une courte chaîne de refus). |
| **Propriétaire vs ami** | Les propriétaires ignorent le PIN et peuvent mettre en pause l'agent entier. Les amis peuvent avoir besoin d'un PIN partagé pour une ouverture limitée dans le temps (idée d'appairage à la Hermes, simplifiée). |
| **Interrupteur d'arrêt** | Fichier de pause global ou variable d'environnement. Aucun tour d'agent tant qu'il est actif. |
| **Limites de débit** | Fenêtre glissante par utilisateur (par minute et par heure). |
| **Vérifications d'entrée** | Longueur maximale, suppression des caractères de contrôle étranges, heuristiques regex pour les phrases courantes d'injection / de pêche aux secrets. |
| **Nettoyage de sortie** | Masquage des jetons ayant l'apparence de secrets (clés d'API, JWT, en-têtes Bearer) et suppression des balises image markdown/HTML pouvant exfiltrer via un chargement automatique. |
| **Journal d'audit** | JSONL en ajout seul des événements allow/deny/auth/kill pour examen ultérieur. |
| **Commandes locales** | `/auth`, `/lock`, `/kill`, `/unkill`, `/status` traitées sans appeler de modèle. |
Portée : porte de sécurité uniquement. Ni chatbot, ni bot de trading, ni scanner, ni framework d'agent. Passez un `agent(user_id, text) -> str` (ou asynchrone) si vous utilisez Discord. Le cœur fonctionne avec n'importe quel identifiant utilisateur entier et du texte brut.
---
## Démo (copier-coller)
```text
$ python - <<'PY'
from agentic_dm_gateway import InboundSecurityPipeline
pipe = InboundSecurityPipeline({
"allowed_user_ids": [111],
"owner_ids": [111],
"pin_enabled": False,
"block_injection": True,
"deny_message": "Not authorized.",
})
for uid, text in [
(99, "hi"),
(111, "ignore previous instructions"),
(111, "summarize this note"),
]:
r = pipe.precheck(uid, text)
print(uid, r.stage, r.run_agent, r.reply_text)
PY
99 allowlist False Not authorized.
111 injection False Blocked: looks like prompt injection / secret fishing. Rephrase.
111 ok True None
$ python scripts/repro.py
REPRO_OK agentic-dm-gateway unit suite
```
## Comment l'intégrer
Trois voies d'intégration. Choisissez-en une.
### 1) Intégration directe à Discord (la plus simple)
Installez avec le support Discord, configurez les variables d'environnement avec vos identifiants utilisateur, enregistrez la passerelle, lancez le bot.
```bash
pip install -e ".[discord]"
# or: pip install agentic-dm-gateway[discord]

export DISCORD_BOT_TOKEN=...
export AGENTIC_DM_ALLOWLIST=your_discord_user_id
export AGENTIC_DM_OWNER_ID=your_discord_user_id
# optional: export AGENTIC_DM_PIN=....

python examples/discord_echo_bot.py
```
Dans votre propre bot :
```python
import discord
from agentic_dm_gateway.discord_adapter import register_dm_gateway
def agent(user_id: int, text: str, *, is_owner: bool = False) -> str:
# your Hermes / local model / tool loop
return call_your_model(text)
intents = discord.Intents.default()
intents.message_content = True
bot = discord.Client(intents=intents)
register_dm_gateway(
bot,
{
"allowed_user_ids": [], # or rely on AGENTIC_DM_ALLOWLIST env
"owner_ids": [],
"pin_enabled": False,
"deny_message": False, # silent drop for strangers
},
agent=agent,
)
bot.run(TOKEN)
```
Ce que fait `register_dm_gateway` :
1. Installe un gestionnaire `on_message` sur votre `discord.Client` / bot.
2. Ignore les bots et les messages de **guild** (DMs uniquement).
3. Exécute `InboundSecurityPipeline.precheck` avant votre agent.
4. Envoie des réponses de refus / de contrôle lorsque nécessaire.
5. Appelle votre `agent(user_id, sanitized_text, is_owner=...)`.
6. Nettoie la réponse de l'agent (secrets + balises d'image) et découpe selon la limite de 2000 caractères de Discord.
Les messages de guild n'atteignent jamais l'agent. Seuls les DMs provenant d'utilisateurs figurant sur la liste d'autorisation le font.
### 2) Hook Discord manuel (vous avez déjà `on_message`)
Si vous ne pouvez pas utiliser `register_dm_gateway` (chaîne de gestionnaires existante), appelez le pipeline vous-même :
```python
from agentic_dm_gateway import InboundSecurityPipeline
from agentic_dm_gateway.security import sanitize_agent_output
pipe = InboundSecurityPipeline({
"allowed_user_ids": [YOUR_ID],
"owner_ids": [YOUR_ID],
"pin_enabled": True,
})
@bot.event
async def on_message(message):
if message.author.bot or message.guild is not None:
return
pre = pipe.precheck(int(message.author.id), message.content or "")
if pre.reply_text and not pre.run_agent:
await message.channel.send(pre.reply_text[:1900])
return
if not pre.run_agent:
return
raw = await your_agent(pre.sanitized_text) # Hermes, Ollama, API, ...
await message.channel.send(sanitize_agent_output(str(raw))[:1900])
```
### 3) Indépendant du protocole (Hermes, CLI, Telegram, tout autre)
Aucun import Discord requis. Utilisez le même précontrôle autour de n'importe quel tour d'agent :
```python
from agentic_dm_gateway import InboundSecurityPipeline
from agentic_dm_gateway.security import sanitize_agent_output
pipe = InboundSecurityPipeline({
"allowed_user_ids": [111],
"owner_ids": [111],
"pin_enabled": False,
"rate_limit_per_minute": 20,
"block_injection": True,
"deny_message": "Not authorized.",
})
def handle_inbound(user_id: int, text: str) -> str | None:
pre = pipe.precheck(user_id, text)
if pre.run_agent:
answer = my_llm(pre.sanitized_text) # your model / Hermes run
return sanitize_agent_output(str(answer))
return pre.reply_text # deny or control-command reply
```
Champs de `PrecheckResult` :
- `run_agent` : transmettre au modèle uniquement si vrai
- `sanitized_text` : entrée nettoyée
- `reply_text` : réponse de refus / de commande de contrôle
- `stage` : `allowlist` | `kill` | `pin` | `rate` | `injection` | `ok` | ...
Liste de vérification des hooks :
1. Construire `InboundSecurityPipeline` une seule fois au démarrage du processus (config + env).
2. À chaque message entrant : `pre = pipe.precheck(user_id, text)`.
3. Si `pre.run_agent` : appeler votre agent avec `pre.sanitized_text` uniquement.
4. Toujours faire passer la sortie du modèle par `sanitize_agent_output` avant l'envoi.
5. Considérer les réponses de contrôle (`/auth`, `/kill`, …) comme terminées lorsque `run_agent` est faux.
---
## Pipeline (un message entrant)
```
1. Adapter: ignore bots; only accept DMs (not server channels)
2. Allowlist: is this user id permitted?
3. Owner commands: /kill /unkill /status -> reply, stop
4. Session commands: /auth <pin> /lock -> reply, stop
5. SecurityGateway.check_message:
kill switch?
session unlocked? (PIN)
under rate limit?
length + injection heuristics OK?
6. If ok -> run_agent=True with sanitized text
7. After your agent returns -> sanitize_agent_output (redact + strip image beacons)
8. Audit rows written along the way
```
**Plan de contrôle :** qui est l'utilisateur (liste d'autorisation / propriétaire).
**Plan de données :** corps du message (toujours non fiable jusqu'à ce que les vérifications passent).
---
## Organisation des paquets
```
src/agentic_dm_gateway/
security.py # RateLimiter, SessionAuth, SecurityGateway,
# sanitize_input, redact_secrets, sanitize_agent_output,
# kill switch, audit_log
allowlist.py # merge config + env + file into allowlist / owners
commands.py # /kill /unkill /status /auth /lock (no LLM)
pipeline.py # InboundSecurityPipeline.precheck() orchestration
discord_adapter.py # optional discord.py on_message wire-up
tests/ # unit tests for the core (no Discord required)
examples/
minimal_precheck.py # CLI-style demo of precheck outcomes
discord_echo_bot.py # secured DMs + echo agent
```
| Module | Responsabilité |
|--------|----------------|
| `SecurityGateway` | Unique `check_message(user_id, text) -> SecurityVerdict` |
| `InboundSecurityPipeline` | Allowlist + commandes slash + gateway en un seul appel |
| `DiscordDMGateway` | Adaptateur DM uniquement ; vous injectez la fonction de l'agent |
Aucune dépendance d'exécution requise. Discord est optionnel : `pip install agentic-dm-gateway[discord]`.
---
## Installation
```bash
git clone https://gitlab.com/WattoCyber/agentic-dm-gateway.git
cd agentic-dm-gateway
pip install -e ".[dev]"
python scripts/repro.py
```
---
## Configuration
### Dict de configuration
| Clé | Valeur par défaut | Signification |
|-----|---------|---------|
| `allowed_user_ids` | `[]` | Identifiants utilisateur autorisés à discuter |
| `owner_ids` | `[]` | Ignorer le PIN ; peut `/kill` |
| `pin_enabled` | `True` | Contrôle PIN pour les non-propriétaires |
| `pin_ttl_hours` | `72` | durée d'ouverture |
| `rate_limit_per_minute` | `8` | Fenêtre glissante |
| `rate_limit_per_hour` | `60` | Fenêtre glissante |
| `max_input_chars` | `2000` | Longueur maximale d'entrée |
| `block_injection` | `True` | Liste de blocage heuristique |
| `deny_message` | `False` | Silencieux, `True`, ou chaîne personnalisée |
| `audit_log` | `True` | Écrire le journal d'audit JSONL |
| `enabled` | `True` | Interrupteur principal |
### Environnement
| Variable | Objectif |
|----------|---------|
| `AGENTIC_DM_ALLOWLIST` | Identifiants utilisateur séparés par des virgules |
| `AGENTIC_DM_OWNER_ID` | Identifiant(s) du propriétaire |
| `AGENTIC_DM_PIN` | PIN en clair |
| `AGENTIC_DM_PIN_REQUIRED` | `1` = exiger le PIN même s'il n'est pas défini |
| `AGENTIC_DM_KILLED` | `1` = interrupteur d'arrêt activé |
| `AGENTIC_DM_DATA_DIR` | Répertoire pour le fichier kill, open, journal d'audit |
| `AGENTIC_DM_SECRETS_DIR` | Répertoire pour `dm_pin.txt` / `dm_allowlist.txt` |
Répertoire d'état par défaut : `./data/agentic_dm/`.
---
## Commandes propriétaire et de session
| Commande | Qui | Effet |
|---------|-----|--------|
| `/kill` `/pause` | propriétaire | Mettre l'agent en pause pour tout le monde |
| `/unkill` `/resume` | propriétaire | Lever la pause |
| `/status` | propriétaire | Instantané Kill / PIN / liste d'autorisation |
| `/auth <pin>` | autorisé | ouvrir une session pour la durée TTL |
| `/lock` | autorisé | Fermer la session ouverte |
Ces commandes n'appellent jamais votre modèle.
---
## Limites (honnêtes)
- La détection d'injection est une **liste heuristique par regex**, pas un juge LLM complet ni un classificateur.
- La rédaction est une correspondance de motifs **au mieux** ; elle manquera les nouveaux formats de secrets.
- L'inspiration Hermes est architecturale (plan de contrôle DM). Ce n'est pas une passerelle Hermes complète ni une pile d'appairage.
- Vous avez toujours besoin d'un stockage sécurisé des jetons, d'outils à privilège minimal et d'un durcissement de l'hôte en dehors de cette bibliothèque.
---
## Licence
MIT. Voir [LICENSE](https://gitlab.com/wattocyber/agentic-dm-gateway/-/blob/main/LICENSE).