
Piano di controllo della sicurezza per agenti LLM: allowlist, kill switch del proprietario, sessioni PIN, limiti di frequenza, rilevamento delle iniezioni di prompt e pulizia dell'output per bloccare la fuga di segreti e l'esfiltrazione tramite beacon nelle immagini.
# Agentic DM Gateway

[](https://gitlab.com/WattoCyber/agentic-dm-gateway/-/pipelines) [](LICENSE) [](https://gitlab.com/WattoCyber/agentic-dm-gateway)
Piano di controllo di sicurezza per agenti LLM su chat private (tipicamente DM di Discord).
Si colloca **davanti al tuo agente**. Decide chi può parlare, se la sessione è sbloccata, se il processo è in pausa e se questo messaggio è sufficientemente sicuro da essere inoltrato. Il tuo modello e i tuoi strumenti restano dietro quel cancello. La libreria non chiama un LLM. Non implementa funzionalità di prodotto al di là della sicurezza.
**Ispirato a Hermes.** Il design segue le stesse idee di piano di controllo usate nei gateway di messaggistica di [Hermes Agent](https://github.com/NousResearch/hermes-agent): consegna DM-first, allowlist di identità, apertura in stile pairing, kill switch del proprietario e una netta separazione tra *chi può agire* (piano di controllo) e *testo del messaggio che il modello vede* (piano dati). Questo pacchetto è un piccolo estratto autonomo di quel pattern per qualsiasi agente richiamabile. Non affiliato a Nous Research.
**Maturità:** implementato · validato in modo indipendente · mantenuto. Vedi [STATUS.md](https://gitlab.com/wattocyber/agentic-dm-gateway/-/blob/main/STATUS.md).
**Riproduci:** `python scripts/repro.py` (attende `REPRO_OK`).
**Test offline:**
```bash
pip install -e ".[dev]" # or: pip install -e . && pip install pytest
python -m pytest -q --tb=line
# or: python scripts/repro.py
```
**Live:** https://gitlab.com/WattoCyber/agentic-dm-gateway
---
## Il problema
Se metti un agente su Discord (o su qualsiasi API di chat) dotato di strumenti, chiunque possa inviare messaggi al bot può tentare di:
- usare l'agente senza autorizzazione
- consumare la quota API con flood
- iniettare prompt del tipo "ignora le istruzioni precedenti"
- indurre il modello a rivelare chiavi API o altri segreti
Serve un **control plane** (controlli di identità e di processo) separato dal **data plane** (il testo dei messaggi che il modello vede).
Questo pacchetto è quel control plane.
---
## Cosa fa
| Controllo | Comportamento |
|---------|----------|
| **Allowlist** | Solo gli ID utente configurati possono procedere. Tutti gli altri vengono scartati (in modo silenzioso o con una breve stringa di rifiuto). |
| **Owner vs friend** | Gli owner saltano il PIN e possono mettere in pausa l'intero agente. I friend possono richiedere un PIN condiviso per un'apertura a tempo limitato (idea di pairing in stile Hermes, semplificata). |
| **Kill switch** | File di pausa globale o flag di ambiente. Nessun turno dell'agente mentre è attivo. |
| **Rate limit** | Finestra scorrevole per utente (al minuto e all'ora). |
| **Controlli sull'input** | Lunghezza massima, rimozione di caratteri di controllo anomali, euristiche regex per frasi comuni di injection / secret-fishing. |
| **Pulizia dell'output** | Oscuramento di token con forma di segreto (chiavi API, JWT, header Bearer) e rimozione di beacon immagine markdown/HTML che possono esfiltrare tramite auto-fetch. |
| **Log di audit** | JSONL append-only di eventi allow/deny/auth/kill per revisioni successive. |
| **Comandi locali** | `/auth`, `/lock`, `/kill`, `/unkill`, `/status` gestiti senza chiamare un modello. |
Ambito: solo gate di sicurezza. Non è un chatbot, un trading bot, uno scanner o un framework per agenti. Passa un `agent(user_id, text) -> str` (o async) se usi Discord. Il core funziona con qualsiasi user id intero e testo semplice.
---
## Demo (copia-incolla)
```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
```
## Come integrarlo
Tre percorsi di integrazione. Scegline uno.
### 1) Drop-in Discord (il più semplice)
Installa con il supporto Discord, punta le variabili d'ambiente ai tuoi user id, registra il gateway, avvia il 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
```
Nel tuo 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)
```
Cosa fa `register_dm_gateway`:
1. Installa un handler `on_message` sul tuo `discord.Client` / bot.
2. Ignora i bot e i messaggi di **guild** (solo DM).
3. Esegue `InboundSecurityPipeline.precheck` prima del tuo agente.
4. Invia risposte di rifiuto / controllo quando necessario.
5. Chiama il tuo `agent(user_id, sanitized_text, is_owner=...)`.
6. Ripulisce la risposta dell'agente (segreti + beacon immagine) e suddivide in chunk il limite di 2000 caratteri di Discord.
I messaggi di guild non raggiungono mai l'agente. Solo i DM degli utenti in allowlist lo fanno.
### 2) Hook Discord manuale (hai già `on_message`)
Se non puoi usare `register_dm_gateway` (catena di handler esistente), chiama tu stesso la 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) Indipendente dal protocollo (Hermes, CLI, Telegram, qualsiasi cosa)
Nessun import di Discord richiesto. Utilizza lo stesso precheck attorno a qualsiasi turno dell'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
```
Campi di `PrecheckResult`:
- `run_agent`: inoltra al modello solo se true
- `sanitized_text`: input ripulito
- `reply_text`: risposta di blocco / comando di controllo
- `stage`: `allowlist` | `kill` | `pin` | `rate` | `injection` | `ok` | ...
Checklist degli hook:
1. Costruisci `InboundSecurityPipeline` una sola volta all'avvio del processo (config + env).
2. Su ogni messaggio in ingresso: `pre = pipe.precheck(user_id, text)`.
3. Se `pre.run_agent`: chiama il tuo agente solo con `pre.sanitized_text`.
4. Passa sempre l'output del modello attraverso `sanitize_agent_output` prima dell'invio.
5. Considera le risposte di controllo (`/auth`, `/kill`, …) come completate quando `run_agent` è false.
---
## Pipeline (un singolo messaggio in ingresso)
```
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
```
**Piano di controllo:** chi è l'utente (allowlist / proprietario).
**Piano dati:** corpo del messaggio (sempre non attendibile finché i controlli non vengono superati).
---
## Struttura del pacchetto
```
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
```
| Modulo | Responsabilità |
|--------|----------------|
| `SecurityGateway` | Singolo `check_message(user_id, text) -> SecurityVerdict` |
| `InboundSecurityPipeline` | Allowlist + comandi slash + gateway in un'unica chiamata |
| `DiscordDMGateway` | Adattatore solo DM; tu inietti la funzione dell'agente |
Zero dipendenze runtime richieste. Discord è opzionale: `pip install agentic-dm-gateway[discord]`.
---
## Installazione
```bash
git clone https://gitlab.com/WattoCyber/agentic-dm-gateway.git
cd agentic-dm-gateway
pip install -e ".[dev]"
python scripts/repro.py
```
---
## Configurazione
### Dict di configurazione
| Chiave | Predefinito | Significato |
|-----|---------|---------|
| `allowed_user_ids` | `[]` | Id utente autorizzati a chattare |
| `owner_ids` | `[]` | Salta il PIN; può eseguire `/kill` |
| `pin_enabled` | `True` | Gate PIN per i non-owner |
| `pin_ttl_hours` | `72` | durata apertura |
| `rate_limit_per_minute` | `8` | Finestra scorrevole |
| `rate_limit_per_hour` | `60` | Finestra scorrevole |
| `max_input_chars` | `2000` | Lunghezza massima input |
| `block_injection` | `True` | Lista di blocco euristica |
| `deny_message` | `False` | Silenzioso, `True`, o stringa personalizzata |
| `audit_log` | `True` | Scrive audit JSONL |
| `enabled` | `True` | Interruttore principale |
### Ambiente
| Variabile | Scopo |
|----------|---------|
| `AGENTIC_DM_ALLOWLIST` | Id utente separati da virgola |
| `AGENTIC_DM_OWNER_ID` | Id owner |
| `AGENTIC_DM_PIN` | PIN in chiaro |
| `AGENTIC_DM_PIN_REQUIRED` | `1` = richiede PIN anche se non impostato |
| `AGENTIC_DM_KILLED` | `1` = kill switch attivo |
| `AGENTIC_DM_DATA_DIR` | Directory per kill file, open, audit log |
| `AGENTIC_DM_SECRETS_DIR` | Directory per `dm_pin.txt` / `dm_allowlist.txt` |
Directory di stato predefinita: `./data/agentic_dm/`.
---
## Comandi owner e sessione
| Comando | Chi | Effetto |
|---------|-----|--------|
| `/kill` `/pause` | owner | Mette in pausa l'agente per tutti |
| `/unkill` `/resume` | owner | Rimuove la pausa |
| `/status` | owner | Snapshot di kill / PIN / allowlist |
| `/auth <pin>` | in allowlist | apre la sessione per il TTL |
| `/lock` | in allowlist | Chiude la sessione aperta |
Questi non chiamano mai il tuo modello.
---
## Limiti (onesti)
- Il rilevamento di injection è una **lista euristica basata su regex**, non un giudice o classificatore LLM completo.
- La redazione è un pattern matching **best-effort**; mancherà i nuovi formati di segreti.
- L'ispirazione a Hermes è architetturale (piano di controllo DM). Non è un gateway Hermes completo né uno stack di pairing.
- Hai comunque bisogno di archiviazione sicura dei token, strumenti con privilegi minimi e hardening dell'host al di fuori di questa libreria.
---
## Licenza
MIT. Vedi [LICENSE](https://gitlab.com/wattocyber/agentic-dm-gateway/-/blob/main/LICENSE).