docker-planesnitch: Snitching on Every Aircraft That Dares Fly Near You

Posted on by

I live under a flight path. Military cargo planes, government jets, police helicopters, the occasional emergency squawk — all of it flying over my head and I had no idea what any of it was. Sure, I could open Flightradar24 and stare at a map all day, but I’m not a retiree with binoculars. I wanted something that watches the sky for me and screams at me when something interesting shows up.

So I built planesnitch. A Docker container that polls public ADS-B APIs, checks aircraft against your watchlists, and fires alerts to Telegram or webhooks. Military jets, government spooks, emergency squawks, sketchy low-flyers — whatever you tell it to watch for. Multiple locations simultaneously. No SDR hardware, no antenna, no bullshit. Just a config file and an internet connection.

How It Works

Every poll cycle (configurable, default 1 minute), planesnitch fetches aircraft data from up to 4 public ADS-B APIs in parallel:

It deduplicates by ICAO hex code, keeping the entry with the most data fields. Some sources return enriched data — aircraft type, owner/operator, registration, year built — while others just give you raw ADS-B fields. Planesnitch automatically keeps the richest entry for each aircraft.

Then it runs every aircraft through your watchlists and alert rules. Match found? Format a message and fire it at your Telegram bot or webhook endpoint. Per-alert per-aircraft cooldowns prevent it from spamming you about the same C-17 doing laps for 3 hours.

If you’re running your own ADS-B receiver with ultrafeeder, you can point planesnitch at that too — same config, just add a local source URL.

Setup

# Grab the config and edit it
curl -sL \
  https://raw.githubusercontent.com/psyb0t/docker-planesnitch/main/config.yaml.example \
  -o config.yaml
# Optional: download military/gov/police watchlists
mkdir -p csv
BASE=https://raw.githubusercontent.com/sdr-enthusiasts/plane-alert-db/main
curl -sLo csv/plane-alert-mil.csv $BASE/plane-alert-mil.csv
curl -sLo csv/plane-alert-gov.csv $BASE/plane-alert-gov.csv
curl -sLo csv/plane-alert-pol.csv $BASE/plane-alert-pol.csv
# Run it
docker run \
  -v ./config.yaml:/app/config.yaml:ro \
  -v ./csv:/csv:ro \
  psyb0t/planesnitch

That’s it. Edit the config with your coordinates, Telegram bot token, and you’re snitching.

The Config

One YAML file controls everything. Define where you are, what to watch for, when to alert, and where to send it.

Locations

Monitor as many places as you want. Your house, your office, grandma’s house, Area 51 — each with its own search radius.

locations:
  home:
    name: "Home"
    lat: 38.8719
    lon: -77.0563
    radius: 150km
  area51:
    name: "Area 51"
    lat: 37.2350
    lon: -115.8111
    radius: 50nm

Unit suffixes work everywhere — km, mi, nm, ft, m. Plain numbers default to km for distances and ft for altitudes.

Watchlists

Five types of watchlists tell planesnitch what to snitch on:

watchlists:
  # Emergency squawk codes
  emergencies:
    type: squawk
    values: ["7500", "7600", "7700", "7400", "7777"]
  # 8,709 military aircraft from community database
  military:
    type: icao_csv
    source: plane-alert-mil.csv
  # Government aircraft
  government:
    type: icao_csv
    source: plane-alert-gov.csv
  # Stalk specific aircraft by ICAO hex
  my_planes:
    type: icao
    values: ["4ca123", "a12345"]
  # Everything within radius
  everything:
    type: all
  # WTF just buzzed my house
  low_flyers:
    type: proximity
    min_altitude: 0ft
    max_altitude: 3000ft

The squawk codes are the panic buttons of aviation — 7700 is general emergency, 7600 is radio failure, 7500 is hijack, 7400 is unmanned aircraft emergency, 7777 is military intercept. The kind of shit you want to know about when it’s happening 6 miles from your house.

