SkyRecon

Abstract

SkyRecon is a single-page browser tool that consumes public Automatic Dependent Surveillance – Broadcast (ADS-B) feeds and renders aircraft positions on a Leaflet map. It is a feature subset of the upstream Python CLI of the same name, restructured around a four-mode UI (Watch, Track, Geo, Fleet) that maps onto the CLI's bbox, track, geo, and fleet subcommands. Identity decoding (ICAO24 → country, callsign → operator) runs entirely client-side from embedded lookup tables, mirroring the CLI's id subcommand. The tool is intended for OSINT analysts, aviation enthusiasts, and anyone exploring the public ADS-B record without committing to a Python install.

Scope vs. the CLI

The CLI ships eight async subcommands. The browser port maps them as follows:

Data Sources

Why the chain is inverted vs. the CLI

The upstream CLI documents the chain as OpenSky → ADSB.lol → Airplanes.live. That order makes sense in a long-running server-side process with OpenSky credentials. From an anonymous browser the order is wrong: OpenSky's free-tier anonymous bbox queries now return 429 Too Many Requests during peak hours, while ADSB.lol and airplanes.live serve the same JSON shape without authentication. The visual tool therefore tries adsblol → airplaneslive → opensky and exposes a Source dropdown so the order can be pinned manually for testing.

Data freshness

• ADSB.lol / airplanes.live: feed-of-feeds aggregating community receivers. The per-aircraft seen field is converted to a wall-clock lastSeen timestamp during normalisation. Positions older than a few seconds are common at the edge of coverage.
• OpenSky: last_contact seconds-since-epoch is multiplied to milliseconds; the top-level time field is the upper bound for the dataset.
• The watch loop refreshes the entire visible bbox on each tick. There is no delta protocol — each sweep is a full replace.

Known limitations

• Aircraft enrolled in the FAA's Privacy ICAO Address (PIA) or Limiting Aircraft Data Displayed (LADD) programmes are omitted or pseudonymised by the feeds. They will not appear in results.
• Military aircraft frequently spoof or suppress squawk and callsign. Identity decoding falls back to the ICAO24 country range and a heuristic match against operator names containing Air Force, Navy, Reach, etc.
• Anonymous OpenSky access is unstable enough that it is essentially diagnostic-only in this tool. The fallback chain is designed around that fact.
• AISHub vessel tracking is omitted because it requires server-side authentication; a proxy or backend would be needed to use it from the browser.

Methodology

1. Five-module separation

The browser app is split into five vanilla-JS modules loaded in dependency order via <script defer>:

• lookup.js — static identity tables (ICAO24 country ranges, ICAO airline codes).
• providers.js — the three data providers, their normalisation, and the fallback orchestrator.
• aircraft.js — Leaflet marker management, rotation, trails, selection.
• export.js — JSON / CSV / GeoJSON serialisers and download triggers.
• app.js — controller (state, modes, watch loop, UI wiring).

Each module attaches a single object to window (SkyReconLookup, SkyReconProviders, …). No bundler, no ES module loader, no build step. This matches the rest of the lab.

2. Provider normalisation

The two readsb-style feeds (ADSB.lol, airplanes.live) and the column-positional OpenSky response are reduced to a single normalised aircraft shape. Everything downstream consumes only this shape:

{
  icao24,        // hex string, lower-case
  callsign,      // trimmed, may be null
  country,       // string or null (from provider; lookup.js fills gaps)
  lat, lon,
  altBaro,       // feet, may be null
  altGeo,        // feet, may be null
  speed,         // knots, may be null
  heading,       // degrees true, may be null
  vRate,         // feet/minute, may be null
  squawk,        // 4-digit string, may be null
  onGround,      // bool
  category,      // ADS-B Cat (A1..C4), may be null
  registration,  // tail number, may be null
  type,          // type code (B738, etc.), may be null
  source,        // provider id
  lastSeen,      // ms epoch
}

OpenSky's metric units (m, m/s) are converted into the readsb defaults (ft, kt, fpm) inside the normaliser so downstream code never branches on provider.

3. Fallback orchestrator & abort handling

The orchestrator iterates the provider list and stops at the first success. Errors are aggregated for diagnostics. The subtle case is distinguishing a caller-initiated abort from an internal timeout:

• The caller (the watch loop) passes an AbortSignal so it can cancel an in-flight sweep when the interval ticks again.
• The provider also has an internal setTimeout that aborts a hung request after 12 s.
• Both surface as AbortError on the fetch promise. If we treat them identically, a hung provider would bubble the abort to the caller and never try the fallback.

The fix is a timedOut flag plus a check on the caller's signal:

try {
  const r = await fetch(url, { signal: ctrl.signal, … });
  …
} catch (e) {
  if (e.name === 'AbortError') {
    if (signal && signal.aborted) throw e;             // caller cancelled — bubble
    if (timedOut) throw new Error(url + ' → timeout');  // try next provider
  }
  throw e;
}

4. Mercator vs. Leaflet

