
مستوى تحكم أمني لوكلاء LLM: القوائم المسموحة، مفتاح الإيقاف الفوري للمالك، جلسات PIN، حدود المعدل، كشف حقن الأوامر، وتنقية المخرجات لمنع تسرب الأسرار والتهريب عبر منارات الصور.
# بوابة الرسائل المباشرة الوكيلية

[](https://gitlab.com/WattoCyber/agentic-dm-gateway/-/pipelines) [](LICENSE) [](https://gitlab.com/WattoCyber/agentic-dm-gateway)
مستوى تحكم أمني لوكلاء نماذج اللغة الكبيرة عبر الدردشة الخاصة (عادةً رسائل Discord المباشرة).
تقع **أمام وكيلك**. وهي تقرر من يُسمح له بالتحدث، وما إذا كانت الجلسة غير مقفلة، وما إذا كانت العملية متوقفة مؤقتًا، وما إذا كانت هذه الرسالة آمنة بما يكفي لإعادة توجيهها. يبقى نموذجك وأدواتك خلف تلك البوابة. لا تستدعي المكتبة أي نموذج لغوي كبير. ولا تنفذ أي ميزات منتج تتجاوز الأمان.
**مستوحاة من 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
---
## المشكلة
إذا وضعت وكيلًا (agent) على Discord (أو أي واجهة برمجة تطبيقات دردشة) مزوّدًا بأدوات، فإن أي شخص يستطيع مراسلة البوت يمكنه محاولة:
- استخدام الوكيل دون إذن
- استهلاك حصة واجهة البرمجة عبر Floods
- حقن مطالبات من نوع "تجاهل التعليمات السابقة"
- خداع النموذج لإعادة إظهار مفاتيح API أو أسرار أخرى
تحتاج إلى **مستوى تحكم** (control plane) (ضوابط الهوية والعمليات) منفصل عن **مستوى البيانات** (data plane) (نص الرسالة الذي يراه النموذج).
هذه الحزمة هي مستوى التحكم ذلك.
---
## ما الذي تفعله
| الضابط | السلوك |
|---------|----------|
| **قائمة السماح** | فقط معرّفات المستخدمين المُهيّأة يُسمح لها بالمتابعة. يُسقَط الجميع الآخرون (بصمت أو برسالة رفض قصيرة). |
| **المالك مقابل الصديق** | يتخطى المالكون رمز PIN ويمكنهم إيقاف الوكيل بالكامل مؤقتًا. قد يحتاج الأصدقاء إلى رمز PIN مشترك لفتح محدود المدة (فكرة الاقتران على نمط Hermes، مبسّطة). |
| **مفتاح الإيقاف** | ملف إيقاف مؤقت عام أو علامة بيئة (env flag). لا دورات للوكيل أثناء تفعيله. |
| **حدود المعدل** | نافذة منزلقة لكل مستخدم (لكل دقيقة ولكل ساعة). |
| **فحوصات الإدخال** | الحد الأقصى للطول، إزالة أحرف التحكم الغريبة، استدلالات regex للعبارات الشائعة المتعلقة بالحقن / استدراج الأسرار. |
| **تنقية الإخراج** | حجب الرموز ذات الشكل السري (مفاتيح API، رموز JWT، ترويسات Bearer) وإزالة منارات الصور بصيغة markdown/HTML التي قد تُسرّب عبر الجلب التلقائي. |
| **سجل التدقيق** | ملف JSONL للإضافة فقط يسجّل أحداث السماح/الرفض/المصادقة/الإيقاف للمراجعة لاحقًا. |
| **الأوامر المحلية** | تُعالَج `/auth` و`/lock` و`/kill` و`/unkill` و`/status` دون استدعاء نموذج. |
النطاق: بوابة أمان فقط. ليست روبوت دردشة، ولا روبوت تداول، ولا ماسحًا ضوئيًا، ولا إطار عمل للوكلاء. مرّر `agent(user_id, text) -> str` (أو نسخة async) إذا كنت تستخدم Discord. يعمل النواة مع أي معرّف مستخدم صحيح ونص عادي.
---
## عرض توضيحي (نسخ ولصق)
```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، ووجّه متغيرات البيئة إلى معرّفات المستخدمين الخاصة بك، وسجّل البوابة، ثم شغّل البوت.
```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. يتجاهل رسائل البوتات ورسائل **guild** (الرسائل المباشرة فقط).
3. يشغّل `InboundSecurityPipeline.precheck` قبل الوكيل الخاص بك.
4. يرسل ردود الرفض / التحكم عند الحاجة.
5. يستدعي `agent(user_id, sanitized_text, is_owner=...)` الخاص بك.
6. ينقّي رد الوكيل (الأسرار + منارات الصور) ويقسّم حد 2000 حرف في Discord.
لا تصل رسائل Guild إلى الوكيل أبدًا. فقط الرسائل المباشرة من المستخدمين المدرجين في قائمة السماح تصل إليه.
### 2) ربط Discord اليدوي (لديك بالفعل `on_message`)
إذا لم تتمكن من استخدام `register_dm_gateway` (سلسلة معالجات موجودة)، فاستدعِ 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` | ...
قائمة التحقق الخاصة بالـ Hook:
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.
---
## Pipeline (رسالة واردة واحدة)
```
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
```
**Control plane:** هوية المستخدم (allowlist / owner).
**Data plane:** جسم الرسالة (غير موثوق دائمًا حتى تنجح الفحوصات).
---
## Package layout
```
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` | قائمة السماح + أوامر الشرطة المائلة + البوابة في استدعاء واحد |
| `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` | دليل ملف الإيقاف والفتح وسجل التدقيق |
| `AGENTIC_DM_SECRETS_DIR` | دليل `dm_pin.txt` / `dm_allowlist.txt` |
دليل الحالة الافتراضي: `./data/agentic_dm/`.
---
## أوامر المالك والجلسة
| الأمر | من | التأثير |
|---------|-----|--------|
| `/kill` `/pause` | المالك | إيقاف الوكيل مؤقتًا للجميع |
| `/unkill` `/resume` | المالك | إلغاء الإيقاف المؤقت |
| `/status` | المالك | لقطة عن الإيقاف / PIN / قائمة السماح |
| `/auth <pin>` | المدرجون في قائمة السماح | فتح جلسة لمدة TTL |
| `/lock` | المدرجون في قائمة السماح | إغلاق الجلسة المفتوحة |
هذه الأوامر لا تستدعي نموذجك أبدًا.
---
## القيود (بصراحة)
- كشف الحقن هو **قائمة استكشافية بتعبيرات نمطية**، وليس حكمًا أو مصنّفًا كاملًا بنموذج لغوي كبير.
- الحجب **بأفضل جهد ممكن** عبر مطابقة الأنماط؛ وسيفوّت صيغ الأسرار الجديدة.
- الإلهام من Hermes معماري (مستوى تحكم DM). هذا ليس بوابة Hermes كاملة أو حزمة اقتران.
- لا تزال بحاجة إلى تخزين آمن للرموز، وأدوات بأقل صلاحية، وتقوية المضيف خارج هذه المكتبة.
---
## الترخيص
MIT. راجع [LICENSE](https://gitlab.com/wattocyber/agentic-dm-gateway/-/blob/main/LICENSE).