opnsense-mcp-server 0.3.2__tar.gz

opnsense_mcp_server-0.3.2/.dockerignore

@@ -0,0 +1,19 @@
+.git/
+.venv/
+tests/
+docs/
+.claude/
+.gitea/
+.github/
+__pycache__/
+*.pyc
+.env
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+Makefile
+*.md
+!README.md

opnsense_mcp_server-0.3.2/.github/workflows/ci.yml

@@ -0,0 +1,52 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+      - name: Ruff lint (includes bandit security rules)
+        run: ruff check src/ tests/
+      - name: Ruff format check
+        run: ruff format --check src/ tests/
+      - name: Type checking (mypy strict)
+        run: mypy src/
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+      - name: Run tests
+        run: pytest -v --tb=short
+
+  security:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+      - name: Dependency vulnerability audit
+        run: pip-audit
+      - name: Check for hardcoded secrets
+        run: ruff check src/ --select S105,S106,S107 --no-fix
+      - name: Check for insecure SSL usage
+        run: ruff check src/ --select S501 --no-fix

opnsense_mcp_server-0.3.2/.github/workflows/publish-docker.yml

@@ -0,0 +1,31 @@
+name: Publish to Docker Hub
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Extract version from tag
+        id: version
+        run: echo "version=${GITHUB_REF#refs/tags/v}" >> "$GITHUB_OUTPUT"
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: |
+            lucamarien/opnsense-mcp-server:latest
+            lucamarien/opnsense-mcp-server:${{ steps.version.outputs.version }}

opnsense_mcp_server-0.3.2/.github/workflows/publish-pypi.yml

@@ -0,0 +1,25 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: release
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Install build tools
+        run: pip install --no-cache-dir build
+      - name: Build wheel and sdist
+        run: python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

opnsense_mcp_server-0.3.2/.gitignore

@@ -0,0 +1,37 @@
+# Claude Code (local dev tooling — not published)
+.claude/
+CLAUDE.md
+.mcp.json
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.venv/
+.eggs/
+
+# Credentials (NEVER commit)
+.env
+*.key
+*_apikey.txt
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing
+.coverage
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

opnsense_mcp_server-0.3.2/CHANGELOG.md

