SkeleTrace

Data formats

SkeleTrace works in plain JSON. This page describes each file it writes, and each file you prepare for it, field by field. Its output can then be checked, archived and processed by other tools.

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:00Z or 2026-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.

CommandEnvelopeContents
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 }
FieldTypeMeaning
latnumberLatitude in degrees, −90 to 90.
lonnumberLongitude in degrees, −180 to 180.
altnumber or nullAltitude, 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": []
      }
    ]
  }
}
FieldMeaning
view_idIdentifier of the view that produced this file.
nodes[].entity_idThe node’s identifier.
nodes[].labelA human-readable name.
nodes[].kind_labelOne of the node kinds.
nodes[].positionA position, or null when the node has none.
nodes[].metricsLatest metric values for the node.
edges[].source, edges[].targetThe entity_id of each end.
edges[].kind_labelOne of the edge kinds.
edges[].geometry_modeHow the link is drawn on maps.
boundaries[].extentAn 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 id is the entity’s identifier.
  • Nodes are Point features and routes are LineString features. Extents are written as closed rectangular Polygon features.
  • properties.metrics is an object keyed by metric name; each entry holds metric_id, value, unit and timestamp.
  • 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": []
  }
}
FieldMeaning
node_count, edge_countThe size of the view analysed.
componentsGroups of connected nodes, largest first, as lists of entity identifiers.
chokepointsNodes 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.
bridgesLinks whose loss splits their group.
dangling_edgesLinks 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": []
  }
}
FieldMeaning
from, toThe two nodes named on the command line, by identifier or exact label.
foundtrue when a chain of believed links joins them. When it is false, confidence is null and the lists of nodes and links are empty.
confidenceThe confidences of the links on the chain, multiplied together.
nodesThe nodes along the chain, from start to end, both included.
linksThe links used, in order along the chain, each with its confidence.
unbelieved_linksLinks with a confidence of 0, which are never used.
dangling_linksLinks 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 name property, or fence 1, fence 2 and 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
      }
    ]
  }
}
FieldMeaning
fencesOne result per fence, in the order of the file. A node can be in several.
fences[].area_km2The fence’s area in square kilometres, holes taken out.
fences[].insideNodes strictly inside the fence.
fences[].on_edgeNodes exactly on its edge, as the numbers are given, with no tolerance.
outside_allNodes with a position that are in no fence and on no edge.
no_positionNodes 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
      }
    ]
  }
}
FieldMeaning
positionedHow many nodes had a usable position.
outlineThe 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_km2The area inside the outline in square kilometres; 0 with fewer than three corners.
geojsonThe outline as a GeoJSON Feature holding a Polygon, ready for any map; null with fewer than three corners.
warningSet when the nodes span more than 180° of longitude, where a flat outline means little.
no_positionNodes 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 #lantern is 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"
      }
    ]
  }
}
FieldMeaning
exactWhether capital letters had to match, set by --exact.
fuzzyThe most typos a near-miss could have: 0 when --fuzzy was not given.
termsHow many different terms were searched for.
inputsOne entry per file, in the order searched: its path as given, the bytes read, its hits and near-misses, and any warning.
countsOne entry per term, in watch-list order: hits in every file, how many files held one, near-misses, and the typos the term allows.
missingThe terms found nowhere as written.
hits_total, hitsEvery hit counted, and the hits listed: the term, the file, the byte offset, the line and column, and the text as written.
truncatedWhether more hits were found than listed. --max-hits sets the limit, 10,000 by default.
near_hits_total, near_hitsThe same for near-misses, each with edits: how many typos it is from the term.
near_truncatedWhether more near-misses were found than listed.
near_onlyThe terms with no exact hit but at least one near-miss. They stay in missing too.
near_skippedThe 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 label or name, and kind_label or kind, 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 nodes and edges or links, using id, label and kind on nodes and source and target on 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"
    }
  ]
}
FieldMeaning
idLowercase letters, digits and hyphens, up to 64 characters. Unique.
nameThe layer's name in the source menu and the layer list.
groupThe heading it sits under in the source menu, such as Internet infrastructure.
fileA file in the same folder: letters, digits, dots, hyphens and underscores, ending in .json, .geojson, .graphml or .xml.
colourOptional, as #rrggbb. Otherwise the viewer picks one.
attribution, licence, licence_urlShown on the map whenever the layer is on, linked to the licence.
tiercommunity for layers published here. layers/layers.py keeps Pro layers out of this catalogue.
description, source_url, features, updatedFor 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.