argus-netbox 0.1.2__tar.gz

argus_netbox-0.1.2/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: argus-netbox
+Version: 0.1.2
+Summary: NetBox-backed network source-of-truth automation server for MCP coding agents
+Author: Jon Freed
+License-Expression: Apache-2.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: mcp>=1.28.0
+Requires-Dist: pynetbox>=7.3
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: fastapi>=0.137.1
+Requires-Dist: uvicorn>=0.34
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: pydantic-settings>=2.3
+Provides-Extra: discovery
+Requires-Dist: napalm>=5.1.0; extra == "discovery"
+Requires-Dist: netmiko>=4.3; extra == "discovery"
+Requires-Dist: pysnmp>=7.1.27; extra == "discovery"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=1.4.0; extra == "dev"
+Requires-Dist: pytest-cov>=7.1.0; extra == "dev"
+Requires-Dist: respx>=0.23.1; extra == "dev"
+Requires-Dist: ruff>=0.15.17; extra == "dev"
+Requires-Dist: mypy>=2.1.0; extra == "dev"
+
+# Argus server
+
+Python MCP + FastAPI server. NetBox source-of-truth tools for coding agents and the
+Argus web dashboard. See the [top-level README](../README.md) and
+[docs/ARCHITECTURE.md](../docs/ARCHITECTURE.md).
+
+## Install
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Configure
+
+Copy `.env.example` to `.env` (or export the vars):
+
+```bash
+NETBOX_URL=https://netbox.lan
+NETBOX_TOKEN=<netbox api token>
+NETBOX_VERIFY_SSL=true
+HTTP_HOST=0.0.0.0
+HTTP_PORT=8080
+```
+
+If unset, tools return a clear "NetBox not configured" message instead of erroring.
+
+## Run
+
+```bash
+argus-mcp     # MCP server over stdio (for Claude Code etc.)
+argus-http    # FastAPI HTTP server on :8080 (for the web app + webhooks)
+```
+
+## Develop
+
+```bash
+ruff check src tests
+mypy src
+pytest -v          # offline — NetBox is mocked
+```
+
+## Tools
+
+| Tool | Kind | Status |
+| --- | --- | --- |
+| `list_devices`, `get_device`, `list_prefixes`, `list_ip_addresses`, `search` | read | real (needs NetBox) |
+| `list_collectors`, `discovery_scan`, `network_topology` | discovery | UniFi real — devices + clients + uplink topology (needs `UNIFI_*`); SNMP/LLDP real for non-UniFi gear (needs `SNMP_TARGETS` + `argus[discovery]`) |
+| `drift_report`, `reconcile_apply` | reconcile | real — diffs and (on confirm) persists, auto-creating supporting NetBox objects |
+| `health` | meta | real |

argus_netbox-0.1.2/README.md

@@ -0,0 +1,50 @@
+# Argus server
+
+Python MCP + FastAPI server. NetBox source-of-truth tools for coding agents and the
+Argus web dashboard. See the [top-level README](../README.md) and
+[docs/ARCHITECTURE.md](../docs/ARCHITECTURE.md).
+
+## Install
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Configure
+
+Copy `.env.example` to `.env` (or export the vars):
+
+```bash
+NETBOX_URL=https://netbox.lan
+NETBOX_TOKEN=<netbox api token>
+NETBOX_VERIFY_SSL=true
+HTTP_HOST=0.0.0.0
+HTTP_PORT=8080
+```
+
+If unset, tools return a clear "NetBox not configured" message instead of erroring.
+
+## Run
+
+```bash
+argus-mcp     # MCP server over stdio (for Claude Code etc.)
+argus-http    # FastAPI HTTP server on :8080 (for the web app + webhooks)
+```
+
+## Develop
+
+```bash
+ruff check src tests
+mypy src
+pytest -v          # offline — NetBox is mocked
+```
+
+## Tools
+
+| Tool | Kind | Status |
+| --- | --- | --- |
+| `list_devices`, `get_device`, `list_prefixes`, `list_ip_addresses`, `search` | read | real (needs NetBox) |
+| `list_collectors`, `discovery_scan`, `network_topology` | discovery | UniFi real — devices + clients + uplink topology (needs `UNIFI_*`); SNMP/LLDP real for non-UniFi gear (needs `SNMP_TARGETS` + `argus[discovery]`) |
+| `drift_report`, `reconcile_apply` | reconcile | real — diffs and (on confirm) persists, auto-creating supporting NetBox objects |
+| `health` | meta | real |

