DibaGuard

A CPU-light attack-detection and protection layer for network flows, HTTP, JSON-RPC and databases, with calibrated false-alarm rates, explainable verdicts and a policy-driven enforcer. This is the public, licence-clean build by Dibachain. Code is Apache-2.0; the model files are CC BY-SA 4.0 (one training source requires ShareAlike). The same release is published as DibaAi/DibaGuard-Open; an interactive demo is at DibaAi/beam-dibaguard.

DibaGuard sits where a WAF, an IDS and a host firewall would sit: inline in front of an application, as an external decision service behind the load balancer you already run (nginx, Envoy, HAProxy, Traefik, Caddy), or beside a host reading flow and log exports. Every alarm comes with a controlled false-alarm rate (conformal calibration on the site's own traffic, default budget 10^-3 per source-minute), a named attack family, the evidence that produced it, and an action chosen by the operator's policy (report only, or enforce). Inference is numpy-only in Python, with a dependency-free Go fast path proven bit-exact against the Python one on parity fixtures. Operators write their own rules in plain language (Persian or English with the built-in parser, any language through an LLM of their choice via the MCP / REST bridge); the layer shows its reading back before the rule goes live, and every LLM proposal passes an approval gate.

What is in this repository

Not in this repository: the HTTP request model. The one in the private build is trained on data that is not cleared for redistribution, and the licence-clean retrain collapses on applications it never saw (docs/CLEAN_MODELS.md), so it is not shipped. The engine supports this configuration natively: the HTTP edge of this build runs the request signatures A01-A22 (JNDI, CMS exploit paths, SQL / NoSQL / command injection, traversal, XSS, SSTI / XXE / SSRF, sensitive-file probes, declared AI crawlers), the SQL-context analysis of every parameter with DbNet as a second opinion, and the behavioural session tier.

The cascade

Every tier looks at a different scale, every score becomes a p-value against the site's own reference, and a tier alarms when its p-value is under its share of the false-alarm budget (docs/TECHNICAL.md, sections 2-7):

• Tier 0, entity state: 36 exponentially decayed behaviour counters per source over three horizons (10 s, 2 min, 30 min): no-reply, SYN-only, reset, new-port, new-host, repeat and short-flow shares, gaps, and three destination-side counters. Identity-free and scale-free, which is why the models transfer between networks.
• Tier 1, monotone tree prior: oblivious trees over 24 attack-direction counters with increasing constraints (more port walking or more failed connects can never look more benign), calibrated per service x source age (Mondrian conformal).
• Tier 1', site-only anomaly: no labels; Fisher's combination of upper-tail p-values of the shape features against the site's own traffic.
• Tier 2, GRU SeqNet: a causal GRU with one hidden state per source, FiLM-conditioned on a site context vector; runs on warm sources only.
• Tier 4, per-source evidence: fast and slow CUSUM over a source's stream, so weak signals accumulate and a first-contact source is never blocked on one event.
• Tier 5, destination flood and tier 6, campaign tracker: floods of new sources on one destination; distributed low-and-slow campaigns found through a fingerprint shared across thousands of sources.
• HTTP edge: one canonical request text on every path (Python and Go produce byte-identical text), signatures A01-A22, SQL-context analysis of parameters, DbNet second opinion, payload provenance between the database tier and the HTTP edge, session tier.
• Database tier: six engines' query / audit logs; DbNet + signatures + behaviour + provenance; an application server is never blocked at the network level, the web source behind the payload is acted on instead.
• Shield: policy (report | enforce), enforcer (nft / iptables / netsh / dry-run) with TTLs, posture audit, rules in any language, NAT / CGNAT / IPv6 identity, operator feedback that an attacker cannot poison, review queue, report.

Open build versus private build

The network models here are the licence-clean set of docs/CLEAN_MODELS.md, trained only on sources the audit marks GREEN (SIMARGL 2021 / 2022, APPRAISE, ACI-IoT-2023, CSE-CIC-IDS2018 from the publisher's AWS bucket, LUFlow from its author). Head-to-head with the private ("shipped") models on the same rows, conformal threshold at alpha = 10^-3, tier-1 prior, per flow:

Per-source evidence on SIMARGL2021 (an unseen network for the clean run), judged per (source, minute): clean FPR 0.00081 with 8 / 8 attacking source-minutes caught, shipped FPR 0.0029 with 16 / 17. The GRU's leave-out AUROC on SIMARGL2021 is 0.991 (shipped 0.822); the LUFlow detector improves from 0.984 to 0.9998 after a loader clock fix.

Where the open models are weaker: on NF-UNSW-NB15-v3 (AUROC 0.958 -> 0.066) and NF-ToN-IoT-v3 (0.955 -> 0.879), which are the private model's own training networks (UNSW Canberra, academic-only terms) and have no openly licensed twin. Expect weaker tier-1 scores on IoT / UNSW-style traffic; the site-only anomaly tier and the evidence tiers do not depend on training data. The open build has no HTTP request model (above).

Results

Reproducible labs of the main repository (scripts/benchmark_all.py, three seeds, reports/benchmark.md). These numbers were measured on the private build with its full model set, including the HTTP model that is not in this repository; the two SQL-injection lines and the libinjection comparison are signature + SQL-context + DbNet results that involve no HTTP model. The open build has not yet been re-run through the labs (see Verified at build time for what was checked on this exact folder).

Real data (same report): SQL injection in the 2025 ModSecurity blocked-request archive with a visible payload 1.000 [0.9977, 1.0] of 1,671 (libinjection on the same requests: 0.9856); all CRS-labelled SQLi rows 0.531 of 3,225; SR-BH 2020 WordPress SQLi 0.608 of 9,886; false alarms on 80,000 benign requests of a production shop log 0.00013 [0.00007, 0.00023]; DbNet + signatures on unseen query templates TPR 0.983 at FPR 0.0; DbNet alone on unseen injection techniques TPR 0.743.

Independent validation

A team that did not build DibaGuard treated every claim as unverified and measured it (docs/VALIDATION_REPORT.md). They reported 22 findings (bypasses of the canonicaliser, silent caps, identity tricks, reference poisoning, state attacks, harm to legitimate users, a global tier that flooded unfamiliar networks with alarms). All 22 were fixed and each reproduction is now a permanent regression test (section 8 of the report). After the fixes: canonicalisation fuzz of 3,000 cases, Python edge and Go path each block 99.3 % with 0 % diverging verdicts (72.5 % / 76.9 % and 32.8 % divergence before); 80,234 benign requests of a real shop log, 0 blocked on every path; harm lab (26 simulated hours, 3 seeds), users blocked per 1,000 per day 146 -> 0.0, partner API clients and the search crawler no longer challenged; OWASP CRS regression tests (4,138 attack / 1,054 negative), hard tiers 14.7 % of attack tests and 4.3 % of negatives (a lower bound: many CRS tests are fragments a context engine is not meant to flag).

Quick start

Python (numpy only)

pip install numpy
export PYTHONPATH=$PWD/runtime/python        # or: pip install -e runtime/python after adding a pyproject of your own

import numpy as np
from dibaguard.engine import Guard
from dibaguard.shield.layer import Layer

guard = Guard.load("models")                # tier-1 prior, GRU SeqNet; guard.http is None in this build
L = Layer.load("models", policy={"mode": "report"},            # report: verdicts and would-be actions, nothing enforced
               inputs={"http": True, "flows": True}, backend="dryrun")   # DbNet is picked up from models/dbnet.npz

# 1. calibrate on this site's own benign traffic (no attack labels needed)
L.calibrate_flows(benign_flows)             # dict of columns, see dibaguard.engine.FLOW_FIELDS
L.calibrate_http(["get /shop?item=12 | h:user-agent=mozilla/5.0", ...])   # canonical texts, dibaguard.http.parse
L.calibrate_db(benign_db_events)            # {t, engine, db, client, query, rows, status}, adapters in shield/database.py

# 2. score, in time order
out = L.flows(flows)                        # per-flow alarm / family / score + actions per source
h = L.http(texts, client=clients, host=hosts, status=statuses, t=times)   # playbook ids, families, actions
d = L.db(events)                            # verdicts with remediation; app servers are never blocked
print(L.report())                           # incident report (JSON); dibaguard.report.render_en for text

The sidecar serves the same engine over MCP and REST, with the operator console:

python -m dibaguard.llm http --models models --port 8787 --policy policy.json --backend dryrun   # REST + console
python -m dibaguard.llm mcp  --models models                                                      # MCP over stdio

Start in report mode with the dry-run backend; switch the policy to enforce only after reviewing the report (docs/INTEGRATIONS.md section 10).

Go fast path

cd runtime/go
go build -o dibaguard-authz ./cmd/dibaguard-authz      # stdlib only, Go 1.22
./dibaguard-authz -listen 127.0.0.1:9300 -models ../../models -sidecar http://127.0.0.1:8787 -mode report

dibaguard-authz answers nginx auth_request, Envoy ext_authz, Traefik ForwardAuth, Caddy forward_auth and HAProxy (docs/INTEGRATIONS.md). Without an HTTP model file it logs model unavailable once and runs on signatures and the sidecar's state, which is the intended configuration of this build. dibaguard-proxy (the inline reverse proxy) requires models/http_v2/http_tier1_v2.bin at start and therefore does not run against this model folder; use dibaguard-authz behind your load balancer, or the Python layer inline.

Data and licences

• Code: Apache-2.0 (LICENSE).
• Model files under models/: CC BY-SA 4.0 (LICENSE-WEIGHTS), because LUFlow (Mills et al., IEEE TNSM 2021), one training source, is CC BY-SA 4.0 and whether trained weights are Adapted Material is legally unsettled; this release applies ShareAlike rather than relying on the answer.
• Training data of the network models (NOTICE): RoEduNet-SIMARGL2021 and SIMARGL2022 (CC BY 4.0, Mihailescu et al., Sensors 2021); APPRAISE H2020 real labelled NetFlow (CC BY 4.0, ITTI); ACI-IoT-2023 (CC BY 4.0, Nack et al., MILCOM 2024, doi:10.21227/qacj-3x32); CSE-CIC-IDS2018 from the publisher's AWS bucket (Sharafaldin et al., ICISSP 2018; https://registry.opendata.aws/cse-cic-ids2018); LUFlow 2020 / 2021 (CC BY-SA 4.0, Mills et al., IEEE TNSM 2021, doi:10.1109/TNSM.2021.3091517). DbNet: own grammar-generated corpus. The same block is stored in each model's metadata.
• Audit: docs/DATA_LICENSES.md classifies every dataset the project ever touched (GREEN / AMBER / RED, with the owner's terms quoted); docs/CLEAN_MODELS.md records how the clean set was built, the licence gate in the training jobs, and every head-to-head number. Evaluation-only material (OWASP CRS tests, SR-BH 2020, the ModSecurity 2025 archive) was never trained on and nothing from it is bundled.

Limitations

• No HTTP request model in this build (above). Payloads the signatures and the SQL-context analysis do not name are caught only when their client's behaviour is; the benign alarm rate of the HTTP edge is correspondingly lower, and so is its recall on obfuscated XSS / command-injection variants.
• Benign alarm rate on public flow captures is above the budget when the scored period differs strongly from the calibration window (docs/VALIDATION_REPORT.md section 8.5, measured with the private models after the fixes): CSE-CIC-IDS2018 (AWS, DDoS day) 6.77 % of benign source-minutes alarmed (3.04 % without the two global tiers; 99.7 % of attack source-minutes caught); SIMARGL 2021 (a 2-million-flow scan) 24.07 % (1.03 % without the global tiers; 100 % caught); LUFlow 2021 temporal hold-out 1.12 % (10.3 % of reputation-labelled attack sources caught). The budget is 0.1 %; the labs meet it, these captures do not yet. A longer calibration window (a day rather than hours) is the first lever.
• IoT / UNSW-style networks: the open tier-1 prior is weak there (section above).
• Payload inspection needs clear text (TLS-terminating proxy or logs); encrypted traffic is covered for behaviour only.
• A slow distributed scan among internet background radiation is found by the campaign tier in 6-17 minutes.
• Python state costs about 3-3.6 KB per tracked source (design budget 300 B): size max_entities to RAM or put the Go tiers in front; re-calibration still runs on the hot path.
• Prose that has the exact shape of an injection (admin'#') is still blocked (2.09 % of technical docstring sentences with an apostrophe; 0 of 16 ordinary review sentences).
• Several uploader identities behind the CC BY sources (SIMARGL, LUFlow, ACI-IoT Kaggle accounts) are inferred from display names, not verified; the CIC redistribution wording should be confirmed by e-mail. Not legal advice.

Model files

Documentation

docs/TECHNICAL.md (design, models, calibration, HTTP edge, database tier, shield, history, results, limitations), docs/VALIDATION_REPORT.md (independent validation and the remediation), docs/CLEAN_MODELS.md (licence-clean models, head-to-head), docs/DATA_LICENSES.md (licence audit), docs/INTEGRATIONS.md (nginx, Envoy, HAProxy, Traefik, Caddy, Kubernetes), docs/CONSOLE.md (operator console), docs/HA.md (state, restarts, replicas), docs/PERFORMANCE.md (throughput, latency, memory), docs/DESIGN.md (the original design note), reports/benchmark.md. The copies in this repository had their Persian sections removed and carry a note about what applies to the open build.

Citation

@software{dibaguard_2026,
  title   = {DibaGuard: a CPU-light, calibrated attack-detection and protection layer},
  author  = {Dibachain},
  year    = {2026},
  url     = {https://huggingface.co/Dibachain/DibaGuard},
  license = {Apache-2.0 (code), CC-BY-SA-4.0 (models)}
}

---

دیباگارد (DibaGuard)

لایهٔ سبکِ تشخیص و دفع حمله برای جریان‌های شبکه، HTTP، گره‌های JSON-RPC و پایگاه‌های داده؛ با نرخ هشدار اشتباهِ کنترل‌شده، حکم‌های قابل‌توضیح و اجراکننده‌ای که فقط طبق سیاست اپراتور عمل می‌کند. این نسخهٔ عمومی و پاک از نظر مجوز است که دیباچین منتشر کرده: کد با مجوز Apache-2.0 و فایل‌های مدل با مجوز CC BY-SA 4.0 (چون یکی از منابع آموزشی ShareAlike است). دموی تعاملی: DibaAi/beam-dibaguard.

دیباگارد چیست

دیباگارد همان‌جایی می‌نشیند که یک WAF، یک IDS و یک فایروال میزبان می‌نشینند: درون‌خط جلوی برنامه، به‌عنوان سرویس تصمیم‌گیری بیرونی پشت لودبالانسری که همین حالا دارید (nginx، Envoy، HAProxy، Traefik، Caddy)، یا کنار میزبان با خواندن خروجی جریان‌ها و لاگ‌ها. هر هشدار سه چیز همراه دارد:

• نرخ هشدار اشتباهِ کنترل‌شده: آستانه‌ها با روش Conformal روی ترافیک خودِ سایت کالیبره می‌شوند (بودجهٔ پیش‌فرض ۰٫۰۰۱ برای هر منبع-دقیقه).
• خانوادهٔ حمله و شواهد: پویش پورت، brute force، DoS/DDoS، تزریق SQL، حرکت جانبی، نشت داده و غیره، با همان شمارنده‌هایی که هشدار را ساخته‌اند.
• اقدامی که سیاست اپراتور تعیین می‌کند: فقط گزارش، یا اجرا (مسدودسازی، محدودسازی نرخ، چالش مرورگر)؛ فقط حکم‌های block_ok اجرا می‌شوند.

استنتاج در پایتون فقط به numpy نیاز دارد و مسیر سریع Go بدون وابستگی، روی نمونه‌های برابری بیت‌به‌بیت با پایتون یکسان است. اپراتور قانون‌هایش را به زبان ساده می‌نویسد (فارسی و انگلیسی با پارسر داخلی؛ هر زبانی از راه مدل زبانی دلخواه از طریق پل MCP/REST). لایه برداشتش را پیش از فعال‌شدن قانون نشان می‌دهد و هر پیشنهاد مدل زبانی از دروازهٔ تأیید می‌گذرد.

آبشار تشخیص

1. طبقهٔ ۰، وضعیت موجودیت: ۳۶ شمارندهٔ رفتاری با کاهش نمایی برای هر منبع در سه افق (۱۰ ثانیه، ۲ دقیقه، ۳۰ دقیقه): سهم بی‌پاسخ، SYN تنها، ریست، پورت تازه، میزبان تازه، تکرار، جریان کوتاه، فاصله‌ها، و سه شمارندهٔ سمت مقصد.
2. طبقهٔ ۱، پیش‌فرض درختی یکنوا: درخت‌های oblivious با قید یکنوایی روی ۲۴ ویژگی جهت‌دارِ حمله؛ p-value به تفکیک سرویس × سن منبع (Mondrian).
3. طبقهٔ '۱، ناهنجاری فقط-سایت: مجموع فیشرِ p-valueهای دم بالا روی همان ویژگی‌ها نسبت به مرجع خودِ سایت؛ بدون برچسب.
4. طبقهٔ ۲، شبکهٔ دنباله‌ای GRU: روی جریان هر منبع (فقط منبع‌های گرم)، با زمینهٔ سایت.
5. شواهد (CUSUM): شواهد انباشتهٔ هر منبع با میانگین صفر، قضاوت در واحد منبع-دقیقه؛ یک افق کند برای پویش‌های آهسته.
6. طبقهٔ مقصد و کارزار: طغیان توزیع‌شده روی یک مقصد؛ کارزارهای آهسته و پخش (صدها آدرس، هرکدام چند تلاش) از راه اثرانگشت سرویس × شکست و شمار منبع‌های متمایز ناموفق در هر پنجره.
7. لبهٔ HTTP: امضاهای A01 تا A22، تحلیل زمینهٔ SQL برای هر پارامتر، DbNet به‌عنوان نظر دوم، و طبقهٔ نشست (هر درخواست یک رویداد از جریان کلاینت است).
8. طبقهٔ پایگاه‌داده: ۱۳ موتور و ۶ قالب لاگ؛ امضاها روی ساختارِ بدون رشته، DbNet، حجم خواندن به تفکیک کلاینت و جدول، شکل کوئری‌های خودِ برنامه؛ ردیابی منشأ محموله تا کلاینت وبِ پشت برنامه.
9. پوستهٔ حفاظتی: سیاست، اجراکننده (nftables/iptables/فایروال ویندوز/آزمایشی)، هویت (NAT/CGNAT، ‎/64 در IPv6)، بازخورد ضدمسموم‌سازی، ممیزی وضعیت، کنسول اپراتور.

چه چیزی در این مخزن هست و چه چیزی نیست

مدل‌های شبکه (پیش‌فرض یکنوا، GRU، آشکارسازهای موجودیت) و DbNet به‌صورت npz و به‌صورت آرایه‌های تخت bin برای Go؛ کل runtime پایتون و Go؛ مستندات فنی، گزارش اعتبارسنجی مستقل، ممیزی مجوز داده‌ها، گزارش مدل‌های پاک، بنچمارک سه‌بذری و نمودارها.

مدل درخواست HTTP در این مخزن نیست. مدل نسخهٔ خصوصی روی داده‌هایی آموزش دیده که مجوز بازنشرشان روشن نیست، و بازآموزی با دادهٔ پاک روی برنامه‌های نادیده فرو می‌ریزد (docs/CLEAN_MODELS.md). موتور این پیکربندی را به‌صورت بومی پشتیبانی می‌کند: لبهٔ HTTP این نسخه با امضاها، تحلیل زمینهٔ SQL، DbNet و طبقهٔ نشست کار می‌کند.

نتایج

آزمایشگاه‌های بازتولیدپذیر (سه seed، reports/benchmark.md)، اندازه‌گیری‌شده روی نسخهٔ خصوصی با مجموعهٔ کامل مدل‌ها؛ خط‌های تزریق SQL و مقایسه با libinjection فقط به امضا + زمینهٔ SQL + DbNet وابسته‌اند:

دادهٔ واقعی: تزریق SQL در آرشیو ۲۰۲۵ ModSecurity با محمولهٔ قابل‌مشاهده ۱٫۰۰۰ از ۱۶۷۱ (libinjection: ۰٫۹۸۶)؛ هشدار اشتباه روی ۸۰ هزار درخواست سالم یک فروشگاه واقعی ۰٫۰۰۰۱۳.

اعتبارسنجی مستقل: تیمی که دیباگارد را نساخته بود ۲۲ یافته گزارش داد (دور زدن کانونی‌ساز، سقف‌های خاموش، ترفندهای هویت، مسموم‌سازی مرجع، آسیب به کاربر سالم). همهٔ ۲۲ مورد از ریشه رفع شد و بازتولید هرکدام تست دائمی رگرسیون است (docs/VALIDATION_REPORT.md بخش ۸). بعد از رفع: در fuzz کانونی‌سازی با ۳۰۰۰ مورد، مسیر پایتون و Go هرکدام ۹۹٫۳٪ را مسدود می‌کنند با ۰٪ اختلاف حکم؛ ۸۰٬۲۳۴ درخواست سالم: ۰ مسدود؛ کاربران سالمِ مسدودشده در هر ۱۰۰۰ کاربر در روز: ۱۴۶ ← ۰.

شروع سریع

pip install numpy
export PYTHONPATH=$PWD/runtime/python

from dibaguard.shield.layer import Layer
L = Layer.load("models", policy={"mode": "report"}, inputs={"http": True, "flows": True}, backend="dryrun")
L.calibrate_flows(benign_flows)          # ترافیک عادی خودِ سایت، بدون برچسب حمله
out = L.flows(flows)                     # هشدار، خانواده، امتیاز و اقدام برای هر منبع
h = L.http(texts, client=clients, host=hosts, status=statuses, t=times)
d = L.db(events)
print(L.report())                        # گزارش رخداد (JSON)؛ متن فارسی: dibaguard.report.render_fa

سایدکار همین موتور را از راه MCP و REST به همراه کنسول اپراتور ارائه می‌دهد:

python -m dibaguard.llm http --models models --port 8787 --policy policy.json --backend dryrun

همیشه با حالت گزارش و backend آزمایشی شروع کنید و فقط پس از بازبینی گزارش، سیاست را به enforce ببرید. مسیر سریع Go (runtime/go, ‏dibaguard-authz) پشت nginx، Envoy، HAProxy، Traefik و Caddy می‌نشیند (docs/INTEGRATIONS.md).

داده و مجوزها

• کد: Apache-2.0 (LICENSE).
• فایل‌های مدل: CC BY-SA 4.0 (LICENSE-WEIGHTS)، چون LUFlow یکی از منابع آموزشی با مجوز ShareAlike است.
• دادهٔ آموزشی مدل‌های شبکه (NOTICE): SIMARGL2021 و SIMARGL2022 ‏(CC BY 4.0)، APPRAISE ‏(CC BY 4.0)، ACI-IoT-2023 ‏(CC BY 4.0)، CSE-CIC-IDS2018 از مخزن AWS ناشر (با ذکر منبع)، LUFlow 2020/2021 ‏(CC BY-SA 4.0). DbNet: پیکرهٔ خودساختهٔ گرامری.
• ممیزی: docs/DATA_LICENSES.md هر دیتاستی را که پروژه لمس کرده طبقه‌بندی می‌کند؛ docs/CLEAN_MODELS.md ساخت مجموعهٔ پاک و همهٔ اعداد مقایسه را ثبت کرده است.

محدودیت‌ها (صادقانه)

• مدل درخواست HTTP در این نسخه نیست؛ شمارش API بدون محموله شواهدی نمی‌سازد.
• مدل‌های باز روی ترافیک شبیه UNSW-NB15 و ToN-IoT از مدل‌های خصوصی ضعیف‌ترند، چون هم‌تای مجازی برای آن داده‌ها وجود ندارد.
• روی بعضی داده‌های جریان عمومی، نرخ هشدار سالم هنوز بالاتر از بودجهٔ ۰٫۰۰۱ است (گزارش اعتبارسنجی، بخش ۸٫۵).
• بازرسی محموله به ترافیک رمزگشایی‌شده نیاز دارد؛ طبقه‌های رفتاری فقط فرادادهٔ جریان می‌خواهند.

---

دیباچین · Dibachain — dibachain.ir · info@dibachain.ir