
Sicherheits-Kontrollebene für LLM-Agenten: Allowlists, Owner-Kill-Switch, PIN-Sitzungen, Rate-Limits, Prompt-Injection-Erkennung und Output-Scrubbing, um Geheimnis-Lecks und Exfiltration über Bild-Beacons zu blockieren.
# Agentic DM Gateway

[](https://gitlab.com/WattoCyber/agentic-dm-gateway/-/pipelines) [](LICENSE) [](https://gitlab.com/WattoCyber/agentic-dm-gateway)
Sicherheits-Kontrollschicht für LLM-Agenten über private Chats (typischerweise Discord-DMs).
Sie sitzt **vor Ihrem Agenten**. Sie entscheidet, wer sprechen darf, ob die Sitzung entsperrt ist, ob der Prozess pausiert ist und ob diese Nachricht sicher genug ist, um weitergeleitet zu werden. Ihr Modell und Ihre Tools bleiben hinter diesem Gate. Die Bibliothek ruft kein LLM auf. Sie implementiert keine Produktfunktionen über die Sicherheit hinaus.
**Von Hermes inspiriert.** Das Design folgt denselben Kontrollschicht-Ideen, die in den Messaging-Gateways von [Hermes Agent](https://github.com/NousResearch/hermes-agent) verwendet werden: DM-first-Zustellung, Identitäts-Allowlists, Pairing-basiertes Öffnen, Owner-Kill-Switch und eine strikte Trennung zwischen *wer handeln darf* (Kontrollschicht) und *Nachrichtentext, den das Modell sieht* (Datenschicht). Dieses Paket ist ein kleiner, eigenständiger Auszug dieses Musters für jeden aufrufbaren Agenten. Nicht mit Nous Research verbunden.
**Reifegrad:** implementiert · unabhängig validiert · gepflegt. Siehe [STATUS.md](https://gitlab.com/wattocyber/agentic-dm-gateway/-/blob/main/STATUS.md).
**Reproduzieren:** `python scripts/repro.py` (erwartet `REPRO_OK`).
**Offline-Tests:**
```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
---
## Das Problem
Wenn Sie einen Agenten mit Tools auf Discord (oder einer beliebigen Chat-API) betreiben, kann jeder, der dem Bot eine Nachricht senden kann, versuchen:
- den Agenten ohne Berechtigung zu nutzen
- das API-Kontingent durch Flutwellen von Nachrichten zu verbrauchen
- Prompts im Stil von „ignoriere vorherige Anweisungen" einzuschleusen
- das Modell dazu zu bringen, API-Schlüssel oder andere Geheimnisse preiszugeben
Sie benötigen eine **Control Plane** (Identitäts- und Prozesskontrollen), getrennt von der **Data Plane** (dem Nachrichtentext, den das Modell sieht).
Dieses Paket ist diese Control Plane.
---
## Was es tut
| Kontrolle | Verhalten |
|---------|----------|
| **Allowlist** | Nur konfigurierte Benutzer-IDs dürfen fortfahren. Alle anderen werden verworfen (stillschweigend oder mit einem kurzen Ablehnungsstring). |
| **Owner vs. Friend** | Owner überspringen die PIN und können den gesamten Agenten pausieren. Friends benötigen möglicherweise eine gemeinsame PIN für eine zeitlich begrenzte Freigabe (vereinfachte Hermes-Pairing-Idee). |
| **Kill Switch** | Globale Pause-Datei oder Env-Flag. Keine Agenten-Turns, solange aktiv. |
| **Rate Limits** | Gleitendes Fenster pro Benutzer (pro Minute und pro Stunde). |
| **Eingabeprüfungen** | Maximale Länge, Entfernen ungewöhnlicher Steuerzeichen, Regex-Heuristiken für gängige Injection-/Secret-Fishing-Phrasen. |
| **Output-Bereinigung** | Redigieren geheimnisartiger Tokens (API-Schlüssel, JWTs, Bearer-Header) und Entfernen von Markdown-/HTML-Bild-Beacons, die per Auto-Fetch exfiltrieren können. |
| **Audit-Log** | Append-only JSONL von Allow/Deny/Auth/Kill-Ereignissen zur späteren Überprüfung. |
| **Lokale Befehle** | `/auth`, `/lock`, `/kill`, `/unkill`, `/status` werden ohne Modellaufruf behandelt. |
Geltungsbereich: nur Sicherheits-Gate. Kein Chatbot, Trading-Bot, Scanner oder Agenten-Framework. Übergeben Sie ein `agent(user_id, text) -> str` (oder async), wenn Sie Discord verwenden. Der Kern funktioniert mit jeder ganzzahligen Benutzer-ID und reinem Text.
---
## Demo (Copy-Paste)
```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
```
## So binden Sie es ein
Drei Integrationswege. Wählen Sie einen.
### 1) Drop-in Discord (am einfachsten)
Mit Discord-Unterstützung installieren, die Umgebungsvariablen auf Ihre Benutzer-IDs zeigen lassen, das Gateway registrieren, den Bot ausführen.
```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
```
In deinem eigenen 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)
```
Was `register_dm_gateway` macht:
1. Installiert einen `on_message`-Handler auf deinem `discord.Client` / Bot.
2. Ignoriert Bots und **Guild**-Nachrichten (nur DMs).
3. Führt `InboundSecurityPipeline.precheck` vor deinem Agenten aus.
4. Sendet Ablehnungs- / Steuerungsantworten, wenn nötig.
5. Ruft deinen `agent(user_id, sanitized_text, is_owner=...)` auf.
6. Bereinigt die Antwort des Agenten (Secrets + Image-Beacons) und teilt sie gemäß Discords 2000-Zeichen-Limit auf.
Guild-Nachrichten erreichen den Agenten nie. Nur DMs von Nutzern auf der Allowlist tun dies.
### 2) Manueller Discord-Hook (du hast bereits `on_message`)
Wenn du `register_dm_gateway` nicht verwenden kannst (bestehende Handler-Kette), rufe die Pipeline selbst auf:
```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) Protokollunabhängig (Hermes, CLI, Telegram, beliebig)
Kein Discord-Import erforderlich. Verwenden Sie denselben Precheck um jeden Agent-Turn:
```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
```
`PrecheckResult`-Felder:
- `run_agent`: nur dann an das Modell weiterleiten, wenn true
- `sanitized_text`: bereinigte Eingabe
- `reply_text`: Ablehnungs- / Steuerbefehl-Antwort
- `stage`: `allowlist` | `kill` | `pin` | `rate` | `injection` | `ok` | ...
Checkliste für den Hook:
1. `InboundSecurityPipeline` einmal beim Prozessstart aufbauen (Konfiguration + Umgebung).
2. Bei jeder eingehenden Nachricht: `pre = pipe.precheck(user_id, text)`.
3. Wenn `pre.run_agent`: den Agenten ausschließlich mit `pre.sanitized_text` aufrufen.
4. Die Modellausgabe immer vor dem Senden durch `sanitize_agent_output` leiten.
5. Steuerantworten (`/auth`, `/kill`, …) als erledigt behandeln, wenn `run_agent` false ist.
---
## Pipeline (eine eingehende Nachricht)
```
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
```
**Control Plane:** wer der Benutzer ist (Allowlist / Eigentümer).
**Data Plane:** Nachrichtentext (immer nicht vertrauenswürdig, bis die Prüfungen bestanden sind).
---
## Paketaufbau
```
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
```
| Modul | Verantwortlichkeit |
|--------|----------------|
| `SecurityGateway` | Einzelnes `check_message(user_id, text) -> SecurityVerdict` |
| `InboundSecurityPipeline` | Allowlist + Slash-Befehle + Gateway in einem Aufruf |
| `DiscordDMGateway` | Nur-DM-Adapter; Sie injizieren die Agent-Funktion |
Keine erforderlichen Laufzeitabhängigkeiten. Discord ist optional: `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
```
---
## Konfiguration
### Config-Dict
| Schlüssel | Standard | Bedeutung |
|-----|---------|---------|
| `allowed_user_ids` | `[]` | Benutzer-IDs, die chatten dürfen |
| `owner_ids` | `[]` | PIN überspringen; dürfen `/kill` ausführen |
| `pin_enabled` | `True` | PIN-Sperre für Nicht-Owner |
| `pin_ttl_hours` | `72` | Öffnungsdauer |
| `rate_limit_per_minute` | `8` | Gleitendes Fenster |
| `rate_limit_per_hour` | `60` | Gleitendes Fenster |
| `max_input_chars` | `2000` | Maximale Eingabelänge |
| `block_injection` | `True` | Heuristische Sperrliste |
| `deny_message` | `False` | Stumm, `True` oder benutzerdefinierter String |
| `audit_log` | `True` | Audit-JSONL schreiben |
| `enabled` | `True` | Hauptschalter |
### Umgebung
| Variable | Zweck |
|----------|---------|
| `AGENTIC_DM_ALLOWLIST` | Kommagetrennte Benutzer-IDs |
| `AGENTIC_DM_OWNER_ID` | Owner-ID(s) |
| `AGENTIC_DM_PIN` | PIN im Klartext |
| `AGENTIC_DM_PIN_REQUIRED` | `1` = PIN erforderlich, auch wenn nicht gesetzt |
| `AGENTIC_DM_KILLED` | `1` = Kill-Switch aktiv |
| `AGENTIC_DM_DATA_DIR` | Verzeichnis für Kill-Datei, Open, Audit-Log |
| `AGENTIC_DM_SECRETS_DIR` | Verzeichnis für `dm_pin.txt` / `dm_allowlist.txt` |
Standard-Zustandsverzeichnis: `./data/agentic_dm/`.
---
## Owner- und Sitzungsbefehle
| Befehl | Wer | Wirkung |
|---------|-----|--------|
| `/kill` `/pause` | Owner | Agent für alle pausieren |
| `/unkill` `/resume` | Owner | Pause aufheben |
| `/status` | Owner | Momentaufnahme von Kill / PIN / Allowlist |
| `/auth <pin>` | Allowlistete | Sitzung für TTL öffnen |
| `/lock` | Allowlistete | Öffnung aufheben |
Diese rufen niemals dein Modell auf.
---
## Grenzen (ehrlich)
- Die Injection-Erkennung ist eine **heuristische Regex-Liste**, kein vollständiger LLM-Richter oder Klassifikator.
- Die Redaktion ist **Best-Effort**-Musterabgleich; neuartige Secret-Formate werden übersehen.
- Die Hermes-Inspiration ist architektonisch (DM-Control-Plane). Dies ist kein vollständiges Hermes-Gateway oder Pairing-Stack.
- Du benötigst weiterhin sichere Token-Speicherung, Tools mit minimalen Rechten und Host-Härtung außerhalb dieser Bibliothek.
---
## Lizenz
MIT. Siehe [LICENSE](https://gitlab.com/wattocyber/agentic-dm-gateway/-/blob/main/LICENSE).