Skip to content

README.md

Latest commit

 

History

History
111 lines (87 loc) · 4.22 KB

README.md

File metadata and controls

111 lines (87 loc) · 4.22 KB
Raw

Thumper

Thumper

Plant fake-but-realistic credentials where the Shai-Hulud npm supply-chain worm scans - and get alerted the instant one is read.
The tokens authenticate to nothing. A read is the signal.

Website  ·  Docs  ·  Get started »

PRs welcome License PRs welcome

Thumper is your self-hosted honeytoken platform for trapping attackers inside your environment. You create tripwires, distribute them across your fleet, and each machine plants unique bait. When an attacker-controlled process touches the bait, Thumper immediately triggers an alert.
It's built and maintained by Jesta under the Apache 2.0 license.

See it in action

Thumper dashboard - fleet overview and live alert feed

Enrolled endpoints

🚀 Getting Started

The whole stack comes as one Docker image: 
docker compose up --build        # → http://localhost:8000

That's it. Open the dashboard, create a tripwire, and ship it.

Run it from source instead (dev mode) 
# backend (Python 3.10+)
pip install -e .
uvicorn thumper.main:app --reload --app-dir server     # → http://localhost:8000

# UI (separate terminal) - Vite proxies /api to the backend
cd ui && npm install && npm run dev                     # → http://localhost:5173
Deploy on Kubernetes (Helm)

A Helm chart lives in deploy/helm/thumper. Build and push the image from the Dockerfile first, then:

helm install thumper ./deploy/helm/thumper \
  --set image.repository=ghcr.io/jestasecurity/thumper \
  --set secrets.enrollToken=$(openssl rand -hex 24) \
  --set secrets.installToken=$(openssl rand -hex 24) \
  --set config.baseUrl=https://thumper.example.com

Defaults to SQLite on a PVC (single replica). Set externalDatabase.url for Postgres/MySQL. See values.yaml for all options.

Architecture

Thumper has three components - a server, a dashboard, and an endpoint agent - shipped as a single Docker image. You create tripwires, deploy them to endpoints, and each machine plants unique bait. When a credential is read, the agent sends a signed callback and the server fans out to your configured alert plugins.

Thumper architecture: operator, control plane, endpoint fleet

See docs/architecture.md for the full architecture reference.

Plugins

Alerting and deployment are pluggable - drop a directory under plugins/{alert,deploy}/ with a manifest.yaml and a plugin.py, restart the server, and it shows up in the dashboard with a generated config form.

  • Alert plugins deliver fired-tripwire events to external systems
  • Deploy plugins distribute the install command to machines

See docs/plugins.md for the full guide.

🌱 Contributing

Refer to CONTRIBUTING.md

💫 Contributors

contributors