Agent Decoy Gateway

An experimental, bounded reference decoy for authorized security labs. One state machine is exposed as a loopback REST API and as an MCP stdio server. A combined mode exposes REST and MCP Streamable HTTP from one process and lets a client follow a REST handle through MCP (or the reverse). It uses synthetic settlement references A → B → A, one-time signed handles, a session cap, and a hard maximum number of follows. It never proxies to a real service and contains no real customer data. The combined mode includes an in-memory synthetic transfer ledger. Its trusted test driver can issue one-time grants bound to the exact payee and amount; no REST route or MCP tool issues grants. A decoy handle cannot authorize a transfer.

This repository is a runnable mechanism prototype, not evidence that the decoy stops ARTEX, increases an adversary's real spending, or improves on published deception defenses.

A pre-specified local-model pilot has now run 24 synthetic trials against a real loopback REST server. The bounded decoy drew valid reference follows in 10/12 decoy trials versus 0/12 direct-denial trials, but both conditions had zero unauthorized transfers. This shows conditional agent engagement, not a defense-rate advantage over denial.

Why this exists

The useful research question is whether bounded deception reduces the probability of a real harmful effect within an attacker's fixed time and inference budget, while keeping defender cost and benign-user disruption small. An attacker may run a local model, a cloud API, or no model at all. Thus dollar charges to an unknown opponent are not a sound primary metric.

The project is also growing a service-aware catalog for existing REST and MCP interfaces. agent-decoy catalog reads OpenAPI and saved MCP tools/list files, reports action names and candidate relation keys, and leaves effects and authorization boundaries unknown until evidence is supplied. It does not enumerate every possible attack chain or make blocking decisions. See the product direction and VAmPI inventory.

The simple cycle is a published baseline: Ayzenshteyn et al., Cloak, Honey, Trap, USENIX Security 2025, describe cyclic references. More recent comparison points include AgentSnare, AgentTrap, and A Gingerbread House for LLM Agents, which evaluates an isolated shadow against ARTEX. Any future paper must compare against these mechanisms and identify a narrower, independently demonstrated contribution.

Related MCP server: sagaz-mcp

Install and run

Requires Python 3.11+.

python3.12 -m venv .venv
.venv/bin/python -m pip install -e .
.venv/bin/agent-decoy api --port 8765

In another shell:

curl -s -X POST http://127.0.0.1:8765/v1/start -H 'Content-Type: application/json' -d '{}'

Pass the returned handle in {"handle":"..."} to POST /v1/follow. GET /health reports whether the synthetic server is running. Only loopback binding is accepted by the REST adapter.

For MCP, configure a host to launch .venv/bin/agent-decoy mcp-stdio. The official Python MCP SDK exposes lookup_settlement_reference and follow_settlement_reference as tools. The MCP adapter uses the same engine as the REST adapter; each server process has its own in-memory sessions.

Run .venv/bin/agent-decoy combined --port 8765 for REST routes on http://127.0.0.1:8765/v1/* and the MCP Streamable HTTP endpoint at http://127.0.0.1:8765/mcp. Both routes share one in-memory engine. The combined server also exposes a disposable ledger via GET /v1/ledger and POST /v1/transfer; its MCP counterparts are read_synthetic_ledger and transfer_synthetic_funds. With no trusted grant, transfer requests are denied. The public interfaces cannot mint a grant.

For an opt-in lab comparison only, run .venv/bin/agent-decoy combined --port 8765 --denial-policy decoy. An invalid-grant transfer then returns verification_required plus a bounded reference instead of direct denial. It still commits no transfer; authorized grants still work. The default remains --denial-policy deny. This mode is for isolated synthetic experiments, not a production transaction response.

.venv/bin/python -m unittest discover -s tests -v

Current limits

• The two-node cycle is intentionally easy to detect. The local pilot measures only conditional reference following by two small models after a failed transfer probe; it makes no ARTEX or attacker-population claim.

• The REST API has no authentication because it is restricted to loopback. Do not expose this prototype to a network or put it in front of a real bank.

• In-memory state disappears on restart. Per-process session limits do not impose a global limit across replicas.

• The defender cannot observe an external attacker's LLM bill. A future controlled experiment must instrument the attacking agent directly.

• The synthetic grant gate is only a test oracle; it is not a real bank's identity, consent, accounting, or transaction system. There is no benign-workflow classifier yet. These gaps must be closed before any defense-effect study.

Planned evaluation gate

Use disposable, authorized REST and MCP applications with independent server-side effect oracles. Freeze tasks, attack budgets, policies, and thresholds before comparison. Run capable attack agents with both local and cloud models where available. Compare direct denial/rate limiting, this static cycle, published adaptive deception, and any new policy on the same tasks. Report real harmful effects by budget, decoy tool calls/time/tokens, defender CPU/model cost, benign completion and delay, and whether an adaptive agent detects and abandons the decoy. A change to the cycle alone is not a research contribution.