wattocyber/agentic-dm-gatewaySecurity control plane for LLM agents: allowlists, owner kill switch, PIN sessions, rate limits, prompt-injection detection, and output scrubbing to block secret leakage and image-beacon exfiltration.
Security control plane for LLM agents over private chat (typically Discord DMs).
It sits in front of your agent. It decides who may talk, whether the session is unlocked, whether the process is paused, and whether this message is safe enough to forward. Your model and tools stay behind that gate. The library does not call an LLM. It does not implement product features beyond security.
Hermes-inspired. Design follows the same control-plane ideas used in Hermes Agent messaging gateways: DM-first delivery, identity allowlists, pairing-style open, owner kill switch, and a hard split between who may act (control plane) and message text the model sees (data plane). This package is a small, standalone extract of that pattern for any agent callable. Not affiliated with Nous Research.
Maturity: implemented · independently validated · maintained. See STATUS.md.
Reproduce: python scripts/repro.py (expects 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
If you put an agent on Discord (or any chat API) with tools, anyone who can message the bot can try to:
You need a control plane (identity and process controls) separate from the data plane (message text the model sees).
This package is that control plane.
| Control | Behavior |
|---|---|
| Allowlist | Only configured user IDs may proceed. Everyone else is dropped (silent or with a short deny string). |
| Owner vs friend | Owners skip PIN and can pause the whole agent. Friends may need a shared PIN for a time-limited open (Hermes-style pairing idea, simplified). |
| Kill switch | Global pause file or env flag. No agent turns while active. |
| Rate limits | Sliding window per user (per minute and per hour). |
| Input checks | Max length, strip odd control chars, regex heuristics for common injection / secret-fishing phrases. |
| Output scrub | Redact secret-shaped tokens (API keys, JWTs, Bearer headers) and strip markdown/HTML image beacons that can exfil via auto-fetch. |
| Audit log | Append-only JSONL of allow/deny/auth/kill events for later review. |
| Local commands | /auth, /lock, /kill, /unkill, /status handled without calling a model. |
Scope: security gate only. Not a chatbot, trading bot, scanner, or agent framework. Pass an agent(user_id, text) -> str (or async) if you use Discord. The core works with any integer user id and plain 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
Three integration paths. Pick one.
Install with Discord support, point env at your user ids, register the gateway, run the bot.
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 your own 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)
What register_dm_gateway does:
on_message handler on your discord.Client / bot.InboundSecurityPipeline.precheck before your agent.agent(user_id, sanitized_text, is_owner=...).Guild messages never reach the agent. Only DMs from allowlisted users do.
on_message)If you cannot use register_dm_gateway (existing handler chain), call the pipeline yourself:
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])
No Discord import required. Use the same precheck around any agent turn:
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 fields:
run_agent: forward to the model only if truesanitized_text: cleaned inputreply_text: deny / control-command replystage: allowlist | kill | pin | rate | injection | ok | ...Hook checklist: