🛰️ S H A D O W B R O K E R

Global Threat Intercept — Real-Time Geospatial Intelligence Platform

---

ShadowBroker is a decentralized intelligence platform that aggregates real-time, multi-domain OSINT telemetry from 60+ live intelligence feeds into a single dark-ops map interface. Aircraft, ships, satellites, conflict zones, CCTV networks, GPS jamming, internet-connected devices, police scanners, mesh radio nodes, and breaking geopolitical events — all updating in real time on one screen as well as an obfuscated communications protocol and information exchange infrastructure.

Built with Next.js, MapLibre GL, FastAPI, and Python. 40+ toggleable data layers, including SAR ground-change detection, Telegram OSINT (public channel previews geoparsed onto the map), a server-side recon toolkit (DNS, WHOIS, sanctions, BGP, IP sweep, and more), supply-chain risk overlays, and malware/C2 + CISA KEV cyber threat feeds. Multiple visual modes (DEFAULT / SATELLITE / FLIR / NVG / CRT). Right-click any point on Earth for a country dossier, head-of-state lookup, entity-graph expansion, and the latest Sentinel-2 satellite photo. ShadowBroker has no accounts, product telemetry, or analytics; the dashboard talks to your self-hosted backend. Sensitive recon and Shodan queries never hit third-party APIs from the browser — they are proxied through the backend with SSRF guards and local-operator auth. The OpenClaw / agent command channel exposes the same recon backends plus full telemetry search — no separate API integration required.

Designed for analysts, researchers, radio operators, and anyone who wants to see what the world looks like when every public signal is on the same map.

Why This Exists

A surprising amount of global telemetry is already public — aircraft ADS-B broadcasts, maritime AIS signals, satellite orbital data, earthquake sensors, mesh radio networks, police scanner feeds, environmental monitoring stations, internet infrastructure telemetry, and more. This data is scattered across dozens of tools and APIs. ShadowBroker combines all of it into a single interface.

The project does not introduce new surveillance capabilities — it aggregates and visualizes existing public datasets. It is fully open-source so anyone can audit exactly what data is accessed and how. ShadowBroker does not include product telemetry, analytics, or accounts. Operator-supplied keys stay in your local deployment, but live OSINT features necessarily make outbound requests to the public data providers you enable or query.

Shodan & Recon (security-first)

