{"id":51277032,"url":"https://github.com/freed-dev-llc/argus","last_synced_at":"2026-06-29T21:32:24.649Z","repository":{"id":365783167,"uuid":"1272524057","full_name":"freed-dev-llc/argus","owner":"freed-dev-llc","description":"NetBox-backed network source-of-truth automation for MCP coding agents — discovers live network state, diffs it against NetBox, and reconciles under confirmation gating. Python MCP + FastAPI server with a React dashboard.","archived":false,"fork":false,"pushed_at":"2026-06-25T22:09:12.000Z","size":387,"stargazers_count":1,"open_issues_count":13,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-25T23:10:46.801Z","etag":null,"topics":["ansible","dcim","fastapi","ipam","mcp","model-context-protocol","netbox","network-automation","network-discovery","networking","python","react","snmp","source-of-truth","typescript","unifi"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/freed-dev-llc.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":"docs/ROADMAP.md","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-06-17T17:35:02.000Z","updated_at":"2026-06-25T22:08:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/freed-dev-llc/argus","commit_stats":null,"previous_names":["freed-dev-llc/argus"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/freed-dev-llc/argus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freed-dev-llc%2Fargus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freed-dev-llc%2Fargus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freed-dev-llc%2Fargus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freed-dev-llc%2Fargus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/freed-dev-llc","download_url":"https://codeload.github.com/freed-dev-llc/argus/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freed-dev-llc%2Fargus/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34944147,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-29T02:00:05.398Z","response_time":58,"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":["ansible","dcim","fastapi","ipam","mcp","model-context-protocol","netbox","network-automation","network-discovery","networking","python","react","snmp","source-of-truth","typescript","unifi"],"created_at":"2026-06-29T21:32:23.943Z","updated_at":"2026-06-29T21:32:24.632Z","avatar_url":"https://github.com/freed-dev-llc.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Argus\n\n![Argus Net](docs/assets/argus/logos/argus_logo_horizontal.svg)\n\n[![CI](https://github.com/freed-dev-llc/argus/actions/workflows/ci.yml/badge.svg)](https://github.com/freed-dev-llc/argus/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/argus-netbox.svg)](https://pypi.org/project/argus-netbox/)\n[![Python](https://img.shields.io/pypi/pyversions/argus-netbox.svg)](https://pypi.org/project/argus-netbox/)\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)\n\n\u003e The all-seeing keeper of your network's truth.\n\n**Argus** is a home- and lab-network automation server built on\n[NetBox](https://netbox.dev). It treats NetBox as the **single source of truth (SoT)**\nfor your network and works to keep that truth *continuously reflecting reality* —\ndevices, IP addresses, prefixes, cabling, and topology — by **discovering** the live\nnetwork, **diffing** it against NetBox, and **reconciling** the difference.\n\nArgus exposes this capability to **MCP-compliant coding agents** (Claude Code, Codex,\nKimi, …) as a set of tools, and ships a small React dashboard to query state, review\ndrift, and trigger reconciliation by hand.\n\nIn Greek myth, Argus Panoptes was the hundred-eyed giant who never slept and saw\neverything. That's the job: always watching, always keeping the record true.\n\n\u003e **Status:** v0.1.7 — the full loop works end-to-end and is validated against a live UniFi\n\u003e network + NetBox 4.6: discover (devices, clients, uplink topology) → diff → confirm →\n\u003e reconcile NetBox (DCIM + IPAM), surfaced via MCP tools, a React dashboard, and Ansible\n\u003e inventory. See [docs/ROADMAP.md](docs/ROADMAP.md) and [CHANGELOG.md](CHANGELOG.md).\n\n**Part of the freed-dev-llc agent family** — Argus is shared tooling for the AI assistants [Aria](https://github.com/freed-dev-llc/aria), [Leeloo](https://github.com/freed-dev-llc/leeloo), and [Elara](https://github.com/freed-dev-llc/elara); sibling tools are [Reach](https://github.com/freed-dev-llc/reach) (remote access), [Sisyphus](https://github.com/freed-dev-llc/sisyphus) (workflow automation), and [Mnemosyne](https://github.com/freed-dev-llc/mnemosyne) (RAG knowledge brain — it *explains* the vendors Argus *discovers*).\n\n[![Aria — freed-dev-llc/aria](docs/assets/buttons/btn_aria.svg)](https://github.com/freed-dev-llc/aria)\n[![Leeloo — freed-dev-llc/leeloo](docs/assets/buttons/btn_leeloo.svg)](https://github.com/freed-dev-llc/leeloo)\n[![Elara — freed-dev-llc/elara](docs/assets/buttons/btn_elara.svg)](https://github.com/freed-dev-llc/elara)\n[![Reach — freed-dev-llc/reach](docs/assets/buttons/btn_reach.svg)](https://github.com/freed-dev-llc/reach)\n[![Sisyphus — freed-dev-llc/sisyphus](docs/assets/buttons/btn_sisyphus.svg)](https://github.com/freed-dev-llc/sisyphus)\n[![Mnemosyne — freed-dev-llc/mnemosyne](docs/assets/buttons/btn_mnemosyne.svg)](https://github.com/freed-dev-llc/mnemosyne)\n[![Helios — freed-dev-llc/helios](docs/assets/buttons/btn_helios.svg)](https://github.com/freed-dev-llc/helios)\n\n## How it fits together\n\n```\nCollectors (UniFi / SNMP-LLDP / DHCP-ARP …) ─► normalize ─► diff vs NetBox ─► reconcile plan ─► apply\n        (server/src/argus/discovery/)                          (reconcile/)     (dry-run default,\n                                                                                 confirmation-gated)\nNetBox ◄── pynetbox client ──► MCP tools (server/src/argus/tools/) ──► coding agents\n                            └─► FastAPI (http_server.py) ──► React dashboard (web/)\n```\n\nNetBox is authoritative; Argus never invents truth — it makes NetBox match what it\nobserves. Writes are **dry-run by default** and real changes are **confirmation-gated**.\nSee [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) and the\n[Architecture Decision Records](docs/architecture/adr/).\n\nThe HTTP server also keeps the record current on its own: it receives NetBox **webhooks**\n(`POST /webhooks/netbox`, classify + structured-log) and can run an **opt-in scheduled drift\nloop** (`SCHEDULE_INTERVAL`) that diffs on an interval — read-only — serving the latest result at\n`GET /api/drift/status` and firing an optional alert webhook (`ALERT_WEBHOOK_URL`) on drift.\nOptional **bearer-token auth** (`HTTP_TOKEN`) gates `/api` + `/webhooks`. See\n[server/README.md](server/README.md) for setup and copy-pasteable examples.\n\n**Vendor packs.** Discovery is a host/plugin layer\n([ADR-0005](docs/architecture/adr/0005-vendor-packs.md)): each vendor is a self-contained\n`VendorPack` (a read-only collector + declarative metadata) discovered via an\n`argus.vendor_packs` entry point, so packs can live out-of-tree and ship independently.\nUniFi ships in-tree; build your own from\n[**argus-vendor-pack-template**](https://github.com/freed-dev-llc/argus-vendor-pack-template)\n(a GitHub “Use this template” repo). See [docs/VENDOR_PACKS.md](docs/VENDOR_PACKS.md) to\ninstall or add packs.\n\n## Repository layout\n\n| Path | What |\n| --- | --- |\n| `server/` | Python MCP + FastAPI server (`mcp`, `fastapi`, `pynetbox`) |\n| `web/` | React + Vite + TypeScript dashboard |\n| `docs/` | Architecture, roadmap, and ADRs |\n| `.github/` | CI, Dependabot, issue/PR templates, CODEOWNERS |\n\n## Quickstart\n\n### Server\n\n```bash\ncd server\npython -m venv .venv \u0026\u0026 source .venv/bin/activate\npip install -e \".[dev]\"\n\n# Point Argus at your NetBox (see .env.example)\nexport NETBOX_URL=\"https://netbox.lan\"\nexport NETBOX_TOKEN=\"\u003ca NetBox API token\u003e\"\n\nargus-http        # FastAPI on :8080  (used by the web app)\nargus-mcp         # MCP server over stdio (used by coding agents)\n\nargus-maint-mcp   # separate maintenance MCP surface — release preview/verify (devtools; read-only)\n```\n\nIf `NETBOX_URL` / `NETBOX_TOKEN` are unset, tools return a clear \"NetBox not\nconfigured\" message rather than failing — handy for first-run exploration.\n\n### Web dashboard\n\n```bash\ncd web\nnpm install\nnpm run dev       # http://localhost:5173 — proxies /api to the server on :8080\n```\n\n### Use from a coding agent (MCP)\n\n`.mcp.json` at the repo root registers the `argus` server. With the package installed\n(`pip install -e server`), Claude Code (and other MCP clients) can call:\n\n- `list_devices`, `get_device`, `list_prefixes`, `list_ip_addresses`, `search` — read NetBox\n- `list_collectors`, `discovery_scan`, `network_topology` — observe live network state + topology\n- `drift_report`, `reconcile_apply` — review and apply reconciliation (confirmation-gated)\n- `evaluate_practices` — run a collector's best-practice rules for advisory findings (read-only)\n\n## Deployment\n\nFor a complete, self-contained environment (NetBox + its datastore + Argus server + web),\nsee [`deploy/`](deploy/README.md): `docker compose --env-file .env up -d --build` brings up\na bundled NetBox (auto-provisioned with the API token Argus uses) plus the Argus server and\ndashboard. Intended for validation and home/lab use.\n\n### Published artifacts\n\nReleased `v*` tags publish to GHCR and PyPI:\n\n- **Container images** — `ghcr.io/freed-dev-llc/argus-server` and\n  `ghcr.io/freed-dev-llc/argus-web` (tags `0.1.7` and `latest`):\n\n  ```bash\n  docker pull ghcr.io/freed-dev-llc/argus-server:0.1.7\n  docker pull ghcr.io/freed-dev-llc/argus-web:0.1.7\n  ```\n\n- **Python package** — the server installs from PyPI as `argus-netbox` (the import package stays\n  `argus`; the console scripts are `argus-mcp` / `argus-http`):\n\n  ```bash\n  pip install argus-netbox\n  argus-http        # FastAPI server on :8080   ·   argus-mcp = MCP over stdio\n  ```\n\n## Integrations\n\nArgus is the **inbound** source-of-truth layer; outbound automation consumes NetBox:\n\n- **Ansible** ([`ansible/`](ansible/README.md)) — read-only `nb_inventory` dynamic inventory\n  sourced from the NetBox Argus keeps current; target hosts by site/role with no\n  hand-maintained inventory. See [ADR-0004](docs/architecture/adr/0004-netbox-ansible-inventory.md)\n  for how Argus, Ansible, and (future) Terraform share NetBox without fighting over it.\n\n## Contributing\n\nThis is a personal project run with the discipline of a shared one: changes land via\n**signed-commit pull requests** with a CHANGELOG entry, decisions are captured as\n**ADRs**, and work is tracked in **issues**. See [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## License\n\n[Apache-2.0](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffreed-dev-llc%2Fargus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffreed-dev-llc%2Fargus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffreed-dev-llc%2Fargus/lists"}