argus-netbox 0.1.2__py3-none-any.whl

argus/__init__.py

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

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/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/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/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/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/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/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

argus/discovery/collectors/unifi.py

@@ -0,0 +1,158 @@
+"""UniFi discovery collector.
+
+Pulls devices from the UniFi Network **Integration API** (X-API-KEY auth, read-only),
+mirroring the approach in the sibling ``aria-unifi-mcp`` server, and normalizes them into
+a :class:`DiscoveryResult`. Requires ``UNIFI_URL`` + ``UNIFI_API_TOKEN`` (see config).
+
+Endpoints used (base ``{UNIFI_URL}/proxy/network/integration/v1``):
+- ``GET /sites`` → ``{"data": [{id, internalReference, name}]}``
+- ``GET /sites/{site_id}/devices`` → ``{"data": [{name, mac, model, state, ipAddress, ...}]}``
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from ...config import get_settings
+from ..base import (
+    Collector,
+    DiscoveredClient,
+    DiscoveredDevice,
+    DiscoveredLink,
+    DiscoveryResult,
+)
+
+# Best-effort NetBox device-role inference from the UniFi model string. The Integration
+# API returns full model names ("UniFi Dream Machine PRO SE", "USW Pro 48 PoE", "U6 Pro"),
+# so match on keywords rather than code prefixes. Order matters — gateway is checked first.
+_ROLE_KEYWORDS: tuple[tuple[str, tuple[str, ...]], ...] = (
+    ("gateway", ("dream machine", "udm", "uxg", "ucg", "ugw", "cloud gateway", "security gateway", "gateway")),
+    ("switch", ("usw", "switch", "aggregation", "us-")),
+    ("ap", ("u6", "u7", "uap", "access point", "nanohd", "ac lite", "ac pro", "ac mesh")),
+)
+
+
+def _role_from_model(model: str | None) -> str | None:
+    if not model:
+        return None
+    text = model.lower()
+    for role, keywords in _ROLE_KEYWORDS:
+        if any(keyword in text for keyword in keywords):
+            return role
+    return None
+
+
+def _pick_site(sites: list[dict[str, Any]], reference: str) -> dict[str, Any] | None:
+    for site in sites:
+        if site.get("internalReference") == reference:
+            return site
+    return sites[0] if sites else None
+
+
+async def _get(client: httpx.AsyncClient, url: str) -> dict[str, Any]:
+    response = await client.get(url)
+    response.raise_for_status()
+    data: dict[str, Any] = response.json()
+    return data
+
+
+class UniFiCollector(Collector):
+    name = "unifi"
+
+    async def collect(self) -> DiscoveryResult:
+        settings = get_settings()
+        result = DiscoveryResult(collector=self.name)
+
+        if not settings.unifi_configured:
+            result.notes.append("UniFi not configured: set UNIFI_URL and UNIFI_API_TOKEN.")
+            return result
+
+        base = settings.unifi_url.rstrip("/") + "/proxy/network/integration/v1"
+        headers = {"X-API-KEY": settings.unifi_api_token, "Accept": "application/json"}
+
+        try:
+            async with httpx.AsyncClient(
+                headers=headers, verify=settings.unifi_verify_ssl, timeout=30.0
+            ) as client:
+                sites = (await _get(client, f"{base}/sites")).get("data", [])
+                site = _pick_site(sites, settings.unifi_site)
+                if site is None:
+                    result.notes.append("No UniFi sites returned by the controller.")
+                    return result
+                devices = (await _get(client, f"{base}/sites/{site['id']}/devices")).get(
+                    "data", []
+                )
+                # Clients are best-effort: a controller without the endpoint still yields devices.
+                try:
+                    clients = (
+                        await _get(client, f"{base}/sites/{site['id']}/clients?limit=200")
+                    ).get("data", [])
+                except httpx.HTTPError as exc:
+                    clients = []
+                    result.notes.append(f"UniFi clients endpoint unavailable: {exc}")
+                # Topology (best-effort): each device's detail carries its uplink device id.
+                uplinks: dict[str, str] = {}
+                for device in devices:
+                    did = device.get("id")
+                    if not did:
+                        continue
+                    try:
+                        detail = await _get(client, f"{base}/sites/{site['id']}/devices/{did}")
+                    except httpx.HTTPError:
+                        continue
+                    remote = (detail.get("uplink") or {}).get("deviceId")
+                    if remote:
+                        uplinks[did] = remote
+        except httpx.HTTPError as exc:
+            result.notes.append(f"UniFi API request failed: {exc}")
+            return result
+
+        site_name = site.get("name") or site.get("internalReference")
+        for device in devices:
+            ip = device.get("ipAddress") or device.get("ip")
+            result.devices.append(
+                DiscoveredDevice(
+                    name=device.get("name") or device.get("mac") or "unknown",
+                    mac=device.get("mac"),
+                    primary_ip=ip,
+                    site=site_name,
+                    role=_role_from_model(device.get("model")),
+                    model=device.get("model"),
+                    manufacturer="Ubiquiti",
+                    raw=device,
+                )
+            )
+            if ip:
+                result.ip_addresses.append(ip)
+
+        for entry in clients:
+            ip = entry.get("ipAddress") or entry.get("ip")
+            result.clients.append(
+                DiscoveredClient(
+                    mac=entry.get("macAddress") or entry.get("mac"),
+                    ip=ip,
+                    hostname=entry.get("name") or entry.get("hostname"),
+                    raw=entry,
+                )
+            )
+            if ip:
+                result.ip_addresses.append(ip)
+
+        id_to_name = {
+            d.get("id"): (d.get("name") or d.get("macAddress") or d.get("id"))
+            for d in devices
+            if d.get("id")
+        }
+        for local_id, remote_id in uplinks.items():
+            local = id_to_name.get(local_id)
+            remote = id_to_name.get(remote_id)
+            if local and remote:
+                result.links.append(DiscoveredLink(local_device=local, remote_device=remote))
+
+        result.notes.append(
+            f"Discovered {len(result.devices)} device(s), {len(result.clients)} client(s), "
+            f"{len(result.links)} link(s) from UniFi site '{site_name}'."
+        )
+        return result