Lumra Lumra
Get started

Documentation · v0.1.0

Lumra docs

Install it, run one command, read the verdict. Lumra diagnoses why a site is blocked, throttled, or tampered with — and where — from packets it measures itself, never a third-party block list.

INSTALL

Install

A single static binary, no account. macOS, Linux, and Windows on amd64/arm64.

# Homebrew (macOS / Linux) $ brew install croc100/tap/lumra # Windows — Scoop > scoop bucket add croc100 https://github.com/croc100/scoop-bucket > scoop install lumra # Windows — no package manager (PowerShell) > irm https://raw.githubusercontent.com/croc100/lumra/main/install.ps1 | iex # Go $ go install github.com/croc100/lumra/cmd/lumra@latest # From source $ git clone https://github.com/croc100/lumra $ cd lumra && go build ./cmd/lumra

Verify it's on your path:

$ lumra version lumra 0.1.0 (…) 2026-…

QUICKSTART

Quickstart

Point it at a domain. Lumra runs its probes from your own vantage and prints a verdict with the evidence behind it.

$ lumra diagnose example.com Target: example.com Verdict: OK (confidence: low) No interference detected by the probes run so far. Evidence: ✓ DNS consistent with DoH ground truth (no tampering) ✓ TLS handshake OK with target SNI on 93.184.216.34 ⓘ HOP attribution not measured: needs raw-socket privilege ✓ RATE target throughput ~2.1 MB/s is healthy ✓ CTRL baseline reachable via 9.9.9.9:443 (not a local issue)

Nothing leaves your machine. Lumra measures; it does not phone home. Analysis is metadata- and behavior-based — no packet contents are logged.

REFERENCE

Commands

lumra diagnose <domain>Run the full diagnosis and print a human-readable verdict.
  --jsonEmit the verdict as JSON ({type, cause, confidence, attribution, evidence[]}) for pipelines.
  --report <file.html>Also write a self-contained HTML evidence page you can share as proof.
lumra versionPrint the build version, commit, and date.
lumra install-host <ext-id>Register the native-messaging host so the browser extension can call the local core.
lumra nm-hostNative-messaging host mode — run by the browser, not by hand.

REFERENCE

Verdict types

Every run resolves to exactly one labeled verdict, with a confidence of high medium low.

OKNo interference detected by the probes run.
DNS_TAMPERINGA DNS answer was poisoned, denied (NXDOMAIN), or injected as a duplicate response.
SNI_FILTERINGTLS reset triggered by the target hostname in the ClientHello, while a benign SNI to the same IP succeeds.
RST_INJECTIONA TCP reset injected from within the path, closer than the destination.
TLS_MITMThe handshake completes but the certificate does not chain to a trusted root — interception.
IP_BLOCKINGEvery connection to the IP is reset regardless of SNI — the address itself is blocked.
THROTTLINGThe target is reachable but its sustained throughput is far below a capable control path.
BLOCK_PAGEThe request was diverted to an operator's self-identifying block server (e.g. warning.or.kr → KCSC).
LOCAL_ISSUEYour own network is down — no control anchor is reachable. Overrides everything.
GENUINE_OUTAGEThe target itself is failing, not being interfered with.
INCONCLUSIVENot enough signal — e.g. a silent blackhole a single vantage can't split from an outage.

REFERENCE

Evidence probes

Each evidence line is tagged by the probe that produced it and marked ✓ pass ✗ fail ⓘ info.

DNSCross-resolver comparison vs. DoH ground truth; NXDOMAIN and duplicate-response injection.
TLSSNI-conditional resets, certificate chain verification (MITM), IP-level reset behavior.
HOPRST/TTL hop distance — how far away the injector is vs. the destination. Needs elevation.
RATESustained throughput vs. a capable control path — throttling vs. congestion.
CTRLBaseline reachability to anycast anchors, so a local outage is never called censorship.
PAGEWhether the request was diverted to a known operator block server.

DEEP PROBES

Attribution & elevation

RST/TTL hop attribution — the HOP signal that places an injector "~6 hops out, before the destination" — reads raw packets, which needs a raw socket. Run elevated to enable it:

# Linux / macOS $ sudo lumra diagnose news.example.kr # or grant the capability once (Linux) $ sudo setcap cap_net_raw+ep $(which lumra)

Without elevation Lumra degrades honestly — it reports attribution not measured rather than guessing. Every other signal (DNS, TLS/SNI, MITM, throttling, block-page) works unprivileged. Raw capture is currently Linux-only; other platforms report it as not measured.

BROWSER

Browser extension

Diagnose the current tab from the toolbar. The extension is a thin front end; the measurement runs in the local core over Native Messaging.

01
Build the core
go build -o lumra ./cmd/lumra and note the path.
02
Load unpacked
chrome://extensions → Developer mode → Load unpacked → the extension/ dir. Copy its ID.
03
Register the host
./lumra install-host <extension-id> wires Chrome to your binary.
04
Diagnose
Reload the extension, click the icon on any site, hit Diagnose.

Without the core, the extension still flags failing navigations in-browser; deep attribution needs the native binary. Full setup in the extension README.

EXAMPLES

Examples

Machine-readable output for scripts and CI:

$ lumra diagnose example.com --json { "target": "example.com", "type": "OK", "confidence": "low", "evidence": [ … ] }

A shareable evidence page — one self-contained file, no dependencies:

$ lumra diagnose news.example.kr --report report.html report written: report.html

Verify Lumra's own discrimination against public test certs:

$ lumra diagnose untrusted-root.badssl.com # → TLS_MITM $ lumra diagnose expired.badssl.com # → OK (expired ≠ MITM)

STANCE

Privacy & non-goals

Lumra never reports "blocked" because a third party said so — a verdict cites packets it observed or infrastructure that named itself. It does not log packet contents, and it does not route around blocks: circumvention is Warren's job. Lumra diagnoses.