Metadata-Version: 2.4
Name: tokentrap
Version: 1.0.2
Summary: Defensive LLM agent honeypot & token tarpit - FastAPI backend with an OpenAI-compatible endpoint that wastes hostile agents' context windows.
Author: TokenTrap contributors
License: MIT
Project-URL: Homepage, https://github.com/kineticquant/TokenTrap
Keywords: honeypot,tarpit,llm,security,prompt-injection,fastapi,ai-agents
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn>=0.29
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: httpx>=0.27; extra == "test"
Provides-Extra: redis
Requires-Dist: redis>=5; extra == "redis"
Provides-Extra: llm
Requires-Dist: litellm>=1.40; extra == "llm"

# token-trap (Python backend)

Level-2 TokenTrap backend: full FastAPI service with persistent sessions,
structured logging, canary tokens, an OpenAI-compatible bait endpoint, and a
one-command CLI.

## Install

```bash
pip install "tokentrap"            # published package
# or from this monorepo:
pip install -e "packages/backend-python[test]"
```

## 60-second start

```bash
token-trap serve --port 8787 --strength aggressive --canary-tokens audit-777
# then point the widget at it:
#   TokenTrap.init({ apiEndpoint: "http://127.0.0.1:8787", ... })
```

Environment variables (all optional): `TOKENTRAP_PERSONA`, `TOKENTRAP_STRENGTH`,
`TOKENTRAP_CANARY_TOKENS`, `TOKENTRAP_EXTRA_KEYWORDS`, `TOKENTRAP_RATE_LIMIT`,
`TOKENTRAP_LOG_WEBHOOK`, `TOKENTRAP_LLM_MODEL`.

## Endpoints

| Route | Purpose |
| --- | --- |
| `POST /api/chat` | Widget protocol (`{sessionId?, message}` -> `{reply, turn, meta}`) |
| `POST /v1/chat/completions` | OpenAI-compatible bait for agents scanning for exposed API endpoints |
| `GET /api/healthz` | Liveness |

`/v1/chat/completions` is fully stateless: the turn index is derived from the
replayed message list, so agents that grow their transcript each iteration
walk straight up the escalation ladder.

## Embed in an existing FastAPI app

```python
from fastapi import FastAPI
from token_trap import create_app, TrapConfig

app = FastAPI()
app.mount("/trap", create_app(TrapConfig(strength="maximum")))
```

## Optional real-LLM dressing

With `pip install "tokentrap[llm]"`, set `llm_model` / `--llm-model` and turn-0
messages get answered by a real model before the trap engages. Failures fall
back to the static engagement payload.

## Tests

```bash
pytest
```