ShadowBroker includes an optional Shodan connector for operator-supplied API access (SHODAN_API_KEY) and a Recon Toolkit panel for keyless OSINT lookups. Both run server-side only: the browser calls your self-hosted /api/osint/* and /api/tools/shodan/* routes; outbound requests are made by the backend after SSRF validation. Recon requires local-operator access (same trust model as layer toggles and admin routes). Shodan results render as a separate map overlay and remain subject to Shodan’s terms of service.

Not included: embedded live-news YouTube grids or a built-in Gemini AI analyst panel — use the OpenClaw / agent channel for AI-assisted analysis instead.

---

Interesting Use Cases

• Track Air Force One, the private jets of billionaires and dictators, and every military tanker, ISR, and fighter broadcasting ADS-B. Air Force One and all of the accompanying Presidential/Vice Presidential planes are highlighted and monitored from the moment they leave the ground.
• Connect an AI agent as a co-analyst through ShadowBroker's HMAC-signed agentic command channel — supports OpenClaw and any other agent that speaks the protocol (Claude, GPT, LangChain, custom). The agent gets full read/write access to all 40+ data layers, compact cross-layer search (search_telemetry, search_news), the full recon toolkit (osint_lookup for IP/DNS/WHOIS/sanctions/CVE/etc.), entity-graph expansion, pin placement, map control, SAR ground-change, mesh networking, and alert delivery. It sees everything the operator sees and can take actions on the map in real time.
• Communicate on the InfoNet testnet — The first decentralized intelligence mesh built into an OSINT tool. Obfuscated messaging with gate personas, Dead Drop peer-to-peer exchange, and a built-in terminal CLI. No accounts, no signup. Privacy is not guaranteed yet — this is an experimental testnet — but the protocol is live and being hardened.
• Right-click anywhere on Earth for a country dossier (head of state, population, languages), Wikipedia summary, and the latest Sentinel-2 satellite photo at 10m resolution
• Click a KiwiSDR node and tune into live shortwave radio directly in the dashboard. Click a police scanner feed and eavesdrop in one click.
• Watch 11,000+ CCTV cameras across 6 countries — London, NYC, California, Spain, Singapore, and more — streaming live on the map
• See GPS jamming zones in real time — derived from NAC-P degradation analysis of aircraft transponder data
• Monitor satellites overhead color-coded by mission type — military recon, SIGINT, SAR, early warning, space stations — with SatNOGS and TinyGS ground station networks
• Track naval traffic including 25,000+ AIS vessels, fishing activity via Global Fishing Watch, and billionaire superyachts
• Follow earthquakes, volcanic eruptions, active wildfires (NASA FIRMS), severe weather alerts, and air quality readings worldwide
• Map military bases, 35,000+ power plants, 2,000+ data centers, and internet outage regions — cross-referenced automatically
• Connect to Meshtastic mesh radio nodes and APRS amateur radio networks — visible on the map and integrated into Mesh Chat
• Detect ground changes through cloud cover with SAR (Synthetic Aperture Radar) — mm-scale ground deformation, flood extent, vegetation disturbance, and damage assessments from NASA OPERA and Copernicus EGMS. Define your own watch areas and get anomaly alerts. Free with a NASA Earthdata account.
• Switch visual modes — DEFAULT, SATELLITE, FLIR (thermal), NVG (night vision), CRT (retro terminal) — via the STYLE button
• Track trains across the US (Amtrak) and Europe (DigiTraffic) in real time
• Estimate where US aircraft carriers are using automated GDELT news scraping — no other open tool does this
• Search internet-connected devices worldwide via Shodan — cameras, SCADA systems, databases — plotted as a live overlay on the map
• Run a full recon toolkit from the left sidebar — IP geolocation, DNS, RDAP/WHOIS, certificate transparency, BGP/ASN, OFAC sanctions search, CVE lookup, Tor/OTX threat checks, and subnet sweeps (InternetDB proxied server-side)
• Expand an entity graph when you select an aircraft, vessel, company, or IP — Wikidata + OFAC + live store cross-links rendered in the Entity Graph panel
• Monitor supply-chain risk — Tier 1/2 semiconductor and battery fabs scored against nearby earthquakes, wildfires, and conflict events (SCM panel)
• Toggle malware C2 hotspots — abuse.ch Feodo Tracker + URLhaus feeds mapped by country (opt-in layer)
• Monitor Telegram OSINT channels — public t.me/s war/conflict feeds (OSINTdefender, NEXTA, etc.) scraped hourly, risk-scored, geoparsed to metro anchors, and plotted as clickable map pins with inline media
• Overlay global submarine cables — static TeleGeography-derived cable routes (opt-in layer)

---

⚡ Quick Start (Docker)

From GitHub (default — uses GHCR images)

git clone https://github.com/bigbodycobain/Shadowbroker.git
cd Shadowbroker
docker compose pull
docker compose up -d

From GitLab (uses GitLab Container Registry)

git clone https://gitlab.com/bigbodycobain/Shadowbroker.git
cd Shadowbroker
docker compose -f docker-compose.yml -f docker-compose.gitlab.yml pull
docker compose -f docker-compose.yml -f docker-compose.gitlab.yml up -d

Both paths produce identical containers — same source, same CI, same images byte-for-byte. Pick whichever ecosystem you already use.

Open http://localhost:3000 to view the dashboard! (Requires Docker Desktop or Docker Engine)

Join the private InfoNet swarm (sb-testnet-0): Click NODE in the dashboard, or run ./meshnode.sh for a headless participant. No manual peer list — fleet defaults discover the seed and pull the signed manifest automatically. Set MESH_INFONET_FLEET_JOIN=false in .env for a private solo node.

Backend port already in use? The browser only needs port 3000, but the backend API is also published on host port 8000 for local diagnostics. If another app already uses 8000, create or edit .env next to docker-compose.yml and set BACKEND_PORT=8001, then run docker compose up -d.

Blank news/UAP/bases/wastewater after several minutes? Check for backend OOM restarts with docker events --since 30m --filter container=shadowbroker-backend --filter event=oom. The default compose file gives the backend 4GB; if your host has less memory, reduce enabled feeds or set BACKEND_MEMORY_LIMIT=3G and expect slower/heavier layers to warm more gradually.

Podman users: Podman works, but podman compose is a wrapper and still needs a Compose provider installed. On Windows/WSL, if you see looking up compose provider failed, install podman-compose and run podman-compose pull followed by podman-compose up -d from inside the cloned Shadowbroker folder. On Linux/macOS/WSL shells you can also use ./compose.sh --engine podman pull and ./compose.sh --engine podman up -d.

---

🔄 How to Update

ShadowBroker uses pre-built Docker images — no local building required. Updating takes seconds:

docker compose pull
docker compose up -d

That's it. pull grabs the latest images, up -d restarts the containers.

Coming from an older version? Pull the latest repo code first, then pull images:

bash git pull origin main docker compose down docker compose pull docker compose up -d

Podman users should run the equivalent provider command, for example podman-compose pull and podman-compose up -d, or use ./compose.sh --engine podman pull and ./compose.sh --engine podman up -d from a bash-compatible shell.

Update Integrity

Docker updates are delivered through signed container registries. The legacy ZIP self-updater verifies release archives through this chain, in order:

• MESH_UPDATE_SHA256 when an operator pins a digest explicitly.
• backend/data/release_digests.json for bundled release pins.
• The release SHA256SUMS.txt asset on GitHub when a bundled pin is not present.

Release maintainers should run python backend/scripts/release_helper.py hash <ShadowBroker_vX.Y.Z.zip> before publishing, then publish SHA256SUMS.txt and update backend/data/release_digests.json when shipping a ZIP updater target. The updater keeps the operator override path intact instead of failing closed on missing bundled digests, so existing installs do not get stranded by a release-process mistake.

CSP Hardening

The production frontend ships with a hydration-compatible CSP and a strict nonce-only CSP in Content-Security-Policy-Report-Only. Set SHADOWBROKER_STRICT_CSP=1 only after verifying the exact build hydrates correctly in your deployment. Runtime Google Fonts are not required; the bundled Next font pipeline serves the dashboard font from the app build.

⚠️ Stuck on the old version?

If git pull fails or docker compose up keeps building from source instead of pulling images, your clone predates a March 2026 repository migration that rewrote commit history. A normal git pull cannot fix this. Run:

# Back up any local config you want to keep (.env, etc.)
cd ..
rm -rf Shadowbroker
git clone https://github.com/bigbodycobain/Shadowbroker.git
cd Shadowbroker
docker compose pull
docker compose up -d

How to tell if you're affected: If docker compose up shows RUN apt-get, RUN npm ci, or RUN pip install — it's building from source instead of pulling pre-built images. You need a fresh clone.

Other troubleshooting:

• Force re-pull: docker compose pull --no-cache
• Prune old images: docker image prune -f
• Check logs: docker compose logs -f backend

---

☸️ Kubernetes / Helm (Advanced)

For high-availability deployments or home-lab clusters, ShadowBroker supports deployment via Helm. This chart is based on the bjw-s-labs template and provides a robust, modular setup for both the backend and frontend.

1. Add the Repository:

helm repo add bjw-s-labs https://bjw-s-labs.github.io/helm-charts/
helm repo update

2. Install the Chart:

# Default — pulls images from GHCR
helm install shadowbroker ./helm/chart --create-namespace --namespace shadowbroker

# GitLab registry variant
helm install shadowbroker ./helm/chart --create-namespace --namespace shadowbroker \
  -f helm/chart/values.yaml \
  -f helm/chart/values-gitlab.yaml

3. Key Features: * Modular Architecture: Individually scale the intelligence backend and the HUD frontend. * Security Context: Runs with restricted UIDs (1001) for container hardening. * Ingress Ready: Compatible with Traefik, Cert-Manager, and Gateway API for secure, external access to your intelligence node.

Special thanks to @chr0n1x for contributing the initial Kubernetes architecture.

---

Experimental Testnet — No Privacy Guarantee

Shad