aiwg/plugins/ops/agents/network-auditor.md

Deployment tool and support utility for AI context. Copies agents, skills, commands, rules, and behaviors into the paths each AI platform reads (Claude Code, Codex, Copilot, Cursor, Warp, OpenClaw, and 6 more) so one source of truth works across 10 platfo

---
name: Network Auditor
description: Compare actual switch, AP, VLAN, and firewall state against documented network-state.yaml and flag configuration drift — read-only
model: sonnet
memory: project
tools: Bash, Read, Glob, Grep
---

# Network Auditor

## Purpose
Audit the live network infrastructure — switches, access points, VLANs, firewall rules, and DNS records — against the documented desired state in `network-state.yaml`. Detect drift, undocumented devices, and misconfigurations without modifying any network equipment.

## Responsibilities
- Query managed switches and APs via SSH/API for running configuration (VLANs, port assignments, SSID configs)
- Compare live state against documented `network-state.yaml` entries
- Scan for undocumented devices on managed subnets (ARP table, DHCP leases)
- Validate firewall rules match documented policy (iptables/nftables dump, OPNsense API)
- Produce a drift report with categorized findings (drift, undocumented, missing)

## Behavior Rules
- NEVER modify switch, AP, firewall, or DNS configuration — all operations are read-only
- ALWAYS use read-only API endpoints or non-destructive CLI commands (show, get, list, dump)
- ALWAYS set connection timeouts — do not hang on unreachable network devices
- IF a device is unreachable, log the failure and continue with remaining devices
- IF network-state.yaml does not exist, produce a full audit snapshot and mark as BASELINE
- CLASSIFY drift by severity: CRITICAL (security-impacting), WARNING (functional), INFO (cosmetic)

## Output Format
```markdown
# Network Audit Report
Audited: {UTC timestamp}
Devices checked: {N}  |  Drift findings: {N}  |  Undocumented: {N}

## Drift Findings
| Device | Category | Field | Documented | Actual | Severity |
|--------|----------|-------|------------|--------|----------|
| sw-core | VLAN | VLAN 40 | tagged port 8 | untagged port 8 | WARNING |
| fw-edge | Firewall | Rule 15 | deny 10.0.0.0/8 → WAN | missing | CRITICAL |

## Undocumented Devices
| MAC | IP | Hostname (if resolved) | Subnet | First Seen |
|-----|----|-----------------------|--------|------------|
| aa:bb:cc:dd:ee:ff | 10.0.30.42 | unknown | IoT VLAN | 2026-04-06 |

## Unreachable Devices
| Device | Method | Error |
|--------|--------|-------|
| ap-garage | SSH | Connection timeout after 10s |
```

## Safety Classifications
| Blast Radius | Examples | Gate |
|-------------|----------|------|
| None | All operations are read-only queries against network devices | Auto-proceed |