|
Download README.md from Dibachain/DibaGuard: direct link, hf CLI and curl.
- Browser
- Download file 31 kB
-
https://huggingface.co/Dibachain/DibaGuard/resolve/main/README.md
- Command line
-
hf download hf://Dibachain/DibaGuard/README.md
-
curl -L -o README.md https://huggingface.co/Dibachain/DibaGuard/resolve/main/README.md
31 kB
| license: apache-2.0 | |
| language: | |
| - en | |
| - fa | |
| tags: | |
| - security | |
| - intrusion-detection | |
| - waf | |
| - network | |
| - numpy | |
| - persian | |
| library_name: none | |
| # 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`](https://huggingface.co/DibaAi/DibaGuard-Open); an interactive demo is at | |
| [`DibaAi/beam-dibaguard`](https://huggingface.co/spaces/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 | |
| | path | content | licence | | |
| |---|---|---| | |
| | `models/seq_v1/nf_entity_mono.npz` | tier-1 monotone tree prior (24 behaviour counters, oblivious trees evaluated in numpy) | CC BY-SA 4.0 | | |
| | `models/seq_v1/seqnet.npz`, `seq_v1_info.json` | tier-2 GRU sequence network (d = 64) | CC BY-SA 4.0 | | |
| | `models/entity_v1/nf_entity_detector.npz`, `lu_entity_detector.npz` | fallback entity detectors (NetFlow view; LUFlow view) | CC BY-SA 4.0 | | |
| | `models/dbnet.npz` | DbNet, the database query network (own grammar-generated corpus) | CC BY-SA 4.0 | | |
| | `models/**/*.bin`, `*.bin.json` | the same weights as flat arrays for the Go runtime | CC BY-SA 4.0 | | |
| | `runtime/python/dibaguard/` | the engine, shield, HTTP edge, database tier, LLM bridge (MCP + REST) and operator console | Apache-2.0 | | |
| | `runtime/go/` | the Go fast path (`dibaguard-authz`, `dibaguard-proxy`) and its parity fixtures | Apache-2.0 | | |
| | `docs/`, `reports/`, `charts/` | technical documentation, independent validation report, licence audit, benchmark, charts | Apache-2.0 | | |
| **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: | |
| | scored network (neither model trained on it) | shipped AUROC | open (clean) AUROC | | |
| |---|---|---| | |
| | SIMARGL2022 | 0.968 | **0.999** | | |
| | APPRAISE | 0.614 | **0.985** | | |
| | ACI-IoT-2023 (author release) | 0.622 | 0.644 | | |
| | CSE-CIC-IDS2018, AWS, Tue 20-02 | 0.949 | **1.000** | | |
| 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). | |
| | lab (3 seeds) | item | mean | min-max | | |
| |---|---|---|---| | |
| | evolving attacker, 12 waves | Log4Shell / SSH brute force / NTP amplification / credential stuffing / peer flood / rapid reset / WordPress exploit / AI scraper, final recall | 1.000 each | 1.0-1.0 | | |
| | evolving attacker, 12 waves | API enumeration, final recall | 0.979 | 0.973-0.983 | | |
| | evolving attacker, 12 waves | benign sources blocked (flows / HTTP) | 0 / 0 | - | | |
| | evolving attacker, 12 waves | benign alarm rate per source-minute (flows / HTTP) | 0.0011 / 0.0010 | budget 0.001 | | |
| | six-wave playbook lab | SSH brute force / HTTP/2 rapid reset / credential stuffing / slow scan / chain peer flood, recall | 0.945 / 0.980 / 0.984 / 0.935 / 0.875 | see report | | |
| | databases, 6 engines, 12 scenarios | detected / correct response | 1.000 / 1.000 (all twelve) | 1.0-1.0 | | |
| | databases | benign alarms per million queries / app servers enforced | 0 / 0 | - | | |
| | low-and-slow campaigns C1-C5 (150-3,000 sources) | member recall | 1.000 / 0.959 / 0.953 / 1.000 / 1.000 | detection delay 4.7 / 8.3 / 15.3 / 0.0 / 0.0 min | | |
| | unfamiliar networks: hosting | flood on one tenant / slow distributed scan / SSH guessing | 0.991 / 0.918 / 1.000 | benign alarms 0.00096 per source-minute, 0 enforced | | |
| | unfamiliar networks: office | SMB lateral movement / Kerberoasting / RDP spraying / LDAP enumeration | 1.000 each | benign alarms 0.00014 per source-minute, 0 enforced | | |
| | unfamiliar networks: OT | PLC subnet scan / Modbus writes / telnet-ssh guessing / MQTT flood | 1.000 / 1.000 / 1.000 / 0.839 | benign alarms 0.000012 per source-minute, 0 enforced | | |
| | platforms (WordPress, Joomla, Drupal, JSON API, generic) | 17 attack scenarios detected | 0.91-1.00 (13 of 17 at 1.000) | 0 benign sources blocked | | |
| | chain RPC | eth_getLogs flood / debug_traceTransaction flood / mempool spam | 1.000 / 1.000 / 0.967 | - | | |
| 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) | |
| ```bash | |
| pip install numpy | |
| export PYTHONPATH=$PWD/runtime/python # or: pip install -e runtime/python after adding a pyproject of your own | |
| ``` | |
| ```python | |
| 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: | |
| ```bash | |
| 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 | |
| ```bash | |
| 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 | |
| | file | bytes | | |
| |---|---| | |
| | `models/dbnet.bin` | 3,160,300 | | |
| | `models/dbnet.bin.json` | 680 | | |
| | `models/dbnet.npz` | 2,403,349 | | |
| | `models/dbnet_eval.json` | 6,016 | | |
| | `models/entity_v1/lu_entity_detector.bin` | 188,976 | | |
| | `models/entity_v1/lu_entity_detector.bin.json` | 1,916 | | |
| | `models/entity_v1/lu_entity_detector.npz` | 152,441 | | |
| | `models/entity_v1/nf_entity_detector.bin` | 274,400 | | |
| | `models/entity_v1/nf_entity_detector.bin.json` | 2,820 | | |
| | `models/entity_v1/nf_entity_detector.npz` | 221,205 | | |
| | `models/seq_v1/nf_entity_mono.bin` | 82,358 | | |
| | `models/seq_v1/nf_entity_mono.bin.json` | 3,116 | | |
| | `models/seq_v1/nf_entity_mono.npz` | 17,794 | | |
| | `models/seq_v1/seq_v1_info.json` | 560 | | |
| | `models/seq_v1/seqnet.bin` | 381,172 | | |
| | `models/seq_v1/seqnet.bin.json` | 5,512 | | |
| | `models/seq_v1/seqnet.npz` | 390,463 | | |
| ## 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 | |
| ```bibtex | |
| @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`](https://huggingface.co/spaces/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 وابستهاند: | |
| | آزمایشگاه | مورد | نتیجه | | |
| |---|---|---| | |
| | مهاجم تکاملیابنده، ۱۲ موج | Log4Shell، brute force SSH، تقویت NTP، پرکردن اعتبارنامه، طغیان همتا، rapid reset، اکسپلویت وردپرس، خزندهٔ هوش مصنوعی | بازیابی نهایی ۱٫۰۰۰ برای همه | | |
| | مهاجم تکاملیابنده | شمارش API | ۰٫۹۷۹ | | |
| | مهاجم تکاملیابنده | منبع سالمِ مسدودشده (جریان / HTTP) | ۰ / ۰ | | |
| | پایگاهداده، ۶ موتور، ۱۲ سناریو | تشخیص / پاسخ درست | ۱٫۰۰۰ / ۱٫۰۰۰ (هر دوازده) ؛ هشدار سالم: ۰ در میلیون کوئری | | |
| | کارزارهای آهسته و پخش C1 تا C5 (۱۵۰ تا ۳۰۰۰ منبع) | بازیابی اعضا | ۱٫۰۰۰ / ۰٫۹۵۹ / ۰٫۹۵۳ / ۱٫۰۰۰ / ۱٫۰۰۰ ؛ تأخیر ۴٫۷ / ۸٫۳ / ۱۵٫۳ / ۰ / ۰ دقیقه | | |
| | شبکههای ناآشنا: هاستینگ / اداری / صنعتی (OT) | ۱۱ حمله | ۰٫۸۴ تا ۱٫۰۰؛ هیچ منبع سالمی اجرا نشد | | |
| | پلتفرمها (وردپرس، جوملا، دروپال، JSON API، عمومی) | ۱۷ سناریو | ۰٫۹۱ تا ۱٫۰۰؛ ۰ منبع سالم مسدود | | |
| دادهٔ واقعی: تزریق SQL در آرشیو ۲۰۲۵ ModSecurity با محمولهٔ قابلمشاهده **۱٫۰۰۰** از ۱۶۷۱ (libinjection: ۰٫۹۸۶)؛ هشدار اشتباه روی ۸۰ هزار درخواست سالم یک فروشگاه واقعی ۰٫۰۰۰۱۳. | |
| **اعتبارسنجی مستقل**: تیمی که دیباگارد را نساخته بود ۲۲ یافته گزارش داد (دور زدن کانونیساز، سقفهای خاموش، ترفندهای هویت، مسمومسازی مرجع، آسیب به کاربر سالم). همهٔ ۲۲ مورد از ریشه رفع شد و بازتولید هرکدام تست دائمی رگرسیون است (`docs/VALIDATION_REPORT.md` بخش ۸). بعد از رفع: در fuzz کانونیسازی با ۳۰۰۰ مورد، مسیر پایتون و Go هرکدام ۹۹٫۳٪ را مسدود میکنند با ۰٪ اختلاف حکم؛ ۸۰٬۲۳۴ درخواست سالم: ۰ مسدود؛ کاربران سالمِ مسدودشده در هر ۱۰۰۰ کاربر در روز: ۱۴۶ ← **۰**. | |
| ## شروع سریع | |
| ```bash | |
| pip install numpy | |
| export PYTHONPATH=$PWD/runtime/python | |
| ``` | |
| ```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 به همراه کنسول اپراتور ارائه میدهد: | |
| ```bash | |
| 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 از مدلهای خصوصی ضعیفترند، چون همتای مجازی برای آن دادهها وجود ندارد. | |
| - روی بعضی دادههای جریان عمومی، نرخ هشدار سالم هنوز بالاتر از بودجهٔ ۰٫۰۰۱ است (گزارش اعتبارسنجی، بخش ۸٫۵). | |
| - بازرسی محموله به ترافیک رمزگشاییشده نیاز دارد؛ طبقههای رفتاری فقط فرادادهٔ جریان میخواهند. | |
| --- | |
| <div align="center"> | |
| **دیباچین · Dibachain** — [dibachain.ir](https://dibachain.ir) · [info@dibachain.ir](mailto:info@dibachain.ir) | |
| </div> | |