bind9-aiops 0.2.0__tar.gz

bind9_aiops-0.2.0/.claude-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
+  "name": "bind9-aiops",
+  "displayName": "BIND 9 AIops",
+  "version": "0.2.0",
+  "description": "Governed BIND 9 DNS operations — 23 MCP tools with audit.",
+  "author": {
+    "name": "Wei Zhou",
+    "email": "zhouwei008@gmail.com",
+    "url": "https://github.com/AIops-tools"
+  },
+  "homepage": "https://github.com/AIops-tools/BIND9-AIops",
+  "repository": "https://github.com/AIops-tools/BIND9-AIops",
+  "license": "MIT",
+  "keywords": [
+    "bind9",
+    "dns",
+    "dnssec",
+    "mcp",
+    "aiops"
+  ]
+}

bind9_aiops-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [bootstrap, main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Install Python and dependencies
+        run: |
+          uv python install 3.11
+          uv sync --dev --python 3.11
+      - name: Tests
+        run: uv run pytest -q
+      - name: Lint
+        run: uv run ruff check .
+      - name: Security scan
+        run: uv run bandit -r bind9_aiops -ll -q
+      - name: Build
+        run: uv build

bind9_aiops-0.2.0/.github/workflows/mcp-publish.yml

@@ -0,0 +1,55 @@
+name: mcp-publish
+
+on:
+  workflow_dispatch:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  publish-mcp:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Wait for PyPI
+        # The release event also triggers the PyPI publish workflow; the MCP
+        # registry validates that the package version exists on PyPI, so poll
+        # until it has propagated (every 15s, up to 10 minutes).
+        run: |
+          python3 - <<'EOF'
+          import json
+          import sys
+          import time
+          import urllib.error
+          import urllib.request
+
+          with open("server.json", encoding="utf-8") as f:
+              package = json.load(f)["packages"][0]
+          name, version = package["identifier"], package["version"]
+          url = f"https://pypi.org/pypi/{name}/{version}/json"
+          deadline = time.monotonic() + 600
+          while True:
+              try:
+                  with urllib.request.urlopen(url, timeout=10):
+                      print(f"{name}=={version} is available on PyPI.")
+                      sys.exit(0)
+              except (urllib.error.URLError, OSError) as exc:
+                  print(f"{name}=={version} not on PyPI yet ({exc}); "
+                        "retrying in 15s...")
+              if time.monotonic() >= deadline:
+                  sys.exit(f"Timed out after 10 minutes waiting for "
+                           f"{name}=={version} to appear on PyPI. "
+                           "Check the PyPI publish workflow, then re-run "
+                           "this workflow via workflow_dispatch.")
+              time.sleep(15)
+          EOF
+      - name: Install mcp-publisher
+        run: |
+          curl -sL "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
+      - name: Login to MCP Registry (GitHub OIDC)
+        run: ./mcp-publisher login github-oidc
+      - name: Publish server.json
+        run: ./mcp-publisher publish

bind9_aiops-0.2.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

bind9_aiops-0.2.0/.gitignore

@@ -0,0 +1,23 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+
+# Virtual envs / build
+.venv/
+dist/
+build/
+
+# uv
+uv.lock
+
+# Local config / secrets (never commit)
+*.env
+.env
+config.yaml
+
+# OS
+.DS_Store
+.coverage

bind9_aiops-0.2.0/.mcp.json

@@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "bind9-aiops": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": [
+        "--from",
+        "bind9-aiops==0.2.0",
+        "bind9-aiops-mcp"
+      ]
+    }
+  }
+}

bind9_aiops-0.2.0/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## v0.2.0 — 2026-11-05
+
+- Expand to 23 governed MCP/CLI tools covering zone DNSSEC, managed keys, stale answers, running zone config and selected-server queries.
+- Add preflighted zone reload, refresh, retransfer, NOTIFY resend and name-specific cache flush with dry-run, explicit unknown outcomes and no fabricated undo.
+- Keep DNS query and probe failures explicit; compare serials only when both SOA responses are parseable.
+- Add GitHub CI for tests, lint, security scan and build.
+
+## 0.1.0
+
+- Initial local development version; not published.

