Skip to content
ARCHONLABSblackpot.io
Documentation menu

Operator guide

This guide is for the SOC analyst or security engineer who reads blackpot.io output day to day. It covers dossier anatomy, threat thresholds, canary-trip interpretation, and the operator surface of the console.

1. Anatomy of a dossier

Every captured session opens as a full dossier page in the console. A dossier has five blocks:

  1. Attribution header — the connecting IP, geoip, ASN, anonymizer verdict, and a confidence score.
  2. Session timeline — connection open, each protocol interaction (HTTP paths hit, Redis commands sent, etc.), and connection close, with per-event millisecond timing.
  3. Payload block — any file uploads, POST bodies, or base64-decoded blobs, with C2 indicators highlighted.
  4. Canary interaction — which canary tokens (if any) the attacker touched, when, and where the values ended up (see § Canaries).
  5. Recommended enforcement — the exact firewall rule (Cloudflare, AWS WAF, iptables) the daemon would push to block this IP or CIDR under your current thresholds.

2. Threat thresholds

Every session is scored on a 0–100 scale. The scoring inputs are additive:

  • Anonymizer confidence (VPN, residential proxy, Tor, Apple Private Relay)
  • Number of scanner-attractive paths probed
  • C2 indicators recovered from payloads
  • Canary trips
  • Session length and interaction depth

Tiers derive from score bands:

  • UNKNOWN (0–19) — most crawl noise lands here
  • SCANNER (20–39) — commodity scanner tooling
  • BOTNET (40–59) — repeated same-tooling from many IPs
  • TARGETED (60–79) — human-in-the-loop, purposeful probing
  • APT (80+) — sustained multi-protocol engagement with C2 recovery

Configure the enforcement thresholds in mitigation.Thresholds. The default is: block any session with tier == APT, or score ≥ 80, and expand to a /24 CIDR when 3+ blocked IPs from the same ASN land inside a 10-minute window.

3. Anonymizer scoring

blackpot.io labels an incoming session as anonymized whentwo or more independent layers agree. This dramatically cuts false positives compared to a single-signal check.

  • TCP/UA OS mismatch: SYN-time TCP window/TTL suggests Linux; declared User-Agent claims Chrome on macOS → probable VPN or residential proxy.
  • Timezone drift: browser-declared timezone disagrees with the GeoIP-inferred country by more than 4 hours.
  • WebRTC LAN leak: the injected JS beacon can expose the internal LAN address, and sometimes the real public address, when the visitor’s browser runs our page.
  • Hosting-ASN heuristic: User-Agent is consumer-shaped but source ASN belongs to a known VPN or hosting provider.
  • Apple Private Relay CIDRs: known-published egress ranges are flagged directly.

4. Understanding canary trips

Every session that receives a config-leak or credential-leak response gets a set of session-bound canary tokens embedded in the response body. Each token is one of:

  • Fake AWS access-key / secret pair
  • Fake Postgres connection string
  • Fake env-var API token
  • Web-beacon URL under canary.blackpot.io/_bp/canary

A canary trip fires when one of these values later appears in a different session — meaning the attacker (or someone downstream who received the loot) used the credential elsewhere. The trip writes to breadcrumb_trips and dispatches to any configured webhook.

What a trip means: the earlier session was not just a noise probe. Someone actually harvested the fake creds and either tried to use them or handed them to a downstream actor. High-signal, always worth a manual look.

5. Enforcement actions

When a session crosses the threshold, the mitigation engine pushes a block to every configured perimeter provider:

  • Cloudflare Access Rule at the account level (applies to every zone in the account)
  • AWS WAF IP set
  • Local iptables on the sensor host

Every push is rate-limited (default 2 rps + burst 5 per provider) and audit-logged to enforcement_events. Nothing gets pushed without an entry in that table.

For the first week of a new deployment, we recommend leaving the enforcement engine disabled (unset CF_API_TOKEN) so you can visually confirm the dossiers look right before automating blocks.

Next

Integrate blackpot.io into a SIEM or SOAR via the integrations guide.