# BGPKit + Signal Atlas — V2 integration brief

Status: training lab implemented; production integration proposed.
Source: 16ba3e2ff66866870e06ee701460340ad0bc6c5b, fetched from Forgejo origin/main on 2026-09-07. Clean local HEAD matched origin/main. This is a focused integration review, not a full security audit or proof of deployed/source parity.

## Judgment

Add BGPKit as historical acquisition, replay and feature extraction upstream of the existing receipt and lineage contracts. Preserve the Radar-led case model. A second acquisition library over the same RIS or RouteViews message adds no independent observer.

## Capability map

| Capability | Atlas use | Boundary |
| --- | --- | --- |
| Broker discovery | Select collector, time, prior RIB and UPDATE archives | Metadata discovery is not detection |
| Parser MRT/BGP/BMP | Normalize routing records on a bounded replay runner | Parsing does not establish legitimacy |
| Historical replay | Reconstruct a peer view from a RIB and intervening updates | Missing archives and resets require unknown state |
| Path analysis | Origin novelty, prepends, path-length delta, new adjacency, withdrawal patterns | No forged-path verdict from repeated ASNs; preserve sets/confederations |
| Collector/peer inventory | Repeatable coverage panel and overlap audit | More collectors may share a peer ASN |
| ROA history lookup | Event-time authorization investigation | Require validation provenance, data time, TAL and coverage gaps |
| ASN/IP/community lookup | Administrative identity and operator policy context | Not physical path, universal policy truth or attribution |
| Reproducible bundles | Analyst review, case replay and regression tests | Retain source terms, integrity, retention and releasability |

Keep raw MRT downloads, decompression and model training outside interactive Worker requests. Use bounded jobs on existing compute. This lab provisions no replay runner, new paid service or production storage.

## Actual architecture and anchors

1. Radar hijacks open cases; the one-minute Worker cron uses scheduled leases and bounded collection. See `worker/index.ts`, `worker/radar.ts`, `worker/scheduled-lease.ts`, `wrangler.jsonc`.
2. RIS Live and RouteViews RIB produce direct receipts. RPKI, IODA and Radar traffic anomalies produce different modalities. See `worker/control-plane.ts`, `worker/evidence-sources.ts`, `worker/rpki-evidence.ts`, `worker/ioda-evidence.ts`, `worker/radar-context-evidence.ts`.
3. D1 preserves native identity, observation/fetch time, transforms and digests. `worker/control-plane-types.ts` defines the receipt contract. `worker/control-plane.ts` implements conservative `peer-as:<ASN>` lineage, overlap checks, digest construction and idempotent insert.
4. `src/lib/proofline.ts` evaluates five distinct gates: routing change, authorization, mission match, operational effect and attribution. They are not interchangeable confidence votes.
5. `worker/threat-graph.ts` builds a bounded graph and 16-feature deterministic kNN assessment. `worker/ai-oap.ts` and `worker/oap-service.ts` implement a parallel code-owned OAP scaffold with bounded prose rewrites. OAP does not currently consume kNN output.
6. `worker/stix-service.ts` verifies stored artifacts. `worker/alert-delivery.ts` governs default-off release. `worker/route-leaks.ts` is a separate queue/dossier outside Proofline.

Also reviewed: `docs/ARCHITECTURE.md`, `docs/SOURCE_LINEAGE.md`, `docs/AI_AND_ML_ASSURANCE.md`, evidence types, receipt migrations and configuration. Source claims were checked against core ingestion, graph and gate implementation.

## Keep / add / complete / remove

**Keep:** Radar as the trigger; RIS Live for updates; RouteViews RIB for current state; current RPKI validation. IODA BGP remains RIS/RouteViews-derived context, while active probing/telescope can supply distinct impact candidates only with subject/time correlation. Radar traffic anomalies remain same-provider context.

**Add:** bounded BGPKit replay, event-time ROA coverage, versioned pre-event baselines. Prioritize operator-owned BMP and approved router change records for first-party observation and policy evidence. Record router identity, policy view, peer, native position and clock quality.

**Complete:** existing RIPE Atlas governance and result receipt ingestion rather than a second tasking service. Request lifecycle exists; execution defaults off; result receipt ingestion is absent. Complete mission identity and intelligence-provider verification before relying on staged governance. OAP currently keeps mission/attribution locked.

**Keep separate:** route leaks; KEV/EPSS vulnerability collection; Planet and country context. They are not routing labels or proof of malicious intent. Planet catalog is default-off. Country is excluded from routing graph/model features.

**Remove skew, not useful records:** API-brand votes; repeated polls treated as new evidence; IODA BGP as independent of its inputs; current ROAs presented as historical; country/CVE metadata as routing labels; unknown disposition treated as benign.

BGPStream, BGPalerter, ARTEMIS, GRIP and MANRS may add access, detection, configured policy or context. Do not count them as independent observation providers without new underlying observers and verified lineage.

## Receipt integration contract

`ControlPlaneSource` currently accepts only `ripe-ris-live` and `routeviews-rib`. Source CHECK constraints in `migrations/0003_control_plane_receipts.sql` also constrain source state, runs and receipts. A replay UPDATE cannot be renamed `routeviews-rib`, and a new source string cannot be inserted without migration.