@@ -0,0 +1,133 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This project follows [Semantic Versioning](https://semver.org/).
+
+## [0.3.2] - 2026-03-17
+
+### Fixed
+
+- **Diagnostics:** `opn_dns_lookup` now sends correct API payload (`dns.settings.hostname` instead of `dns.hostname`) — lookups were silently failing with validation error
+- **VPN:** `opn_ipsec_status` now uses POST for `searchPhase1`/`searchPhase2` endpoints — GET was returning empty or failed responses
+- **VPN:** `opn_openvpn_status` now uses POST with pagination for all three search endpoints (instances, sessions, routes)
+- **Services:** `opn_crowdsec_status` now uses POST for decisions/alerts search — consistent with `opn_crowdsec_alerts`
+
+### Security
+
+- **Diagnostics:** Expanded hostname validation to reject additional shell metacharacters (`(`, `)`, `{`, `}`, `<`, `>`, `'`, `"`, `\`, space)
+- **Diagnostics:** `opn_dns_lookup` now validates the `server` parameter against the same injection rules as `hostname`
+
+### Changed
+
+- **Firewall:** `opn_firewall_log` now supports client-side filtering via `source_ip`, `destination_ip`, `action`, `interface`, and `limit` parameters — reduces context window size when investigating specific devices
+
+## [0.3.1] - 2026-02-25
+
+Packaging readiness and documentation sync.
+
+### Fixed
+
+- Version numbers synced across pyproject.toml, \_\_init\_\_.py, and CHANGELOG (was stuck at 0.1.0)
+- README updated to document all 60 tools (was 57 — missing firewall categories, ICMPv6 rules, NDP table, IPv6 status)
+- Narrowed broad `except Exception` to specific exceptions in `opn_ipv6_status`
+
+### Added
+
+- CLI entry point: `opnsense-mcp` command available after `pip install`
+- `__main__.py` for `python -m opnsense_mcp` support
+- PEP 561 `py.typed` marker for downstream type checking
+- Test registration updated to cover all 60 tools
+
+## [0.3.0] - 2026-02-22
+
+Comprehensive security audit overhaul — from 4 surface-level checks to 11 in-depth security areas with compliance framework tagging.
+
+### Changed
+
+- **Security:** `opn_security_audit` completely rewritten with 11 audit sections (was 4):
+  - **Firewall rules:** Paginated analysis (no more 500-row cap), MVC + legacy config.xml rules, broad source/destination detection, port grouping best practices (SSH isolation, mixed service detection), management port exposure on WAN, insecure protocol detection (FTP, Telnet, plaintext SMTP/POP3/IMAP/LDAP, rsh/rlogin)
+  - **NAT port forwarding:** Dangerous port exposure, unrestricted sources, UDP amplification risk, insecure protocol forwarding
+  - **DNS security:** DNSSEC validation, DNS-over-TLS forwarding, resolver identity/version hiding
+  - **System hardening:** Web GUI HTTPS enforcement, SSH root login/password auth/default port, remote syslog configuration
+  - **Services:** Expanded critical service list (7 services, was 4), CrowdSec plugin detection
+  - **Certificates:** ACME + system certificate store + CA certificates (not just ACME)
+  - **VPN security:** WireGuard config audit with stale peer detection, IPsec status, OpenVPN instances
+  - **HAProxy security:** HTTP frontend detection, HTTPS redirect checks, backend health checks, security header audit (HSTS, X-Frame-Options, X-Content-Type-Options)
+  - **Gateway health:** Down/offline detection, packet loss >5%, latency >100ms
+  - **Compliance tagging:** Every finding tagged with applicable PCI DSS v4.0, BSI IT-Grundschutz, NIST SP 800-41, and CIS Benchmark controls. Manual review items listed separately.
+
+### Added
+
+- 6 new read-only API endpoint registrations: WireGuard server/client search, HAProxy frontend/backend/server/action search
+- `_fetch_all_pages` pagination helper for unbounded rule analysis
+- Port parsing, classification, and insecure protocol detection helpers
+- 97 security tests (was 18)
+
+## [0.2.0] - 2026-02-22
+
+Expands from 35 to 41 tools with NAT port forwarding, full VPN coverage, DNS write operations, and static route visibility.
+
+### Added
+
+- **Firewall:** `opn_list_nat_rules` — list NAT port forwarding (DNAT) rules with search/pagination
+- **Firewall:** `opn_add_nat_rule` — create NAT port forwarding rules with savepoint protection
+- **VPN:** `opn_ipsec_status` — IPsec tunnel status (IKE Phase 1 + ESP/AH Phase 2)
+- **VPN:** `opn_openvpn_status` — OpenVPN instances, sessions, and routes
+- **DNS:** `opn_add_dns_override` — add Unbound host overrides (A/AAAA) with auto-reconfigure and input validation
+- **Network:** `opn_list_static_routes` — list configured static routes with search/pagination
+- 11 new API endpoint registrations with dual camelCase/snake_case support
+- DNS input validation (hostname, domain, IP address regex)
+- NAT protocol validation (TCP, UDP, TCP/UDP)
+
+## [0.1.0] - 2026-02-21
+
+Initial release with 35 tools across 9 domains.
+
+### Added
+
+#### Phase 1: Foundation
+
+- Core infrastructure: config loading, API client with HTTP Basic Auth, SSL verification, 30s timeout
+- OPNsense version auto-detection (camelCase for pre-25.7, snake_case for 25.7+)
+- Dual endpoint registry supporting both API naming conventions
+- Endpoint blocklist: `halt`, `reboot`, `poweroff`, `firmware update/upgrade` are permanently blocked
+- FastMCP server with STDIO transport
+- 16 read-only tools:
+  - **System:** `opn_system_status`, `opn_list_services`, `opn_gateway_status`
+  - **Network:** `opn_interface_stats`, `opn_arp_table`
+  - **Firewall:** `opn_list_firewall_rules`, `opn_list_firewall_aliases`, `opn_firewall_log`
+  - **DNS:** `opn_list_dns_overrides`, `opn_list_dns_forwards`, `opn_dns_stats`
+  - **DHCP:** `opn_list_dhcp_leases`
+  - **VPN:** `opn_wireguard_status`
+  - **Services:** `opn_haproxy_status`, `opn_list_acme_certs`, `opn_list_cron_jobs`
+
+#### Phase 2: Write Operations
+
+- SavepointManager for safe firewall modifications with 60-second auto-rollback
+- Write guard requiring `OPNSENSE_ALLOW_WRITES=true` environment variable
+- 8 write tools:
+  - **Firewall:** `opn_confirm_changes`, `opn_toggle_firewall_rule`, `opn_add_firewall_rule`, `opn_delete_firewall_rule`, `opn_add_alias`
+  - **DNS:** `opn_reconfigure_unbound`
+  - **Services:** `opn_reconfigure_haproxy`
+
+#### Phase 3: Advanced Features
+
+- **Security:** `opn_security_audit` — comprehensive firewall audit (firmware, permissive rules, disabled rules, critical services, ACME certificates)
+- **Config:** `opn_download_config` — download `config.xml` with XML-aware sensitive data stripping (passwords, keys, secrets redacted by default)
+- **Config:** `opn_scan_config` — session-cached full configuration scan with runtime inventory
+- **Config:** `opn_get_config_section` — retrieve individual config sections as structured JSON
+- **Diagnostics:** `opn_ping` (async job-based with guaranteed cleanup), `opn_traceroute`, `opn_dns_lookup`, `opn_pf_states`
+- **DHCP:** `opn_list_kea_leases` — Kea DHCP server leases
+- **DHCP:** `opn_list_dnsmasq_leases` — dnsmasq DNS/DHCP server leases
+- **Services:** `opn_crowdsec_status`, `opn_crowdsec_alerts` — CrowdSec security engine status and alerts
+- ConfigCache system for session-scoped config caching with automatic invalidation on writes
+- Hostname input validation against shell metacharacter injection
+- `get_text()` API client method for non-JSON responses (XML config backup)
+
+### Security
+
+- Bandit security scanning via Ruff (S105/S106/S107 for hardcoded credentials, S501 for SSL verification)
+- Strict mypy type checking
+- All tests use mocked API — no real OPNsense credentials in test suite
+- 242 tests with full coverage of security-critical paths

opnsense_mcp_server-0.3.2/CONTRIBUTING.md

@@ -0,0 +1,143 @@
+# Contributing to OPNsense MCP Server
+
+Thank you for your interest in contributing! This guide covers the coding standards, security requirements, and workflow for adding tools or fixing bugs.
+
+## Development Setup
+
+```bash
+git clone https://github.com/lucamarien/opnsense-mcp-server
+cd opnsense-mcp-server
+pip install -e ".[dev]"
+```
+
+## Coding Standards
+
+- **Python 3.11+** with strict typing (`mypy --strict`)
+- **Linting:** `ruff check src/ tests/` (includes bandit security rules)
+- **Formatting:** `ruff format src/ tests/`
+- **Tests:** `pytest -v` (all tests use mocked API responses, no real OPNsense needed)
+- **No external dependencies** beyond `fastmcp` (which provides `httpx`)
+
+Run the full CI pipeline locally before submitting:
+
+```bash
+make validate
+```
+
+This runs: lint, format check, security scan, type check, tests, and dependency audit.
+
+## Adding a New Tool
+
+1. Pick the right domain file in `src/opnsense_mcp/tools/`
+2. Add your function with the `@mcp.tool()` decorator
+3. Use Python type hints — FastMCP auto-generates JSON schema from them
+4. Write a clear docstring (it's the AI's **only** guide to tool selection)
+5. Return `dict`, not formatted strings
+6. Add tests in `tests/test_tools/`
+7. Review against the security checklist below
+
+```python
+@mcp.tool()
+async def opn_example_tool(ctx: Context, search: str = "", limit: int = 50) -> dict[str, Any]:
+    """One-line description of what this does.
+
+    Use this when you need to [specific scenario].
+    Returns: dict with 'rows' (list) and 'total' (int).
+    """
+    api = get_api(ctx)
+    return await api.get("endpoint.logical_name")
+```
+
+### Tool Naming
+
+- All tools use the `opn_` prefix
+- Use descriptive names: `opn_list_firewall_rules`, `opn_add_dns_override`
+- Read tools: `opn_list_*`, `opn_*_status`, `opn_get_*`
+- Write tools: `opn_add_*`, `opn_delete_*`, `opn_toggle_*`, `opn_reconfigure_*`
+
+### Endpoint Registry
+
+Never hardcode API paths in tools. Use logical endpoint names resolved by the API client:
+
+```python
+# Good — uses the endpoint registry (auto-resolves camelCase/snake_case)
+await api.get("firewall.search_rule")
+
+# Bad — hardcodes the endpoint path
+await api.get("api/firewall/filter/searchRule")
+```
+
+Add new endpoints to `ENDPOINT_REGISTRY` in `src/opnsense_mcp/api_client.py` with both naming variants:
+
+```python
+"firewall.search_rule": ("firewall/filter/searchRule", "firewall/filter/search_rule"),
+```
+
+## Security Requirements
+
+These are non-negotiable for all contributions:
+
+### Never Do
+
+- Hardcode credentials, API keys, or secrets (enforced by Ruff S105/S106/S107)
+- Log, print, or include API keys in any output or error messages
+- Add API endpoints without checking against the blocklist
+- Disable SSL verification without explicit user configuration
+- Use global mutable state for credential storage
+- Expose internal file paths, stack traces, or sensitive config in tool responses
+
+### Always Do
+
+- Load credentials from environment variables only
+- Guard write operations with the `OPNSENSE_ALLOW_WRITES` check
+- Use the savepoint/rollback mechanism for all firewall modifications
+- Keep transport as STDIO only — never expose HTTP/SSE endpoints
+- Validate user-provided inputs (hostnames, IP addresses) against injection
+
+### Blocked Endpoints
+
+The following endpoints are **permanently blocked** at the API client level and must never be exposed through any tool:
+
+- `core/system/halt` — shuts down the firewall instantly
+- `core/system/reboot` — reboots instantly
+- `core/firmware/poweroff` — powers off instantly
+- `core/firmware/update` — triggers system update
+- `core/firmware/upgrade` — triggers major upgrade
+
+## Testing Requirements
+
+- **All tests must use mocked API responses** — never connect to a real OPNsense instance
+- Test both success and error paths
+- Test that blocked endpoints are rejected
+- Test that write guards work (`ALLOW_WRITES=false` must fail)
+- Test both camelCase and snake_case endpoint variants for version compatibility
+
+```bash
+# Run all tests
+pytest -v
+
+# Run tests for a specific domain
+make test-domain DOMAIN=firewall
+
+# Run with verbose output on failures
+pytest -v --tb=long
+```
+
+## Quick Decision Trees
+
+- **GET vs POST:** Status/read operations use GET. Search with filters uses POST. Modifications/actions use POST.
+- **Write guard?** Read operations don't need one. Firewall changes need write guard + savepoint. Other modifications (DNS, HAProxy) need write guard only.
+- **Savepoint?** Firewall rule changes (add/delete/toggle) use savepoints with 60-second auto-revert. Service reconfigurations (Unbound, HAProxy, dnsmasq) do not.
+
+## Pull Request Checklist
+
+- [ ] `make validate` passes locally
+- [ ] New tools have tests with mocked API responses
+- [ ] Docstrings are clear and describe when to use the tool
+- [ ] No hardcoded credentials or sensitive data
+- [ ] Write operations are guarded and use savepoints where appropriate
+- [ ] Total tool count stays under 65 (currently 62)
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

opnsense_mcp_server-0.3.2/Dockerfile

@@ -0,0 +1,13 @@
+FROM python:3.13-slim AS builder
+
+WORKDIR /build
+COPY pyproject.toml README.md LICENSE ./
+COPY src/ src/
+RUN pip install --no-cache-dir build && python -m build --wheel
+
+FROM python:3.13-slim
+
+COPY --from=builder /build/dist/*.whl /tmp/
+RUN pip install --no-cache-dir /tmp/*.whl && rm /tmp/*.whl
+
+ENTRYPOINT ["opnsense-mcp"]

opnsense_mcp_server-0.3.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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.

opnsense_mcp_server-0.3.2/Makefile

@@ -0,0 +1,47 @@
+.PHONY: lint format format-check typecheck test test-domain security audit validate clean install build docker
+
+install:  ## Install project with dev dependencies
+	pip install -e ".[dev]"
+
+lint:  ## Run ruff linter (includes bandit security rules)
+	ruff check src/ tests/
+
+format:  ## Format code with ruff
+	ruff format src/ tests/
+
+format-check:  ## Check formatting without modifying files
+	ruff format --check src/ tests/
+
+typecheck:  ## Run mypy strict type checking
+	mypy src/
+
+test:  ## Run test suite
+	pytest -v --tb=short
+
+test-domain:  ## Run tests for a specific domain (usage: make test-domain DOMAIN=system)
+	pytest tests/test_tools/test_$(DOMAIN).py -v --tb=long
+	ruff check src/opnsense_mcp/tools/$(DOMAIN).py
+	mypy src/opnsense_mcp/tools/$(DOMAIN).py
+
+security:  ## Run security-specific checks
+	ruff check src/ --select S105,S106,S107 --no-fix
+	ruff check src/ --select S501 --no-fix
+
+audit:  ## Run dependency vulnerability audit
+	pip-audit
+
+validate: lint format-check security typecheck test audit  ## Run full CI pipeline locally
+	@echo "All checks passed!"
+
+build:  ## Build wheel and sdist
+	python -m build
+
+docker:  ## Build Docker image locally
+	docker build -t opnsense-mcp-server .
+
+clean:  ## Remove build artifacts
+	rm -rf build/ dist/ *.egg-info/ .pytest_cache/ .mypy_cache/ .ruff_cache/ htmlcov/
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+
+help:  ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-15s\033[0m %s\n", $$1, $$2}'