netcanon 0.1.0

Multi-vendor network config translator with a verifiable cross-vendor audit

Netcanon

Multi-vendor network config translator with a verifiable cross-vendor audit.

Translates running-config between Cisco IOS-XE, Juniper Junos, Aruba AOS-S, Arista EOS, FortiGate, MikroTik RouterOS, and OPNsense. Per-field capability declarations and a cross-mesh audit catch silent translation errors before they ship. Explicit Tier-3 boundary on firewall / NAT / VPN / QoS — see docs/CAPABILITIES.md. See also docs/COMPARISON.md for positioning vs Batfish / Capirca / NAPALM and the rest of the network-automation landscape.

Two concerns, one FastAPI application:

1. Backup — pull running-config (or vendor equivalent) from network devices over SSH / NETCONF / REST, store verbatim in configs/<hostname>.<ext>. Runs on a schedule or on demand.
2. Migration — translate a stored backup from one vendor's config grammar to another through a shared canonical intent tree. Cisco IOS-XE → Aruba AOS-S, FortiGate → OPNsense, etc.

Ships on two platforms kept at strict feature parity:

Platform	Package	Entry point
Web (browser)	netcanon/	uvicorn netcanon.main:app
Desktop (Windows)	netcanon_desktop/	python -m netcanon_desktop

---

Quickstart

pip install -e ".[dev]"
uvicorn netcanon.main:app --host 127.0.0.1 --port 8000
# -> http://127.0.0.1:8000        (UI)
# -> http://127.0.0.1:8000/docs   (Swagger)

Desktop shell:

pip install -e ".[desktop]"
python -m netcanon_desktop

Run the test suite:

pytest                       # unit + integration + desktop (fast)
pytest -m e2e                # Playwright browser tests (slower)

Tests run across four layers: unit (pure functions, no I/O — the real-capture validation harness lives here as a unit subset), integration (TestClient + mocked SSH), e2e (Playwright against a live Uvicorn), and desktop (PySide6 + pystray mocked). CI output is the source of truth for pass counts.

---

Where to go next

You want to…	Start here
Understand the architecture	ARCHITECTURE.md — four-layer model, canonical bridge, codec types
Follow the contributor rules	CLAUDE.md — hard rules, parity checklist, gotchas
Look up project jargon	docs/glossary.md — canonical, codec, mesh, ship-before-wire, target profile, etc.
Read the canonical model overview	netcanon/migration/canonical/README.md — Tier 1 / 2 / 3 fields and promotion rules
Add or change an HTTP route	netcanon/api/routes/README.md — frozen pipeline-stage signatures, endpoint inventory
Add a new codec (vendor parser/renderer)	netcanon/migration/codecs/README.md
Add a new device definition / target profile	definitions/README.md — layered definitions (family base + os_version / model overlays), target-profile module-variant schema
Add a new canonical field	docs/adding-a-canonical-field.md — MTU as a worked example
Add a new target-profile YAML	docs/adding-a-target-profile.md — flat-port + module-variant shapes, fit-check propagation
Ship a feature across web + desktop	docs/feature-parity-walkthrough.md — SNMPv3 USM rename as a worked example
See what's shipped recently / current state	CHANGELOG.md — authoritative per-wave shipping log
Read the slower-changing architectural sketch	translator-plans.txt — dense, grep-friendly long-term roadmap; most R / GAP / Phase items now [SHIPPED]
Check codec certification tiers	tests/fixtures/real/RESULTS.md
Manually exercise recent changes	HUMAN_TESTING.md
Write tests	tests/README.md
Review the security model	SECURITY.md — threat model, controls, known limitations
Look up what Netcanon translates and what it doesn't	docs/CAPABILITIES.md — operator-facing capabilities, per-codec unsupported/lossy paths, Tier-3 boundary, notification surfaces

---

Layout

netcanon/              FastAPI application (shared by both platforms)
 ├── api/routes/          HTTP endpoints (backups, migration, configs, …)
 ├── collectors/          SSH/NETCONF/REST fetchers — one factory,
 │                        one mock-point (`get_collector`)
 ├── migration/           Cross-vendor translation pipeline
 │   ├── canonical/         CanonicalIntent model + shared transforms
 │   ├── codecs/            Per-vendor parse/render implementations
 │   └── ...
 ├── services/            Plain-function orchestrators (pipeline, detect, …)
 ├── storage/             FileConfigStore
 └── templates/           Jinja2 templates (every interactive element
                          must carry a data-testid — see CLAUDE.md)

netcanon_desktop/      Windows tray/webview shell around the same server
definitions/            Device definition YAMLs (shared with backup layer)
tests/unit/             Pure-function tests, no I/O
tests/integration/      FastAPI TestClient tests, SSH mocked at get_collector
tests/e2e/              Playwright browser tests against a live Uvicorn
tests/desktop/          PySide6/pystray-mocked desktop shell tests
tests/fixtures/real/    Real-capture validation corpus (see RESULTS.md)
scripts/                One-off utilities (Aruba template renderer, …)

---

Certification status

Per-codec certainty (read from CanonicalCodec.certainty at module load, surfaced via GET /api/v1/migration/adapters). See tests/fixtures/real/RESULTS.md for the live per-codec status — RESULTS.md is the source of truth and this README intentionally omits per-codec counts to avoid drift.

---

License

See SECURITY.md for responsible-disclosure policy. Project licence is per-file (most files are MIT; third-party fixtures keep their upstream licences — see tests/fixtures/real/NOTICE.md).