
Плоскость управления безопасностью для LLM-агентов: списки разрешений, аварийный выключатель владельца, PIN-сессии, ограничения частоты запросов, обнаружение промпт-инъекций и очистка вывода для блокировки утечки секретов и экфильтрации через изображения-маяки.
# Agentic DM Gateway

[](https://gitlab.com/WattoCyber/agentic-dm-gateway/-/pipelines) [](LICENSE) [](https://gitlab.com/WattoCyber/agentic-dm-gateway)
Плоскость управления безопасностью для LLM-агентов в приватных чатах (обычно в личных сообщениях Discord).
Она находится **перед вашим агентом**. Она решает, кому можно общаться, разблокирована ли сессия, приостановлен ли процесс и достаточно ли безопасно это сообщение, чтобы его переслать. Ваша модель и инструменты остаются за этим шлюзом. Библиотека не вызывает LLM. Она не реализует продуктовые функции сверх безопасности.
**Вдохновлено Hermes.** Дизайн следует тем же идеям плоскости управления, что используются в шлюзах обмена сообщениями [Hermes Agent](https://github.com/NousResearch/hermes-agent): доставка в первую очередь через личные сообщения, списки разрешённых идентичностей, открытие в стиле сопряжения, аварийный выключатель владельца и жёсткое разделение между *кто может действовать* (плоскость управления) и *текстом сообщения, который видит модель* (плоскость данных). Этот пакет — небольшое автономное извлечение этого паттерна для любого вызываемого агента. Не связан с Nous Research.
**Зрелость:** реализовано · независимо проверено · поддерживается. См. [STATUS.md](https://gitlab.com/wattocyber/agentic-dm-gateway/-/blob/main/STATUS.md).
**Воспроизведение:** `python scripts/repro.py` (ожидается `REPRO_OK`).
**Офлайн-тесты:**
```bash
pip install -e ".[dev]" # or: pip install -e . && pip install pytest
python -m pytest -q --tb=line
# or: python scripts/repro.py
```
**Демо:** https://gitlab.com/WattoCyber/agentic-dm-gateway
---
## Проблема
Если вы подключите агента к Discord (или к любому чат-API) с инструментами, любой, кто может написать боту, может попытаться:
- использовать агента без разрешения
- сжечь квоту API флудом
- внедрить промпты в стиле «игнорируй предыдущие инструкции»
- обманом заставить модель выдать API-ключи или другие секреты
Вам нужна **плоскость управления** (идентификация и управление процессами), отделённая от **плоскости данных** (текст сообщений, который видит модель).
Этот пакет и есть такая плоскость управления.
---
## Что он делает
| Контроль | Поведение |
|---------|----------|
| **Список разрешённых** | Продолжать могут только настроенные ID пользователей. Все остальные отбрасываются (молча или с короткой строкой отказа). |
| **Владелец vs друг** | Владельцы пропускают PIN и могут приостановить всего агента. Друзьям может потребоваться общий PIN для временного открытия (упрощённая идея спаривания в стиле Hermes). |
| **Аварийный выключатель** | Глобальный файл паузы или флаг окружения. Пока активен, ходы агента не выполняются. |
| **Ограничения частоты** | Скользящее окно на пользователя (в минуту и в час). |
| **Проверки ввода** | Максимальная длина, удаление странных управляющих символов, эвристики на регулярных выражениях для типичных фраз внедрения / выманивания секретов. |
| **Очистка вывода** | Редактирование токенов, похожих на секреты (API-ключи, JWT, заголовки Bearer), и удаление markdown/HTML-маячков-изображений, которые могут осуществлять эксфильтрацию через автозагрузку. |
| **Журнал аудита** | Только дописываемый JSONL событий allow/deny/auth/kill для последующего просмотра. |
| **Локальные команды** | `/auth`, `/lock`, `/kill`, `/unkill`, `/status` обрабатываются без вызова модели. |
Область применения: только защитный шлюз. Не чат-бот, не торговый бот, не сканер и не фреймворк для агентов. Передайте `agent(user_id, text) -> str` (или асинхронную версию), если используете Discord. Ядро работает с любым целочисленным ID пользователя и обычным текстом.
---
## Демо (скопируйте и вставьте)
```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
```
## Как это подключить
Три пути интеграции. Выберите один.
### 1) Готовая интеграция с Discord (самый простой)
Установите с поддержкой Discord, укажите в переменных окружения свои user id, зарегистрируйте шлюз, запустите бота.
```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
```
В вашем собственном боте:
```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)
```
Что делает `register_dm_gateway`:
1. Устанавливает обработчик `on_message` на ваш `discord.Client` / бота.
2. Игнорирует ботов и сообщения в **гильдиях** (только личные сообщения).
3. Запускает `InboundSecurityPipeline.precheck` перед вашим агентом.
4. Отправляет ответы с отказом / управляющие ответы при необходимости.
5. Вызывает ваш `agent(user_id, sanitized_text, is_owner=...)`.
6. Очищает ответ агента (секреты + маячки изображений) и разбивает его на части с учётом лимита Discord в 2000 символов.
Сообщения в гильдиях никогда не доходят до агента. Только личные сообщения от пользователей из белого списка.
### 2) Ручной хук Discord (у вас уже есть `on_message`)
Если вы не можете использовать `register_dm_gateway` (существующая цепочка обработчиков), вызовите конвейер самостоятельно:
```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) Независимость от протокола (Hermes, CLI, Telegram и что угодно ещё)
Импорт Discord не требуется. Используйте ту же предварительную проверку перед любым ходом агента:
```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`:
- `run_agent`: передавать модели только если true
- `sanitized_text`: очищенный ввод
- `reply_text`: ответ на deny / управляющую команду
- `stage`: `allowlist` | `kill` | `pin` | `rate` | `injection` | `ok` | ...
Чек-лист хуков:
1. Создайте `InboundSecurityPipeline` один раз при старте процесса (config + env).
2. На каждое входящее сообщение: `pre = pipe.precheck(user_id, text)`.
3. Если `pre.run_agent`: вызывайте ваш агент только с `pre.sanitized_text`.
4. Всегда пропускайте вывод модели через `sanitize_agent_output` перед отправкой.
5. Считайте управляющие ответы (`/auth`, `/kill`, …) выполненными, когда `run_agent` равен false.
---
## Конвейер (одно входящее сообщение)
```
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
```
**Плоскость управления:** кто является пользователем (список разрешённых / владелец).
**Плоскость данных:** тело сообщения (всегда недоверенное, пока проверки не пройдены).
---
## Структура пакета
```
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
```
| Модуль | Ответственность |
|--------|----------------|
| `SecurityGateway` | Единственный `check_message(user_id, text) -> SecurityVerdict` |
| `InboundSecurityPipeline` | Allowlist + slash-команды + шлюз в одном вызове |
| `DiscordDMGateway` | Адаптер только для личных сообщений; вы внедряете функцию агента |
Нулевые обязательные зависимости времени выполнения. Discord опционален: `pip install agentic-dm-gateway[discord]`.
---
## Установка
```bash
git clone https://gitlab.com/WattoCyber/agentic-dm-gateway.git
cd agentic-dm-gateway
pip install -e ".[dev]"
python scripts/repro.py
```
---
## Конфигурация
### Словарь конфигурации
| Ключ | По умолчанию | Значение |
|-----|---------|---------|
| `allowed_user_ids` | `[]` | Идентификаторы пользователей, которым разрешено общаться |
| `owner_ids` | `[]` | Пропуск PIN; могут выполнять `/kill` |
| `pin_enabled` | `True` | PIN-защита для не-владельцев |
| `pin_ttl_hours` | `72` | длительность открытой сессии |
| `rate_limit_per_minute` | `8` | Скользящее окно |
| `rate_limit_per_hour` | `60` | Скользящее окно |
| `max_input_chars` | `2000` | Максимальная длина ввода |
| `block_injection` | `True` | Эвристический список блокировок |
| `deny_message` | `False` | Тихий режим, `True` или пользовательская строка |
| `audit_log` | `True` | Запись аудита в JSONL |
| `enabled` | `True` | Главный переключатель |
### Переменные окружения
| Переменная | Назначение |
|----------|---------|
| `AGENTIC_DM_ALLOWLIST` | Идентификаторы пользователей через запятую |
| `AGENTIC_DM_OWNER_ID` | Идентификатор(ы) владельца |
| `AGENTIC_DM_PIN` | PIN в открытом виде |
| `AGENTIC_DM_PIN_REQUIRED` | `1` = требовать PIN, даже если он не задан |
| `AGENTIC_DM_KILLED` | `1` = аварийный выключатель включён |
| `AGENTIC_DM_DATA_DIR` | Каталог для kill-файла, open, журнала аудита |
| `AGENTIC_DM_SECRETS_DIR` | Каталог для `dm_pin.txt` / `dm_allowlist.txt` |
Каталог состояния по умолчанию: `./data/agentic_dm/`.
---
## Команды владельца и сессии
| Команда | Кто | Эффект |
|---------|-----|--------|
| `/kill` `/pause` | владелец | Приостановить агента для всех |
| `/unkill` `/resume` | владелец | Снять приостановку |
| `/status` | владелец | Снимок состояния kill / PIN / allowlist |
| `/auth <pin>` | из allowlist | Открыть сессию на TTL |
| `/lock` | из allowlist | Закрыть сессию |
Эти команды никогда не вызывают вашу модель.
---
## Ограничения (честно)
- Обнаружение инъекций — это **эвристический список регулярных выражений**, а не полноценный LLM-судья или классификатор.
- Редактирование — это **сопоставление с шаблонами по мере возможности**; оно пропустит новые форматы секретов.
- Вдохновение от Hermes носит архитектурный характер (плоскость управления DM). Это не полноценный шлюз Hermes и не стек сопряжения.
- Вам всё ещё нужны безопасное хранение токенов, инструменты с минимальными привилегиями и укрепление хоста вне этой библиотеки.
---
## Лицензия
MIT. См. [LICENSE](https://gitlab.com/wattocyber/agentic-dm-gateway/-/blob/main/LICENSE).