Security & Firewall Analysis
Relevant source files
The following files were used as context for generating this wiki page:
The Security & Firewall Analysis system acts as a specialized digital auditor for your network's security posture. It identifies hygiene issues like shadowed or redundant rules and overly-permissive access controls, while ensuring no changes happen without human oversight.
Overview
The platform is a self-hosted AI assistant designed to help network engineering teams manage multi-vendor environments. It solves the problem of manual, error-prone security audits by using deterministic analysis engines to review firewall policies and Access Control Lists (ACLs) as data.
Supported Vendors and Protocols
The platform supports a wide range of infrastructure including:
- Routing/Switching: Cisco (IOS, IOS-XE, NX-OS), Juniper JunOS, Arista EOS.
- Security/Firewalls: Palo Alto PAN-OS, Fortinet FortiOS.
- Load Balancers & DDI: F5 BIG-IP, BlueCat, Infoblox.
- Cloud & Virtualization: AWS, Azure, VMware.
Sources: CLAUDE.md:16-30, README.md:17-21
Design Philosophy
The system is built on four core principles:
- Local-First & Self-Hosted: All data and AI inference (via Ollama) stay within your infrastructure to maintain privacy.
- Human-in-the-Loop: The AI can only draft changes; a second human must approve every modification before it is executed.
- Auditability: Every decision made by the AI is explained and logged in an audit trail.
- Specialized Agents: Tasks are routed to specific "specialized team members" (Agents) based on the request.
Sources: CLAUDE.md:46-53, backend/app/agents/security/agent.py:12-25
The Security Agent
The Security Agent is a specialized team member focused on auditing firewall and security policies. Unlike the Troubleshooting Agent, which diagnoses why a specific flow is currently failing, the Security Agent performs proactive hygiene checks to find redundant rules, overly-permissive "any-to-any" access, and rules missing logging.
Sources: backend/app/agents/security/agent.py:44-59, backend/app/llm/prompts/init.py:365-385
Architecture
The platform consists of seven key components that work together to provide the AI Network Engineer experience.
Platform Components
- frontend: The operations console where you chat with the AI and view topology maps.
- api: The central brain that manages sessions and communicates with the agents.
- worker: The background engine that runs heavy jobs like discovery scans and configuration backups.
- postgres: The system of record that stores all persistent data, such as device inventory and audit logs.
- neo4j: A living topology map that tracks how every device, interface, and application connects to everything else.
- redis: A temporary staging area and cache used by the background engine.
- ollama: The local engine that handles the AI's "thinking" and language processing.
Sources: README.md:25-33, deploy/docker/README.md:8-16
Vendor Plugin System
The platform uses a standardized connector for each vendor. No matter whether you are talking to a Cisco router or a Palo Alto firewall, the platform normalizes the output into a consistent format before doing anything with it. This allows the Security Agent to audit policies from different vendors using the same set of analysis rules.
Sources: README.md:35-41, backend/app/agents/security/tools.py:14-19
Deployment Options
- Docker Compose: A single-server setup ideal for a lab environment or a small team.
- Kubernetes (Helm): A production-grade deployment for multi-node, highly available environments.
Sources: README.md:47-59, deploy/docker/README.md:1-6
Change Approval Workflow
Every change follows a strict lifecycle:
- Draft: The AI Specialist (e.g., Security Agent) creates a proposed change.
- Pending Approval: The change waits for a human engineer to review and sign off.
- Approved: Once a human approves, the change is ready to run.
- Executing: The Automation Agent applies the change to the device.
- Completed/Rolled Back: The change is finalized or undone if a failure occurs.
Sources: backend/app/agents/security/agent.py:20-25, backend/app/agents/security/tools.py:23-31
Analysis Logic and Tools
The Security Agent uses a deterministic engine to ensure accuracy. It does not "guess"—it narrates the findings produced by the platform's analysis logic.
Security Tool Tiers
| Tool Type | Function | Description |
|---|---|---|
| Read-Only Analysis | analyze_firewall_policy | Finds shadowed, redundant, or overly-permissive rules in a policy. |
| Read-Only Posture | assess_security_posture | Checks for missing logging or exposed management planes. |
| State-Changing | propose_remediation | Drafts a Change Request (CR) to fix a security issue for human approval. |
| Sources: backend/app/agents/security/tools.py:11-31, backend/app/agents/security/agent.py:27-38 |
Redaction and Security
To prevent leaking sensitive information, the system uses an "A9 Redaction" layer. Any secret values like community strings or passwords in rule descriptions are replaced with tokens like <<REDACTED:...>> before the data is ever seen by the AI model.
Sources: backend/app/agents/security/tools.py:34-39, backend/tests/agents/security/test_security_agent.py:236-248
Diagrams
System Overview
This diagram shows how users interact with the platform and what external systems the platform connects to.
The platform sits between the engineer and the network infrastructure, acting as a secure interface for management and auditing.
Agent Routing
When you send a question, the Master Architect (supervisor) determines which specialist team member should handle it.
Read-only requests (like "Is this rule shadowed?") provide immediate answers, while write requests (like "Fix this rule") must pass through an approval gate.
Sources: backend/app/llm/prompts/init.py:365-385, backend/app/agents/security/agent.py:40-45
Change Approval Flow
The lifecycle of a security change request ensures no unauthorized modifications.
Before any change is executed, the platform always takes a configuration backup to allow for a safe rollback if needed.
Sources: backend/app/agents/security/agent.py:20-25, backend/app/agents/security/tools.py:145-155
Topology Data Model
This represents the "Living Topology Map" (Neo4j) and how the platform understands your network structure.
The Security Agent uses these relationships to understand the context of firewall rules and ACLs during an audit.
Sources: CLAUDE.md:63-68, README.md:32
Deployment Options
A comparison of how the platform can be hosted.
Docker Compose is simple for labs, while Kubernetes provides the resilience required for enterprise production environments.
Sources: README.md:47-59, deploy/docker/README.md:1-6
Summary
The Security & Firewall Analysis module provides a rigorous, data-driven approach to network security hygiene. By separating proactive audits (Security Agent) from reactive repairs (Troubleshooting Agent) and enforcing a mandatory human approval gate for all changes, the platform ensures that security operations are both efficient and safe.