argus_netbox-0.1.2/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["setuptools>=77.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "argus-netbox"
+version = "0.1.2"
+description = "NetBox-backed network source-of-truth automation server for MCP coding agents"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.12"
+authors = [{ name = "Jon Freed" }]
+dependencies = [
+    "mcp>=1.28.0",
+    "pynetbox>=7.3",
+    "httpx>=0.28.1",
+    "fastapi>=0.137.1",
+    "uvicorn>=0.34",
+    "pydantic>=2.13.4",
+    "pydantic-settings>=2.3",
+]
+
+[project.optional-dependencies]
+# Heavy network-discovery libraries — declared for P1, not used by the scaffold yet.
+discovery = [
+    "napalm>=5.1.0",
+    "netmiko>=4.3",
+    "pysnmp>=7.1.27",
+]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=1.4.0",
+    "pytest-cov>=7.1.0",
+    "respx>=0.23.1",
+    "ruff>=0.15.17",
+    "mypy>=2.1.0",
+]
+
+[project.scripts]
+argus-mcp = "argus.server:main"
+argus-http = "argus.http_server:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+ignore = ["E501"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["argus"]
+
+[tool.mypy]
+python_version = "3.12"
+warn_return_any = true
+warn_unused_configs = true
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

argus_netbox-0.1.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

argus_netbox-0.1.2/src/argus/__init__.py

@@ -0,0 +1,3 @@
+"""Argus — NetBox-backed network source-of-truth automation server."""
+
+__version__ = "0.1.2"

argus_netbox-0.1.2/src/argus/config.py

@@ -0,0 +1,68 @@
+"""Application settings, resolved from environment variables (and an optional .env)."""
+
+from __future__ import annotations
+
+from functools import lru_cache
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """Argus runtime configuration.
+
+    Environment variables are matched case-insensitively, so ``NETBOX_URL`` maps to
+    :attr:`netbox_url`. A local ``.env`` file is read if present.
+    """
+
+    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
+
+    # NetBox (the source of truth)
+    netbox_url: str = ""
+    netbox_token: str = ""
+    netbox_verify_ssl: bool = True
+
+    # UniFi Network controller (discovery collector — Integration API, X-API-KEY)
+    unifi_url: str = ""
+    unifi_api_token: str = ""
+    unifi_site: str = "default"
+    unifi_verify_ssl: bool = False  # UniFi controllers use self-signed certs
+
+    # SNMP/LLDP collector (generic, for non-UniFi gear). Comma-separated host[:community].
+    snmp_targets: str = ""
+    snmp_community: str = "public"
+
+    # FastAPI HTTP server
+    http_host: str = "0.0.0.0"
+    http_port: int = 8080
+    http_token: str = ""  # optional static bearer token; unset disables auth
+
+    # Scheduled discovery + drift alerting (in-process asyncio loop; opt-in)
+    schedule_interval: int = 0  # seconds between drift cycles; 0 disables (e.g. 300 = 5 min)
+    schedule_collector: str = "unifi"  # collector the scheduled drift cycle observes
+    alert_webhook_url: str = ""  # Slack-compatible webhook; alert fires only on drift when set
+
+    @property
+    def http_auth_enabled(self) -> bool:
+        """True when a static bearer token is configured for the HTTP API."""
+        return bool(self.http_token)
+
+    @property
+    def schedule_enabled(self) -> bool:
+        """True when the scheduled drift loop is enabled (a positive interval is set)."""
+        return self.schedule_interval > 0
+
+    @property
+    def netbox_configured(self) -> bool:
+        """True when both a NetBox URL and token are set."""
+        return bool(self.netbox_url and self.netbox_token)
+
+    @property
+    def unifi_configured(self) -> bool:
+        """True when both a UniFi URL and API token are set."""
+        return bool(self.unifi_url and self.unifi_api_token)
+
+
+@lru_cache
+def get_settings() -> Settings:
+    """Return the cached settings instance."""
+    return Settings()

