Skip to content
ARCHONLABSblackpot.io
Documentation menu

Integrator guide

This guide walks you through deploying a blackpot.io sensor from scratch. During the alpha the source repository is private; we share access with alpha participants on request at [email protected].

1. Prerequisites

  • A Linux host (Ubuntu 22.04+ or equivalent), 1 vCPU / 512 MB RAM minimum
  • Docker Engine ≥ 24 with the Compose plugin — or Go 1.22+ to build the binary from source
  • A Postgres instance (managed Supabase, self-hosted, or the container ships with the compose file)
  • A Cloudflare account (for tunnel routing) or a router capable of port-forwarding

2. Deploy the daemon

The fastest path is docker-compose. Clone the repository (alpha access required), copy the environment example, fill in your secrets, and start:

git clone https://github.com/MarkJGreen/blackpot.io
cd blackpot.io/deploy/morpheus
cp .env.example .env
# fill in .env — SUPABASE_DB_URL, BP_NODE_ID, ...
docker compose up -d
docker compose logs -f blackpot-daemon

Alternatively, run the raw binary under a systemd user unit — see the deploy/morpheus/ directory for a working example of the loopback-only, no-sudo variant we run on the founder's own alpha.

3. Cloudflare Tunnel setup

blackpot.io ships an HTTP bait listener bound to loopback. To expose it to the public internet without opening a port on your network, use a Cloudflare Tunnel:

cloudflared tunnel login
cloudflared tunnel create blackpot-alpha
cloudflared tunnel route dns blackpot-alpha bait.yourdomain.com

Then add an ingress rule that forwards traffic to the daemon:

ingress:
  - hostname: bait.yourdomain.com
    service: http://127.0.0.1:8080
  - service: http_status:404

Real client IP: Cloudflare adds Cf-Connecting-Ip on every request. The daemon reads it automatically when the immediate peer (loopback here) is in the BP_TRUSTED_PROXIES allowlist. See the operator guide for details on how that flows into anonymizer scoring.

4. Optional: TCP bait exposure

Cloudflare Tunnel does not carry TCP protocols beyond HTTP on the free tier. For Redis, MongoDB, MSSQL, Elasticsearch, Kubernetes API, and Docker API bait, you have three options:

  1. Router port-forward from the well-known TCP port to the daemon's offset port. Fastest, but exposes your public IP.
  2. Cloudflare Spectrum (Enterprise plan) — full TCP passthrough with real-IP preservation. Enterprise-only.
  3. Cloud VM sensor — a $5/mo VM as an isolated sensor host. Best isolation, adds a monthly bill and a host to maintain.

5. Wire the webhooks

Set these environment variables to send canary-trip events (a decoy credential used from somewhere else) to your existing pipeline. All are optional:

  • BP_SLACK_WEBHOOK — Slack incoming webhook URL
  • BP_TEAMS_WEBHOOK — Microsoft Teams incoming webhook URL
  • BP_PAGERDUTY_ROUTING_KEY — Events API v2 routing key
  • BP_GENERIC_WEBHOOK — any HTTPS endpoint; POST is JSON

6. Verify

Once the daemon is running:

  • curl -s http://127.0.0.1:9100/metrics should show a growing blackpot_sessions_total counter as traffic arrives.
  • SELECT COUNT(*) FROM attacker_sessions; in your Postgres should return non-zero after a few sessions have been evicted (default retention: 10 minutes).

Next

Hand off to your SOC team with the operator guide.