bind9_aiops-0.2.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.

bind9_aiops-0.2.0/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.5
+Name: bind9-aiops
+Version: 0.2.0
+Summary: Governed BIND 9 DNS diagnosis for service, zones, DNSSEC and SOA replication.
+Author-email: Wei Zhou <zhouwei008@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: mcp[cli]<3.0,>=2.0
+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/bind9-aiops -->
+# BIND 9 AIops
+
+Governed BIND 9 DNS operations with 23 MCP tools and corresponding CLI commands. It executes `rndc`, `named-checkconf` and `dig` as fixed argument lists without a shell. Every call is audited and budgeted by the bundled governance harness.
+
+## What it checks
+
+- Named service and zone status from `rndc`.
+- Configuration and loaded-zone validation with `named-checkconf -z`.
+- DNSSEC validation mode.
+- Zone DNSSEC signing, managed-key and serve-stale status; running zone configuration where enabled.
+- Recursive fetch-limit hits, DNSSEC trust anchors, DNS TCP timeouts and per-zone signing progress.
+- DNS queries with their actual DNS response code.
+- Queries against a selected secondary server.
+- Guarded secondary retransfer and single-zone NOTIFY resend.
+- Primary and secondary SOA serial comparison. A failed or unparseable query returns `null`, never a fabricated zero or match.
+- `bind_diagnose_zone` keeps individual probe failures visible.
+
+## Setup from source
+
+Requires Python 3.11+, `uv`, and BIND 9 command utilities on the operator host. Run `uv sync --dev`, `uv run bind9-aiops init`, then `uv run bind9-aiops doctor`. A manual `~/.bind9-aiops/config.yaml` can specify paths and a DNS server:
+
+```yaml
+targets:
+  - name: local
+    server: 127.0.0.1
+    dns_port: 53
+    rndc_config: /etc/bind/rndc.conf
+    named_config: /etc/bind/named.conf
+    timeout: 10
+```
+
+Use `uv run bind9-aiops diagnose example.org` or `uv run bind9-aiops compare-soa example.org 192.0.2.2`. The MCP entry point is `uv run bind9-aiops-mcp`. The process account needs access to its `rndc` key file and BIND config, but no elevated shell is given to the agent.
+
+## Scope and verification
+
+`reload-zone`, `refresh-zone`, `flush-name`, `retransfer-zone` and `notify-zone` support dry-run and two CLI confirmations. RNDC command acceptance does not prove a queued zone reload or transfer completed, so these writes report `outcomeUnknown`; a lost command response does too. No safe undo exists for a cache flush, retransfer, NOTIFY delivery or externally edited zone file. Zone-file editing, DNSSEC key changes and global service restarts remain outside this release. See [verification](docs/VERIFICATION.md). Missing features and live-environment feedback are welcome as issues or PRs.

bind9_aiops-0.2.0/README.md

