
Plano de controlo de segurança para agentes LLM: listas de permissões, kill switch do proprietário, sessões com PIN, limites de taxa, deteção de injeção de prompts e limpeza de saída para bloquear a fuga de segredos e a exfiltração por beacons de imagem.
# Agentic DM Gateway

[](https://gitlab.com/WattoCyber/agentic-dm-gateway/-/pipelines) [](LICENSE) [](https://gitlab.com/WattoCyber/agentic-dm-gateway)
Plano de controle de segurança para agentes LLM em chat privado (tipicamente DMs do Discord).
Ele fica **à frente do seu agente**. Ele decide quem pode falar, se a sessão está desbloqueada, se o processo está pausado e se esta mensagem é segura o suficiente para ser encaminhada. Seu modelo e suas ferramentas permanecem atrás desse portão. A biblioteca não chama um LLM. Ela não implementa funcionalidades de produto além de segurança.
**Inspirado no Hermes.** O design segue as mesmas ideias de plano de controle usadas nos gateways de mensagens do [Hermes Agent](https://github.com/NousResearch/hermes-agent): entrega DM-first, allowlists de identidade, abertura no estilo pairing, kill switch do proprietário e uma separação rígida entre *quem pode agir* (plano de controle) e *o texto da mensagem que o modelo vê* (plano de dados). Este pacote é um extrato pequeno e autônomo desse padrão para qualquer agente chamável. Não afiliado à Nous Research.
**Maturidade:** implementado · validado de forma independente · mantido. Veja [STATUS.md](https://gitlab.com/wattocyber/agentic-dm-gateway/-/blob/main/STATUS.md).
**Reproduzir:** `python scripts/repro.py` (espera `REPRO_OK`).
**Testes offline:**
```bash
pip install -e ".[dev]" # or: pip install -e . && pip install pytest
python -m pytest -q --tb=line
# or: python scripts/repro.py
```
**Ao vivo:** https://gitlab.com/WattoCyber/agentic-dm-gateway
---
## O problema
Se você colocar um agente no Discord (ou em qualquer API de chat) com ferramentas, qualquer pessoa que consiga enviar mensagem ao bot pode tentar:
- usar o agente sem permissão
- esgotar a cota de API com floods
- injetar prompts do tipo "ignore as instruções anteriores"
- enganar o modelo para que ele revele chaves de API ou outros segredos
Você precisa de um **plano de controle** (identidade e controles de processo) separado do **plano de dados** (o texto da mensagem que o modelo vê).
Este pacote é esse plano de controle.
---
## O que ele faz
| Controle | Comportamento |
|---------|----------|
| **Allowlist** | Apenas os IDs de usuário configurados podem prosseguir. Todos os outros são descartados (silenciosamente ou com uma breve mensagem de negação). |
| **Owner vs friend** | Owners ignoram o PIN e podem pausar o agente inteiro. Friends podem precisar de um PIN compartilhado para uma abertura com tempo limitado (ideia de pareamento estilo Hermes, simplificada). |
| **Kill switch** | Arquivo de pausa global ou flag de ambiente. Nenhum turno do agente enquanto estiver ativo. |
| **Limites de taxa** | Janela deslizante por usuário (por minuto e por hora). |
| **Verificações de entrada** | Comprimento máximo, remoção de caracteres de controle estranhos, heurísticas de regex para frases comuns de injeção / pesca de segredos. |
| **Sanitização de saída** | Redige tokens com formato de segredo (chaves de API, JWTs, cabeçalhos Bearer) e remove beacons de imagem markdown/HTML que podem exfiltrar via busca automática. |
| **Log de auditoria** | JSONL somente-anexação de eventos de allow/deny/auth/kill para revisão posterior. |
| **Comandos locais** | `/auth`, `/lock`, `/kill`, `/unkill`, `/status` tratados sem chamar um modelo. |
Escopo: apenas barreira de segurança. Não é um chatbot, bot de trading, scanner ou framework de agente. Passe um `agent(user_id, text) -> str` (ou async) se você usar Discord. O núcleo funciona com qualquer ID de usuário inteiro e texto simples.
---
## Demonstração (copiar-colar)
```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
```
## Como integrá-lo
Três caminhos de integração. Escolha um.
### 1) Discord pronto para uso (mais fácil)
Instale com suporte a Discord, aponte as variáveis de ambiente para os seus IDs de usuário, registre o gateway e execute o 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
```
No seu próprio 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)
```
O que `register_dm_gateway` faz:
1. Instala um handler `on_message` no seu `discord.Client` / bot.
2. Ignora bots e mensagens de **guild** (apenas DMs).
3. Executa `InboundSecurityPipeline.precheck` antes do seu agente.
4. Envia respostas de negação / controle quando necessário.
5. Chama seu `agent(user_id, sanitized_text, is_owner=...)`.
6. Sanitiza a resposta do agente (segredos + beacons de imagem) e divide respeitando o limite de 2000 caracteres do Discord.
Mensagens de guild nunca chegam ao agente. Apenas DMs de usuários na allowlist chegam.
### 2) Hook manual do Discord (você já tem `on_message`)
Se você não pode usar `register_dm_gateway` (cadeia de handlers existente), chame o pipeline você mesmo:
```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) Independente de protocolo (Hermes, CLI, Telegram, qualquer coisa)
Nenhuma importação do Discord é necessária. Use a mesma verificação prévia em qualquer turno do 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`: encaminhar para o modelo apenas se verdadeiro
- `sanitized_text`: entrada higienizada
- `reply_text`: resposta de negação / comando de controle
- `stage`: `allowlist` | `kill` | `pin` | `rate` | `injection` | `ok` | ...
Lista de verificação dos hooks:
1. Construa `InboundSecurityPipeline` uma vez na inicialização do processo (config + env).
2. Em cada mensagem de entrada: `pre = pipe.precheck(user_id, text)`.
3. Se `pre.run_agent`: chame seu agente apenas com `pre.sanitized_text`.
4. Sempre passe a saída do modelo por `sanitize_agent_output` antes do envio.
5. Trate as respostas de controle (`/auth`, `/kill`, …) como concluídas quando `run_agent` for falso.
---
## Pipeline (uma mensagem de entrada)
```
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 controle:** quem é o usuário (allowlist / proprietário).
**Plano de dados:** corpo da mensagem (sempre não confiável até que as verificações passem).
---
## Estrutura do pacote
```
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 | Responsabilidade |
|--------|----------------|
| `SecurityGateway` | Único `check_message(user_id, text) -> SecurityVerdict` |
| `InboundSecurityPipeline` | Allowlist + comandos slash + gateway em uma única chamada |
| `DiscordDMGateway` | Adaptador apenas para DM; você injeta a função do agente |
Zero dependências de runtime obrigatórias. O Discord é opcional: `pip install agentic-dm-gateway[discord]`.
---
## Instalação
```bash
git clone https://gitlab.com/WattoCyber/agentic-dm-gateway.git
cd agentic-dm-gateway
pip install -e ".[dev]"
python scripts/repro.py
```
## Configuração
### Dicionário de configuração
| Chave | Padrão | Significado |
|-----|---------|---------|
| `allowed_user_ids` | `[]` | IDs de usuário autorizados a conversar |
| `owner_ids` | `[]` | Ignorar PIN; pode usar `/kill` |
| `pin_enabled` | `True` | Barreira de PIN para não-proprietários |
| `pin_ttl_hours` | `72` | duração da sessão aberta |
| `rate_limit_per_minute` | `8` | Janela deslizante |
| `rate_limit_per_hour` | `60` | Janela deslizante |
| `max_input_chars` | `2000` | Comprimento máximo da entrada |
| `block_injection` | `True` | Lista de bloqueio heurística |
| `deny_message` | `False` | Silencioso, `True`, ou string personalizada |
| `audit_log` | `True` | Gravar auditoria em JSONL |
| `enabled` | `True` | Interruptor principal |
### Ambiente
| Variável | Finalidade |
|----------|---------|
| `AGENTIC_DM_ALLOWLIST` | IDs de usuário separados por vírgula |
| `AGENTIC_DM_OWNER_ID` | ID(s) do proprietário |
| `AGENTIC_DM_PIN` | PIN em texto simples |
| `AGENTIC_DM_PIN_REQUIRED` | `1` = exigir PIN mesmo se não definido |
| `AGENTIC_DM_KILLED` | `1` = interruptor de desligamento ativado |
| `AGENTIC_DM_DATA_DIR` | Diretório para arquivo de kill, open, log de auditoria |
| `AGENTIC_DM_SECRETS_DIR` | Diretório para `dm_pin.txt` / `dm_allowlist.txt` |
Diretório de estado padrão: `./data/agentic_dm/`.
---
## Comandos de proprietário e de sessão
| Comando | Quem | Efeito |
|---------|-----|--------|
| `/kill` `/pause` | proprietário | Pausar o agente para todos |
| `/unkill` `/resume` | proprietário | Limpar a pausa |
| `/status` | proprietário | Instantâneo de kill / PIN / allowlist |
| `/auth <pin>` | na allowlist | abrir sessão pelo TTL |
| `/lock` | na allowlist | Limpar sessão aberta |
Estes nunca chamam o seu modelo.
---
## Limitações (honestas)
- A detecção de injeção é uma **lista heurística de regex**, não um juiz ou classificador LLM completo.
- A redação é correspondência de padrões **de melhor esforço**; ela deixará passar formatos de segredos inéditos.
- A inspiração no Hermes é arquitetural (plano de controle de DM). Isto não é um gateway Hermes completo nem uma pilha de emparelhamento.
- Você ainda precisa de armazenamento seguro de tokens, ferramentas com privilégio mínimo e endurecimento do host fora desta biblioteca.
---
## Licença
MIT. Consulte [LICENSE](https://gitlab.com/wattocyber/agentic-dm-gateway/-/blob/main/LICENSE).