wattocyber/agentic-dm-gatewaySicherheits-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.
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 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.
Reproduzieren: python scripts/repro.py (erwartet REPRO_OK).
Offline-Tests:
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
Wenn Sie einen Agenten mit Tools auf Discord (oder einer beliebigen Chat-API) betreiben, kann jeder, der dem Bot eine Nachricht senden kann, versuchen:
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.
| 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.
$ 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
Drei Integrationswege. Wählen Sie einen.
Mit Discord-Unterstützung installieren, die Umgebungsvariablen auf Ihre Benutzer-IDs zeigen lassen, das Gateway registrieren, den Bot ausführen.
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:
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:
on_message-Handler auf deinem discord.Client / Bot.InboundSecurityPipeline.precheck vor deinem Agenten aus.agent(user_id, sanitized_text, is_owner=...) auf.Guild-Nachrichten erreichen den Agenten nie. Nur DMs von Nutzern auf der Allowlist tun dies.
on_message)Wenn du register_dm_gateway nicht verwenden kannst (bestehende Handler-Kette), rufe die Pipeline selbst auf:
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])
Kein Discord-Import erforderlich. Verwenden Sie denselben Precheck um jeden Agent-Turn:
from agentic_dm_gateway import InboundSecurityPipeline
from agentic_dm_gateway.security import sanitize_agent_output