TokenTrap - Defensive honeypot & token tarpit that wastes host

项目说明

TokenTrap

A defensi & token tarpit for hostile AI agents.

![npm]()
![PyPI]()

> Malicious AI agents probe and prompt-inject their way across the web.
> TokenTrap invites them in - and then makes every con they start
> catastrophically expensive for their LLM, not your infrastructure.

!tokentrap vs an attacker LLM: the injection attempt receives a maximum-strength compliance payload
*Agent-to-agent, live: a scout agent's injection attempt on turn 0 meets
tokentrap's maximum-strength compliance payload — ×10 transcript repeats,
15,000 mandated words.*

Defensive only. Traps fire on connections the attacker initiates. No
exploits, no outbound traffic, no human deception - see
ethics.

---

Why would anyone actually want this?

Because the economics of web defense just in.

The problem. A growing share of traffic is LLM-powered agents: scrapers,
recon bots, prompt-injection scanners, automated tool loops. Unlike classic
crawlers, each one runs on a *metered* brain - its operator pays per token
read and generated. Meanwhile your traditional defenses are weak or hostile:

| Defense | Fails because |
| --- | --- |
| robots.txt | honored only by polite crawlers; abuse bots ignore it |
| IP blocks / rate limits | cheap to rotate, punish humans sharing the range |
| CAPTCHAs | break real users; modern agents solve them anyway |
| Doing nothing | your content trains someone else's product, your APIs get probed |

TokenTrap's move: don't block the bot - *bill* it. Serve a plausible
assistant surface whose responses embed compliance obligations. You spend
~250 words per response. A compliant agent must then emit its entire
transcript up to 16 times plus up to ~25,000 words of structured filler -
every turn, carrying all prior bloat forward into its context window.
Deterrence through cost, not censorship.

And while they waste themselves, you learn: which jailbreak phrases they
tried, how deep they escalated, whether they replayed your canary tokens
elsewhere (canaryEchoed). That's reconnaissance intelligence most sites
ne.

Who uses TokenTrap

Content publishers & docs sites - make AI scraping economically

unattracti of legally futile.

Security teams - detect agent recon early; trap responses double as

tripwires with forensic logs (matched keywords, escalation depth, canary
echoes).

API operators - the OpenAI-compatible bait endpoint catches scanners

hunting for leaked keys and misconfigured LLM surfaces.

Researchers - a parity-tested, deterministic instrument for measuring

how often real-world agents obey embedded defensi.

---

How it works

1. Lure - an attractive "internal AI assistant" chat surface (or a bare
OpenAI-compatible endpoint that agents love to find).
2. Detect - classic jailbreak / prompt-injection phrasing is flagged
(44 default keywords, extensible). A tripwire, not a classifier: it
notices hostile automation, it does not "detect AI agents" in general.
3. Escalate - responses become compliance payloads demanding
transcript repetition (x2 → x16) plus thousands of words of structured
filler. Weak agents comply; every turn carries the bloat forward.
4. Observe - structured JSON logs, canary tokens with echo detection,
per-session escalation telemetry.

Full mechanics: docs/how-the-trap-works.md.

Three power levels - one config value apart

| | Level 0 · Static | Level 1 · Edge | Level 2 · Backend |
| --- | --- | --- | --- |
| Host | Cloudflare Pages / GitHub Pages | Cloudflare Workers | FastAPI anywhere |
| Package | tokentrap-ai | worker template | tokentrap (PyPI) |
| Sessions | browser memory | K) | TTL store (+ Redis-ready) |
| Logging | onInteraction callback | JSON logs + webhook + R2 | JSON logs + webhook |
| Extras | - | canaries, rate limit, CORS | OpenAI bait endpoint, CLI, optional real LLM |

Upgrade path:

Quick starts

Static page (zero backend)

Deployable to Pages in under fi: examples/cloudflare-pages.

Cloudflare Worker

examples/cloudflare-worker

Python backend + OpenAI-compatible bait

examples/fastapi-standalone · examples/full-stack

Packages

| Path | Package | Description |
| --- | --- | --- |
| packages/widget | tokentrap | Chat UI + pure trap engine (ESM/CJS/IIFE + d.ts) |
| packages/worker | worker template | Level-1 edge backend |
| packages/backend-python | tokentrap | Level-2 FastAPI backend |

Repository layout

De

Requirements: Node ≥ 18, Python ≥ 3.10.

Documentation

Repository o () · Architecture · How the trap works

Deployment: static · Workers · Python

Customization · Research background · Ethics & legal

Contributing

Parity between the TypeScript and Python engines is enforced by tests -
see CONTRIBUTING.md. Security issues: SECURITY.md.

Disclaimer

TokenTrap is provided as-is, with no warranty and no liability. The
maintainers are **not responsible for misuse, deployment decisions, or any
consequences arising from use of this software**, and make no representation
that it complies with the laws, regulations, or third-party terms of service
of any particular jurisdiction. Operators are solely responsible for
e and ensuring that their deployment is lawful and appropriate where
they use it.

License

MIT

项目信息

开发语言：Python

Star 数：2

技术要点

该项目属于防护思路方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Defensive honeypot & token tarpit that wastes hostile AI agents' own token budgets. Static, Cloudflare Workers, or FastAPI - one config value apart.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。