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.

6.6 KB
Raw Blame
#!/usr/bin/env python3
"""
Export the AiSOC FastAPI OpenAPI schema to docs/openapi.yaml.

Usage
-----
  python scripts/export_openapi.py [--check]

  --check   Diff mode: exit 1 if docs/openapi.yaml differs from what the app
            currently generates.  Used by CI to keep the committed schema in sync.

The script imports the FastAPI application directly (no running server needed)
and calls ``app.openapi()`` to get the schema, then serialises it to YAML.

MIT License — AiSOC (open-source AI Security Operations Center)
"""

from __future__ import annotations

import argparse
import os
import sys
from pathlib import Path

# `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(Path(__file__).resolve().parent))

from gate_toolkit import repo_root, self_test_if_requested

self_test_if_requested(__file__)

# ── Ensure the api service is importable ─────────────────────────────────────
REPO_ROOT = repo_root()
API_SRC = REPO_ROOT / "services" / "api"
if str(API_SRC) not in sys.path:
    sys.path.insert(0, str(API_SRC))

# Set minimal env vars so settings validation doesn't fail
os.environ.setdefault("ENVIRONMENT", "development")
os.environ.setdefault("SECRET_KEY", "export-openapi-dummy-secret-key-32bytes!")
os.environ.setdefault("DATABASE_URL", "postgresql+asyncpg://x:x@localhost/x")

try:
    import yaml  # PyYAML
except ImportError:
    print("ERROR: PyYAML is required. Install with: pip install pyyaml", file=sys.stderr)
    sys.exit(1)

from app.main import app  # noqa: E402  (after sys.path manipulation)


def get_schema() -> dict:
    return app.openapi()


def write_yaml(schema: dict, dest: Path) -> None:
    dest.parent.mkdir(parents=True, exist_ok=True)
    with dest.open("w", encoding="utf-8") as fh:
        yaml.dump(schema, fh, allow_unicode=True, sort_keys=False, default_flow_style=False)
    print(f"OpenAPI schema written to {dest.relative_to(REPO_ROOT)}")


def _locked_version(package: str) -> str | None:
    """What `services/api/poetry.lock` pins `package` to, if it can be read."""
    lock = REPO_ROOT / "services" / "api" / "poetry.lock"
    if not lock.exists():
        return None
    wanted = f'name = "{package}"'
    lines = lock.read_text(encoding="utf-8").splitlines()
    for i, line in enumerate(lines):
        if line.strip() == wanted:
            for follow in lines[i + 1 : i + 4]:
                stripped = follow.strip()
                if stripped.startswith("version = "):
                    return stripped.split('"')[1]
    return None


def _report_generator_versions() -> None:
    """Name a toolchain mismatch, because it is the usual cause and the
    message above cannot fix it.

    The schema is generated by pydantic and FastAPI, and both change their
    output between minors -- pydantic 2.13 emits `additionalProperties: true`
    on bare `dict` responses where 2.8 did not, which is 252 lines of diff
    across this file and nothing to do with anyone's change. Told only to
    "run export_openapi.py", a contributor runs the command that produced the
    rejected file and gets the same result, which is the least useful place a
    gate can leave somebody.
    """
    for package, module in (("pydantic", "pydantic"), ("fastapi", "fastapi")):
        locked = _locked_version(package)
        try:
            installed = __import__(module).VERSION if package == "pydantic" else __import__(module).__version__
        except Exception:  # pragma: no cover - a missing generator fails earlier
            continue
        if locked and installed != locked:
            print(
                f"    {package} {installed} is installed and services/api/poetry.lock pins {locked}.\n"
                f"    That alone changes the generated schema. Install the locked version first:\n"
                f"        pip install '{package}=={locked}'",
                file=sys.stderr,
            )


def _report_first_differences(existing: dict, schema: dict, limit: int = 8) -> None:
    """Print the first few paths that differ, so the cause is visible here.

    A gate that says only "these two documents differ" over a 30,000-line file
    leaves the reader to reconstruct the diff by hand.
    """

    def walk(a: object, b: object, trail: str) -> list[str]:
        if isinstance(a, dict) and isinstance(b, dict):
            out: list[str] = []
            for key in sorted(set(a) | set(b)):
                if key not in a:
                    out.append(f"{trail}.{key}: only in the generated schema")
                elif key not in b:
                    out.append(f"{trail}.{key}: only in the committed file")
                else:
                    out.extend(walk(a[key], b[key], f"{trail}.{key}"))
                if len(out) >= limit:
                    break
            return out
        if a != b:
            return [f"{trail}: committed {a!r} vs generated {b!r}"]
        return []

    differences = walk(existing, schema, "")[:limit]
    if differences:
        print("    First differences:", file=sys.stderr)
        for line in differences:
            print(f"      {line}"[:200], file=sys.stderr)


def check_yaml(schema: dict, dest: Path) -> bool:
    """Return True if file matches generated schema."""
    if not dest.exists():
        print(f"{dest.relative_to(REPO_ROOT)} does not exist. Run: python scripts/export_openapi.py", file=sys.stderr)
        return False

    with dest.open("r", encoding="utf-8") as fh:
        existing = yaml.safe_load(fh)

    if existing != schema:
        print(
            f"{dest.relative_to(REPO_ROOT)} is out of date.\n    Run: python scripts/export_openapi.py  then commit the result.",
            file=sys.stderr,
        )
        _report_generator_versions()
        _report_first_differences(existing, schema)
        return False

    print(f"{dest.relative_to(REPO_ROOT)} is up to date.")
    return True


def main() -> None:
    parser = argparse.ArgumentParser(description="Export or verify AiSOC OpenAPI schema.")
    parser.add_argument(
        "--check",
        action="store_true",
        help="Exit with code 1 if docs/openapi.yaml differs from the current schema.",
    )
    parser.add_argument(
        "--output",
        default=str(REPO_ROOT / "docs" / "openapi.yaml"),
        help="Destination path (default: docs/openapi.yaml)",
    )
    args = parser.parse_args()

    dest = Path(args.output)
    schema = get_schema()

    if args.check:
        ok = check_yaml(schema, dest)
        sys.exit(0 if ok else 1)
    else:
        write_yaml(schema, dest)


if __name__ == "__main__":
    main()