4.3 RECON — three modules about what is out there

Recon is the passive half of the toolkit. Nothing in this category transmits, and that is why it is safe to start here: the first hour of any operation should cost nothing but time, and everything learned in it makes the later steps cheaper.

4.3.1 02_cell_recon — Cell Recon

The reference module: survey GSM, UMTS, LTE or NR cells from a radio or from a capture, and keep what you found. It is also the module this manual treats as the worked example of the house contract — self-locating header, shared tmp/, TSV output with untrusted text sanitised, hardware guards that name the missing radio, and a --selftest that runs with no radio at all.

modules/02_cell_recon.sh --scan lte 20          # one survey pass, band 20
modules/02_cell_recon.sh --scan pcap capture.pcap
modules/02_cell_recon.sh --node van-1           # through a fleet node instead
modules/02_cell_recon.sh --list-tsv             # everything surveyed so far
modules/02_cell_recon.sh --arfcn lte 6300       # EARFCN to downlink MHz
modules/02_cell_recon.sh --plmn 262-01          # PLMN to operator and country
modules/02_cell_recon.sh --set-target lte 6300 262-01
modules/02_cell_recon.sh --export               # copy the survey into loot/

--set-target writes the shared radio target — the one row other modules read when they need to know which cell the session is about. That is why it is a verb here and not a setting: the target changes as you move, and it should change in one place.

What it keeps: loot/cell_recon/cells.tsv for the current answer and one survey_<timestamp>.tsv per pass, so a survey can be compared with the one before it rather than overwriting it. ARFCN, PLMN and operator names are decoded from tables in the module, which is what makes --arfcn and --plmn usable with no radio at all.

When it refuses: --scan with no radio stops and names the device; --scan pcap does not need one. --node refuses if the node is UNKNOWN rather than OFFLINE, because those two mean different things (§4.2.5).

Read next: 04_tower_map to put the cells on a plane, and §5.3 for a survey as a technique.

4.3.2 03_gsmtap — GSMTAP Live Feed

GSMTAP is Osmocom's wrapper: a raw GSM, UMTS, LTE or NR message inside a UDP packet on port 4729. Everything that can log a message — a base station, an SDR stack, 05_field_kit --emit — can log it in this shape, and this module is the toolkit's ear for it.

The header codec here was verified against Wireshark's GSMTAP dissector rather than recalled, which matters more than it sounds: two fields in this header are easy to get backwards (the uplink flag shares a word with the ARFCN, and the sub-type byte means different things per RAT), and both are asserted in --selftest and in the gates.

modules/03_gsmtap.sh --listen 30                      # fill a pcap for 30 seconds
modules/03_gsmtap.sh --listen 60 --pipe | wireshark -k -i -
modules/03_gsmtap.sh --read capture.pcap              # decode into the store
modules/03_gsmtap.sh --decode-tsv                     # the store, as TSV
modules/03_gsmtap.sh --identities-tsv                 # identities seen in the clear
modules/03_gsmtap.sh --parse-header 02040d00...
modules/03_gsmtap.sh --build-header 2 1 0 0 0 0 1 0  # build one, as hex

The modifiers do the filtering that decides whether a long capture is useful: --port, --iface, --any-port, --since / --until, --arfcn, --channel, --uplink. --forward host:port relays every datagram live; --watchlist FILE flags a TMSI, IMSI or IMEI you are looking for.

What it keeps: loot/gsmtap/decoded.tsv, one row per frame, with the timestamp, the channel, the direction, the payload in hex and the decoded type where the toolkit has a decoder for it.

When it refuses: --listen with no usable network binding says so rather than capturing nothing quietly; --read on a file that is not a pcap names the file and exits 2.

Read next: 06_gsm_air, 10_lte_air and 17_pcap_analysis consume what this module stores; §5.3 is the technique.

4.3.3 04_tower_map — Tower Survey

The GPS-tagged survey: one point per cell, with the fix that was in effect when the cell was seen, and three exporters. It is a separate module from 02_cell_recon on purpose — a survey without position is a list of cells, and a survey with position is evidence of where they were.

modules/04_tower_map.sh --start-gpsd              # default /dev/ttyUSB0
modules/04_tower_map.sh --gps-quality-tsv         # fix now, or "no"
modules/04_tower_map.sh --survey lte 20           # one pass, one point per cell
modules/04_tower_map.sh --history                 # with a fix, without, distinct
modules/04_tower_map.sh --export-geojson
modules/04_tower_map.sh --export-kml              # points with a fix only
modules/04_tower_map.sh --export-csv

--history is the honesty check on the whole exercise: it reports how many points were recorded with a fix, how many without, and how many distinct cells they cover. A drive with 400 points and 12 with a fix is not a map, and the module says so before you export one.

What it keeps: loot/tower_map/points.tsv, one row per observation with the cell, the measurements and the position — or the absence of a position, recorded as absence rather than as zero.

When it refuses: with no GPS fix it still surveys, and the points are stored without one; the exporters exclude them from KML rather than inventing a place.

Read next: §4.13.4 for the Map page, which reads the layer files this module and others write.

Part 4 continues with RADIO (§4.4), the fourteen modules that put the toolkit in contact with the air, and then, category by category, the rest of the catalogue: ACCESS, CORE NETWORK, SIM / IDENTITY, TRACKING, BASEBAND / DEVICE, ANALYSIS, EXPLOIT KITS and INTERCEPT / CARRIER. The window's ten pages follow at §4.13 and the target panel at §4.14.