Device Discovery & Inventory
Relevant source files
The following files were used as context for generating this wiki page:
Overview
The Device Discovery & Inventory system acts as the platform's eyes and memory, automatically finding your network hardware and keeping a detailed record of every device, interface, and connection. It solves the common problem of stale spreadsheets by building a live, multi-vendor inventory through protocols like SNMP and SSH.
The platform supports a wide range of vendors and protocols to ensure comprehensive visibility across the enterprise. Key design principles focus on being "local-first" and "self-hosted," ensuring your sensitive network data never leaves your infrastructure. Every change identified or requested must be approved by a human, and all AI reasoning is audited for transparency.
Supported Vendors and Protocols
- Vendors: Cisco (IOS, IOS-XE, NX-OS), Juniper JunOS, Arista EOS, Palo Alto PAN-OS, Fortinet FortiOS, F5 BIG-IP, BlueCat, Infoblox, AWS, Azure, and VMware.
- Protocols: SNMP, SSH, APIs, LLDP, CDP, and Route collection.
Sources: CLAUDE.md
Specialist Agents
In this platform, "Agents" are like specialized team members that the system routes your requests to based on their expertise:
- Master Architect: The supervisor who decides which specialist should handle your question.
- Discovery Agent: The specialist focused on enumerating and inspecting the managed-device inventory.
- Troubleshooting Agent: Diagnoses live faults, such as routing or BGP issues.
- DDI Agent: Manages DNS, DHCP, and IPAM (IP Address Management).
Sources: backend/app/llm/prompts/init.py:183-255, backend/app/agents/documentation/agent.py:59-65
Architecture
The platform is built using seven core components that work together to provide a seamless experience for network operations.
- frontend: The web console where you chat with the AI, view your topology map, and approve changes.
- api: The central brain that handles your requests and coordinates between the web console and the background engines.
- worker: The background engine that runs discovery jobs, takes configuration backups, and captures packets without blocking your session.
- postgres: The main database (system of record) that stores your device inventory and audit logs.
- neo4j: A living topology map that tracks how every device, interface, subnet, and application connects to everything else.
- redis: A fast message carrier that passes jobs from the API to the workers and stores temporary data.
- ollama: The local AI engine that provides reasoning and intelligence without sending data to the cloud.
Sources: README.md, deploy/docker/README.md
Vendor Plugin System
The platform uses a standardized connector for each vendor. No matter whether you are talking to a Cisco router, a Juniper switch, or a BlueCat Address Manager, the platform normalizes the output into a consistent format before doing anything with it. This allows the AI to understand your network regardless of the underlying hardware brands.
Sources: README.md, backend/app/agents/documentation/agent.py:27-35
Deployment Options
- Docker Compose: A single-server setup that is ideal for a lab environment or a small team. It runs all components as containers on one machine.
- Kubernetes/Helm: A production-grade deployment for multi-node, highly available environments. It includes hardening features like NetworkPolicies and automated backups.
Sources: deploy/docker/README.md, deploy/kubernetes/netops/README.md
Change Approval Workflow
Every modification to the network follows a strict safety process:
- Draft: An agent creates a proposed change based on your request.
- Pending Approval: The change waits for a human engineer to review it in the web console.
- Approved: A human clicks "Approve," authorizing the execution.
- Executing: The platform takes a pre-change configuration backup and then applies the change.
- Completed or Rolled Back: If the change fails, the platform can restore the previous configuration from the backup.
Sources: README.md, backend/app/agents/ddi/agent.py:18-28
Discovery Process & Data Model
The Discovery Agent is responsible for "enumeration"—listing what exists in the network rather than diagnosing faults. It collects data on devices, interfaces, neighbors, and routes.
Sources: backend/app/llm/prompts/init.py:183-205, backend/app/agents/documentation/agent.py:59-65
Inventory Data Model
The platform tracks several key entities to build its understanding of the network:
| Entity | Description | Key Fields |
|---|---|---|
| Device | The physical or virtual hardware. | Hostname, MGMT IP, Vendor, Model, Serial. |
| Interface | Physical or logical ports on a device. | Name, Description, IP Address, Admin/Oper Status. |
| Neighbor | Adjacent devices discovered via LLDP or CDP. | Local Port, Neighbor Name, Neighbor Port. |
| Route | Routing table entries for L3 reachability. | Prefix, Protocol (OSPF/BGP), Next Hop. |
Sources: backend/scripts/seed_smb_scenario.py:46-135, backend/app/agents/documentation/agent.py:59-65
System Overview
This diagram shows how users interact with the platform and what external systems it connects to.
Sources: README.md, deploy/docker/docker-compose.yml
Agent Routing
When you send a message, the Master Architect determines which specialist needs to step in.
Topology Data Model
This diagram shows how the platform relates different pieces of network information to build a complete map.
Configuration Example
The following snippet shows how a device and its interfaces are represented in the platform's inventory seeding system.
# A four-device network for Northwind Traders
DEVICES = [
{
"mgmt_ip": "10.0.0.1",
"hostname": "edge-fw-01", # Unique name for the device
"vendor_id": "paloalto_panos",
"model": "PA-440",
"interfaces": [
# interface name, description, admin state, oper state, IP address, speed, vlan
("ethernet1/1", "ISP uplink", "UP", "UP", "203.0.113.2", 1000, None),
("ethernet1/2", "LAN trunk", "UP", "UP", "10.0.0.1", 1000, 1),
],
}
]
Sources: backend/scripts/seed_smb_scenario.py:61-75
Summary
The Device Discovery & Inventory system provides the foundational data required for all other platform features. By automating the collection of multi-vendor device data and visualizing it through a live topology map, it enables network engineers to spend less time manually updating documentation and more time resolving complex infrastructure issues. All data is kept secure through local-first deployment and a human-in-the-loop approval process for every change.