Skip to content

armgit / AiSOC

Public Imported from GitHub
0

Open-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATT&CK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.

3.2 KB
Raw Blame
#!/usr/bin/env python3
"""
Phase 2.5 — verify every `runbook_url` referenced from
``infra/docker/alerts/aisoc.rules.yml`` points at a file that
actually exists under ``docs/runbooks/``.

The alert rules embed runbook URLs like
``https://github.com/beenuar/AiSOC/blob/main/docs/runbooks/
service-down.md`` so Alertmanager's notification template can
deep-link the on-call. If those files don't exist, the on-call
gets a 404 at the worst possible moment.

This script enforces the invariant: every URL pointing into the
repo's ``docs/runbooks/`` directory must resolve to a tracked file.
External URLs (vendor docs, RFC pages) are skipped.

Usage::

    python3 scripts/audit_runbook_links.py            # report mode
    python3 scripts/audit_runbook_links.py --check    # CI mode
"""

from __future__ import annotations

import argparse
import pathlib
import re
import sys

# `scripts/` is on sys.path when this file is run as a program, but not when a
# test loads it by path with importlib. gate_toolkit sits beside it either way.
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))

from gate_toolkit import repo_root, self_test_if_requested

self_test_if_requested(__file__)

REPO_ROOT = repo_root()
ALERTS = REPO_ROOT / "infra" / "docker" / "alerts" / "aisoc.rules.yml"
RUNBOOK_PATH_PREFIX = "docs/runbooks/"

RUNBOOK_LINK_RE = re.compile(r"runbook_url:\s*(\S+)")


def extract_runbook_paths() -> list[str]:
    """Return runbook relative paths referenced from alert rules.

    Accepts both repo-rooted paths (``docs/runbooks/foo.md``) and
    GitHub blob URLs (``https://github.com/.../docs/runbooks/foo.md``)
    — both should resolve to the same on-disk file.
    """
    text = ALERTS.read_text(encoding="utf-8")
    paths: list[str] = []
    for m in RUNBOOK_LINK_RE.finditer(text):
        raw = m.group(1).strip().rstrip(",")
        idx = raw.find(RUNBOOK_PATH_PREFIX)
        if idx == -1:
            continue
        paths.append(raw[idx:])
    return paths


def main() -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument(
        "--check",
        action="store_true",
        help="exit non-zero if any runbook URL points at a missing file",
    )
    args = parser.parse_args()

    paths = extract_runbook_paths()
    if not paths:
        print(
            f"WARN: no runbook URLs found in {ALERTS.relative_to(REPO_ROOT)} — did the alert rule schema change?",
            file=sys.stderr,
        )
        return 0 if not args.check else 1

    missing: list[str] = []
    print(f"Auditing {len(paths)} runbook URLs in {ALERTS.relative_to(REPO_ROOT)}:")
    for rel in sorted(set(paths)):
        on_disk = REPO_ROOT / rel
        if on_disk.exists():
            print(f"  OK   {rel}")
        else:
            print(f"  MISS {rel}")
            missing.append(rel)

    if args.check and missing:
        print(
            "\nFAIL: alert rules reference runbooks that don't exist:\n  - "
            + "\n  - ".join(missing)
            + "\n\nEither create the runbook under docs/runbooks/ or remove "
            "the `runbook_url` from the alert.",
            file=sys.stderr,
        )
        return 1
    return 0


if __name__ == "__main__":
    sys.exit(main())