The icao_csv type integrates with plane-alert-db — a community-curated database of 15,000+ interesting aircraft maintained by the fine degenerates of the plane spotting community:

  • Military — 8,709 aircraft
  • Government — 1,743 aircraft
  • Police — 932 aircraft
  • Civilian — 4,530 notable aircraft
  • Privacy (PIA) — 94 privacy-conscious operators
  • Everything — 15,914 combined

The proximity watchlist is for catching low-flyers. Set an altitude range and planesnitch alerts you when anything flies within your radius below that ceiling. Useful for answering “what the fuck was that” when something rattles your windows at 2am.

Alerts

Connect watchlists to notification targets. Optionally filter by location — if omitted, all locations are checked. Cooldowns prevent spam:

alerts:
  - name: "Emergency Alert"
    watchlists: [emergencies]
    cooldown: 1m
    notify: [tg_emergencies]
  - name: "Military Spotter"
    watchlists: [military, government]
    cooldown: 5m
    notify: [tg_spotting]
  - name: "Everything at Home"
    locations: [home]
    watchlists: [everything]
    cooldown: 1m
    notify: [tg_main]

Duration strings support s, m, h — so 5m, 1h30m, 90s, or plain seconds all work. Different alerts can go to different Telegram channels — emergencies to one, military spotting to another, low-flyers to a third.

Notifications

Telegram and webhooks. Route different alerts to different destinations:

notifications:
  tg_emergencies:
    type: telegram
    bot_token: "123456:ABC-DEF"
    chat_id: "-100123456789"
  tg_spotting:
    type: telegram
    bot_token: "123456:ABC-DEF"
    chat_id: "-100987654321"
  my_webhook:
    type: webhook
    url: "https://example.com/hook"
    headers:
      Authorization: "Bearer xxx"

What The Alerts Look Like

Telegram alerts are formatted with emojis and all the data you’d want at a glance:

🔔 Emergency Alert
🚨 squawk 7700 (EMERGENCY)
✈️ RYR1234
🛩️ BOEING 737-800 | EI-ABC | 2015
💼 RYANAIR
📍 45.5000, 28.1000 | 3,200 ft
📏 6 nm from home
💨 280 kts
🗺️ https://globe.adsb.fi/?icao=4ca123
🔔 Military Spotter
✈️ TEDDY64
🛩️ BOEING C-17A Globemaster III | 94-0067 | 1994
💼 USAF
🏷️ USAF — USAF
📍 37.9306, -78.7019 | 12,350 ft
📏 99 nm from home
💨 413 kts
📡 squawk 1613
🗺️ https://globe.adsb.fi/?icao=ae07e1

Click the link and you get a real-time map of the aircraft on globe.adsb.fi. The squawk line includes the meaning — planesnitch has a built-in database of squawk code meanings and scopes, so it tells you why that code matters.

Webhook payloads are JSON arrays with full metadata — aircraft details, match reason, watchlist info, CSV metadata if from plane-alert-db, distance from location, and display units. Everything you need to build your own integrations on top of it.

Display Units

Three presets control how altitude, distance, and speed show up in alerts:

display_units: aviation   # ft / nm / kts (default)
display_units: metric     # m / km / km/h
display_units: imperial   # ft / mi / mph

Conversions happen at send time. Internal math is always metric. Use whatever makes sense for your situation — if you’re a pilot, aviation units. If you’re a normal human, metric. If you’re American, imperial.

Hot Reload and Health

Config changes are picked up on the next poll cycle without restarting the container. CSV watchlists auto-refresh every 24 hours. A health endpoint on port 8080 exposes uptime, last poll time, and aircraft count for monitoring and orchestration.

The Bottom Line

A Docker container that watches the sky and rats out every interesting aircraft to your Telegram. Military jets, government planes, emergency squawks, sketchy low-flyers, specific tail numbers — whatever you want. Multiple locations, multiple sources, multiple notification targets, all from one YAML file.

No SDR hardware. No antenna. No dedicated receiver. Just public ADS-B APIs and a paranoid config file.

Go grab it: github.com/psyb0t/docker-planesnitch

Licensed under WTFPL — because snitching on aircraft shouldn’t require a license agreement.