@@ -0,0 +1,37 @@
+<!-- mcp-name: io.github.AIops-tools/bind9-aiops -->
+# BIND 9 AIops
+
+Governed BIND 9 DNS operations with 23 MCP tools and corresponding CLI commands. It executes `rndc`, `named-checkconf` and `dig` as fixed argument lists without a shell. Every call is audited and budgeted by the bundled governance harness.
+
+## What it checks
+
+- Named service and zone status from `rndc`.
+- Configuration and loaded-zone validation with `named-checkconf -z`.
+- DNSSEC validation mode.
+- Zone DNSSEC signing, managed-key and serve-stale status; running zone configuration where enabled.
+- Recursive fetch-limit hits, DNSSEC trust anchors, DNS TCP timeouts and per-zone signing progress.
+- DNS queries with their actual DNS response code.
+- Queries against a selected secondary server.
+- Guarded secondary retransfer and single-zone NOTIFY resend.
+- Primary and secondary SOA serial comparison. A failed or unparseable query returns `null`, never a fabricated zero or match.
+- `bind_diagnose_zone` keeps individual probe failures visible.
+
+## Setup from source
+
+Requires Python 3.11+, `uv`, and BIND 9 command utilities on the operator host. Run `uv sync --dev`, `uv run bind9-aiops init`, then `uv run bind9-aiops doctor`. A manual `~/.bind9-aiops/config.yaml` can specify paths and a DNS server:
+
+```yaml
+targets:
+  - name: local
+    server: 127.0.0.1
+    dns_port: 53
+    rndc_config: /etc/bind/rndc.conf
+    named_config: /etc/bind/named.conf
+    timeout: 10
+```
+
+Use `uv run bind9-aiops diagnose example.org` or `uv run bind9-aiops compare-soa example.org 192.0.2.2`. The MCP entry point is `uv run bind9-aiops-mcp`. The process account needs access to its `rndc` key file and BIND config, but no elevated shell is given to the agent.
+
+## Scope and verification
+
+`reload-zone`, `refresh-zone`, `flush-name`, `retransfer-zone` and `notify-zone` support dry-run and two CLI confirmations. RNDC command acceptance does not prove a queued zone reload or transfer completed, so these writes report `outcomeUnknown`; a lost command response does too. No safe undo exists for a cache flush, retransfer, NOTIFY delivery or externally edited zone file. Zone-file editing, DNSSEC key changes and global service restarts remain outside this release. See [verification](docs/VERIFICATION.md). Missing features and live-environment feedback are welcome as issues or PRs.

bind9_aiops-0.2.0/SECURITY.md

@@ -0,0 +1,5 @@
+# Security
+
+Report vulnerabilities privately through GitHub security advisories when the repository is available. Do not share `rndc` keys or private zone data in public issues.
+
+The tool invokes configured binaries with argument lists, never a shell. It does not accept an agent-provided command or file path. Access to `rndc` is controlled by the operating-system account and the `rndc` key file; keep that file private. Reload, refresh, name-specific cache flush, high-risk secondary retransfer and NOTIFY resend have dry-run and CLI double confirmation. RNDC acceptance is recorded as unknown until the operator verifies the resulting DNS state. Audit records and budget enforcement are bundled locally.

bind9_aiops-0.2.0/bind9_aiops/__init__.py

