
LLM एजेंटों के लिए सुरक्षा नियंत्रण विमान: अनुमत सूचियाँ, स्वामी किल स्विच, पिन सत्र, दर सीमाएँ, प्रॉम्प्ट-इंजेक्शन पहचान, और गुप्त जानकारी के रिसाव तथा इमेज-बीकन बहिर्वेशन को रोकने के लिए आउटपुट स्क्रबिंग।
# Agentic DM Gateway

[](https://gitlab.com/WattoCyber/agentic-dm-gateway/-/pipelines) [](LICENSE) [](https://gitlab.com/WattoCyber/agentic-dm-gateway)
निजी चैट (आमतौर पर Discord DMs) पर LLM एजेंट्स के लिए सुरक्षा नियंत्रण तल।
यह **आपके एजेंट के सामने** बैठता है। यह तय करता है कि कौन बात कर सकता है, सत्र अनलॉक है या नहीं, प्रक्रिया रोकी गई है या नहीं, और यह संदेश आगे भेजने के लिए पर्याप्त सुरक्षित है या नहीं। आपका मॉडल और टूल्स उस गेट के पीछे रहते हैं। लाइब्रेरी किसी LLM को कॉल नहीं करती। यह सुरक्षा से आगे कोई उत्पाद सुविधा लागू नहीं करती।
**Hermes-प्रेरित।** डिज़ाइन उन्हीं कंट्रोल-प्लेन विचारों का पालन करता है जो [Hermes Agent](https://github.com/NousResearch/hermes-agent) मैसेजिंग गेटवे में उपयोग होते हैं: DM-प्रथम डिलीवरी, पहचान allowlists, pairing-शैली खुला, owner kill switch, और *कौन कार्य कर सकता है* (कंट्रोल प्लेन) तथा *मॉडल जो संदेश पाठ देखता है* (डेटा प्लेन) के बीच सख्त विभाजन। यह पैकेज उस पैटर्न का एक छोटा, स्वतंत्र निष्कर्षण है जो किसी भी कॉल करने योग्य एजेंट के लिए है। 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) पर रखते हैं, तो जो भी बॉट को संदेश भेज सकता है, वह इनका प्रयास कर सकता है:
- बिना अनुमति के एजेंट का उपयोग करना
- बाढ़ (floods) से API कोटा जलाना
- "पिछले निर्देशों को अनदेखा करें" शैली के प्रॉम्प्ट इंजेक्ट करना
- मॉडल को API कुंजियाँ या अन्य रहस्य प्रतिध्वनित करने के लिए धोखा देना
आपको **डेटा प्लेन** (मॉडल जो संदेश टेक्स्ट देखता है) से अलग एक **कंट्रोल प्लेन** (पहचान और प्रक्रिया नियंत्रण) की आवश्यकता होती है।
यह पैकेज वही कंट्रोल प्लेन है।
---
## यह क्या करता है
| नियंत्रण | व्यवहार |
|---------|----------|
| **अनुमति सूची (Allowlist)** | केवल कॉन्फ़िगर किए गए उपयोगकर्ता ID ही आगे बढ़ सकते हैं। बाकी सभी को हटा दिया जाता है (चुपचाप या एक छोटे अस्वीकृति संदेश के साथ)। |
| **मालिक बनाम मित्र** | मालिक PIN छोड़ देते हैं और पूरे एजेंट को रोक सकते हैं। मित्रों को समय-सीमित खुलेपन के लिए साझा PIN की आवश्यकता हो सकती है (Hermes-शैली की पेयरिंग अवधारणा, सरलीकृत)। |
| **किल स्विच** | वैश्विक पॉज़ फ़ाइल या env फ़्लैग। सक्रिय रहने के दौरान कोई एजेंट टर्न नहीं। |
| **दर सीमाएँ** | प्रति उपयोगकर्ता स्लाइडिंग विंडो (प्रति मिनट और प्रति घंटा)। |
| **इनपुट जाँच** | अधिकतम लंबाई, विषम नियंत्रण वर्णों को हटाना, सामान्य इंजेक्शन / रहस्य-मछली पकड़ने वाले वाक्यांशों के लिए regex ह्यूरिस्टिक्स। |
| **आउटपुट स्क्रब** | रहस्य-आकार के टोकन (API कुंजियाँ, JWTs, Bearer हेडर) को रीडैक्ट करना और markdown/HTML इमेज बीकन हटाना जो ऑटो-फ़ेच के माध्यम से डेटा चुरा सकते हैं। |
| **ऑडिट लॉग** | बाद की समीक्षा के लिए allow/deny/auth/kill घटनाओं का केवल-जोड़ने वाला (append-only) JSONL। |
| **स्थानीय कमांड** | `/auth`, `/lock`, `/kill`, `/unkill`, `/status` मॉडल को कॉल किए बिना संभाले जाते हैं। |
दायरा: केवल सुरक्षा गेट। चैटबॉट, ट्रेडिंग बॉट, स्कैनर, या एजेंट फ्रेमवर्क नहीं। यदि आप Discord का उपयोग करते हैं तो एक `agent(user_id, text) -> str` (या async) पास करें। कोर किसी भी पूर्णांक उपयोगकर्ता 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 समर्थन के साथ इंस्टॉल करें, env को अपने user ids पर पॉइंट करें, गेटवे रजिस्टर करें, बॉट चलाएँ।
```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. आपके `discord.Client` / bot पर एक `on_message` handler इंस्टॉल करता है।
2. bots और **guild** संदेशों को अनदेखा करता है (केवल DMs)।
3. आपके agent से पहले `InboundSecurityPipeline.precheck` चलाता है।
4. आवश्यकता पड़ने पर deny / control उत्तर भेजता है।
5. आपके `agent(user_id, sanitized_text, is_owner=...)` को कॉल करता है।
6. agent के उत्तर को साफ़ करता है (secrets + image beacons) और Discord की 2000-char सीमा में विभाजित करता है।
Guild संदेश कभी agent तक नहीं पहुँचते। केवल allowlisted उपयोगकर्ताओं के DMs ही पहुँचते हैं।
### 2) मैन्युअल Discord hook (आपके पास पहले से `on_message` है)
यदि आप `register_dm_gateway` का उपयोग नहीं कर सकते (मौजूदा handler chain), तो pipeline को स्वयं कॉल करें:
```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`: अस्वीकार / नियंत्रण-कमांड उत्तर
- `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
```
**कंट्रोल प्लेन:** उपयोगकर्ता कौन है (allowlist / owner)।
**डेटा प्लेन:** संदेश का मुख्य भाग (जब तक जाँच पास न हो, हमेशा अविश्वसनीय)।
---
## पैकेज लेआउट
```
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 commands + gateway |
| `DiscordDMGateway` | केवल DM के लिए adapter; आप agent function inject करते हैं |
शून्य आवश्यक runtime dependencies। 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` | किल फ़ाइल, ओपन, ऑडिट लॉग के लिए डायरेक्टरी |
| `AGENTIC_DM_SECRETS_DIR` | `dm_pin.txt` / `dm_allowlist.txt` के लिए डायरेक्टरी |
डिफ़ॉल्ट स्टेट डायरेक्टरी: `./data/agentic_dm/`।
---
## मालिक और सत्र कमांड
| कमांड | कौन | प्रभाव |
|---------|-----|--------|
| `/kill` `/pause` | मालिक | सभी के लिए एजेंट को रोकें |
| `/unkill` `/resume` | मालिक | रोक हटाएँ |
| `/status` | मालिक | किल / PIN / allowlist स्नैपशॉट |
| `/auth <pin>` | allowlisted | TTL के लिए सत्र खोलें |
| `/lock` | allowlisted | ओपन साफ़ करें |
ये कभी भी आपके मॉडल को कॉल नहीं करते।
---
## सीमाएँ (ईमानदारी से)
- इंजेक्शन डिटेक्शन एक **रेगेक्स ह्यूरिस्टिक सूची** है, पूर्ण LLM जज या क्लासिफायर नहीं।
- रिडैक्शन **बेस्ट-एफर्ट** पैटर्न मिलान है; यह नए सीक्रेट फ़ॉर्मेट को चूक जाएगा।
- Hermes प्रेरणा आर्किटेक्चरल है (DM कंट्रोल प्लेन)। यह पूर्ण Hermes गेटवे या पेयरिंग स्टैक नहीं है।
- आपको अभी भी इस लाइब्रेरी के बाहर सुरक्षित टोकन स्टोरेज, न्यूनतम-विशेषाधिकार टूल्स, और होस्ट हार्डनिंग की आवश्यकता है।
---
## लाइसेंस
MIT। देखें [LICENSE](https://gitlab.com/wattocyber/agentic-dm-gateway/-/blob/main/LICENSE)।