Conventions
- Encoding. Files are UTF-8; a byte-order mark is tolerated. The viewer also reads UTF-16, which is what Windows PowerShell writes when output is redirected with
>. - Identifiers. Entity identifiers are UUIDs written as strings.
- Times. Times are RFC 3339 strings with a time zone, such as
2026-09-30T21:00:00Zor2026-09-30T22:00:00+01:00. - Coordinates. Positions are WGS 84 degrees, latitude from −90 to 90 and longitude from −180 to 180. GeoJSON coordinates are written longitude first, as RFC 7946 requires.
- Names of things. Kinds and modes are written as their names, such as
"Observer"or"Geodesic". The order of keys inside an object carries no meaning.
This page covers the files SkeleTrace writes, and the two you prepare for its tools: fences and watch lists. The engine’s own configuration (profiles, view jobs, filters, saved queries and watchlists) is outside its scope. The offline demonstration in the source code writes a complete set to copy.
Command output
Every skeletrace command prints a single JSON document. Results are wrapped in a named envelope that says what they are, so the viewer and any script can unwrap them by name.
| Command | Envelope | Contents |
|---|---|---|
materialize-topology | {"Topology": …} | Topology view |
materialize-sparse-geo | {"SparseGeo": …} | Sparse-geo map |
analyze-topology | {"TopologyAnalysis": …} | Bottleneck report |
strongest-chain | {"StrongestChain": …} | Strongest chain |
fence-check | {"FenceCheck": …} | Fence check |
cover-area | {"CoverArea": …} | Covered area |
sweep-text | {"Sweep": …} | Sweep report |
The other commands answer under their own names: Tick for tick and poll-source, Export, Query, QueryEnvelope for saved queries, Watchlist and HealthReport. profile-validate answers with a topology view of every node in the profile.
Shared building blocks
Position
{ "lat": 51.481, "lon": -3.179, "alt": null }
| Field | Type | Meaning |
|---|---|---|
lat | number | Latitude in degrees, −90 to 90. |
lon | number | Longitude in degrees, −180 to 180. |
alt | number or null | Altitude, where known. |
Extent
A rectangle on the map, used for boundaries and for the viewport of a sparse-geo map.
{ "min_lat": 35.0, "min_lon": -11.0, "max_lat": 62.0, "max_lon": 30.0 }
Metric value
As it appears in topology views:
{
"metric_id": "5f0c2a1e-8d3b-4c55-9e1a-2b7c4d6e8f90",
"metric_name": "latency",
"display_value": "42.0",
"unit": "ms",
"timestamp": "2026-09-30T21:00:00Z"
}
display_value is text, already formatted for reading. timestamp is the time of the sample shown.
Kinds and modes
- Node kinds
Endpoint,Hop,Relay,Observer,Anchor,Exchange,Identity,Account,Topic,Cluster,Chokepoint,Unknown- Edge kinds
Route,Link,Inference,Association,Membership,Reference,BoundaryCrossing- Geometry modes
Straight,Geodesic,RaisedArc,ThroughGlobe,Abstract; see place and geometry
Topology view
Written by materialize-topology.
{
"Topology": {
"view_id": "b8e5e04c-13de-55f0-97b3-8f8f46327759",
"nodes": [
{
"entity_id": "4a4c857b-fe5c-5dd7-8c9b-b91f4e5ac455",
"label": "Cardiff observer",
"kind_label": "Observer",
"position": { "lat": 51.481, "lon": -3.179, "alt": null },
"metrics": []
},
{
"entity_id": "662fc329-bc88-5f6b-ab76-4f34cb036591",
"label": "London exchange",
"kind_label": "Exchange",
"position": { "lat": 51.507, "lon": -0.128, "alt": null },
"metrics": [
{
"metric_id": "5f0c2a1e-8d3b-4c55-9e1a-2b7c4d6e8f90",
"metric_name": "throughput",
"display_value": "3.1",
"unit": "Tbit/s",
"timestamp": "2026-09-30T21:00:00Z"
}
]
}
],
"edges": [
{
"entity_id": "18af9bb0-d3a4-58e8-9bd6-2b67e6bca3d0",
"source": "4a4c857b-fe5c-5dd7-8c9b-b91f4e5ac455",
"target": "662fc329-bc88-5f6b-ab76-4f34cb036591",
"kind_label": "Route",
"geometry_mode": "Straight",
"metrics": []
}
],
"boundaries": [
{
"entity_id": "0d6c1b8e-6a4f-4f4e-9b1e-3c2d5e7f9a10",
"label": "EU jurisdiction",
"kind_label": "Legal",
"extent": { "min_lat": 35.0, "min_lon": -11.0, "max_lat": 62.0, "max_lon": 30.0 },
"metrics": []
}
]
}
}
| Field | Meaning |
|---|---|
view_id | Identifier of the view that produced this file. |
nodes[].entity_id | The node’s identifier. |
nodes[].label | A human-readable name. |
nodes[].kind_label | One of the node kinds. |
nodes[].position | A position, or null when the node has none. |
nodes[].metrics | Latest metric values for the node. |
edges[].source, edges[].target | The entity_id of each end. |
edges[].kind_label | One of the edge kinds. |
edges[].geometry_mode | How the link is drawn on maps. |
boundaries[].extent | An extent, or null when the boundary has no geography. |
Sparse-geo map
Written by materialize-sparse-geo. The map itself is a standard GeoJSON feature collection, wrapped with the viewport it was drawn for.
{
"SparseGeo": {
"viewport": { "min_lat": 30.0, "min_lon": -80.0, "max_lat": 60.0, "max_lon": 10.0 },
"feature_count": 2,
"geojson": {
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"id": "4a4c857b-fe5c-5dd7-8c9b-b91f4e5ac455",
"geometry": { "type": "Point", "coordinates": [-3.179, 51.481] },
"properties": {
"label": "Cardiff observer",
"kind": "Observer",
"metrics": {
"latency": {
"metric_id": "5f0c2a1e-8d3b-4c55-9e1a-2b7c4d6e8f90",
"value": "11",
"unit": "ms",
"timestamp": "2026-09-30T21:00:00+00:00"
}
}
}
},
{
"type": "Feature",
"id": "18af9bb0-d3a4-58e8-9bd6-2b67e6bca3d0",
"geometry": { "type": "LineString", "coordinates": [[-3.179, 51.481], [-74.006, 40.713]] },
"properties": { "label": "Transatlantic route", "kind": "Route", "metrics": {} }
}
]
}
}
}
- A feature’s
idis the entity’s identifier. - Nodes are
Pointfeatures and routes areLineStringfeatures. Extents are written as closed rectangularPolygonfeatures. properties.metricsis an object keyed by metric name; each entry holdsmetric_id,value,unitandtimestamp.- When a line’s two ends match two points, the viewer treats it as a link between them. Other lines are drawn as tracks.
Bottleneck report
Written by analyze-topology. The examples from here on come from one made-up view of five nodes: four with positions and one account without.
{
"TopologyAnalysis": {
"node_count": 5,
"edge_count": 5,
"components": [
[
"41e4102b-fb1c-5034-bf4d-4b9fd94f07da",
"e4a2a4b4-9f03-5fa9-ac3a-af162b27e7b7",
"799c10dd-887a-55ed-b239-c425de6c7a44",
"9e5487d5-0803-5344-853d-60baa57c1a57",
"4a576ce0-28b6-5564-8d15-fa8c751447bc"
]
],
"chokepoints": [
{
"entity_id": "799c10dd-887a-55ed-b239-c425de6c7a44",
"label": "Example station C",
"kind_label": "Relay",
"degree": 3,
"splits_into": 2
},
{
"entity_id": "9e5487d5-0803-5344-853d-60baa57c1a57",
"label": "Example mast D",
"kind_label": "Observer",
"degree": 2,
"splits_into": 2
}
],
"bridges": [
{
"entity_id": "34acaa10-592a-532b-b5ba-5dba342d2dec",
"source": "799c10dd-887a-55ed-b239-c425de6c7a44",
"target": "9e5487d5-0803-5344-853d-60baa57c1a57",
"kind_label": "Link"
},
{
"entity_id": "e4e9736a-e3dc-566d-afc7-c838aaa58d8a",
"source": "9e5487d5-0803-5344-853d-60baa57c1a57",
"target": "4a576ce0-28b6-5564-8d15-fa8c751447bc",
"kind_label": "Link"
}
],
"dangling_edges": []
}
}
| Field | Meaning |
|---|---|
node_count, edge_count | The size of the view analysed. |
components | Groups of connected nodes, largest first, as lists of entity identifiers. |
chokepoints | Nodes whose removal splits their group, the most disruptive first. degree counts the node’s links; splits_into is the number of pieces its removal leaves. |
bridges | Links whose loss splits their group. |
dangling_edges | Links whose ends are not both in the view. They are left out of the analysis. |
A topology view lists its links in an order that can change from run to run. So can the order of group members and bridges here. The findings themselves do not change. Sort by entity_id before comparing two reports.
A report holds no positions and only some of the links. Opened on its own, the viewer shows what it can. Dropped onto the topology view it came from, the viewer compares it with its own analysis.
Strongest chain
Written by strongest-chain. Here the direct link from A to C has a confidence of 0.5, so the chain through B wins, at 0.9 × 0.9 = 0.81. The link from C to D has a confidence of 0, so it is never used.
{
"StrongestChain": {
"from": {
"entity_id": "41e4102b-fb1c-5034-bf4d-4b9fd94f07da",
"label": "Example station A",
"kind_label": "Relay"
},
"to": {
"entity_id": "799c10dd-887a-55ed-b239-c425de6c7a44",
"label": "Example station C",
"kind_label": "Relay"
},
"found": true,
"confidence": 0.81,
"nodes": [
{ "entity_id": "41e4102b-fb1c-5034-bf4d-4b9fd94f07da", "label": "Example station A", "kind_label": "Relay" },
{ "entity_id": "e4a2a4b4-9f03-5fa9-ac3a-af162b27e7b7", "label": "Example relay B", "kind_label": "Relay" },
{ "entity_id": "799c10dd-887a-55ed-b239-c425de6c7a44", "label": "Example station C", "kind_label": "Relay" }
],
"links": [
{
"entity_id": "28e46505-1bbc-56e7-aa85-88af587e6c4d",
"source": "41e4102b-fb1c-5034-bf4d-4b9fd94f07da",
"target": "e4a2a4b4-9f03-5fa9-ac3a-af162b27e7b7",
"kind_label": "Link",
"confidence": 0.9
},
{
"entity_id": "e57ede44-eab2-53dd-bfa7-3cb2512d3680",
"source": "e4a2a4b4-9f03-5fa9-ac3a-af162b27e7b7",
"target": "799c10dd-887a-55ed-b239-c425de6c7a44",
"kind_label": "Link",
"confidence": 0.9
}
],
"unbelieved_links": ["34acaa10-592a-532b-b5ba-5dba342d2dec"],
"dangling_links": []
}
}
| Field | Meaning |
|---|---|
from, to | The two nodes named on the command line, by identifier or exact label. |
found | true when a chain of believed links joins them. When it is false, confidence is null and the lists of nodes and links are empty. |
confidence | The confidences of the links on the chain, multiplied together. |
nodes | The nodes along the chain, from start to end, both included. |
links | The links used, in order along the chain, each with its confidence. |
unbelieved_links | Links with a confidence of 0, which are never used. |
dangling_links | Links whose ends are not both in the view, left out. |
The viewer opens a strongest chain as a small graph of the chain.
Fences and fence checks
Fences
Read by fence-check: standard GeoJSON, as geojson.io, QGIS and most mapping tools save it. A file can hold a Polygon or MultiPolygon, a Feature holding one, or a FeatureCollection of them.
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": { "name": "Valley watch zone" },
"geometry": {
"type": "Polygon",
"coordinates": [[[-3.05, 51.95], [-2.85, 51.95], [-2.85, 52.1], [-3.05, 52.1], [-3.05, 51.95]]]
}
}
]
}
- Each feature is one fence, named by its
nameproperty, orfence 1,fence 2and so on. Features that are not polygons are skipped. - Coordinates are longitude first, as in all GeoJSON. A ring may repeat its first corner at the end, or not.
- Holes are respected: a node in a hole is outside the fence.
- A ring that spans more than 180° of longitude is refused. Split a fence that crosses the 180° meridian in two.
Fence check
Written by fence-check.
{
"FenceCheck": {
"fences": [
{
"name": "Valley watch zone",
"area_km2": 228.23991696237027,
"inside": [
{
"entity_id": "41e4102b-fb1c-5034-bf4d-4b9fd94f07da",
"label": "Example station A",
"kind_label": "Relay",
"position": { "lat": 52.0, "lon": -3.0, "alt": null }
},
{
"entity_id": "e4a2a4b4-9f03-5fa9-ac3a-af162b27e7b7",
"label": "Example relay B",
"kind_label": "Relay",
"position": { "lat": 52.05, "lon": -2.9, "alt": null }
}
],
"on_edge": [
{
"entity_id": "799c10dd-887a-55ed-b239-c425de6c7a44",
"label": "Example station C",
"kind_label": "Relay",
"position": { "lat": 52.1, "lon": -3.0, "alt": null }
}
]
}
],
"outside_all": [
{
"entity_id": "9e5487d5-0803-5344-853d-60baa57c1a57",
"label": "Example mast D",
"kind_label": "Observer",
"position": { "lat": 52.2, "lon": -3.2, "alt": null }
}
],
"no_position": [
{
"entity_id": "4a576ce0-28b6-5564-8d15-fa8c751447bc",
"label": "Example account E",
"kind_label": "Account",
"position": null
}
]
}
}
| Field | Meaning |
|---|---|
fences | One result per fence, in the order of the file. A node can be in several. |
fences[].area_km2 | The fence’s area in square kilometres, holes taken out. |
fences[].inside | Nodes strictly inside the fence. |
fences[].on_edge | Nodes exactly on its edge, as the numbers are given, with no tolerance. |
outside_all | Nodes with a position that are in no fence and on no edge. |
no_position | Nodes without a usable position, which cannot be placed. |
A fence check is a set of lists, not a picture, so the viewer does not draw it. To see the fences themselves, open the fence file in the viewer.
Covered area
Written by cover-area.
{
"CoverArea": {
"positioned": 4,
"outline": [
{
"entity_id": "9e5487d5-0803-5344-853d-60baa57c1a57",
"label": "Example mast D",
"kind_label": "Observer",
"position": { "lat": 52.2, "lon": -3.2, "alt": null }
},
{
"entity_id": "41e4102b-fb1c-5034-bf4d-4b9fd94f07da",
"label": "Example station A",
"kind_label": "Relay",
"position": { "lat": 52.0, "lon": -3.0, "alt": null }
},
{
"entity_id": "e4a2a4b4-9f03-5fa9-ac3a-af162b27e7b7",
"label": "Example relay B",
"kind_label": "Relay",
"position": { "lat": 52.05, "lon": -2.9, "alt": null }
},
{
"entity_id": "799c10dd-887a-55ed-b239-c425de6c7a44",
"label": "Example station C",
"kind_label": "Relay",
"position": { "lat": 52.1, "lon": -3.0, "alt": null }
}
],
"area_km2": 114.0561746603334,
"geojson": {
"geometry": {
"coordinates": [[[-3.2, 52.2], [-3.0, 52.0], [-2.9, 52.05], [-3.0, 52.1], [-3.2, 52.2]]],
"type": "Polygon"
},
"properties": { "area_km2": 114.0561746603334, "name": "cover area", "nodes": 4 },
"type": "Feature"
},
"warning": null,
"no_position": [
{
"entity_id": "4a576ce0-28b6-5564-8d15-fa8c751447bc",
"label": "Example account E",
"kind_label": "Account",
"position": null
}
]
}
}
| Field | Meaning |
|---|---|
positioned | How many nodes had a usable position. |
outline | The nodes at the corners of the outline, anticlockwise on a map. Fewer than three when the nodes all sit on one spot or one line. |
area_km2 | The area inside the outline in square kilometres; 0 with fewer than three corners. |
geojson | The outline as a GeoJSON Feature holding a Polygon, ready for any map; null with fewer than three corners. |
warning | Set when the nodes span more than 180° of longitude, where a flat outline means little. |
no_position | Nodes without a usable position, left out. |
The viewer opens a covered area as its outline on the map.
Watch lists and sweep reports
Watch list
Read by sweep-text: plain text, one term per line.
# Terms for the example. Lines that start with # and a space are notes.
lantern@example.org
jdoe88
@moth_relay
+44 7700 900123
- The file can be UTF-8, with or without a byte-order mark, or the UTF-16 that Windows PowerShell writes with
>. - Spaces round a term are trimmed, and blank lines are skipped. A line that is just
#is a note too, but#lanternis a term. - Terms cannot span lines.
Sweep report
Written by sweep-text. The example swept this four-line file, with --fuzzy 2:
2026-10-01 login ok user=jdoe88 from 203.0.113.9
2026-10-01 mail to lantern@example.org bounced
2026-10-02 new account jdeo88 registered
2026-10-02 reply from lantern@exmaple.org
{
"Sweep": {
"exact": false,
"fuzzy": 2,
"terms": 4,
"inputs": [
{ "path": "dump-1.txt", "bytes": 179, "hits": 2, "near_hits": 2, "warning": null }
],
"counts": [
{ "term": "lantern@example.org", "hits": 1, "files": 1, "near_hits": 1, "edits_allowed": 2 },
{ "term": "jdoe88", "hits": 1, "files": 1, "near_hits": 1, "edits_allowed": 1 },
{ "term": "@moth_relay", "hits": 0, "files": 0, "near_hits": 0, "edits_allowed": 2 },
{ "term": "+44 7700 900123", "hits": 0, "files": 0, "near_hits": 0, "edits_allowed": 0 }
],
"missing": ["@moth_relay", "+44 7700 900123"],
"hits_total": 2,
"hits": [
{ "term": "jdoe88", "input": "dump-1.txt", "offset": 25, "line": 1, "column": 26, "matched": "jdoe88" },
{
"term": "lantern@example.org",
"input": "dump-1.txt",
"offset": 68,
"line": 2,
"column": 20,
"matched": "lantern@example.org"
}
],
"truncated": false,
"near_hits_total": 2,
"near_hits": [
{
"term": "jdoe88",
"input": "dump-1.txt",
"offset": 119,
"line": 3,
"column": 24,
"matched": "jdeo88",
"edits": 1
},
{
"term": "lantern@example.org",
"input": "dump-1.txt",
"offset": 159,
"line": 4,
"column": 23,
"matched": "lantern@exmaple.org",
"edits": 1
}
],
"near_truncated": false,
"near_only": [],
"near_skipped": [
{
"term": "+44 7700 900123",
"reason": "not one word: words hold only letters, digits and @ . _ - + #, and don't start or end with a full stop"
}
]
}
}
| Field | Meaning |
|---|---|
exact | Whether capital letters had to match, set by --exact. |
fuzzy | The most typos a near-miss could have: 0 when --fuzzy was not given. |
terms | How many different terms were searched for. |
inputs | One entry per file, in the order searched: its path as given, the bytes read, its hits and near-misses, and any warning. |
counts | One entry per term, in watch-list order: hits in every file, how many files held one, near-misses, and the typos the term allows. |
missing | The terms found nowhere as written. |
hits_total, hits | Every hit counted, and the hits listed: the term, the file, the byte offset, the line and column, and the text as written. |
truncated | Whether more hits were found than listed. --max-hits sets the limit, 10,000 by default. |
near_hits_total, near_hits | The same for near-misses, each with edits: how many typos it is from the term. |
near_truncated | Whether more near-misses were found than listed. |
near_only | The terms with no exact hit but at least one near-miss. They stay in missing too. |
near_skipped | The terms only matched exactly although --fuzzy was given, each with the reason: too short, or not one word. |
Lines count from 1. Columns count from 1 in characters, as text editors count them, and a byte-order mark at the start of a file is not counted. Byte offsets count every byte. A sweep report is a set of lists, so the viewer does not draw it.
Other files the viewer opens
- GeoJSON
- Points become nodes, lines between two points become links, other lines become tracks and polygons become areas. The properties
labelorname, andkind_labelorkind, are used when present. - CSV
- One row per place, under a header row. Latitude and longitude columns are found by name (lat, latitude, lon, lng or longitude). A name, label or title column names each point, and a kind, type or category column sets its kind. Every other column shows in its details. Commas, semicolons and tabs all work, and so do decimal commas.
- KML and KMZ
- Points, lines, areas and tracks from Google Earth and similar tools, with their names, descriptions and extended data. Each item’s folder becomes its kind. KMZ files are unzipped in the browser.
- GPX
- Waypoints become points; tracks and routes become lines.
- GraphML
- Nodes, edges and their data keys. Exports from the OSINTropy case notebook open with sources, observations and leads told apart.
- Graph JSON
- An object with
nodesandedgesorlinks, usingid,labelandkindon nodes andsourceandtargeton links. Index references and Cytoscape element lists are accepted. - Case files
- OSINTropy’s case documents, and plain JSON lists of observations, open as a case. See works with.
A landscape report from Maxwell’s Demon Detector is not a graph or a map, and the viewer says so rather than guessing. It says the same of fence checks and sweep reports.
Viewer layer catalogue
The viewer on skeletrace.com offers built-in map layers, listed in /viewer/layers/catalog.json. Each entry names a file in the same folder, in any format the viewer opens; GeoJSON is usual.
{
"version": 1,
"generated": "2026-10-05T09:00:00+00:00",
"layers": [
{
"id": "osm-undersea-cables",
"name": "Undersea cables",
"group": "Internet infrastructure",
"file": "osm-undersea-cables.geojson",
"colour": "#60a5fa",
"description": "Undersea communication cables mapped in OpenStreetMap.",
"attribution": "© OpenStreetMap contributors",
"licence": "ODbL 1.0",
"licence_url": "https://opendatacommons.org/licenses/odbl/1-0/",
"source_url": "https://www.openstreetmap.org/copyright",
"features": 2,
"updated": "2026-10-05"
}
]
}
| Field | Meaning |
|---|---|
id | Lowercase letters, digits and hyphens, up to 64 characters. Unique. |
name | The layer's name in the source menu and the layer list. |
group | The heading it sits under in the source menu, such as Internet infrastructure. |
file | A file in the same folder: letters, digits, dots, hyphens and underscores, ending in .json, .geojson, .graphml or .xml. |
colour | Optional, as #rrggbb. Otherwise the viewer picks one. |
attribution, licence, licence_url | Shown on the map whenever the layer is on, linked to the licence. |
tier | community for layers published here. layers/layers.py keeps Pro layers out of this catalogue. |
description, source_url, features, updated | For people reading the catalogue, and the Credits page. |
Only layers whose licence allows republishing belong here: public domain, CC BY, or the ODbL with its attribution. Never data from sources that forbid redistribution or commercial use.