<a name="top"></a>

<div align="center"> <img src="https://capsule-render.vercel.app/api?type=rect&color=0:6b46c1,100:2b6cb0&height=120&section=header&text=ADSBWATCH&fontSize=48&fontColor=ffffff&fontAlignY=58" width="100%" alt="ADSBWATCH"/>

ADSBWATCH

Analyze an ADS-B feed/CSV for anomalies: callsign spoofing, squawk 7500/7600/7700, and unusual loiter patterns.

<img src="https://readme-typing-svg.demolab.com?font=Fira+Code&size=18&duration=3500&pause=1000&color=6B46C1&center=true&vCenter=true&width=720&lines=Analyze+an+ADSB+feedCSV+for+anomalies+callsign+spoofing+squa;Self-hostable+%C2%B7+MCP-native+%C2%B7+CI-ready+%C2%B7+polyglot" width="720"/>

Part of the Cognis Neural Suite.

</div>

pip install cognis-adsbwatch
adsbwatch scan .            # → prioritized findings in seconds

<!-- cognis:example:start -->

Watch the walkthrough

A full narrated tour — setup, the tool in action, and every demo scenario:

▶ Watch the walkthrough (MP4)

🔎 Example output

Real, reproducible output from the tool — runs offline:

$ adsbwatch-emit --version
adsbwatch 0.3.0

$ adsbwatch-emit --help
usage: adsbwatch [-h] [--version] {scan,assess,feeds} ...

Defensive OSINT analysis of an ADS-B feed for anomalies (emergency squawks,
callsign spoofing, loiter patterns).

positional arguments:
  {scan,assess,feeds}
    scan               Scan an ADS-B CSV feed for anomalies.
    assess             Decision support: triage anomalies, correlate with
                       local sensor logs, and recommend operator actions
                       (advisory; human-in-the-loop, no effectors).
    feeds              Live ADS-B data-feed layer (OpenSky): list | update |
                       get <id> [--offline].

options:
  -h, --help           show this help message and exit
  --version            show program's version number and exit

Blocks above are real adsbwatch output — reproduce them from a clone.

Sample result format (illustrative values — run on your own data for real findings):

{
"adsb": {
"type": "aircraft",
"icao24": "A12345",
"callsign": "XYZ456",
"latitude": 37.7749,
"longitude": -122.4194,
"altitude": 3000,
"velocity": 200,
"heading": 270
},
"findings": [
{
"id": "1",
"type": "aircraft-track",
"start_time": "2023-02-15T14:30:00Z",
"end_time": "2023-02-15T14:35:00Z"
}
]
}

<!-- cognis:example:end -->

Usage — step by step

adsbwatch runs defensive OSINT analysis of an ADS-B feed (CSV) for anomalies — emergency squawks, callsign spoofing, and loiter patterns.

1. Install (Python 3.10+):

   pip install -e .            # or: pipx install adsbwatch
   

2. Scan an ADS-B CSV feed (human-readable table):

   adsbwatch scan feed.csv
   

3. Tune loiter detection (track radius, cumulative turn, min points):

   adsbwatch scan feed.csv --loiter-radius 5 --loiter-turn 270 --loiter-points 6
   

4. Read the output as JSON for piping / alerting:

   adsbwatch scan feed.csv --format json | jq '.anomalies'
   

   Or export the picture straight to maps and threat-intel platforms — native, zero-dep:

   adsbwatch scan feed.csv --format geojson > anomalies.geojson   # Leaflet/Mapbox/QGIS/kepler
   adsbwatch scan feed.csv --format stix    > anomalies.json       # STIX 2.1 bundle for OpenCTI/TIPs
   

   GeoJSON plots each geolocated anomaly (emergency squawks, spoofed callsigns, loiter orbits); STIX pairs a location + observed-data + note per anomaly in a report. (A live Finding stream to MISP/Splunk/Slack is in adsbwatch.connect.)
5. Drive alerting in CI/cron — exit 2 when anomalies are found, 0 when clean, 1 on parse error:

   - run: pip install -e . && adsbwatch scan feed.csv   # exit 2 => trigger alert
   

Live data feed — OpenSky, edge & air-gap ready

adsbwatch ships a real, stdlib-only data-feed layer that ingests live ADS-B state vectors from the OpenSky Network, caches them to disk, and re-serves that snapshot offline — so the tool keeps hunting anomalies on disconnected / edge / air-gapped gear. The cached states are converted straight into the same Observation rows the anomaly engine already scans, so a live emergency squawk (7500/7600/7700), callsign spoof, or loiter orbit surfaces exactly as it would from a CSV.

Only the single ADS-B-relevant feed is wired in — endpoints come from the bundled catalog (adsbwatch/data_feeds_2026.json); nothing is invented:

| feed id | source | URL | |------------------|------------------------------------------|-----| | opensky-states | OpenSky Network — live aircraft states | https://opensky-network.org/api/states/all |

adsbwatch feeds list                         # wired feed(s) + cache freshness
adsbwatch feeds update opensky-states        # fetch + cache the live snapshot
adsbwatch feeds get opensky-states           # ingest -> scan-ready summary
adsbwatch feeds get opensky-states --offline # serve cache only (no network)

adsbwatch scan --live                         # ingest live airspace + full scan
adsbwatch scan --live --region 24,-125,49,-66 # clip to a bounding box (CONUS)
adsbwatch scan --live --offline               # scan the last cached snapshot

