firewall-aiops 0.1.0__tar.gz

firewall_aiops-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: Publish to PyPI
+
+# Trusted Publishing (OIDC) — publishes from GitHub's runners with no API token,
+# sidestepping the local-IP / account new-project rate limit. Configure a matching
+# "trusted publisher" for this package on PyPI (see the repo release notes).
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write   # required for PyPI Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+      - name: Build sdist + wheel
+        run: uv build
+      - name: Publish to PyPI (Trusted Publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1

firewall_aiops-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+dist/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+*.egg-info/

firewall_aiops-0.1.0/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to firewall-aiops are documented here. This project adheres
+to [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] — preview
+
+Initial preview release: governed AI-ops for **OPNsense** and **pfSense**
+firewalls, with a bundled governance harness. One MCP server spans both platforms
+via a per-target `platform` field; the same tools work on either firewall.
+**Mock-validated only — not yet verified against a live firewall.**
+
+### Added
+
+- **32 MCP tools** (24 read, 8 write), every one wrapped with the bundled
+  `@governed_tool` harness (audit, policy, token/runaway budget, undo,
+  risk-tiers):
+  - **System (read)** — `firmware_status`, `health_status`, `interface_status`,
+    `gateway_status`.
+  - **Rules (read)** — `list_rules`, `rule_detail`, `rule_stats` (hit
+    counts/evaluations), `rule_states`.
+  - **NAT (read)** — `nat_port_forwards`, `nat_outbound`, `nat_one_to_one`.
+  - **Aliases (read)** — `list_aliases`, `alias_entries`.
+  - **VPN (read)** — `wireguard_status`, `openvpn_sessions`, `ipsec_sas`.
+  - **DHCP (read)** — `dhcp_leases`, `dhcp_static_mappings`.
+  - **Diagnostics (read)** — `firewall_log`, `states_table`, `top_talkers`.
+  - **Flagship analyses (read)** — `gateway_health_rca`,
+    `rule_hit_and_shadow_analysis`, `blocked_traffic_rca` — transparent
+    heuristics that report their numbers, not a black-box verdict.
+  - **Writes** — `toggle_rule` (med, undo restores prior enabled),
+    `add_alias_entry` / `remove_alias_entry` (med, capture prior entries, invert),
+    `kill_states` (med), `restart_service` (med), `apply_changes` (**high**),
+    `reconfigure` (**high**), `reboot` (**high**, irreversible/audit-only). Every
+    write takes a `dry_run` preview; high-risk writes require an approver.
+- **Platform abstraction** — a name-keyed platform registry maps each target's
+  `platform` (`opnsense` / `pfsense`) to its auth style + REST resource paths, so
+  the ops/CLI/MCP layers stay platform-neutral. OPNsense uses HTTP Basic
+  (key+secret); pfSense uses an `X-API-Key` header.
+- **Encrypted secret store** — the OPNsense API secret or pfSense API key is
+  stored encrypted in `~/.firewall-aiops/secrets.enc` (Fernet + scrypt); never
+  plaintext on disk. Legacy `FIREWALL_<TARGET>_SECRET` env var honoured as a
+  fallback.
+- **CLI** (`firewall-aiops`) — `init` platform-picking wizard, `overview`,
+  `rules list/show/toggle` (dry-run + double-confirm), `log`, `secret`
+  management, and a `doctor` connectivity check (firmware/version query on both
+  platforms).
+
+### Known limitations
+
+- 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 welcome.

firewall_aiops-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wei <zhouwei008@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

firewall_aiops-0.1.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: firewall-aiops
+Version: 0.1.0
+Summary: Governed AI-ops for OPNsense + pfSense firewalls: rules, NAT, aliases, VPN, DHCP, diagnostics, flagship RCA analyses, and governed writes (rule toggle, alias entries, apply/reconfigure/reboot) with a built-in governance harness (audit, budget, undo, risk tiers)
+Author-email: wei <zhouwei008@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=42.0
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: mcp[cli]<2.0,>=1.10
+Requires-Dist: pyyaml<7.0,>=6.0
+Requires-Dist: rich<16.0,>=13.0
+Requires-Dist: typer<1.0,>=0.12
+Description-Content-Type: text/markdown
+
+<!-- mcp-name: io.github.AIops-tools/firewall-aiops -->
+
+# Firewall AIops (preview)
+
+Governed, audited AI-ops for **OPNsense** and **pfSense** firewalls — for AI agents (via MCP) and humans (via CLI).
+
+> **Disclaimer**: Community-maintained open-source project. **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. MIT licensed.
+
+firewall-aiops speaks to two firewall platforms behind one MCP server — **OPNsense**
+(REST API under `/api/...`, API key+secret via HTTP Basic auth) and **pfSense**
+(REST API v2 under `/api/v2/...` from the pfSense-pkg-RESTAPI package, API key via
+an `X-API-Key` header) — with the **same tools working on both**. Each target in the
+config names its own `platform`; a name-keyed platform registry selects the API shape
+(auth + resource paths), so an agent never has to know which firewall it is talking to.
+
+Every tool runs through a **built-in governance harness** (vendored, zero external
+dependency): audit log, token/call budget with runaway circuit-breaker, graduated
+risk-tier approval, undo-token recording, and prompt-injection sanitisation.
+
+## Why this exists
+
+- **One server, both firewalls** — OPNsense and pfSense in a mixed estate, spoken to
+  through identical tool names. Adding a third firewall later is a new platform
+  descriptor, not a rewrite.
+- **Read the whole firewall** — firmware/health, interfaces & gateways, filter rules
+  (with hit counts and state table), NAT (port-forward / outbound / 1:1), aliases,
+  VPN (WireGuard / OpenVPN / IPsec), DHCP leases & reservations, and the firewall log.
+- **Flagship RCA analyses** — transparent heuristics that show their numbers, never a
+  black-box verdict: `gateway_health_rca` (WAN loss/latency/down → cause + action),
+  `rule_hit_and_shadow_analysis` (never-hit + shadowed/redundant rules), and
+  `blocked_traffic_rca` (top blocked sources/ports → scan / brute-force / probe).
+- **Governed writes** — toggle a rule, add/remove an alias entry (reversible,
+  undo-recorded from the fetched before-state), flush states, restart a service, and
+  the "make it live" commit (`apply_changes` / `reconfigure`) and `reboot` at
+  **risk=high** with a dry-run preview and an approver gate.
+
+## Tool inventory (32 tools)
+
+| Domain | Tools | # | Kind |
+|--------|-------|:-:|------|
+| **System** | `firmware_status`, `health_status`, `interface_status`, `gateway_status` | 4 | read |
+| **Rules** | `list_rules`, `rule_detail`, `rule_stats`, `rule_states` | 4 | read |
+| **NAT** | `nat_port_forwards`, `nat_outbound`, `nat_one_to_one` | 3 | read |
+| **Aliases** | `list_aliases`, `alias_entries` | 2 | read |
+| **VPN** | `wireguard_status`, `openvpn_sessions`, `ipsec_sas` | 3 | read |
+| **DHCP** | `dhcp_leases`, `dhcp_static_mappings` | 2 | read |
+| **Diagnostics** | `firewall_log`, `states_table`, `top_talkers` | 3 | read |
+| **Flagship analyses** | `gateway_health_rca`, `rule_hit_and_shadow_analysis`, `blocked_traffic_rca` | 3 | read |
+| **Writes** | `toggle_rule`, `add_alias_entry`, `remove_alias_entry`, `kill_states`, `restart_service` | 5 | write (**med**) |
+| **Writes** | `apply_changes`, `reconfigure`, `reboot` | 3 | write (**high**) |
+
+Reversible writes record an inverse **undo descriptor** built from the real fetched
+before-state (`toggle_rule` restores the rule's prior enabled flag; alias add/remove
+invert). `apply_changes` / `reconfigure` / `reboot` are high-risk with `dry_run` +
+an approver requirement; `reboot` is irreversible (audit only).
+
+## Install
+
+```bash
+uv tool install firewall-aiops        # or: pipx install firewall-aiops
+```
+
+## Quick start
+
+```bash
+firewall-aiops init                     # wizard: pick platform (opnsense/pfsense) + store the secret (encrypted)
+firewall-aiops doctor                   # verify config, secrets, and connectivity
+firewall-aiops overview                 # one-shot: version + gateway/interface health + rule count
+firewall-aiops rules list               # list filter rules
+firewall-aiops rules toggle <uuid> --disable   # dry-run + double-confirm governed write
+firewall-aiops log --action block -n 50 # recent blocked traffic
+```
+
+Run the MCP server (stdio) for an agent:
+
+```bash
+firewall-aiops mcp                      # or: firewall-aiops-mcp
+```
+
+### MCP client config
+
+```json
+{
+  "mcpServers": {
+    "firewall-aiops": {
+      "command": "uvx",
+      "args": ["--from", "firewall-aiops", "firewall-aiops-mcp"],
+      "env": { "FIREWALL_AIOPS_MASTER_PASSWORD": "your-master-password" }
+    }
+  }
+}
+```
+
+## Configuration
+
+`~/.firewall-aiops/config.yaml` (non-secret connection details only):
+
+```yaml
+targets:
+  - name: fw1
+    platform: opnsense       # opnsense | pfsense
+    host: 192.0.2.1
+    port: 443
+    username: <opnsense-api-key>   # OPNsense API key (unused for pfSense)
+    verify_ssl: false        # false for self-signed lab certs
+  - name: edge
+    platform: pfsense
+    host: 192.0.2.2
+    verify_ssl: false
+```
+
+The **secret** — the OPNsense API *secret* (paired with the key for HTTP Basic auth)
+or the pfSense **API key** — is stored **encrypted** in `~/.firewall-aiops/secrets.enc`
+(Fernet + scrypt-derived key), never plaintext on disk. Set it with
+`firewall-aiops secret set <target>` or the `init` wizard. The store is unlocked by a
+master password from `FIREWALL_AIOPS_MASTER_PASSWORD` (non-interactive/MCP/CI) or an
+interactive prompt (CLI on a TTY). A legacy plaintext env var
+`FIREWALL_<TARGET>_SECRET` is honoured as a fallback (migrate with
+`firewall-aiops secret migrate`).
+
+## Governance
+
+Every MCP tool is wrapped by `@governed_tool`:
+
+- **Audit** — every call is logged to `~/.firewall-aiops/audit.db` (tool, params with
+  secrets redacted, status, duration, risk tier, approver, rationale).
+- **Budget / runaway guard** — per-process token/call caps and a repeat-call circuit
+  breaker (`FIREWALL_MAX_TOOL_CALLS`, `FIREWALL_RUNAWAY_MAX`, …).
+- **Graduated risk tiers** — high-risk writes (`apply_changes`, `reconfigure`,
+  `reboot`) require an approver: set `FIREWALL_AUDIT_APPROVED_BY` (and
+  `FIREWALL_AUDIT_RATIONALE`) before they will run.
+- **Undo recording** — reversible writes record an inverse descriptor to
+  `~/.firewall-aiops/undo.db` from the fetched before-state (recording only; an
+  external orchestrator executes it).
+- **Sanitisation** — all firewall-returned text is bounded + injection-sanitised
+  before it reaches the agent.
+
+## Preview status
+
+- **Platforms**: OPNsense (REST API) and pfSense (REST API v2, pfSense-pkg-RESTAPI).
+- **Preview — mock-validated only. Not run against a live firewall.** All behaviour is
+  validated against mocked OPNsense/pfSense JSON responses; the concrete REST paths are
+  modelled from each project's public API and need live verification. Both platforms are
+  free and self-hostable (OPNsense is fully open-source; pfSense CE is free), so a home
+  lab is the easiest live check — `firewall-aiops doctor` (a firmware/version query on
+  both) is the fastest connectivity check.
+- **Missing a capability?** Open an issue or PR at
+  [github.com/AIops-tools/Firewall-AIops](https://github.com/AIops-tools/Firewall-AIops)
+  — contributions and feedback welcome.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

firewall_aiops-0.1.0/README.md

@@ -0,0 +1,153 @@
+<!-- mcp-name: io.github.AIops-tools/firewall-aiops -->
+
+# Firewall AIops (preview)
+
+Governed, audited AI-ops for **OPNsense** and **pfSense** firewalls — for AI agents (via MCP) and humans (via CLI).
+
+> **Disclaimer**: Community-maintained open-source project. **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. MIT licensed.
+
+firewall-aiops speaks to two firewall platforms behind one MCP server — **OPNsense**
+(REST API under `/api/...`, API key+secret via HTTP Basic auth) and **pfSense**
+(REST API v2 under `/api/v2/...` from the pfSense-pkg-RESTAPI package, API key via
+an `X-API-Key` header) — with the **same tools working on both**. Each target in the
+config names its own `platform`; a name-keyed platform registry selects the API shape
+(auth + resource paths), so an agent never has to know which firewall it is talking to.
+
+Every tool runs through a **built-in governance harness** (vendored, zero external
+dependency): audit log, token/call budget with runaway circuit-breaker, graduated
+risk-tier approval, undo-token recording, and prompt-injection sanitisation.
+
+## Why this exists
+
+- **One server, both firewalls** — OPNsense and pfSense in a mixed estate, spoken to
+  through identical tool names. Adding a third firewall later is a new platform
+  descriptor, not a rewrite.
+- **Read the whole firewall** — firmware/health, interfaces & gateways, filter rules
+  (with hit counts and state table), NAT (port-forward / outbound / 1:1), aliases,
+  VPN (WireGuard / OpenVPN / IPsec), DHCP leases & reservations, and the firewall log.
+- **Flagship RCA analyses** — transparent heuristics that show their numbers, never a
+  black-box verdict: `gateway_health_rca` (WAN loss/latency/down → cause + action),
+  `rule_hit_and_shadow_analysis` (never-hit + shadowed/redundant rules), and
+  `blocked_traffic_rca` (top blocked sources/ports → scan / brute-force / probe).
+- **Governed writes** — toggle a rule, add/remove an alias entry (reversible,
+  undo-recorded from the fetched before-state), flush states, restart a service, and
+  the "make it live" commit (`apply_changes` / `reconfigure`) and `reboot` at
+  **risk=high** with a dry-run preview and an approver gate.
+
+## Tool inventory (32 tools)
+
+| Domain | Tools | # | Kind |
+|--------|-------|:-:|------|
+| **System** | `firmware_status`, `health_status`, `interface_status`, `gateway_status` | 4 | read |
+| **Rules** | `list_rules`, `rule_detail`, `rule_stats`, `rule_states` | 4 | read |
+| **NAT** | `nat_port_forwards`, `nat_outbound`, `nat_one_to_one` | 3 | read |
+| **Aliases** | `list_aliases`, `alias_entries` | 2 | read |
+| **VPN** | `wireguard_status`, `openvpn_sessions`, `ipsec_sas` | 3 | read |
+| **DHCP** | `dhcp_leases`, `dhcp_static_mappings` | 2 | read |
+| **Diagnostics** | `firewall_log`, `states_table`, `top_talkers` | 3 | read |
+| **Flagship analyses** | `gateway_health_rca`, `rule_hit_and_shadow_analysis`, `blocked_traffic_rca` | 3 | read |
+| **Writes** | `toggle_rule`, `add_alias_entry`, `remove_alias_entry`, `kill_states`, `restart_service` | 5 | write (**med**) |
+| **Writes** | `apply_changes`, `reconfigure`, `reboot` | 3 | write (**high**) |
+
+Reversible writes record an inverse **undo descriptor** built from the real fetched
+before-state (`toggle_rule` restores the rule's prior enabled flag; alias add/remove
+invert). `apply_changes` / `reconfigure` / `reboot` are high-risk with `dry_run` +
+an approver requirement; `reboot` is irreversible (audit only).
+
+## Install
+
+```bash
+uv tool install firewall-aiops        # or: pipx install firewall-aiops
+```
+
+## Quick start
+
+```bash
+firewall-aiops init                     # wizard: pick platform (opnsense/pfsense) + store the secret (encrypted)
+firewall-aiops doctor                   # verify config, secrets, and connectivity
+firewall-aiops overview                 # one-shot: version + gateway/interface health + rule count
+firewall-aiops rules list               # list filter rules
+firewall-aiops rules toggle <uuid> --disable   # dry-run + double-confirm governed write
+firewall-aiops log --action block -n 50 # recent blocked traffic
+```
+
+Run the MCP server (stdio) for an agent:
+
+```bash
+firewall-aiops mcp                      # or: firewall-aiops-mcp
+```
+
+### MCP client config
+
+```json
+{
+  "mcpServers": {
+    "firewall-aiops": {
+      "command": "uvx",
+      "args": ["--from", "firewall-aiops", "firewall-aiops-mcp"],
+      "env": { "FIREWALL_AIOPS_MASTER_PASSWORD": "your-master-password" }
+    }
+  }
+}
+```
+
+## Configuration
+
+`~/.firewall-aiops/config.yaml` (non-secret connection details only):
+
+```yaml
+targets:
+  - name: fw1
+    platform: opnsense       # opnsense | pfsense
+    host: 192.0.2.1
+    port: 443
+    username: <opnsense-api-key>   # OPNsense API key (unused for pfSense)
+    verify_ssl: false        # false for self-signed lab certs
+  - name: edge
+    platform: pfsense
+    host: 192.0.2.2
+    verify_ssl: false
+```
+
+The **secret** — the OPNsense API *secret* (paired with the key for HTTP Basic auth)
+or the pfSense **API key** — is stored **encrypted** in `~/.firewall-aiops/secrets.enc`
+(Fernet + scrypt-derived key), never plaintext on disk. Set it with
+`firewall-aiops secret set <target>` or the `init` wizard. The store is unlocked by a
+master password from `FIREWALL_AIOPS_MASTER_PASSWORD` (non-interactive/MCP/CI) or an
+interactive prompt (CLI on a TTY). A legacy plaintext env var
+`FIREWALL_<TARGET>_SECRET` is honoured as a fallback (migrate with
+`firewall-aiops secret migrate`).
+
+## Governance
+
+Every MCP tool is wrapped by `@governed_tool`:
+
+- **Audit** — every call is logged to `~/.firewall-aiops/audit.db` (tool, params with
+  secrets redacted, status, duration, risk tier, approver, rationale).
+- **Budget / runaway guard** — per-process token/call caps and a repeat-call circuit
+  breaker (`FIREWALL_MAX_TOOL_CALLS`, `FIREWALL_RUNAWAY_MAX`, …).
+- **Graduated risk tiers** — high-risk writes (`apply_changes`, `reconfigure`,
+  `reboot`) require an approver: set `FIREWALL_AUDIT_APPROVED_BY` (and
+  `FIREWALL_AUDIT_RATIONALE`) before they will run.
+- **Undo recording** — reversible writes record an inverse descriptor to
+  `~/.firewall-aiops/undo.db` from the fetched before-state (recording only; an
+  external orchestrator executes it).
+- **Sanitisation** — all firewall-returned text is bounded + injection-sanitised
+  before it reaches the agent.
+
+## Preview status
+
+- **Platforms**: OPNsense (REST API) and pfSense (REST API v2, pfSense-pkg-RESTAPI).
+- **Preview — mock-validated only. Not run against a live firewall.** All behaviour is
+  validated against mocked OPNsense/pfSense JSON responses; the concrete REST paths are
+  modelled from each project's public API and need live verification. Both platforms are
+  free and self-hostable (OPNsense is fully open-source; pfSense CE is free), so a home
+  lab is the easiest live check — `firewall-aiops doctor` (a firmware/version query on
+  both) is the fastest connectivity check.
+- **Missing a capability?** Open an issue or PR at
+  [github.com/AIops-tools/Firewall-AIops](https://github.com/AIops-tools/Firewall-AIops)
+  — contributions and feedback welcome.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

firewall_aiops-0.1.0/RELEASE_NOTES.md

@@ -0,0 +1,67 @@
+# 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
+
+```bash
+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.

firewall_aiops-0.1.0/SECURITY.md

@@ -0,0 +1,78 @@
+# Security Policy
+
+## Disclaimer
+
+Community-maintained open-source project. **Not affiliated with, endorsed by, or
+sponsored by the OPNsense project, Deciso, Netgate, or the pfSense project.**
+Product and trademark names (OPNsense, pfSense, Netgate) belong to their owners.
+Source is auditable under the MIT license.
+
+## Reporting Vulnerabilities
+
+Report privately via a GitHub Security Advisory on
+[github.com/AIops-tools/Firewall-AIops](https://github.com/AIops-tools/Firewall-AIops/security/advisories)
+or email zhouwei008@gmail.com. Please do not open public issues for security
+reports.
+
+## Security Design
+
+### Credential Management
+- Per-target secrets — the OPNsense API **secret** (paired with the API key for
+  HTTP Basic auth) or the pfSense **API key** — live **encrypted** in
+  `~/.firewall-aiops/secrets.enc` (Fernet/AES-128 + scrypt-derived key; chmod
+  600), never in `config.yaml` and never in source. The master password is never
+  stored — only a per-store random salt and the ciphertext are on disk.
+- A legacy plaintext env var `FIREWALL_<TARGET_NAME_UPPER>_SECRET` is still
+  honoured as a fallback with a deprecation warning (migrate with
+  `firewall-aiops secret migrate`).
+- The secret is held only in memory and never logged or echoed. It is presented
+  as HTTP Basic auth (OPNsense) or an `X-API-Key` header (pfSense) at request
+  time; the config file holds only platform, host, port, username, and TLS
+  settings.
+
+### Governed Operations
+Every MCP tool runs through the bundled `@governed_tool` harness
+(`firewall_aiops.governance`):
+- **Audit** — every call logged to a local SQLite DB under `~/.firewall-aiops/`
+  (relocatable via `FIREWALL_AIOPS_HOME`), agent-attributed, secret-redacted.
+- **Token/runaway budget** — hard ceilings (`FIREWALL_MAX_TOOL_CALLS` /
+  `FIREWALL_MAX_TOOL_SECONDS`) plus an on-by-default guard that trips a tight
+  poll/retry loop, preventing unbounded API consumption.
+- **Graduated risk tiers** — `~/.firewall-aiops/rules.yaml` `risk_tiers` gate
+  writes by environment/tag; the highest tiers require a recorded approver.
+- **Undo-token recording** — reversible writes capture the BEFORE state (via a
+  real GET) and record an inverse descriptor (e.g. `toggle_rule` restores the
+  prior enabled flag; `add_alias_entry`→`remove_alias_entry`) so the change can
+  be rolled back.
+
+### State-Changing Operations
+The "make it live" commits — `apply_changes`, `reconfigure` — and `reboot` are
+`risk_level=high`, accept a `dry_run` preview, and (under `risk_tiers`) require a
+recorded approver (`FIREWALL_AUDIT_APPROVED_BY` + `FIREWALL_AUDIT_RATIONALE`).
+`reboot` is irreversible (audit only, no undo). Rule toggle, alias entry
+add/remove, `kill_states`, and `restart_service` are `risk_level=medium`;
+reversible ones capture before-state and record an undo token.
+
+### SSL/TLS Verification
+`verify_ssl` defaults to true; disable only for self-signed lab certificates.
+
+### Prompt-Injection Protection
+All firewall-returned text (rule descriptions, alias entries, log lines, VPN peer
+names, gateway names) is passed through a `sanitize()` truncate + control-character
+strip before reaching the agent.
+
+### Network Scope
+No webhooks, no telemetry, no outbound calls beyond the configured OPNsense /
+pfSense REST API endpoints. No post-install scripts or background services.
+
+## Static Analysis
+
+```bash
+uvx bandit -r firewall_aiops/ mcp_server/
+uv run ruff check .
+```
+
+## Supported Versions
+
+The latest released version receives security fixes. This is a preview (0.x);
+pin a version in production.

firewall_aiops-0.1.0/firewall_aiops/__init__.py

@@ -0,0 +1,9 @@
+"""firewall-aiops — governed OPNsense + pfSense firewall operations for AI agents.
+
+Standalone and self-contained: the governance harness (audit, token budget,
+undo-token recording, graduated risk tiers, prompt-injection sanitize) is
+bundled under ``firewall_aiops.governance`` — this package has no external
+skill-family dependency. Preview: not yet full-coverage.
+"""
+
+__version__ = "0.1.0"

firewall_aiops-0.1.0/firewall_aiops/cli/__init__.py

@@ -0,0 +1,9 @@
+"""CLI package for firewall-aiops.
+
+Re-exports ``app`` so the pyproject entry point
+``firewall-aiops = "firewall_aiops.cli:app"`` works unchanged.
+"""
+
+from firewall_aiops.cli._root import app
+
+__all__ = ["app"]