# Access Network Config Audit Agent

An MCP server exposing read-only GPON access-network operations, and a LangGraph
agent that uses it to audit ONT configuration against a golden baseline.

> **This runs against a simulated network.** There is no real OLT, no real ONT,
> and no vendor equipment involved. The device layer is a SQLite database seeded
> with a small synthetic topology. Optical and profile values are modelled on
> ITU-T G.984 class B+ conventions but are not taken from any operator's
> production standard. See [Limitations](#limitations).

---

## Why this exists

Configuration drift is a real operational problem in broadband access networks:
ONTs get provisioned by hand, migrations leave legacy profiles behind, and a
mis-set service VLAN can sit undetected until it causes an incident. Auditing it
is exactly the kind of repetitive, well-specified work an agent should be good
at — *if* the agent is built so that its findings can be trusted.

This project is an experiment in that "if".

---

## Architecture

```
┌──────────────────┐
│  LangGraph agent │   decides what to inspect, correlates alarms
│  (LLM)           │   with findings, writes the report
└────────┬─────────┘
         │  LangChain StructuredTools (agent/mcp_bridge.py)
┌────────▼─────────┐
│   MCP server     │   5 read-only tools, stdio transport
│  (protocol)      │   read_only_hint=True on every tool
└────────┬─────────┘
         │
    ┌────┴─────┬──────────────┐
    │          │              │
┌───▼────┐ ┌───▼──────────┐ ┌─▼─────────────┐
│ OltAcc │ │ audit engine │ │ golden config │
│ (data) │ │ (pure code)  │ │   (YAML)      │
└────────┘ └──────────────┘ └───────────────┘
```

---

## Three design decisions

### 1. The LLM does not decide compliance

The comparison between running config and golden baseline happens in
`audit/engine.py` — ordinary, pure, unit-tested Python. The model orchestrates
(which devices, which order, how to explain a finding) but never returns the
verdict itself.

The reason is that an audit which gives different answers to the same input is
not evidence of anything. `tests/test_audit.py` asserts the engine finds exactly
the nine deviations planted by the seed script, and that repeated runs are
byte-identical. None of that would be assertable if the logic lived in a prompt.

This also bounds the failure mode: the engine can only report deviations on
fields that were actually retrieved, so the agent cannot invent a finding about
a device that does not exist.

### 2. Read-only by design, and the constraint is checked

There is no `set_config`, no `reboot`, no `provision`. The absence is the point.
An agent with a write path into a production access network can take subscribers
off-line from one bad inference, and a prompt instruction is not a control.

The constraint is enforced at three levels rather than asserted once:

| Level | Mechanism |
|---|---|
| Data layer | `OltAccess` exposes no write method at all |
| Protocol | every tool carries `read_only_hint=True`, `destructive_hint=False` |
| Client | `MCPToolset.assert_read_only()` refuses to start the agent if the server ever advertises a mutating tool |

Remediation is emitted as a recommendation for a human to execute through
change control. The system prompt forbids claiming an action was applied.

Extending this to writes would need, at minimum: a separate server with its own
credentials, an explicit approval step in the call path, a dry-run mode, and
per-call audit logging. That is deliberately out of scope.

### 3. MCP rather than direct function-calling

Binding these five functions straight into one agent's tool schema would have
been less code. MCP was chosen because:

- The server is testable on its own. `tests/test_mcp_server.py` drives it over
  real stdio with no model involved — the tool contract is verified independently
  of whichever LLM happens to call it.
- The device layer is swappable without touching the agent. Replacing the
  simulator with GenieACS, NETCONF, or a vendor CLI means reimplementing
  `OltAccess` only.
- The same server is reusable by a different agent, a different model, or an
  operator's desktop MCP client.
- Capability boundaries are declared in the protocol, not buried in prompt text.

---

## Golden baseline

`audit/golden_config.yaml` is the single source of truth for correct
provisioning, versioned alongside the code. An audit result is only defensible
if the baseline it was measured against is itself reviewable and diffable.

Severity model:

| Severity | Meaning | Example rules |
|---|---|---|
| `critical` | Service-affecting now, or an isolation/security violation | `vlan_mismatch`, `srv_profile_unapproved`, `admin_disabled`, `rx_power_out_of_range` |
| `major` | Policy violation with degraded service or SLA risk | `line_profile_unapproved`, `dba_profile_unapproved`, `gem_port_count` |
| `minor` | Hygiene, documentation, or planning deviation | `description_convention`, `distance_exceeded`, `rx_power_marginal` |

---

## Tool surface

| Tool | Purpose |
|---|---|
| `list_onts(olt_id?, pon_port?)` | Inventory discovery |
| `get_ont_status(serial)` | Operational state, Rx power, ranging distance |
| `get_running_config(serial)` | Configuration-bearing fields |
| `diff_against_golden(serial)` | Deterministic compliance verdict + findings |
| `get_alarms(olt_id, active_only)` | Active/cleared faults for correlation |

---

## Running it

```bash
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# 1. Seed the simulated network (2 OLTs, 14 ONTs, 9 planted deviations)
python simulator/seed.py

# 2. Verify every layer — none of these need an API key
python tests/test_audit.py         # audit engine determinism + correctness
python tests/test_mcp_server.py    # MCP contract over real stdio
python tests/test_bridge.py        # MCP -> LangChain conversion + guardrail

# 3. Run the agent (needs an Anthropic API key)
export ANTHROPIC_API_KEY=...
python agent/audit_agent.py --olt OLT-BDG-GGK-01
```

The MCP server can also be attached to any MCP client directly:

```bash
python mcp_server/server.py     # stdio transport
```

---

## Limitations

Stating these plainly matters more than the demo does.

1. **The network is simulated.** No GPON hardware, no vendor CLI, no OMCI. The
   simulator models the *shape* of ONT provisioning data, not any real OLT's
   command syntax or YANG model.
2. **The golden baseline is invented.** Profile names, VLAN ranges, and the
   naming convention are plausible but fictional. A real deployment's baseline
   would come from the operator's provisioning standard.
3. **One use case only.** Configuration audit. Fault handling, device
   configuration, and network optimisation are not implemented.
4. **No scale testing.** 14 ONTs. A real PON port carries up to 64 ONTs and a
   regional OLT thousands; per-device tool calls would not be the right shape at
   that size — a batch audit tool returning aggregated findings would be.
5. **Alarm correlation is left to the model.** The engine does not join alarms
   to findings; the agent is asked to notice the overlap. That part is therefore
   *not* deterministic, and it is the weakest link in the output.
6. **No authentication or authorisation.** stdio transport, single local user.
   Any real deployment needs credential scoping per OLT and per operator role.

---

## Layout

```
simulator/    olt_sim.py    read-only device accessor (swap this for real transport)
              seed.py       synthetic topology with deliberately planted faults
audit/        engine.py     deterministic golden-config diff
              golden_config.yaml
mcp_server/   server.py     5 read-only MCP tools, stdio
agent/        mcp_bridge.py MCP -> LangChain tool conversion + guardrail check
              audit_agent.py LangGraph ReAct agent
tests/        test_audit.py, test_mcp_server.py, test_bridge.py
```