Air-gap / sneakernet workflow

# On a connected box: build a portable snapshot of the feed cache
COGNIS_FEEDS_CACHE=./snap adsbwatch feeds update opensky-states
python -m adsbwatch.datafeeds snapshot-export feeds.tar.gz

# Carry feeds.tar.gz across the air gap, then on the isolated box:
python -m adsbwatch.datafeeds snapshot-import feeds.tar.gz
adsbwatch scan --live --offline               # full anomaly scan, zero network

The cache location is COGNIS_FEEDS_CACHE (default ~/.cache/cognis-feeds). --offline never touches the network. OpenSky is keyless (anonymous access is rate-limited; an account raises the limits). See demos/04-live-feed/.

Contents

• Why adsbwatch? · Features · Quick start · Example · Architecture · AI stack · How it compares · Integrations · Install anywhere · Related · Contributing

<a name="why"></a>

Why adsbwatch?

Analyze an ADS-B feed/CSV for anomalies: callsign spoofing, squawk 7500/7600/7700, and unusual loiter patterns. — without standing up heavyweight infrastructure.

adsbwatch is single-purpose, scriptable, and self-hostable: point it at a target, get prioritized results in the format your workflow already speaks (table · JSON · SARIF), gate CI on it, and let agents drive it over MCP.

<div align="right"><a href="#top">↑ back to top</a></div>

<a name="features"></a>

Features

• ✅ ADS-B anomaly detection — emergency squawks (7500/7600/7700), callsign spoofing, loiter
• ✅ Decision support (human-in-the-loop) — assess: triage, multi-sensor correlation, advisory recommendations
• ✅ Sensor correlation — fuse alerts with local camera / RF / access-control logs on a timeline (evidence + pattern-of-life)
• ✅ Data sovereignty — fully local/offline, pure standard library; nothing leaves the box
• ✅ Runs on Linux/macOS/Windows · Docker · devcontainer
• ✅ Ports in Python, JavaScript, Go, and Rust (ports/)

Decision support — the layer above the alert (human stays in command)

The sensor layer tells you something happened. adsbwatch assess is the decision architecture above it — it triages anomalies by priority, correlates them with your other local sensors (cameras, RF logs, access control) to build an evidence picture, and recommends courses of action to an operator (log, notify, escalate to the responsible authority, cross-cue a camera, request ID, preserve evidence).

adsbwatch assess feed.csv --sensors local_sensors.csv      # triage + correlate + recommend
adsbwatch assess feed.csv --format json                    # for your SOC / C2 dashboard

Boundary (by design and enforced by tests): this is decision support, not decision authority. It produces recommendations and notifications for a person — it has no interface to weapons, jammers, or any effector, and never acts autonomously. Every recommended action requires human authorization. Use of force stays with a human.

<div align="right"><a href="#top">↑ back to top</a></div>

<a name="quick-start"></a>

Quick start

pip install cognis-adsbwatch
adsbwatch --version
adsbwatch scan .                       # scan current project
adsbwatch scan . --format json         # machine-readable
adsbwatch scan . --fail-on high        # CI gate (non-zero exit)

<div align="right"><a href="#top">↑ back to top</a></div>

<a name="example"></a>

Example

$ adsbwatch scan .
  [HIGH    ] ADS-001  example finding             (./src/app.py)
  [MEDIUM  ] ADS-002  another signal              (./config.yaml)

  2 findings · risk score 5 · 38ms

<div align="right"><a href="#top">↑ back to top</a></div>

<a name="architecture"></a>

Architecture

flowchart LR
  csv[ADS-B CSV] --> P[adsbwatch<br/>analyze]
  osk[OpenSky live/cache] --> P
  P --> emerg[emergency squawk]
  P --> spoof[callsign spoof]
  P --> loiter[loiter]
  emerg --> R[(AnalysisResult)]
  spoof --> R
  loiter --> R
  R --> OUT[table / JSON]
  R --> intel[GeoJSON / STIX]
  R --> decide[decision support<br/>human-in-the-loop]

See docs/ARCHITECTURE.md for the full design.

<div align="right"><a href="#top">↑ back to top</a></div>

<a name="demos"></a>

Demos

Five runnable, offline scenarios in demos/ — each uses the real adsbwatch API over a bundled sample feed (no fabricated output). They double as smoke tests (tests/test_demos.py).

python demos/run_all.py             # all five, end to end (exits 0)
python demos/01_anomaly_scan.py     # or just one

| # | Scenario | Audience | What it shows | |---|----------|----------|---------------| | 1 | 01_anomaly_scan.py | OSINT / aviation analysts | Full scan, findings ranked critical → low | | 2 | 02_callsign_spoofing.py | Journalists / OSINT | One ICAO, two callsigns → citable JSON | | 3 | 03_force_protection.py | Defense / force-protection | Triage + sensor correlation, advisory only (human-in-the-loop) | | 4 | 04_intel_export.py | Researchers / SOC | GeoJSON for maps, STIX 2.1 for TIPs | | 5 | 05_live_feed_offline.py | Edge / air-gap operators | Live OpenSky ingest served from an offline cache |

See docs/DEMOS.md for details and docs/ARCHITECTURE.md for the design.

<div align="right"><a href="#to