tokentrap (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.
Defensive only. Traps fire on connections the attacker initiates — no exploits, no outbound traffic, no human deception. Operators are solely responsible for lawful use in their jurisdiction. See https://github.com/kineticquant/TokenTrap/blob/main/docs/ethics-and-legal.md.
Install
pip install "tokentrap" # published package
# or from this monorepo:
pip install -e "packages/backend-python[test]"
60-second start
tokentrap 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
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
pytest
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file tokentrap-1.0.3.tar.gz.
File metadata
- Download URL: tokentrap-1.0.3.tar.gz
- Upload date:
- Size: 19.4 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
0a971b8ad323422619de2b9d69e10ec17c3e4b6a03abbdcf79ee46b057e82545
|
|
| MD5 |
26d50c023f7a298961dad1a07a13e0bc
|
|
| BLAKE2b-256 |
b7e0e28175f004debad0a25c605194a9df1720c9633060859bef7a14c8fa1461
|
Provenance
The following attestation bundles were made for tokentrap-1.0.3.tar.gz:
Publisher:
publish.yml on kineticquant/TokenTrap
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
tokentrap-1.0.3.tar.gz -
Subject digest:
0a971b8ad323422619de2b9d69e10ec17c3e4b6a03abbdcf79ee46b057e82545 - Sigstore transparency entry: 2582071065
- Sigstore integration time:
-
Permalink:
kineticquant/TokenTrap@79d6b7e44845951f6560d62c43a8538732f608b0 -
Branch / Tag:
refs/tags/v1.0.3 - Owner: https://github.com/kineticquant
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@79d6b7e44845951f6560d62c43a8538732f608b0 -
Trigger Event:
push
-
Statement type:
File details
Details for the file tokentrap-1.0.3-py3-none-any.whl.
File metadata
- Download URL: tokentrap-1.0.3-py3-none-any.whl
- Upload date:
- Size: 17.4 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
1b3e6d853b0d112bf1ecff05c5f30e793e483c97abd1ec4c21f9628a2d638708
|
|
| MD5 |
4f2450713872355b355ec8848c32a894
|
|
| BLAKE2b-256 |
3565cc0ae0c9165e653cd8810a115aa6cf58db5bb535f61b6633b8ce5786584c
|
Provenance
The following attestation bundles were made for tokentrap-1.0.3-py3-none-any.whl:
Publisher:
publish.yml on kineticquant/TokenTrap
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
tokentrap-1.0.3-py3-none-any.whl -
Subject digest:
1b3e6d853b0d112bf1ecff05c5f30e793e483c97abd1ec4c21f9628a2d638708 - Sigstore transparency entry: 2582071075
- Sigstore integration time:
-
Permalink:
kineticquant/TokenTrap@79d6b7e44845951f6560d62c43a8538732f608b0 -
Branch / Tag:
refs/tags/v1.0.3 - Owner: https://github.com/kineticquant
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@79d6b7e44845951f6560d62c43a8538732f608b0 -
Trigger Event:
push
-
Statement type:
