Add bounded route dossiers

Author: copyleftdev

.github/workflows/ci.yml

@@ -102,13 +102,24 @@ jobs:
             --locked \
             --root "$CARGO_INSTALL_ROOT" \
             skbx-cli
+          cargo install \
+            --git "file://$GITHUB_WORKSPACE" \
+            --rev "$GITHUB_SHA" \
+            --locked \
+            --root "$CARGO_INSTALL_ROOT" \
+            skbx-route
           version="$(cargo metadata --no-deps --format-version 1 |
             jq -r '.packages[] | select(.name == "skbx-cli") | .version')"
           "$CARGO_INSTALL_ROOT/bin/skbx" describe --format json | jq -e --arg version "$version" '
             .name == "skbx"
             and .version == $version
             and .contract_version == "traceq/0.1.0"
           '
+          "$CARGO_INSTALL_ROOT/bin/skbx-route" describe | jq -e --arg version "$version" '
+            .name == "skbx-route"
+            and .version == $version
+            and .contract_version == "routeq/0.1.0"
+          '
 
       - name: Verify agent contract
         run: |
@@ -121,6 +132,19 @@ jobs:
             ."$schema" == "https://json-schema.org/draft/2020-12/schema"
             and ."$defs".EventEnvelope
           '
+          target/release/skbx-route describe | jq -e '
+            .contract_version == "routeq/0.1.0"
+            and .limits.max_packets == 256
+            and (.invariants | index("a silent hop is unknown and is not labeled as a drop"))
+          '
+          route_file="$RUNNER_TEMP/demo.routeq.jsonl"
+          target/release/skbx-route demo --output "$route_file"
+          target/release/skbx-route replay "$route_file" --format json | jq -e '
+            .hops == 4
+            and .responsive_hops == 3
+            and .destination_reached == true
+            and .complete == true
+          '
 
       - name: Verify embedded eBPF metadata
         run: |

.github/workflows/publish.yml

@@ -85,4 +85,5 @@ jobs:
           publish_crate skbx-contract
           publish_crate skbx-core
           publish_crate skbx-sensor
+          publish_crate skbx-route
           publish_crate skbx-cli

Cargo.lock

@@ -6,6 +6,7 @@ members = [
     "crates/skbx-contract",
     "crates/skbx-core",
     "crates/skbx-mission",
+    "crates/skbx-route",
     "crates/skbx-sensor",
 ]
 resolver = "2"

Cargo.toml

@@ -145,6 +145,52 @@ loopback-only by default, and there is no authentication or live remote capture
 backend. See [the Arc architecture and rollout guide](docs/arc.md) for the
 evidence contract, correlation algorithm, trust boundary, and production gates.
 
+## Route dossiers: beyond a line of hops
+
+`skbx-route` is an experimental sibling CLI that performs bounded, rootless
+IPv4 UDP route observation and records every TTL as a replayable `routeq`
+evidence dossier. It keeps one five-tuple across the run to reduce per-flow
+load-balancing artifacts, and it never treats a silent router as proof of a
+drop. [Explore the interactive route-dossier field guide](https://copyleftdev.github.io/skbx/route.html)
+for the evidence levels, visibility boundaries, and packet-budget model.
+
+```console
+# Install the sibling CLI from the repository.
+cargo install --git https://github.com/copyleftdev/skbx --locked skbx-route
+
+# Inspect the exact packet and time budget without resolving or probing.
+skbx-route plan example.com --json
+
+# Exercise replay and explanation without touching the network.
+skbx-route demo --output demo.routeq.jsonl
+skbx-route replay demo.routeq.jsonl --format json
+
+# Run a bounded live observation on Linux without root.
+skbx-route trace example.com \
+  --max-hops 20 \
+  --probes 2 \
+  --timeout-ms 500 \
+  --max-duration-ms 30000 \
+  --output route.routeq.jsonl
+
+# Opt in to passive prefix, origin-ASN, and RPKI context from RIPEstat.
+skbx-route enrich route.routeq.jsonl \
+  --max-lookups 64 \
+  --max-duration-ms 30000 \
+  --output route.enriched.routeq.jsonl
+```
+
+The initial vertical slice performs standards-based UDP path observation only.
+It does not port-scan intermediate routers, enumerate their services, or claim
+to observe remote forwarding decisions. Passive RIPEstat enrichment is a
+separate opt-in command with independent HTTPS request and duration budgets.
+It skips private and special-purpose addresses and sends each remaining public
+responder address to the
+[RIPEstat Data API](https://stat.ripe.net/docs/data-api/ripestat-data-api);
+RIPEstat's service terms apply. The dossier contract distinguishes observed,
+enriched, correlated, candidate, and unknown facts so public routing metadata
+and future cooperative skbx-sensor evidence cannot blur that boundary.
+
 ## What it can observe
 
 - BTF-discovered `struct sk_buff *` arguments in positions 1–5;

README.md

@@ -0,0 +1,34 @@
+[package]
+name = "skbx-route"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+homepage.workspace = true
+rust-version.workspace = true
+description = "Bounded route observation with per-hop evidence dossiers"
+keywords = ["linux", "networking", "observability", "traceroute", "security"]
+categories = ["command-line-utilities", "network-programming"]
+
+[dependencies]
+anyhow.workspace = true
+blake3.workspace = true
+clap.workspace = true
+libc.workspace = true
+nix = { workspace = true, features = ["net", "poll", "socket", "uio"] }
+reqwest = { workspace = true, features = ["query"] }
+serde.workspace = true
+serde_json.workspace = true
+thiserror.workspace = true
+tokio.workspace = true
+
+[dev-dependencies]
+tempfile = "3.27.0"
+
+[lib]
+name = "skbx_route"
+path = "src/lib.rs"
+
+[[bin]]
+name = "skbx-route"
+path = "src/main.rs"