Skip to content

EXPLAINME.adoc

Latest commit

 

History

History
84 lines (59 loc) · 5.34 KB

EXPLAINME.adoc

File metadata and controls

84 lines (59 loc) · 5.34 KB
Raw

Cyber-Focused Network Diagnostic Suite (CF-NDS) — Show Me The Receipts

Table of Contents

The README makes claims. This file backs them up.

Real Claims From The README

Claim 1: "Zero-telemetry speedtest… BGP path visibility… Jitter persistence… Hardened access with rate-limiting" (README, Key Features section)

Aerie integrates three network diagnostic tools behind a single Zig gateway (port 4000):

  1. LibreSpeed (port 8080) — Zero-telemetry speedtest for bandwidth measurement

  2. Hyperglass (port 8082) — BGP looking glass for routing path analysis

  3. SmokePing (port 8081) — ICMP latency monitor for jitter tracking

The gateway in src/api/zig/main.zig acts as a reverse proxy and access control layer. All requests are logged to Redis and wrapped in ProofEnvelope structures (SHA-256 hash + query ID + timestamp). The policy gate in src/api/zig/policy.zig checks X-Api-Key headers and rate-limits by key. (Estate rule: no gatekeeperless gateways — every gateway fronts a policy gate.)

How it works: The gateway reads configuration from environment variables (LIBRESPEED_URL, HYPERGLASS_URL, REDIS_URL). Incoming requests hit the policy gate first. If authorized, the request is forwarded to the appropriate backend service. The response is hashed and wrapped in ProofEnvelope. The full request/response is logged to Redis for audit trail. Caveat: Phase 1 (current) uses SHA-256; Phase 2+ will add Ed448 signatures for cryptographic proof. Rate limiting is per-key; there is no global circuit breaker yet.

Claim 2: "Dual passive/active forensics: Zeek/Suricata listening + Hyperglass/SmokePing/LibreSpeed probes" (README, Key Features section)

The architecture distinguishes between:

  • Passive forensics — Network packet inspection via Zeek (IDS) or Suricata (threat detection)

  • Active forensics — Measurement probes (LibreSpeed speedtest, SmokePing pings, Hyperglass BGP queries)

The clients in src/api/zig/ are implemented as Zig modules: - librespeed_client.zig — Speed measurement wrapper - smokeping_client.zig — Jitter/latency monitoring - hyperglass_client.zig — BGP path lookup

Each client has a corresponding resolver in src/api/zig/resolvers.zig that fields GraphQL/REST requests.

How it works: Passive Zeek/Suricata instances listen on network interfaces and post alerts to the audit log (Redis). Active probes are on-demand: user requests trigger a new speed test or BGP query. Results are cached in Redis (TTL configurable per probe type). The frontend dashboard displays both real-time probe results and historical passive alerts. Caveat: Zeek/Suricata are not yet containerized in the compose stack (planned Phase 2); only the three primary probes are running currently.

Dogfooded Across The Account

Aerie uses the hyperpolymath ABI/FFI standard (Idris2 ABI + Zig FFI) for proof envelopes and cryptographic operations. This pattern is shared across:

  • proven — Model verification with formal proofs

  • burble — Media platform with proof-based audit logs

  • gossamer — Window manager with Idris2 state machines

The proof envelope concept (hash + metadata) is reused in all hyperpolymath API services.

Technology Choices

Technology Learn More Why

Idris2

https://www.idris-lang.org

ABI: formal proofs of proof-envelope correctness (estate ABI standard)

Zig

https://ziglang.org

API gateway, HTTP server, service clients, FFI / C interop (estate API+FFI standard)

Nickel

https://nickel-lang.org

K9 spec assembly for component definitions

Podman Compose

https://podman.io

Container orchestration, Chainguard base images

Redis

https://redis.io

Audit log, cache, real-time event stream

File Map

Path What’s There Key Details

src/api/zig/main.zig

Gateway entry point

Triple-mount API (GraphQL, REST, gRPC), protocol config, banner

src/api/zig/policy.zig

Policy gate

X-Api-Key validation, rate limiting per key, request logging

src/api/zig/proof.zig

Proof envelope

SHA-256 hashing, ProofEnvelope struct wrapping, response signing

src/api/zig/librespeed_client.zig

Speed probe client

HTTP wrapper for LibreSpeed results, bandwidth metrics

src/api/zig/smokeping_client.zig

Jitter probe client

Latency time series, ICMP RTT collection

src/api/zig/hyperglass_client.zig

BGP client

AS path resolution, prefix origin validation

src/api/zig/redis_client.zig

Cache/audit

Audit log persistence, request/response archival

src/api/zig/resolvers.zig

GraphQL resolvers

Field resolvers for all three probe types

src/abi/*.idr

Idris2 ABI

Foreign/Layout/Types — formal interface contract

src/api/graphql/schema.graphql

GraphQL schema

Type definitions (Speed, Jitter, BGPPath, ProofEnvelope)

src/api/proto/aerie.proto

Protobuf definitions

gRPC message definitions (Phase 1.1+)

specs/

K9 component specs

active-probe.adoc, alerting-retention.adoc, known-limitations.adoc

docker-compose.yml

Container stack

LibreSpeed, Hyperglass, SmokePing, Redis services

Questions?

Open an issue or reach out directly — happy to explain anything in more detail.