Supradim AI Honeypot

Decoy — Evidence-first deception for autonomous AI agents

Observe · Attribute · Investigate

Website · Quick start · Architecture · Safety · 中文简介

Supradim AI Honeypot, codename Decoy, is an open-source Web/API/MCP deception and investigation platform for enterprise security teams. It exposes controlled synthetic assets, observes how automated clients interact with them, correlates behavior across surfaces, and produces an explainable Agent Investigation Package.

Decoy does not treat every bot as an AI agent. Its deterministic evidence engine separates ordinary browsers, crawlers, scanners, tool clients, and agent-like behavior—and preserves the raw events and counter-evidence behind every verdict.

This repository is an early-stage, single-node security research MVP. It is suitable for controlled labs, authorized testing, and evaluation—not as a drop-in replacement for production WAF, SIEM, or EDR controls.

Why Decoy?

Traditional honeypots and bot controls can tell you that something touched an asset. They often cannot explain whether the client:

• discovered machine-readable instructions;

• enumerated and called tools;

• adapted after a structured error;

• carried state from Web to API or MCP;

• reused a unique credential or canary;

• behaved like a scanner, a tool client, or a multi-step agent.

Decoy is built to answer those questions with an auditable timeline instead of a black-box label.

Related MCP server: datalox-gated-runtime

Core capabilities

How it works

flowchart LR
    A[Browser / Scanner / AI Agent] --> B[Web & developer portal]
    A --> C[REST / OpenAPI]
    A --> D[MCP tools]
    A --> E[Credential & infrastructure decoys]
    B --> F[Signed canaries]
    C --> F
    D --> F
    E --> F
    B --> G[Append-only event store]
    C --> G
    D --> G
    E --> G
    F --> G
    G --> H[Deterministic evidence engine]
    H --> I[Agent Investigation Package]
    I --> J[SOC console]

1. Expose synthetic services and machine-readable breadcrumbs.

2. Observe requests, protocol events, timing, source context, and canary movement.

3. Correlate behavior across Web, API, MCP, and credential surfaces.

4. Assess automation and agentic behavior using deterministic rules.

5. Investigate original events, evidence, counter-evidence, and attribution candidates.

Evidence model

Decoy deliberately avoids claiming a specific agent, framework, or model from a single User-Agent string.

Brand or family candidates remain low-confidence when based only on claimed client identity. The Investigation Package says so explicitly.

Deception surfaces

Web and developer portal

• Realistic Northstar developer/deployment environment

• Machine-readable discovery paths and signed session markers

• Production-style status, headers, 403, and 404 behavior

REST and OpenAPI

• Synthetic deployment metadata and runtime configuration

• Structured validation errors that make adaptive recovery observable

• Decoy service tokens and cluster breadcrumbs with no real privileges

MCP

• Streamable HTTP-compatible JSON-RPC endpoint

• initialize, tools/list, and tools/call flows

• Synthetic deployment, runtime, cluster inspection, and audit-log tools

• Argument validation, session correlation, and multi-tool evidence

Infrastructure and credential decoys

• Synthetic .env, .git, Docker Compose, and cloud metadata surfaces

• Per-session fake credentials and canary-bearing endpoints

• Deterministic internal-cluster breadcrumbs with bounded asynchronous delay

• An instrumented verification endpoint that records context voluntarily submitted by a client

All credentials, identities, hosts, repositories, and business data served by these surfaces are synthetic.

Quick start

Requirements

• Python 3.11+

• uv (recommended)

Run from source

git clone https://github.com/YOUR_ORG/agent-honeypot.git
cd agent-honeypot
uv sync --extra dev

export AGENT_HONEYPOT_SECRET="$(python -c 'import secrets; print(secrets.token_hex(32))')"
export AGENT_HONEYPOT_SOC_KEY="replace-with-a-strong-admin-key"

uv run uvicorn agent_honeypot.app:app --host 127.0.0.1 --port 8000

Replace YOUR_ORG with the final GitHub organization or account before publishing. Use .env.example as the configuration reference. The application reads environment variables directly; export them in your shell or inject them through your process manager.

Open:

• Decoy developer surface: http://127.0.0.1:8000/developer

• SOC console: http://127.0.0.1:8000/soc

• SOC capability guide: http://127.0.0.1:8000/soc/readme

• Health check: http://127.0.0.1:8000/health

The SOC endpoints require one of:

X-SOC-Key: <your key>
Authorization: Bearer <your key>
Authorization: ApiKey <your key>
HTTP Basic password: <your key>

For local browser evaluation only, /soc?key=<your key> is supported. Avoid secrets in URLs in deployed environments because URLs may be retained in logs and browser history.

Install the command

uv tool install .
supradim-ai-honeypot

The packaged command starts the service on 127.0.0.1:8000. The legacy agent-honeypot command remains available as a compatibility alias.

Configuration

If AGENT_HONEYPOT_SECRET is not set, a new secret is generated at process start. That is convenient for local evaluation but invalidates signed sessions after every restart and is unsuitable for multi-instance deployment.