@@ -0,0 +1,8 @@
+"""BIND 9 AIops: governed read-only DNS operations."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("bind9-aiops")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"

bind9_aiops-0.2.0/bind9_aiops/cli/__init__.py

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

bind9_aiops-0.2.0/bind9_aiops/cli/_common.py

@@ -0,0 +1,118 @@
+"""Shared helpers for bind9-aiops CLI sub-modules."""
+
+from __future__ import annotations
+
+import functools
+from collections.abc import Callable
+from typing import Annotated, Any
+
+import typer
+from rich.console import Console
+from rich.markup import escape
+
+console = Console()
+
+# ─── Shared Option types ───────────────────────────────────────────────────
+
+TargetOption = Annotated[str | None, typer.Option("--target", "-t", help="Target name from config")]
+DryRunOption = Annotated[
+    bool, typer.Option("--dry-run", help="Print the API call without executing")
+]
+
+
+def _cli_error_types() -> tuple[type[BaseException], ...]:
+    """Exceptions translated to a one-line teaching error instead of a traceback.
+
+    ``BudgetExceeded`` (and the retained ``PolicyDenied`` type) are raised by
+    ``@governed_tool`` OUTSIDE the tool body, so ``tool_errors`` never sees them
+    and they never arrive as an ``{"error": ...}`` dict. Their message is the
+    teaching text (e.g. which budget was hit) — without them here such a refusal
+    reaches the CLI as a traceback instead.
+    """
+    from bind9_aiops.connection import BindCommandError
+    from bind9_aiops.governance import BudgetExceeded, PolicyDenied
+
+    return (BindCommandError, PolicyDenied, BudgetExceeded, KeyError, OSError, ValueError)
+
+
+def cli_errors(fn: Callable) -> Callable:
+    """Translate known exceptions into one red line + exit code 1."""
+
+    @functools.wraps(fn)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        try:
+            return fn(*args, **kwargs)
+        except (typer.Exit, typer.Abort):
+            raise
+        except _cli_error_types() as e:
+            message = str(e)
+            if isinstance(e, KeyError):
+                message = f"Missing required key or environment variable: {message}"
+            # Upstream text can contain "[/bold]"; unescaped, rich raises on it and the
+            # real error is replaced by a MarkupError traceback.
+            console.print(f"[red]Error: {escape(message)}[/]")
+            raise typer.Exit(1) from e
+
+    return wrapper
+
+
+#: Exit status for a write whose outcome could not be determined — kept distinct
+#: from 0 (confirmed) and 1 (failed) so a script can tell all three apart.
+EXIT_UNDETERMINED = 2
+
+
+def governed(result: Any) -> dict:
+    """Return a governed tool's result, or print its error and exit 1.
+
+    The ``bind9_aiops.mcp_server.tools`` twins never raise: ``@tool_errors`` flattens every
+    failure — an unreachable service, a refused login, a bad argument — into
+    ``{"error": ...}``. A CLI command that drops that on the floor prints an empty
+    table and exits 0 as if the service had nothing to report. Route every governed
+    call through here.
+    """
+    # ``outcomeUnknown`` is judged BEFORE ``error``, matching the harness: a
+    # write whose response was lost carries BOTH keys, and it is audited
+    # `unknown` precisely because it may have taken effect. Reporting that as a
+    # plain failure would tell a script the change did not happen and invite the
+    # double-apply the payload's own note warns about.
+    if isinstance(result, dict) and result.get("outcomeUnknown"):
+        console.print(f"[yellow]Outcome undetermined: {escape(str(result.get('note') or ''))}[/]")
+        raise typer.Exit(EXIT_UNDETERMINED)
+    if isinstance(result, dict) and result.get("error"):
+        console.print(f"[red]Error: {escape(str(result['error']))}[/]")
+        raise typer.Exit(1)
+    return result if isinstance(result, dict) else {}
+
+
+def dry_run_print(*, operation: str, api_call: str, parameters: dict | None = None) -> None:
+    """Print a dry-run preview of the API call that would be made."""
+    console.print("\n[bold magenta][DRY-RUN] No changes will be made.[/]")
+    console.print(f"[magenta]  Operation: {operation}[/]")
+    console.print(f"[magenta]  API Call:  {api_call}[/]")
+    for k, v in (parameters or {}).items():
+        console.print(f"[magenta]  Param:     {k} = {v}[/]")
+    console.print("[magenta]  Run without --dry-run to execute.[/]\n")
+
+
+def double_confirm(action: str, resource: str) -> None:
+    """Require two confirmations for a destructive operation."""
+    console.print(f"[bold yellow]⚠️  About to: {action} '{resource}'[/]")
+    typer.confirm(f"Confirm 1/2: {action} '{resource}'?", abort=True)
+    typer.confirm(
+        f"Confirm 2/2: really {action} '{resource}'? This may be irreversible.",
+        abort=True,
+    )
+
+
+def print_truncation_note(result: dict, noun: str) -> None:
+    """Print a visible warning when a listing envelope was capped.
+
+    The JSON already carries ``truncated``, but a human scrolling a long dump
+    will not spot it — and neither will a model summarising the terminal. Say
+    it in words, on the last line, where it cannot be missed.
+    """
+    if isinstance(result, dict) and result.get("truncated"):
+        console.print(
+            f"[yellow]… showing {result.get('returned')} of more {noun} — "
+            f"truncated, re-run with a higher --limit[/]"
+        )