v0.5.0

Release notes — firewall-aiops 0.5.0

Previous release: 0.4.0.

In this tool

• restart_service refuses the service that serves the API, and apply_changes / reconfigure filter refuse a staged change that would block management access to the configured host and port. The service name was previously interpolated straight into the path with no allow-list, so "restart the web service" killed the only management path.
• New pending_changes read, and the apply dry-run now shows the staged set. apply_changes was a blind commit: its preview named only the platform, and nothing in the package could read what was pending — including edits staged outside the tool.
• New scheme: (default https). The base URL was hardcoded to https with no override, so a firewall GUI behind a TLS-terminating proxy was unreachable with only a TLS record-layer error as the clue.

Every tool in the line: previews and undetermined outcomes

This release fixes three harness defects that were silently degrading the audit
trail and the undo store.

A write that loses its response is no longer recorded as a failure. The
harness assumed a sanitized error meant nothing had happened. That assumption is
false in exactly the case that matters most: when a write severs its own
connection, the request has already landed, the response cannot come back, and
the operation was recorded as status=error with no undo token created at
all. Transport-level failures are now audited as status=unknown, the result
says plainly that the operation may have taken effect and should be verified
before retrying, and a write that stashed its before-state has its inverse
recorded anyway — flagged effectVerified: false, which undo_list and
undo_apply both surface. Existing undo.db files are migrated in place; their
rows read as verified, which is accurate, since the old code only ever recorded
on the confirmed path.

A dry-run no longer writes an undo token. Previews were recording inverses
built from a before-state they never had: the undo callback's permissive default
filled the gap with a guess, producing a real, applicable token for an operation
that never happened.

A dry-run no longer demands a named approver. Requiring an approval in order
to ask whether something needs approval inverts what a preview is for. The tier
is still computed and still audited, so the preview can tell you an approver
will be needed; it just no longer refuses to answer. The write itself is gated
exactly as before.

The invariant, now stated: a dry_run may read; it must never write. Guards
run on the preview path, which means a preview can and does report that an
operation would be refused.

Also line-wide

• Truncated text now ends in an ellipsis instead of being cut silently. This
  line already treats a silent cut as a defect for lists; it was doing exactly
  that to strings.
• Error messages are capped at 800 characters, not 300. These messages end
  with what to do instead, so the cap was removing the most useful sentence of
  every long refusal.

v0.4.0

Release notes — firewall-aiops 0.4.0

Previous release: 0.3.0.

Headline: read-only mode

export FIREWALL_READ_ONLY=1

With this set the 9 write tools are never registered — an MCP
client lists 25 tools instead of 34. The writes are not hidden
behind a flag and not merely refused on call: they are absent from the session,
so a model cannot invoke one and cannot be argued into one. For a reviewer this
is checkable rather than promised — connect, list the tools, and the writes are
not there.

Enforcement is two layers deep: the @governed_tool harness refuses every
non-read operation (covering the CLI and in-process callers too), and the MCP
server removes write tools from list_tools(). Changing entry point does not
get around it.

BREAKING — return shapes changed

This release changes payloads that callers may be parsing. Both changes exist
to stop a result from misrepresenting itself:

1. Absent fields are now null, not "". A missing value and an empty value
   were previously indistinguishable, which invited consumers to invent the
   difference. Keys are still always present — only the value may be null.
2. Anything with a limit now returns an envelope —
   {"<items>": [...], "returned": N, "limit": L, "truncated": bool}. Truncation is
   measured (one extra row is fetched), never inferred from the page happening to
   be full. Where a genuine pre-cap total is knowable it is reported as total;
   where it isn't, total is deliberately omitted rather than echoing returned.

Also in this release

• docs/VERIFICATION.md — what the mock suite actually guarantees, a live
  verification checklist, and the criteria for claiming this tool verified.
• skills/firewall-aiops/references/agent-guardrails.md — for driving this tool with a
  smaller / local model: which guardrails are now enforced for you, and a
  ready-made system prompt for the rest.
• Expanded operator playbooks in the skill documentation.
• The advertised tool count now matches what an MCP client actually lists
  (it includes undo_list / undo_apply), and a release gate keeps it honest.
• The (preview) label has been dropped. It never meant unreleased; verification
  status now lives in docs/VERIFICATION.md where it can be specific.