This project does not reproduce the manual Mercator rendering used in /gpxeditor. SkyRecon needs rotated markers that move every few seconds, popups, polylines for trails, and tile-aware pan/zoom. Hand-rolling all of that on a canvas would duplicate Leaflet for no benefit. The previous brutalist black/red design carries over via heavy CSS overrides on Leaflet's default DOM (zoom buttons, attribution, popups).

5. Rotation by CSS transform

Leaflet markers cannot rotate natively. Instead of pulling in a plugin (Leaflet.RotatedMarker), each aircraft uses a divIcon whose root element carries an inline transform: rotate(°) derived from the aircraft's track angle. The plane silhouette is a single inline SVG <path> (no <use>, no external file). The icon class also encodes climb / descent / ground / selected state, which CSS uses to swap the SVG fill colour.

6. Bbox ↔ point conversion

ADSB.lol and airplanes.live expose a radius-from-point endpoint but no native bbox endpoint. The watch loop converts the map's bounds to {lat, lon, radiusNm} using the diagonal great-circle distance plus a 10% pad, then client-side clips the response back to the exact bbox. OpenSky's bbox query is used directly when that provider is selected.

7. Identity tables

Two compact tables live at the top of lookup.js:

• ICAO24 country ranges — about 140 entries derived from ICAO Annex 10 Vol III, cross-checked with the public tables maintained by ADSBexchange, dump1090, and OpenSky. Each entry has a flag for military allocations so the selected panel can append (military).
• Airline ICAO codes — about 120 carriers covering essentially all commercial European traffic, plus common military prefixes (RCH, SAM, RFR, GAF, …).

Decoding is a linear scan on the country table (sub-microsecond on ~140 entries) and a hash lookup on the operator table. Both are extended by editing the literals; no build step, no JSON loader.

8. Marker reconciliation

The renderer maintains parallel Map instances of icao24 → aircraft and icao24 → L.Marker. On each sweep, replace(list):

1. Computes the set of incoming ICAO24s.
2. For each, upserts the marker (create or move + re-icon).
3. Removes any pre-existing marker whose ICAO24 is no longer in the set — except the currently-selected aircraft, which is kept on the map even after it leaves the bbox so the user does not lose their selection mid-investigation.

Trail positions accumulate in a separate Map bounded by TRAIL_MAX (200) entries and a TRAIL_TTL (30 minutes). Only the selected aircraft's trail is rendered, as a dashed red polyline. Trails outlive marker removal so re-selecting a previously-seen aircraft restores its history.

9. Map state persistence

The current centre and zoom are saved to localStorage on every moveend / zoomend. On next load, the saved view is restored; if absent, the default is Luxembourg City (49.611, 6.131) at zoom 8 — the lab's home airport area.

Stack & Tooling

• Languages: HTML5, CSS3 (custom properties), vanilla JavaScript ES2020+
• Libraries: Leaflet 1.9.4 (CDN, SRI-pinned)
• Map tiles: CARTO Dark Matter (free, no key, attribution shown)
• Fonts: JetBrains Mono, self-hosted WOFF2 via /fonts/fonts.css
• Backend: none — static HTML / CSS / JS
• Build tools: none — source is production
• Browser targets: Chrome 110+, Firefox 115+, Safari 16+

Key Observations & Limitations

What works

• Same readsb JSON across ADSB.lol and airplanes.live means a single normaliser handles two-thirds of the fallback chain.
• The CSS-transform rotation approach avoids a Leaflet plugin and renders correctly at every zoom level.
• The fallback chain with proper abort/timeout discrimination survives a single-provider outage transparently.
• Client-side identity decoding keeps the round-trip count low and works offline once the page is loaded.

Known gaps

• No marker clustering. In dense terminal-area airspace the icons overlap.
• PDF reports are not generated. Export is limited to JSON / CSV / GeoJSON.
• The Signal-webhook alert pathway from the CLI's watch subcommand has no browser equivalent.
• Anonymous OpenSky calls fail often; users with credentials would need a small proxy to send them.
• No aircraft photo lookup (the CLI optionally uses Planespotters) — deliberately omitted to keep the tool keyless.

Possible future directions

• Leaflet.markercluster (or canvas-renderer) for dense bboxes.
• Named bbox presets (Luxembourg, English Channel, Gibraltar, Suez) matching the CLI's preset list.
• Optional OpenSky token in localStorage with a tiny proxy snippet documented in the README.
• Server-side proxy + AISHub credentials to re-enable vessel tracking.
• Local persistence of selected-aircraft trails across page reloads.

Responsible Use

• Do not use this tool to assemble harassment workflows, stalking dossiers, or any kind of personalised real-time targeting.
• Operators who opt out of broadcast via PIA / LADD have actively asked not to be tracked — the feeds may still leak fragments, but treat absence as a stated preference, not a defect.
• Aggregating, redistributing, or commercialising the raw feed may violate the upstream providers' terms of service. Read them before scraping.
• Output is best-effort OSINT, not ground truth. Multi-source corroboration is required for any decision that matters.