argus_netbox-0.1.2/src/argus/confirmations.py

@@ -0,0 +1,79 @@
+"""Confirmation store gating state-changing actions (e.g. reconcile apply).
+
+A tool returns a confirmation token instead of acting; a second, explicit call with that
+token performs the action. Tokens expire after a short TTL. This keeps an agent from
+silently mutating the source of truth.
+"""
+
+from __future__ import annotations
+
+import secrets
+from dataclasses import dataclass, field
+from datetime import UTC, datetime, timedelta
+from typing import Any
+
+
+@dataclass
+class PendingAction:
+    """An action awaiting explicit confirmation."""
+
+    action_id: str
+    tool_name: str
+    description: str
+    created_at: datetime
+    expires_at: datetime
+    tool_args: dict[str, Any] = field(default_factory=dict)
+
+
+class ConfirmationStore:
+    """In-memory store of pending, confirmable actions."""
+
+    def __init__(self, ttl_minutes: int = 5) -> None:
+        self._actions: dict[str, PendingAction] = {}
+        self.ttl = timedelta(minutes=ttl_minutes)
+
+    def create(
+        self, tool_name: str, description: str, tool_args: dict[str, Any] | None = None
+    ) -> PendingAction:
+        """Register a pending action and return it (with its ``action_id``)."""
+        self.cleanup_expired()
+        now = datetime.now(UTC)
+        action = PendingAction(
+            action_id=secrets.token_urlsafe(16),
+            tool_name=tool_name,
+            description=description,
+            created_at=now,
+            expires_at=now + self.ttl,
+            tool_args=tool_args or {},
+        )
+        self._actions[action.action_id] = action
+        return action
+
+    def get(self, action_id: str) -> PendingAction | None:
+        """Return a pending action, or ``None`` if missing or expired."""
+        action = self._actions.get(action_id)
+        if action and datetime.now(UTC) > action.expires_at:
+            del self._actions[action_id]
+            return None
+        return action
+
+    def confirm(self, action_id: str) -> tuple[PendingAction | None, str | None]:
+        """Consume and return an action. Returns ``(action, error)``."""
+        action = self.get(action_id)
+        if not action:
+            return None, "Action expired or not found."
+        del self._actions[action_id]
+        return action, None
+
+    def cleanup_expired(self) -> int:
+        """Drop expired actions; return how many were removed."""
+        now = datetime.now(UTC)
+        expired = [aid for aid, a in self._actions.items() if a.expires_at < now]
+        for aid in expired:
+            del self._actions[aid]
+        return len(expired)
+
+    def list_pending(self) -> list[PendingAction]:
+        """Return all currently pending (non-expired) actions."""
+        self.cleanup_expired()
+        return list(self._actions.values())

argus_netbox-0.1.2/src/argus/discovery/__init__.py

@@ -0,0 +1,17 @@
+"""Discovery layer: pluggable collectors that observe live network state."""
+
+from .base import (
+    Collector,
+    DiscoveredClient,
+    DiscoveredDevice,
+    DiscoveredLink,
+    DiscoveryResult,
+)
+
+__all__ = [
+    "Collector",
+    "DiscoveredClient",
+    "DiscoveredDevice",
+    "DiscoveredLink",
+    "DiscoveryResult",
+]

