# DibaGuard console

> **Open-release copy** ([DibaAi/DibaGuard-Open](https://huggingface.co/DibaAi/DibaGuard-Open)). This document was written for the private build of DibaGuard. Numbers that involve the HTTP request model (`http_v2`) were measured with that model, which is **not** part of the open release; the open release ships the licence-clean network models described in `CLEAN_MODELS.md`. Licence statements inside this document are superseded by `DATA_LICENSES.md`, `CLEAN_MODELS.md` and the repository's `LICENSE`, `LICENSE-WEIGHTS` and `NOTICE` files. Sections of the original that were written in Persian were removed from this copy; nothing else was edited.

The operator console is one self-contained page served by the sidecar at `GET /console` (`/` and `/dashboard` redirect
to it). It loads nothing from anywhere else - no CDN, font or script - so it works on an air-gapped server. Tabs:
Overview, Incidents (with a per-source drawer: evidence, timeline, what the layer did and why, database remediation),
Review queue, Rules, Policy, Databases, Posture & enforcement, Teach. Light and dark themes follow the OS; the sun/moon
button overrides it.

## Opening it

The sidecar binds to `127.0.0.1` by default. From your laptop, tunnel to it:

```
ssh -N -L 8787:127.0.0.1:8787 user@guard-host
# then open http://127.0.0.1:8787/console
```

Start the sidecar with the shield layer (without `--policy` the console is read-only, engine only):

```
python -m dibaguard.llm http --models models --policy policy.json --inputs http,flows --port 8787
```

Reading needs nothing. Every write (verdicts, rules, policy, block / lift, teaching) needs the **console token**:

- set `DIBAGUARD_CONSOLE_TOKEN` in the sidecar's environment, or
- leave it unset: the sidecar generates one and prints it **once** on stderr at startup.

Click **Read-only** in the header and paste the token. It is kept in that browser tab only (sessionStorage) and
forgotten when the tab closes or you click **Unlocked** to lock again.

## Connecting an LLM (Teach)

The model is configured in the sidecar's environment, never in the page; the key never reaches the browser.

| variable | value |
|---|---|
| `DIBAGUARD_LLM_PROVIDER` | `openai` - any OpenAI-compatible `/chat/completions` endpoint (vLLM, llama.cpp server, Ollama, LM Studio, OpenAI) - or `anthropic` (Messages API) |
| `DIBAGUARD_LLM_BASE_URL` | e.g. `http://10.0.0.30:8000/v1`; for `anthropic` defaults to `https://api.anthropic.com` |
| `DIBAGUARD_LLM_MODEL` | the model name |
| `DIBAGUARD_LLM_API_KEY` | the key (optional for local servers; required for `anthropic`) |
| `DIBAGUARD_LLM_TIMEOUT` | seconds per call, default 120 |

On an air-gapped site, point `DIBAGUARD_LLM_BASE_URL` at a model served on the local network; the model must support
tool / function calling. Without an LLM, the Teach tab explains this and still offers the built-in Persian / English
rule parser.

The Rules tab can also use the connected LLM to interpret a rule written in any language (interpreter
"Connected LLM", or "Auto" when the built-in parser finds no condition). The result is shown as a precise rule first.

## The approval model

The sidecar runs the tool loop itself (`POST /console/chat`), with the dispatcher's tools (`guard_*`) plus four
console tools (`console_entity`, `console_rule_install`, `console_rule_remove`, `console_enforce`).

- **Reads run at once**: status, report, entity details, review queue, fast state, rules / policy (viewing), database
  status, playbook.
- **Everything that changes state becomes a proposal**: rule install / removal, verdicts, policy changes, block / lift,
  calibration, and feeding traffic to the engine (scoring can lead to actions). The model is told "proposed - not
  executed" and the proposal appears in the transcript and in *Pending proposals* with its exact tool call.
- **Only you execute it**, by clicking **Approve** (`POST /console/approve`). A rule proposal installs exactly the rule
  you saw in the preview - it is not re-interpreted. A mode switch additionally needs the target mode typed back.
  Proposals expire after an hour; each can be decided once.
- The assistant hears your decisions (approved, rejected, failed, and your own changes from other tabs) at the start of
  its next turn. The server keeps a bounded history (40 messages for the model, 300 transcript lines); **Clear** forgets it.

Policy changes from the Policy tab are validated by `Policy.validate` before they apply. Switching between REPORT and
ENFORCE asks you to type `ENFORCE` / `REPORT`, server-side (an API caller cannot skip it either). Fields that only take
effect at start-up (`alpha`, database thresholds read at load) are not editable live: edit `policy.json` and restart.
Rules and policy changed in the console live in memory; **Policy -> Effective policy -> Download** gives a
`policy.json` with the installed rules to keep them across restarts.

## Security notes

- **Bind to loopback** and reach it over SSH. If you bind elsewhere the sidecar warns at startup; put TLS and access
  control in front.
- **Writes**: every `POST /console/*` needs `X-DibaGuard-Token` (or `Authorization: Bearer`), the custom header
  `X-DibaGuard-Console: 1`, and `Content-Type: application/json`. Cross-site requests (`Origin` not matching `Host`,
  `Sec-Fetch-Site: cross-site|same-site`) are refused. No CORS headers are ever sent, so another site's page can neither
  send those headers nor read answers.
- **DNS rebinding**: `/console*` is only served when `Host` is an IP literal or `localhost`; add names (a reverse proxy)
  with `DIBAGUARD_CONSOLE_HOSTS=guard.example.internal`.
- **The page** carries a CSP that pins its one inline script by hash, forbids every external load, framing, forms and
  base changes. Everything shown is inserted as text - evidence, queries and user-agents from attackers never become markup.
- **The tool API** (`POST /tools/<name>`): calls that change what the layer enforces - `guard_policy` with `set`,
  `guard_feedback`, `guard_rules` with `add` (not `interpret_only`), `guard_posture` when port closing is on - need the
  same token **and** `X-DibaGuard-Console: 1`, and so do `guard_calibrate` / `guard_db_calibrate` (re-calibration
  rewrites what the site's normal is). Reads stay open on loopback. **Traffic feeds that carry sources**
  (`guard_score_http` with `client` / `t` / `status`, `guard_score_flows`, `guard_db`, `guard_rpc`) need the **feed
  token** - `DIBAGUARD_FEED_TOKEN`, sent as `X-DibaGuard-Feed-Token` by the Go proxy and the authz service, which read
  the same variable - or the console token: otherwise anyone who can reach the port could feed traffic that makes the
  layer block an address of their choice (validation finding V-16). Without `DIBAGUARD_FEED_TOKEN` the sidecar makes
  one and prints it once on stderr. A score-only `guard_score_http` (texts, no client or time) changes nothing and stays
  open. `DIBAGUARD_FEEDS_OPEN=1` reopens every feed (an isolated loopback deployment only; the sidecar warns at
  startup); `DIBAGUARD_FEEDS_NEED_TOKEN=1` demands the console token and header for feeds too. MCP over stdio is
  unchanged (it is the local process's own channel).
- **Prompt injection**: tool results contain attacker-written text. The system prompt tells the model it is data, and
  the approval gate means a manipulated model can at most *propose*; read each proposal's exact tool call before approving.
- The LLM key stays in the sidecar process; provider errors are redacted before they are shown.

## Endpoints

| method | path | |
|---|---|---|
| GET | `/console` | the page |
| GET | `/console/state` | counters, pressure, drift, mode, backend, latest alarms / actions, per-minute series |
| GET | `/console/incidents?limit=` | sources with risk, score, families, playbook names, enforcement |
| GET | `/console/entity?ip=` | one source: evidence, timeline, audit (what was done, why), explanation, remediation, verdicts |
| GET | `/console/review` | review queue (incl. `site:drift`), verdict stats, recent verdicts |
| GET | `/console/rules`, `/console/policy`, `/console/databases`, `/console/posture`, `/console/chat` | tab data |
| POST | `/console/auth` | check the token |
| POST | `/console/rules/interpret` `{text, engine: auto\|builtin\|llm}` | preview only |
| POST | `/console/rules/install` `{rule, text}` / `/console/rules/remove` `{id}` | |
| POST | `/console/policy` `{set, confirm?}` | 409 + `confirm_word` when the mode changes |
| POST | `/console/feedback` `{entity, verdict, note}` | confirm / reject / benign_source |
| POST | `/console/enforce` `{ip, action: block\|rate_limit\|challenge\|lift, reason}` | |
| POST | `/console/posture/run` | runs the audit (closes ports only if the policy allows) |
| POST | `/console/chat` `{message}` / `/console/chat/reset` | the assistant |
| POST | `/console/approve` `{id, decision: approve\|reject, confirm?, note?}` | execute or drop a proposal |