{"id":51847115,"url":"https://github.com/inth3shadows/boundary-probe","last_synced_at":"2026-07-23T14:01:59.331Z","repository":{"id":354300403,"uuid":"1221803999","full_name":"inth3shadows/boundary-probe","owner":"inth3shadows","description":"Deterministic network boundary diagnosis with evidence-backed remediation","archived":false,"fork":false,"pushed_at":"2026-07-17T20:28:35.000Z","size":576,"stargazers_count":0,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-07-17T22:23:40.106Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/inth3shadows.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-26T17:47:18.000Z","updated_at":"2026-07-17T20:27:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/inth3shadows/boundary-probe","commit_stats":null,"previous_names":["inth3shadows/boundary-probe"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/inth3shadows/boundary-probe","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inth3shadows%2Fboundary-probe","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inth3shadows%2Fboundary-probe/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inth3shadows%2Fboundary-probe/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inth3shadows%2Fboundary-probe/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/inth3shadows","download_url":"https://codeload.github.com/inth3shadows/boundary-probe/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inth3shadows%2Fboundary-probe/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35804545,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-23T02:00:06.683Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-23T14:01:58.699Z","updated_at":"2026-07-23T14:01:59.325Z","avatar_url":"https://github.com/inth3shadows.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Boundary Probe\n\n[![CI](https://github.com/inth3shadows/boundary-probe/actions/workflows/ci.yml/badge.svg)](https://github.com/inth3shadows/boundary-probe/actions/workflows/ci.yml)\n[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)\n[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux-lightgrey)]()\n\n`boundary-probe` is a CLI tool for deterministic network boundary diagnosis. It runs a targeted set of probes, classifies the most likely failure boundary with a confidence score, and gives the operator specific remediation steps — not generic advice.\n\nThe boundaries it answers: **local device / LAN**, **router-gateway**, **WAN/modem**, **captive portal**, **DNS**, **ISP upstream path**, and **remote service**. Every result is backed by evidence collected in the same run and stored locally in SQLite for history review.\n\n## Demo\n\nThe local web UI (`boundary-probe ui`) shows each run's boundary verdict, confidence band, evidence, collector measurements, and raw signal flags. Here it is catching a DNS failure — connectivity is up, but name resolution is down:\n\n![Boundary Probe web UI showing a DNS-failure diagnosis: the dns boundary at Moderate confidence, with evidence, collector details, and color-coded signal flags](docs/images/ui-demo.png)\n\nPrefer the terminal? `boundary-probe diagnose \u003ctarget\u003e` prints the same diagnosis as plain text. To try it yourself: `pip install boundary-probe` then `boundary-probe diagnose 8.8.8.8`.\n\n## How It Works\n\n`boundary-probe diagnose \u003ctarget\u003e` runs six collectors sequentially — gateway ping, DNS resolution, IP-level canary ping, control-host quorum check, target-service reachability, and a traceroute path analysis — then feeds the results into a deterministic rule engine. The engine emits a boundary classification, a confidence score, and an evidence-backed remediation list. Every run is persisted to a local SQLite database.\n\nThe rule engine is intentionally deterministic: same signals → same result, every time. Probabilistic layers and LLM-assisted diagnosis are deferred until the rules are calibrated on real-world captures.\n\n## Prerequisites\n\n**Windows 10/11:**\n- Python 3.11 or newer\n- `ping.exe`, `tracert.exe`, and `route.exe` on PATH (standard on all supported Windows versions)\n\n**Linux (Ubuntu 20.04+, Debian, Fedora, Arch):**\n- Python 3.11 or newer\n- `ping`, `traceroute`, and `ip` (iproute2) — install with `sudo apt install traceroute iputils-ping iproute2`\n\n**macOS:**\n- Python 3.11 or newer\n- `ping`, `traceroute`, and `route` (all ship with macOS — no install needed)\n\nNo additional runtime dependencies — stdlib only.\n\n## Quick Start\n\n**Windows (PowerShell):**\n```powershell\npython -m venv .venv\n.venv\\Scripts\\Activate.ps1\npip install -e .[dev]\n```\n\n**Linux:**\n```bash\npython -m venv .venv\nsource .venv/bin/activate\npip install -e .[dev]\n```\n\nDiagnose a target:\n\n```bash\nboundary-probe diagnose example.com\nboundary-probe diagnose https://app.example.com\nboundary-probe diagnose 1.1.1.1\n```\n\nSkip the traceroute for a faster result:\n\n```bash\nboundary-probe diagnose example.com --no-path\n```\n\nView recent run history:\n\n```bash\nboundary-probe diagnose --history 10\n```\n\nCapture a fixture from a live run (for testing or sharing):\n\n```bash\nboundary-probe capture my-snapshot --target example.com\n```\n\nConfiguration is optional — the defaults work out of the box. To view the\neffective settings and the config file path:\n\n```bash\nboundary-probe config\n```\n\nSee [Configuration](USAGE.md#configuration) for the full TOML schema (probe\nhosts, thresholds, timeouts) and the `BOUNDARY_PROBE_CONFIG` override.\n\nRun tests:\n\n```bash\npytest\npytest -m integration   # requires live network\n```\n\n## Project Structure\n\n```\nsrc/boundary_probe/\n    cli.py              Entry point — subcommands: diagnose, capture, roadmap\n    engine.py           Deterministic rule engine and confidence tiers\n    models.py           SignalSnapshot (7 booleans), Diagnosis, EvidenceItem\n    targets.py          Target parser — host / IP / URL classification\n    normalizer.py       Path signal normalizer — persistent-loss detection\n    collectors/         Windows subprocess collectors (ping, tracert, DNS, TCP)\n    store/              SQLite persistence — schema, insert, fetch\n    templates/          Escalation template generators (Phase 4)\ntests/\n    fixtures/           JSON signal snapshots and raw ping/tracert text fixtures\n    test_engine.py      Rule engine unit tests\n    test_parsers.py     ping/tracert/route-print parser tests\n    test_collectors_unit.py  Per-collector tests with FakeRunner (no network)\n    test_normalizer.py  Path normalizer algorithm tests\n    test_store.py       SQLite schema and round-trip tests\n    test_cli.py         CLI integration tests (monkeypatched collectors)\n    test_collectors_integration.py  Live-network tests (gated: -m integration)\ndocs/\n    product-brief.md          Product framing and scope\n    architecture-decision.md  Chosen product shape and phased delivery\n    technical-direction.md    Architecture and implementation path\n    rules-engine.md           Rule model and confidence design\n```\n\n## Phase Status\n\n| Phase | Scope | Status |\n|-------|-------|--------|\n| 0 | Scaffold — rule engine, CLI stub, target parser, fixtures | Done |\n| 1 | Real collectors, path normalizer, SQLite persistence | Done |\n| 2 | Rich signal facts, config file, collector details output | Done |\n| 3 | Local web UI | Done |\n| 4 | Escalation output (clipboard + .txt) | Done |\n| 5 | Hardening and calibration | Done |\n| 6 | Linux support, CI, PyPI packaging | Done |\n\n## Related Documentation\n\n- [Technical Reference](TECHNICAL.md) — architecture, collector design, deployment, maintenance\n- [Usage Guide](USAGE.md) — end-user guide for running diagnoses and reading results\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finth3shadows%2Fboundary-probe","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finth3shadows%2Fboundary-probe","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finth3shadows%2Fboundary-probe/lists"}