| Replay input | Existing contract | Required treatment |
| --- | --- | --- |
| Collector and peer | collectorFamily, collectorId, collectorLineage, peerAsn, peerIp, peerLineage | Retain RIS/RouteViews family and conservative peer-AS boundary |
| Case/prefix/path | radarSource, radarEventId, watchedPrefix, observedPrefix, originAsns, asPath, matchKind | Exact case scope; preserve AS sets; add withdrawal message type without fabricated origin |
| Source and fetch times | observedAt, fetchedAt | Explicit historical mode; retrieval cannot refresh old evidence |
| Archive/record identity | sourceNativeId, sourceUrl, raw | Add file hash, record/element position, parser version, reset markers and gap ledger |
| Integrity/provenance | observationDigest, transformVersion, retrievalRunId, licenseClass | Retain digest and add semantic linkage separately; enforce retention/releasability |

Extend source types, SQL constraints, source definitions, readers, public schemas and tests together. Preserve old receipts with a forward migration. No production schema, ingest endpoint or receipt write is delivered by this lab.

The existing observation digest includes source, URL and raw provenance. Different transports can therefore hash differently. Add a **separate semantic linkage** over the canonical underlying collector/session, peer, prefix, source time/position, message type and structured attributes. Retain both retrieval receipts. A time-only key can merge legitimate repeated messages; missing position/identity must preserve ambiguity. Then apply peer-AS lineage accounting. Integrity, observation deduplication and independence are three different operations.

## ML: extend what exists

`deterministic-knn-v1` has 16 features and eight synthetic exercise analogues: four benign, four suspicious. It requires at least eight eligible reviewed examples including at least three per class. Its relative index is experimental, not calibrated probability or validated operational accuracy.

Current features: Radar score, message volume, duration, reported peers, prefix scope, expected-origin ambiguity, direct candidate peer coverage, cross-source corroboration, path diversity, maximum path length, candidate observation ratio, authorization conflict, valid counterevidence, impact sensor diversity, staleness and ongoing-signal context.

Proposed replay features: pre-event origin novelty; prepend-aware path-length change; prepend ratio; new adjacencies; announcements/withdrawals; recurrence; recovery time; visibility loss against a stable eligible peer panel. Rates need coverage-aware denominators. Missingness and resets remain explicit. New adjacency does not itself prove a policy violation.

Evaluate Isolation Forest only as a shadow novelty-ranking challenger against current deterministic rules and kNN. Keep it only if held-out analyst utility improves. Active learning may prioritize uncertain cases for review; analysts own disposition. OAP remains prose assistance with code-owned evidence, citations, gates and actions. This lab runs no model inference or training.

### Evaluation protocol

1. Build a versioned independently adjudicated corpus: benign maintenance, MOAS, origin changes, leaks, failures and counterevidence. Keep synthetic fixtures out of real-world performance claims.
2. Group incidents, related windows and replay copies before splitting forward in time. Add collector/peer holdout as stress tests. Fit transforms only on training folds.
3. Exclude future dispositions and future authorization information. A provider score cannot be both the target's definition and evidence of independent predictive success. Unknown labels are not benign.
4. Measure precision at a fixed review budget, recall on independently labeled incidents, detection delay, false alerts per prefix-day, abstention and analyst time. Report uncertainty and disagreements.
5. Ablate Radar score, duplicate transports and each evidence family. Simulate collector/source dropout. Stratify by address family, prefix/peer coverage and missingness.
6. Promote only if held-out utility improves while provenance, counterevidence and gate invariants hold. No accuracy target or improvement result is invented here.

### Acceptance checks before production

- Replaying twice adds no duplicate semantic observations or independent peers.
- Fetch-time changes do not refresh old observations or change semantic assessment identity.
- Shared RIS/RouteViews/Radar peers remain conservative; unknown lineage cannot advance independence claims.
- Withdrawals, prepends, sets, confederations, malformed input, resets, missing archives and out-of-order records behave explicitly.
- Current and event-time authorization stay separate; missing validation coverage remains unknown.
- Changed evidence invalidates/regenerates dependent graph/OAP/STIX artifacts while preserving analyst-closed dispositions.
- Resource bounds, licensing, private access, redaction, retention and rollback pass review.

## Five-minute demonstration

0:00 — Explain the real architecture and label the synthetic exercise.
1:00 — Replay baseline, candidate announcement, withdrawal and recovery.
2:00 — Add a duplicate transport and show unchanged independent peer count.
3:00 — Bound the routing judgment; show missing authorization, impact and attribution evidence.
4:00 — Reject a leaked ML split, export the brief, and state shadow-adapter admission tests.

## Primary external references

- https://github.com/bgpkit/bgpkit-broker
- https://github.com/bgpkit/bgpkit-parser
- https://github.com/bgpkit/pybgpkit
- https://developers.cloudflare.com/radar/investigate/bgp-anomalies/
- https://developers.cloudflare.com/workers/static-assets/billing-and-limitations/

The interface and local simulations use free Static Asset serving. Existing Broker/Radar API handlers remain Worker requests. No new inference, storage or scheduled job is introduced. This is not an account-wide spending guarantee.