examples: add agent-action-monitor (behavioural gate for AI agent actions)

[ritiksah141]

Summary

Adds a new example at examples/agent-action-monitor/. A behavioural gate for AI agent actions, built on DUSK, an open source behavioural threat detection project. The core idea: a hijacked AI agent still holds valid credentials, so a credential check waves it through. This gate asks a different question, does this agent normally do this, by scoring a proposed control-plane action (a firewall rule change, a route change, a role grant) against that agent's own learned baseline before the action reaches a downstream system.

SIE is optional and degrades gracefully throughout the request path. Semantic novelty and qualifying extraction results can increase, but never reduce, the deterministic anomaly score.

• extract uses GLiNER with the labels role, privilege, resource, segment, and port. Confident, previously unknown role or privilege entities contribute an additional bounded anomaly signal; neutral resource, segment, and port entities do not add score by themselves.
• encode (BAAI/bge-m3) embeds each recorded verdict once. When sufficient history exists, it also embeds the incoming action for the bounded fleet-wide similar-decision lookup. It does not contribute directly to the anomaly score.
• score (BAAI/bge-reranker-v2-m3) reranks the acting agent's learned baseline history to detect semantic novelty and separately reranks the fleet-wide similar-decision shortlist.

Repeat-offense memory persists refused verdicts per agent. A matching later attempt receives a bounded, decaying contribution and cites the earlier trace ID. Storage is capped at 50 offenses per agent and 500 tracked agents.

Also adds a row to examples/README.md's gallery table.

Architecture

Five services on one Docker Compose stack, no API key required by default: dusk-gate (the Flask /v1/gate service), sie (self-hosted, CPU default image), n8n (three webhooks, decision, report, alert, baked in and active from container start), mock-prod (a dummy downstream target), and agent-demo (a Bedrock or mock agent harness that runs a clean and a poisoned scenario against the gate, then exits).

Watch mode is the default: a refused action is logged as WOULD-BLOCK but still reaches mock-prod, since an inline gate that wrongly blocks a legitimate action can disrupt a network. Enforce mode upgrades WOULD-BLOCK to BLOCK, which stops the action before it reaches mock-prod.

Run it

cd examples/agent-action-monitor
docker compose up

Brings up the full stack. agent-demo runs a clean and a poisoned scenario against the gate automatically, then exits. See the example's own README for the full walkthrough, watch versus enforce mode, and the n8n webhook views.

Validated end to end

Documented in the example's own docs/sie-primitives.md, from a run against Superlinked's hosted tester cluster:

• sie_encode returns a real 1024-dimensional dense vector from BAAI/bge-m3, confirming the model actually loaded and served
• Precision and recall on the labelled fixture stay at 1.0 and 1.0 with SIE enabled, matching the deterministic-only baseline exactly, no regression from enabling SIE
• At least one attack's reasons carries a real SIE rerank or SIE extract marker, confirming the primitives are actually contributing a signal over the network
• The full test suite passes unchanged with live SIE enabled
• Restart persistence is covered by an automated test, test_offense_memory_persists_across_a_simulated_restart, which restarts the gate engine and confirms a repeat offense is still cited afterward

Test plan

• docker compose up starts the full stack; health-gated services become healthy and agent-demo completes both scenarios successfully
• agent-demo's clean scenario returns ALLOW and reaches mock-prod
• agent-demo's poisoned scenario returns WOULD-BLOCK in watch mode and still reaches mock-prod
• Setting DUSK_ENFORCE=true on dusk-gate turns the same poisoned scenario into BLOCK, and it no longer reaches mock-prod
• pytest passes standalone from a fresh pip install -e ".[dev]" of this directory alone, 186 passed, 2 skipped
• ruff check, mypy, and bandit clean

Notes and caveats

• /v1/gate is unauthenticated with CORS open to all origins by default, appropriate for a local example, not a production security boundary
• The deterministic feature checks carry the primary anomaly scoring; the three SIE primitives are an enrichment layer on top, not a replacement, so the gate's core detection logic never depends on any AI model at runtime
• This example covers only the agent-action gate. DUSK's separate network and packet detection layer stays in the main DUSK repository and is out of scope here

Built by Ritik Sah and Tanvir Farhad.

[TFT444]

Hi @svonava,Quick update load testing is done, the latency table is in the README, and CI is green.

This is ready for review whenever you get a chance.

Thanks again for the support.