
Plano de control de seguridad para agentes LLM: listas permitidas, kill switch del propietario, sesiones PIN, límites de tasa, detección de inyección de prompts y depuración de salidas para bloquear la fuga de secretos y la exfiltración mediante balizas de imagen.
# Agentic DM Gateway

[](https://gitlab.com/WattoCyber/agentic-dm-gateway/-/pipelines) [](LICENSE) [](https://gitlab.com/WattoCyber/agentic-dm-gateway)
Plano de control de seguridad para agentes LLM sobre chat privado (típicamente MD de Discord).
Se sitúa **delante de tu agente**. Decide quién puede hablar, si la sesión está desbloqueada, si el proceso está en pausa y si este mensaje es lo suficientemente seguro como para reenviarlo. Tu modelo y tus herramientas permanecen detrás de esa puerta. La biblioteca no llama a un LLM. No implementa funcionalidades de producto más allá de la seguridad.
**Inspirado en Hermes.** El diseño sigue las mismas ideas de plano de control utilizadas en las pasarelas de mensajería de [Hermes Agent](https://github.com/NousResearch/hermes-agent): entrega prioritaria por MD, listas de identidades permitidas, apertura estilo emparejamiento, interruptor de apagado del propietario y una separación estricta entre *quién puede actuar* (plano de control) y *el texto del mensaje que ve el modelo* (plano de datos). Este paquete es un extracto pequeño y autónomo de ese patrón para cualquier agente invocable. No está afiliado a Nous Research.
**Madurez:** implementado · validado de forma independiente · mantenido. Consulta [STATUS.md](https://gitlab.com/wattocyber/agentic-dm-gateway/-/blob/main/STATUS.md).
**Reproducir:** `python scripts/repro.py` (espera `REPRO_OK`).
**Pruebas sin conexión:**
```bash
pip install -e ".[dev]" # or: pip install -e . && pip install pytest
python -m pytest -q --tb=line
# or: python scripts/repro.py
```
**En vivo:** https://gitlab.com/WattoCyber/agentic-dm-gateway
---
## El problema
Si pones un agente en Discord (o en cualquier API de chat) con herramientas, cualquiera que pueda enviar mensajes al bot puede intentar:
- usar el agente sin permiso
- agotar la cuota de API con floods
- inyectar prompts del estilo "ignora las instrucciones anteriores"
- engañar al modelo para que repita claves de API u otros secretos
Necesitas un **plano de control** (controles de identidad y de proceso) separado del **plano de datos** (el texto de los mensajes que ve el modelo).
Este paquete es ese plano de control.
---
## Qué hace
| Control | Comportamiento |
|---------|----------|
| **Lista de permitidos** | Solo los IDs de usuario configurados pueden continuar. Todos los demás son descartados (en silencio o con una cadena breve de denegación). |
| **Propietario vs amigo** | Los propietarios omiten el PIN y pueden pausar todo el agente. Los amigos pueden necesitar un PIN compartido para una apertura de tiempo limitado (idea de emparejamiento estilo Hermes, simplificada). |
| **Interruptor de emergencia** | Archivo de pausa global o flag de entorno. Ningún turno del agente mientras esté activo. |
| **Límites de tasa** | Ventana deslizante por usuario (por minuto y por hora). |
| **Comprobaciones de entrada** | Longitud máxima, eliminación de caracteres de control extraños, heurísticas de regex para frases comunes de inyección / pesca de secretos. |
| **Depuración de salida** | Redacta tokens con forma de secreto (claves de API, JWT, cabeceras Bearer) y elimina balizas de imagen markdown/HTML que pueden exfiltrar mediante auto-fetch. |
| **Registro de auditoría** | JSONL de solo adición de eventos de permitir/denegar/auth/kill para revisión posterior. |
| **Comandos locales** | `/auth`, `/lock`, `/kill`, `/unkill`, `/status` gestionados sin llamar a un modelo. |
Alcance: solo puerta de seguridad. No es un chatbot, bot de trading, escáner ni framework de agentes. Pasa un `agent(user_id, text) -> str` (o asíncrono) si usas Discord. El núcleo funciona con cualquier id de usuario entero y texto plano.
---
## Demo (copiar y pegar)
```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
```
## Cómo integrarlo
Tres rutas de integración. Elige una.
### 1) Integración directa con Discord (la más fácil)
Instálalo con soporte para Discord, configura las variables de entorno con tus ids de usuario, registra el gateway y ejecuta el 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
```
En tu propio 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)
```
Qué hace `register_dm_gateway`:
1. Instala un manejador `on_message` en tu `discord.Client` / bot.
2. Ignora los bots y los mensajes de **guild** (solo DMs).
3. Ejecuta `InboundSecurityPipeline.precheck` antes que tu agente.
4. Envía respuestas de denegación / control cuando es necesario.
5. Llama a tu `agent(user_id, sanitized_text, is_owner=...)`.
6. Depura la respuesta del agente (secretos + balizas de imagen) y divide el límite de 2000 caracteres de Discord.
Los mensajes de guild nunca llegan al agente. Solo lo hacen los DMs de usuarios en la lista de permitidos.
### 2) Hook manual de Discord (ya tienes `on_message`)
Si no puedes usar `register_dm_gateway` (cadena de manejadores existente), llama tú mismo al pipeline:
```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) Independiente del protocolo (Hermes, CLI, Telegram, cualquier cosa)
No se requiere importar Discord. Utilice la misma verificación previa en torno a cualquier turno del agente:
```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
```
Campos de `PrecheckResult`:
- `run_agent`: reenviar al modelo solo si es true
- `sanitized_text`: entrada saneada
- `reply_text`: respuesta de denegación / comando de control
- `stage`: `allowlist` | `kill` | `pin` | `rate` | `injection` | `ok` | ...
Lista de verificación de hooks:
1. Construir `InboundSecurityPipeline` una vez al inicio del proceso (config + env).
2. En cada mensaje entrante: `pre = pipe.precheck(user_id, text)`.
3. Si `pre.run_agent`: llamar a tu agente solo con `pre.sanitized_text`.
4. Pasar siempre la salida del modelo por `sanitize_agent_output` antes de enviar.
5. Tratar las respuestas de control (`/auth`, `/kill`, …) como completadas cuando `run_agent` es false.
---
## Pipeline (un mensaje entrante)
```
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
```
**Plano de control:** quién es el usuario (lista de permitidos / propietario).
**Plano de datos:** cuerpo del mensaje (siempre no confiable hasta que las comprobaciones pasen).
---
## Estructura del paquete
```
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
```
| Módulo | Responsabilidad |
|--------|----------------|
| `SecurityGateway` | Único `check_message(user_id, text) -> SecurityVerdict` |
| `InboundSecurityPipeline` | Lista de permitidos + comandos slash + gateway en una sola llamada |
| `DiscordDMGateway` | Adaptador solo para DM; tú inyectas la función del agente |
Cero dependencias de tiempo de ejecución requeridas. Discord es opcional: `pip install agentic-dm-gateway[discord]`.
---
## Instalación
```bash
git clone https://gitlab.com/WattoCyber/agentic-dm-gateway.git
cd agentic-dm-gateway
pip install -e ".[dev]"
python scripts/repro.py
```
---
## Configuración
### Diccionario de configuración
| Clave | Predeterminado | Significado |
|-----|---------|---------|
| `allowed_user_ids` | `[]` | Ids de usuario autorizados a chatear |
| `owner_ids` | `[]` | Omitir PIN; pueden usar `/kill` |
| `pin_enabled` | `True` | Puerta PIN para no propietarios |
| `pin_ttl_hours` | `72` | duración de apertura |
| `rate_limit_per_minute` | `8` | Ventana deslizante |
| `rate_limit_per_hour` | `60` | Ventana deslizante |
| `max_input_chars` | `2000` | Longitud máxima de entrada |
| `block_injection` | `True` | Lista de bloqueo heurística |
| `deny_message` | `False` | Silencioso, `True`, o cadena personalizada |
| `audit_log` | `True` | Escribir auditoría JSONL |
| `enabled` | `True` | Interruptor maestro |
### Entorno
| Variable | Propósito |
|----------|---------|
| `AGENTIC_DM_ALLOWLIST` | Ids de usuario separados por comas |
| `AGENTIC_DM_OWNER_ID` | Id(s) de propietario |
| `AGENTIC_DM_PIN` | PIN en texto plano |
| `AGENTIC_DM_PIN_REQUIRED` | `1` = requerir PIN incluso si no está establecido |
| `AGENTIC_DM_KILLED` | `1` = interruptor de apagado activado |
| `AGENTIC_DM_DATA_DIR` | Directorio para el archivo kill, open, registro de auditoría |
| `AGENTIC_DM_SECRETS_DIR` | Directorio para `dm_pin.txt` / `dm_allowlist.txt` |
Directorio de estado predeterminado: `./data/agentic_dm/`.
---
## Comandos de propietario y de sesión
| Comando | Quién | Efecto |
|---------|-----|--------|
| `/kill` `/pause` | propietario | Pausar el agente para todos |
| `/unkill` `/resume` | propietario | Borrar la pausa |
| `/status` | propietario | Instantánea de kill / PIN / lista de permitidos |
| `/auth <pin>` | en lista de permitidos | abrir sesión por el TTL |
| `/lock` | en lista de permitidos | Borrar apertura |
Estos nunca llaman a tu modelo.
---
## Limitaciones (con honestidad)
- La detección de inyección es una **lista heurística de expresiones regulares**, no un juez o clasificador LLM completo.
- La redacción es una coincidencia de patrones de **mejor esfuerzo**; pasará por alto formatos de secretos novedosos.
- La inspiración en Hermes es arquitectónica (plano de control de DM). Esto no es una pasarela Hermes completa ni una pila de emparejamiento.
- Aún necesitas almacenamiento seguro de tokens, herramientas de mínimo privilegio y endurecimiento del host fuera de esta biblioteca.
---
## Licencia
MIT. Ver [LICENSE](https://gitlab.com/wattocyber/agentic-dm-gateway/-/blob/main/LICENSE).