v0.3.0

Undo executor (undo list / undo apply) line-wide + this tool's platform/framework expansion + coverage. See CHANGELOG.md.

v0.2.1

Fix release: secrets.enc follows _AIOPS_HOME; sanitized failures audit as status=error (no undo recorded for failed calls); doctor/init fully test-covered. Tool-specific fixes in CHANGELOG.md.

v0.2.0

Security-hardening release from a line-wide code review. Highlights: secure-by-default approver gate for high/critical operations (init seeds a starter rules.yaml), percent-encoded URL path segments, single-sourced version, governance persistence + CLI write-path tests. See CHANGELOG.md for the full list. BREAKING: fresh installs with no rules.yaml now deny high/critical writes until an approver is recorded.

Firewall-AIops v0.1.1

Patch: config.yaml now honors the *_AIOPS_HOME env var; CLI writes are now audited + undo-recorded through the governance path (previously MCP-only). See CHANGELOG.

firewall-aiops v0.1.0 — preview

Firewall AIops v0.1.0 — preview

Governed AI-ops for OPNsense and pfSense firewalls for AI agents, with a
built-in governance harness (audit, policy, token/runaway budget, undo-token
recording, graduated risk tiers) and an encrypted credential store. Standalone —
no external skill-family dependency. One MCP server spans both platforms: a
per-target platform field selects the API shape, and the same 32 tools work on
OPNsense (REST /api/..., key+secret via HTTP Basic) and pfSense (REST v2
/api/v2/..., API key via X-API-Key header).

Not affiliated with, endorsed by, or sponsored by the OPNsense project,
Deciso, Netgate, or the pfSense project. OPNsense, pfSense and Netgate are
trademarks of their respective owners.

Preview / mock-only. All behaviour is validated against mocked
OPNsense/pfSense JSON responses; it has not been run against a live
firewall. The concrete REST paths are modelled from each project's public API
and need live verification. Both platforms are free/self-hostable, so a home
lab is the easiest live check — firewall-aiops doctor is the fastest.

Highlights

• 32 MCP tools (24 read, 8 write), every one wrapped with @governed_tool:
  • System — firmware_status, health_status, interface_status,
    gateway_status.
  • Rules — list_rules, rule_detail, rule_stats (hit counts),
    rule_states.
  • NAT — nat_port_forwards, nat_outbound, nat_one_to_one.
  • Aliases — list_aliases, alias_entries.
  • VPN — wireguard_status, openvpn_sessions, ipsec_sas.
  • DHCP — dhcp_leases, dhcp_static_mappings.
  • Diagnostics — firewall_log, states_table, top_talkers.
  • Writes — toggle_rule, add_alias_entry, remove_alias_entry,
    kill_states, restart_service (med); apply_changes, reconfigure,
    reboot (high).
• Flagship analyses (transparent heuristics that show their numbers):
  • gateway_health_rca — rank gateways by loss + latency, flag down/degraded,
    map each to a likely cause + recommended action.
  • rule_hit_and_shadow_analysis — never-hit (0 evaluations) enabled rules,
    plus rules shadowed by an earlier terminating rule or duplicating one.
  • blocked_traffic_rca — noisiest blocked sources/ports classified as scan,
    service brute-force/probe, or generic — with an action.
• Governed writes — reversible writes capture the real fetched
  before-state and record an undo descriptor (toggle_rule restores the prior
  enabled flag; alias add/remove invert). High-risk commits (apply_changes /
  reconfigure / reboot) take a dry_run preview and require an approver;
  reboot is irreversible.
• Encrypted secret store — the OPNsense API secret or pfSense API key lives
  encrypted in ~/.firewall-aiops/secrets.enc (Fernet + scrypt), never plaintext;
  legacy FIREWALL_<TARGET>_SECRET env fallback.
• CLI with an init platform-picking wizard, doctor, overview,
  rules list/show/toggle, log, and secret management.

Install

uv tool install firewall-aiops
firewall-aiops init       # pick platform (opnsense/pfsense) + store the secret
firewall-aiops doctor

Caveats

• Preview / mock-only: OPNsense and pfSense responses are mocked and need live
  verification against a real firewall (the modelled REST paths especially).
• Missing a capability? Open an issue or PR — contributions and feedback
  welcome.