argus_netbox-0.1.2/src/argus/discovery/base.py

@@ -0,0 +1,71 @@
+"""Discovery interfaces.
+
+A :class:`Collector` observes live network state from one source and returns a
+normalized :class:`DiscoveryResult`. Collectors are read-only against the network — the
+only writes Argus makes are into NetBox, via the reconcile engine (see ADR-0003).
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class DiscoveredDevice:
+    """A device observed on the live network, normalized across collectors."""
+
+    name: str
+    mac: str | None = None
+    primary_ip: str | None = None
+    site: str | None = None
+    role: str | None = None
+    model: str | None = None
+    manufacturer: str | None = None
+    raw: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class DiscoveredClient:
+    """An endpoint/client observed on the network (the IP/MAC-binding side)."""
+
+    mac: str | None = None
+    ip: str | None = None
+    hostname: str | None = None
+    raw: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class DiscoveredLink:
+    """A directed link between two devices (e.g. a device and its uplink)."""
+
+    local_device: str
+    remote_device: str
+    local_port: str | None = None
+    remote_port: str | None = None
+    raw: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class DiscoveryResult:
+    """The normalized output of a single collector run."""
+
+    collector: str
+    devices: list[DiscoveredDevice] = field(default_factory=list)
+    clients: list[DiscoveredClient] = field(default_factory=list)
+    links: list[DiscoveredLink] = field(default_factory=list)
+    ip_addresses: list[str] = field(default_factory=list)
+    notes: list[str] = field(default_factory=list)
+
+
+class Collector(ABC):
+    """Observes live network state from one source."""
+
+    #: Stable, unique collector name (used in the registry and as a tool argument).
+    name: str = "base"
+
+    @abstractmethod
+    async def collect(self) -> DiscoveryResult:
+        """Collect current state from this source."""
+        raise NotImplementedError

argus_netbox-0.1.2/src/argus/discovery/collectors/__init__.py

@@ -0,0 +1,16 @@
+"""Discovery collector registry — name → collector class."""
+
+from __future__ import annotations
+
+from ..base import Collector
+from .dhcp_arp import DhcpArpCollector
+from .snmp_lldp import SnmpLldpCollector
+from .unifi import UniFiCollector
+
+COLLECTORS: dict[str, type[Collector]] = {
+    UniFiCollector.name: UniFiCollector,
+    SnmpLldpCollector.name: SnmpLldpCollector,
+    DhcpArpCollector.name: DhcpArpCollector,
+}
+
+__all__ = ["COLLECTORS", "DhcpArpCollector", "SnmpLldpCollector", "UniFiCollector"]

argus_netbox-0.1.2/src/argus/discovery/collectors/dhcp_arp.py

@@ -0,0 +1,19 @@
+"""DHCP / ARP collector (stub).
+
+Planned P1: read DHCP leases and ARP tables to learn IP/MAC bindings.
+See docs/ROADMAP.md.
+"""
+
+from __future__ import annotations
+
+from ..base import Collector, DiscoveryResult
+
+
+class DhcpArpCollector(Collector):
+    name = "dhcp_arp"
+
+    async def collect(self) -> DiscoveryResult:
+        return DiscoveryResult(
+            collector=self.name,
+            notes=["DHCP/ARP collector not yet implemented (planned P1)."],
+        )

argus_netbox-0.1.2/src/argus/discovery/collectors/snmp_lldp.py

@@ -0,0 +1,112 @@
+"""SNMP / LLDP discovery collector (generic, for non-UniFi gear).
+
+Per target: SNMP GET ``sysName`` + an LLDP-MIB neighbor walk for links. Configured via
+``SNMP_TARGETS`` (comma-separated ``host[:community]``) and ``SNMP_COMMUNITY``. Requires the
+optional ``discovery`` extra: ``pip install 'argus[discovery]'`` (pysnmp).
+
+NOTE: the pysnmp glue (`_query_target`) is best-effort and **unvalidated against live SNMP
+devices**; the collector logic (config parsing, mapping, links) is unit-tested by mocking it.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from ...config import get_settings
+from ..base import Collector, DiscoveredDevice, DiscoveredLink, DiscoveryResult
+
+logger = logging.getLogger(__name__)
+
+SYSNAME_OID = "1.3.6.1.2.1.1.5.0"
+LLDP_REM_SYSNAME_OID = "1.0.8802.1.1.2.1.4.1.1.9"
+
+
+def _parse_targets(raw: str, default_community: str) -> list[tuple[str, str]]:
+    """Parse ``host[:community],host2,...`` into (host, community) pairs."""
+    targets: list[tuple[str, str]] = []
+    for item in raw.split(","):
+        item = item.strip()
+        if not item:
+            continue
+        host, _, community = item.partition(":")
+        targets.append((host.strip(), community.strip() or default_community))
+    return targets
+
+
+async def _query_target(host: str, community: str) -> tuple[str | None, list[str]]:
+    """Return ``(sysName, [neighbor sysNames])`` for a target. Raises ImportError if pysnmp
+    is absent; other failures are caught by the caller."""
+    from pysnmp.hlapi.asyncio import (
+        CommunityData,
+        ContextData,
+        ObjectIdentity,
+        ObjectType,
+        SnmpEngine,
+        UdpTransportTarget,
+        get_cmd,
+        walk_cmd,
+    )
+
+    engine = SnmpEngine()
+    auth = CommunityData(community, mpModel=1)
+    transport = await UdpTransportTarget.create((host, 161))
+
+    err_ind, err_stat, _, var_binds = await get_cmd(
+        engine, auth, transport, ContextData(), ObjectType(ObjectIdentity(SYSNAME_OID))
+    )
+    if err_ind or err_stat or not var_binds:
+        return None, []
+    sysname = str(var_binds[0][1])
+
+    neighbors: list[str] = []
+    try:
+        async for w_err_ind, w_err_stat, _, w_binds in walk_cmd(
+            engine, auth, transport, ContextData(), ObjectType(ObjectIdentity(LLDP_REM_SYSNAME_OID))
+        ):
+            if w_err_ind or w_err_stat:
+                break
+            for _, value in w_binds:
+                name = str(value).strip()
+                if name:
+                    neighbors.append(name)
+    except Exception as exc:  # LLDP is optional; keep the device even if the walk fails
+        logger.debug("LLDP walk failed for %s: %s", host, exc)
+
+    return sysname, neighbors
+
+
+class SnmpLldpCollector(Collector):
+    name = "snmp_lldp"
+
+    async def collect(self) -> DiscoveryResult:
+        settings = get_settings()
+        result = DiscoveryResult(collector=self.name)
+        targets = _parse_targets(settings.snmp_targets, settings.snmp_community)
+
+        if not targets:
+            result.notes.append("SNMP not configured: set SNMP_TARGETS (host[:community],...).")
+            return result
+
+        for host, community in targets:
+            try:
+                sysname, neighbors = await _query_target(host, community)
+            except ImportError:
+                result.notes.append("pysnmp not installed: pip install 'argus[discovery]'.")
+                return result
+            except Exception as exc:
+                result.notes.append(f"SNMP query failed for {host}: {exc}")
+                continue
+
+            if not sysname:
+                result.notes.append(f"No SNMP response from {host}.")
+                continue
+
+            result.devices.append(DiscoveredDevice(name=sysname, primary_ip=host))
+            for neighbor in neighbors:
+                result.links.append(DiscoveredLink(local_device=sysname, remote_device=neighbor))
+
+        result.notes.append(
+            f"SNMP: {len(result.devices)} device(s), {len(result.links)} link(s) "
+            f"from {len(targets)} target(s)."
+        )
+        return result