Audit Logging & Traceability
Relevant source files
The following files were used as context for generating this wiki page:
Overview
The AI Network Operations Platform is a self-hosted assistant designed for network engineering teams to manage multi-vendor infrastructure using plain English. It solves the problem of manual, error-prone configuration and troubleshooting by providing an AI-driven interface that can discover inventory, build topology maps, and analyze complex network issues across vendors like Cisco, Juniper, Arista, Palo Alto, and Fortinet.
The platform follows a "local-first" philosophy, meaning it runs within your own data center or cloud environment to keep sensitive data secure. A core design principle is that every network change requires human approval before execution. To ensure accountability, the platform implements "Audit Everything": every AI decision, reasoning step, and command execution is logged and verified using a secure hash-chain to prevent tampering.
In this platform, "Agents" are specialized team members that the platform routes your questions to. For example, if you ask about a BGP fault, the Master Architect (the team lead) routes the request to the Troubleshooting Agent. If you ask for a DNS change, it goes to the DDI Agent to draft a request for your approval.
Sources: CLAUDE.md:1-35, README.md:1-15, deploy/kubernetes/netops/templates/NOTES.txt:1-10
Architecture
The platform consists of several interconnected components working together to provide a seamless operations experience:
- frontend: The operations console where you chat with the AI, view the topology map, and manage approvals.
- api: The entry point that handles user requests, authentication, and manages the various AI agent sessions.
- worker: The background engine that runs time-consuming jobs like discovering new devices, taking configuration backups, or capturing packets without blocking your session.
- postgres: The primary system of record that stores information about your devices, user accounts, and the secure audit logs.
- neo4j: A living topology map that tracks how every device, interface, subnet, and application connects to everything else.
- redis: A fast temporary storage used to manage the communication between the API and the background workers.
- ollama: An optional local engine that runs the AI models (LLMs) entirely on your own hardware so no data leaves your network.
To support different hardware, the platform uses a standardized "vendor plugin" system. This acts as a connector for each vendor; whether you are talking to a Cisco router, a Juniper switch, or a BlueCat IPAM, the platform normalizes the specific commands and outputs into a consistent format before the AI processes it.
Sources: README.md:17-35, deploy/docker/README.md:1-15
Deployment Options
The platform supports two main deployment methods depending on your environment:
- Docker Compose: Best for laboratory environments or small teams. It runs all components on a single server using a single configuration file.
- Kubernetes/Helm: The production-ready option for high-scale environments. It supports multi-node deployments and provides hardened security features like automated certificates and network segmentation.
Sources: README.md:38-45, deploy/kubernetes/netops/README.md:1-10
Change Approval Workflow
Security is maintained through a strict "Human-in-the-Loop" workflow for any action that modifies the network:
- Draft: An AI agent (like the DDI or Config Agent) creates a proposed change based on your request.
- Pending Approval: The change appears in the "Approvals" dashboard for a second human to review.
- Approved: Once a human signs off, the change is scheduled for execution.
- Executing: The Automation Agent takes a pre-change configuration backup and then applies the commands.
- Completed or Rolled Back: If the change succeeds, it is logged; if it fails, the platform uses the backup to restore the previous state.
Sources: README.md:1-15, backend/app/llm/prompts/init.py:220-250
System Diagrams
Platform Connectivity
This diagram shows how users interact with the platform and how the platform connects to your infrastructure and AI providers.
Sources: CLAUDE.md:15-30, deploy/docker/README.md:5-15
Agent Routing and Execution
When you send a request, the Master Architect determines which specialist should handle it.
Change Lifecycle
The full process for network modifications, ensuring every step is tracked and reversible.
Network Knowledge Model
What the platform tracks about your network in its "living topology map" (Neo4j).
Sources: CLAUDE.md:65-75
Traceability Components
The platform uses several specific data structures and logs to ensure that every AI action can be explained and audited.
Specialist Agents Roster
The following specialized agents (team members) are available for routing requests:
| Agent Name | Primary Responsibility |
|---|---|
| Master Architect | Supervisor that routes requests to specialists. |
| Troubleshooting | Diagnoses faults like OSPF/BGP flaps or reachability issues. |
| Discovery | Scans the network and lists inventory/neighbors. |
| DDI Agent | Manages DNS records and DHCP scopes. |
| Configuration | Checks for config drift and compliance violations. |
| Security | Audits firewall policies for overly permissive rules. |
| Documentation | Generates diagrams and network inventories. |
| Automation | Executes approved change requests. |
| Packet Analysis | Analyzes PCAP files for protocol errors. |
Sources: CLAUDE.md:38-50, backend/app/llm/prompts/init.py:220-300
Audit Integrity
To ensure logs haven't been modified, the platform uses an audit hash-chain. This is similar to how a blockchain works: each log entry contains a mathematical "fingerprint" of the previous entry.
- Hash-Chain Verification: A scheduled job runs daily to check the integrity of the audit logs. If a single character in an old log is changed, the chain will "break" and alert the administrators.
- Reasoning Traces: Every AI decision is recorded with a "Trace ID". This log includes the exact prompt version used and the AI's internal reasoning (rationale), allowing engineers to see why the AI chose a specific action.
Sources: backend/app/llm/prompts/init.py:10-25, deploy/kubernetes/netops/templates/NOTES.txt:40-55
Conclusion
Audit Logging & Traceability is the backbone of trust within the AI Network Operations Platform. By ensuring that every AI decision is grounded in versioned prompts, every network change is approved by a human, and every log entry is protected by a tamper-evident hash-chain, the platform provides the transparency required for enterprise network operations. This architecture allows network engineers to embrace AI automation without sacrificing control or security.