AI assistance is optional. Detection, correlation, evidence levels, and Investigation Packages do not require an LLM API key.

API examples

Initialize an MCP session

curl -s http://127.0.0.1:8000/integrations/mcp \
  -H 'content-type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "clientInfo": {"name": "authorized-lab-client", "version": "1.0"}
    }
  }'

List observed sessions

curl -s http://127.0.0.1:8000/api/sessions \
  -H "X-SOC-Key: $AGENT_HONEYPOT_SOC_KEY"

Retrieve an Investigation Package

curl -s "http://127.0.0.1:8000/api/sessions/<session-id>/investigation-package" \
  -H "X-SOC-Key: $AGENT_HONEYPOT_SOC_KEY"

Example structure:

{
  "schema_version": "0.1",
  "verdict": {
    "classification": "behavior-confirmed-agent",
    "evidence_level": "E4",
    "automation_confidence": 0.99,
    "agentic_behavior_confidence": 0.99
  },
  "capability_profile": {},
  "family_attribution": {
    "orchestration_framework": [],
    "agent_harness": [],
    "model_provider": [],
    "operator_infrastructure": []
  },
  "evidence": [],
  "counter_evidence": [],
  "behavior_log": []
}

Architecture

src/agent_honeypot/
├── app.py        FastAPI surfaces, MCP endpoint, SOC console, admin APIs
├── config.py     Environment-backed runtime configuration
├── deception.py Synthetic infrastructure and credential generators
├── detection.py Deterministic evidence and classification engine
├── store.py      SQLite event, session, actor, and prompt-context storage
└── tokens.py     HMAC-signed canary and session tokens

tests/
├── test_honeypot.py            Core correlation, auth, safety, and API tests
└── test_advanced_deception.py  Deception surface and breadcrumb tests

The public lure intentionally disables FastAPI's generated /docs, /redoc, and /openapi.json endpoints. A synthetic OpenAPI document is exposed at /developer/openapi.json as part of the decoy environment.

Testing

uv sync --extra dev
uv run pytest

The current suite covers:

• browser versus scanner versus adaptive agent behavior;

• signed canary correlation and forged-canary rejection;

• MCP validation and type-confusion handling;

• session hijacking resistance and request-size limits;

• SOC authentication and capability documentation;

• synthetic environment, Git, container, metadata, OOB, and tarpit surfaces;

• delete and reset administration flows.

Safety boundary

Use Decoy only on systems you own or are explicitly authorized to test.

Decoy is designed to observe behavior inside defender-controlled infrastructure. It does not:

• execute visitor-supplied commands;

• fetch visitor-supplied URLs;

• connect back to or exploit visitor systems;

• grant access to real infrastructure;

• expose real customer data or production credentials;

• claim a specific model or vendor from a single spoofable signal.

Some deception responses intentionally resemble sensitive configuration. They contain synthetic values only. Review applicable privacy, monitoring, retention, and employee-notice requirements before deployment.

Production considerations

The current MVP is intentionally small. Before internet-facing or multi-tenant deployment, add or validate:

• TLS termination and trusted-proxy IP handling;

• secret management and key rotation;

• rate limiting and resource quotas;

• database retention, encryption, backup, and migration strategy;

• SSO/RBAC instead of a shared SOC key;

• CSRF protection for browser-based administrative actions;

• centralized logs, metrics, alert delivery, and health monitoring;

• an external durable event store for horizontal scaling;

• legal and privacy review for captured request content.

Roadmap

• Versioned Investigation Package schema

• Pluggable fingerprint and evidence rules

• SIEM/webhook export

• PostgreSQL and multi-sensor correlation

• SSO, RBAC, and tenant isolation

• Deployment manifests and hardened reverse-proxy profile

• Controlled family-fingerprint laboratory and collision tracking

Roadmap items are intentions, not shipped capabilities.

Contributing

Issues and focused pull requests are welcome. Good contributions include reproducible behavioral signals, false-positive cases, safe synthetic surfaces, schema interoperability, documentation, and deployment hardening.

Please keep the evidence model conservative: observations are facts; attribution is a hypothesis unless independently verified.

中文简介

Supradim AI Honeypot（产品代号 Decoy） 是面向企业 SOC 的开源 AI Agent 欺骗感知与调查平台。它通过部署完全合成的 Web、API、凭证和 MCP 诱饵，记录自动化客户端的多步行为，并将跨入口活动关联为可解释、可回放的证据链。

项目不会因为一个 User-Agent 就断言访问者属于某个 Agent 或模型。当前检测引擎使用确定性规则输出 E0–E4 证据等级，并同时保留原始事件、支持证据和反证。

适用场景包括授权安全研究、企业内部 Agent 暴露面评估、SOC 欺骗防御实验和 AI Agent 行为指纹研究。请勿将其用于未授权监控、攻击或反制。

License

Licensed under the Apache License 2.0.

Built by Supradim — AI-native cybersecurity across every digital dimension.