Files
MikrotikManager/docs/mcp-recursive-native-acquisition-contract.md
T

8.2 KiB
Raw Blame History

Native recursive nexthop acquisition contract

This is a read-only evidence acquisition procedure, not a recursive resolver or semantic proof. The CLI is inert until explicitly run by the operator. No CHR was contacted while implementing it.

Fixed scope and transport

backend/scripts/acceptance/chr-recursive-observation.mjs permits exactly owned CHR 194.226.121.150 (server 1) and 104.165.244.7 (server 2). HTTPS connects to that literal IP on port 443 with normal certificate and hostname validation. No TLS disabling, redirects, retries, external plaintext HTTP, writes, scripts, exports or dump-dot commands are permitted.

The alternate ssh-loopback transport uses only 127.0.0.1:19081 for server 1 and 127.0.0.1:19082 for server 2. Before using it, the operator must establish their owned SSH forward through 161.104.46.222, verify its known host key with rejection of unknown/changed keys, and independently record the SSH host fingerprint and exact forward destination. The explicit option --owned-tunnel-attestation verified-known-host-161.104.46.222-owned-forward records that operator assertion. A matching loopback port or option is not cryptographic proof of the peer, capability, or SSH provenance. The script does not establish or authenticate the tunnel itself.

Invocation and private input

From the repository root, choose a new directory beneath tmp/:

node backend/scripts/acceptance/chr-recursive-observation.mjs --source 194.226.121.150 --transport ssh-loopback --output tmp/chr-recursive-capture-server1 --owned-tunnel-attestation verified-known-host-161.104.46.222-owned-forward

Credentials enter exclusively as private stdin JSON with username and password fields. Interactive terminal input is hidden; automated operators must pipe stdin privately without command-line arguments, environment variables, shell history, transcripts or logging containing secrets. No credentials or authorization headers are saved. Use a read-only account when available; any explicitly authorized existing account does not expand the fixed GET protocol.

Raw bodies are sensitive private artifacts, saved with exclusive wx creation and mode 0600 (directory 0700 on POSIX). Windows operators must keep the output under a user-private ACL; POSIX mode bits do not configure Windows ACLs. Public stdout contains only completion/source/count metadata. Failure reports use a fixed generic code; error bodies and raw reflected errors are never saved. A successful body containing the supplied password or Basic authorization value is refused before writing.

Fixed acquisition and limits

One pass executes these GET resources in order (all under /rest): /system/resource, /routing/route, /routing/nexthop, /interface, /routing/table, /ip/vrf, /routing/nexthop, /routing/route, /system/resource. No projection is used: exact nested object/flattened serialization must be preserved. Each successful body is saved byte-for-byte, with SHA256, source/server identity, version, HTTP status, content type and capture timestamps in report.json. Both resource reads must identify the same supported exact version/build in the 7.20–7.26 range. Missing endpoints or unsupported shapes stop the capture. Re-run only as a separate, explicitly initiated acquisition in a new directory.

Caps: 1 MiB per response, 8 MiB total response bodies, 256 requests, 1000 rows per response, 10000 total rows, 120-second absolute network deadline, 16 KiB response headers per request. The fixed protocol normally makes nine requests. Caps or failures stop acquisition without retries. Partial artifacts remain identifiable as incomplete. Captures cannot be overwritten; symlink/junction output components are refused. The operator must retain exclusive control of the output tree during execution to prevent filesystem replacement races.

After a complete acquisition, snapshotBracket.routeByteEqual and snapshotBracket.nexthopByteEqual compare the SHA-256 values of the opening and closing bodies independently. If either value is false, keep the raw captures as separate observations. A partial acquisition reports snapshotBracket: null. Historical reports without this field need their stored hashes compared before using the read sequence. Two matching pairs establish byte equality only. An atomic snapshot, numeric namespace equivalence, forwarding and reserved inverse eligibility remain unverified.

Missing identity evidence

The official 7.26 route reference types nexthop-id as numeric and describes immediate-gw as the resolved forwarding endpoint. The nexthop reference types numeric links.route-id, links.fwp-id and immediate-gw.interface-idx, but does not establish joins to REST .id. The interface reference does not specify that numeric index mapping. IP Routing describes separate nexthops by address/scope/gateway check and internal scope correction. Therefore scope/LPM reconstruction or interpreting hexadecimal-looking .id values as these numeric keys is insufficient.

Before implementing a resolver, obtain version-specific manufacturer documentation or equally authoritative identity contracts for:

  • Route nexthop-id to the exact native nexthop key.
  • Nexthop links.route-id/fwp-id to exact route identities and input/output direction semantics.
  • Numeric interface-idx to an exact interface identity.
  • REST nested/flattened object serialization, cardinality and absent-field semantics for links and immediate gateways.
  • Complete graph acquisition and consistency semantics, including ECMP, unresolved links, loops and table/VRF context.

Preserve unmodified native examples from existing direct and recursive IPv4/IPv6 paths, VRFs, ECMP, unresolved gateways and overlapping scope/check combinations on each available version. Missing scenarios remain unverified; this procedure authorizes no configuration changes to manufacture them. Raw samples alone do not establish undocumented numeric join semantics. The parser continues returning unknown for recursive chains until the contract and bounded adversarial resolver tests exist.

Direct SSH observation from the local PC

On 2026-11-15, both test CHRs running RouterOS 7.24.5 stable completed the nine-read sequence through direct SSH with pinned host keys. The route and nexthop catalogues were byte-identical within each device's bracket. The first device returned 8 route and 4 nexthop rows, and the second returned 9 route and 6 nexthop rows. CLI print as-value serialized immediate-gw on routes and immediate-gw.interface-idx on nexthops as arrays. The observed rows omitted nexthop-id and links.route-id/fwp-id.

This direct SSH observation made no configuration changes. An offline check of the November 1 REST capture verified all eight saved route/nexthop bodies against their report hashes and found matching opening and closing pairs on both devices. A fresh direct REST capture needs HTTPS with a validated certificate or a verified SSH loopback transport. Recursive identity remains unverified.

Run node backend/scripts/acceptance/chr-recursive-direct-links.mjs <reviewed-capture-directory> to check exact direct references in the original November 1 REST capture. It verifies the fixed private report and each selected raw body against SHA-256. It found 6 and 7 exact opaque nexthop-id to .id matches. On each device, 3 named route gateways corroborated the uniquely matching /interface ifindex and did not match that interface's id. Routing tables were reported by name, and neither device returned any links fields. This corroborates the observed direct links only.

The next read needs an existing multi-hop route and its selected nexthop with nonempty links.route-id or links.fwp-id, together with the exact named and indexed interface and table/VRF catalogues. Bracket route, nexthop, interface, table and VRF reads on the same verified source and version. Obtain a version-specific contract for the link fields and their direction before interpreting the recursive chain.