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.
Python agentic-aiai-securityalert-triageblue-teamcybersecuritydetection-engineeringincident-responselanggraphllm-agentsmcpmitre-attackmodel-context-protocolpurple-teamsecurity-operationsself-hostedsiemsoarsocthreat-detectionthreat-intelligence
#!/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()