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
"""Tool-attribution gate.
AiSOC never attributes work to a development tool or AI assistant — not in code,
comments, docs, plan files, commit messages, commit trailers, PR bodies, release
notes or marketing copy. This gate fails CI when such an attribution appears in:
* a commit message on the pull request's commits,
* a file changed by the pull request (or the whole tree with --all),
* the pull request body.
It reads its patterns from .githooks/attribution-patterns.txt — the same file
.githooks/commit-msg reads — so the client-side hook that strips attribution and
the server-side gate that blocks it cannot drift apart and start disagreeing.
Legitimate human `Co-authored-by:` trailers are untouched: a pattern only fires
when the trailer names a known tool, so a real contributor is never flagged. The
allowlist (.githooks/attribution-allowlist.txt) is the escape hatch for a human
whose name collides with a vendor string, and for prose that names a vendor
neutrally rather than as an attribution.
Usage:
python3 scripts/check_attribution.py --self-test
python3 scripts/check_attribution.py --all
python3 scripts/check_attribution.py --diff-base origin/main
python3 scripts/check_attribution.py --commits origin/main..HEAD
python3 scripts/check_attribution.py --text-file pr-body.md
"""
from __future__ import annotations
import argparse
import json
import re
import subprocess
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
ROOT = repo_root()
PATTERN_FILE = ROOT / ".githooks" / "attribution-patterns.txt"
ALLOWLIST_FILE = ROOT / ".githooks" / "attribution-allowlist.txt"
FIXTURES = ROOT / "scripts" / "attribution_fixtures.json"
HOOK = ROOT / ".githooks" / "commit-msg"
# Paths that legitimately contain the vendor strings because they are the
# machinery for detecting them, or a record of the cleanup. Scanning these would
# make the gate flag itself.
SELF_REFERENTIAL = {
".githooks/attribution-patterns.txt",
".githooks/attribution-allowlist.txt",
".githooks/commit-msg",
"scripts/check_attribution.py",
"scripts/attribution_fixtures.json",
".github/workflows/attribution.yml",
}
# Binary / generated paths that are never prose and would only produce noise.
SKIP_SUFFIXES = (
".png",
".jpg",
".jpeg",
".gif",
".webp",
".svg",
".ico",
".pdf",
".woff",
".woff2",
".ttf",
".eot",
".zip",
".gz",
".tar",
".jar",
".lock",
".bin",
".onnx",
".parquet",
)
SKIP_DIRS = ("node_modules/", ".git/", "dist/", "build/", ".next/", "vendor/")
def _load_patterns(path: Path) -> list[re.Pattern]:
if not path.exists():
sys.exit(f"check_attribution: missing pattern file {path}")
out = []
for raw in path.read_text(encoding="utf-8").splitlines():
line = raw.strip()
if not line or line.startswith("#"):
continue
try:
out.append(re.compile(line, re.IGNORECASE))
except re.error as exc:
sys.exit(f"check_attribution: bad pattern {line!r} in {path.name}: {exc}")
if not out:
sys.exit(f"check_attribution: {path.name} defines no patterns — refusing to run vacuously")
return out
PATTERNS = _load_patterns(PATTERN_FILE)
ALLOWLIST = _load_patterns(ALLOWLIST_FILE) if ALLOWLIST_FILE.exists() else []
def is_attribution(line: str) -> bool:
"""True when a single line is tool attribution and not allowlisted."""
if not any(p.search(line) for p in PATTERNS):
return False
return not any(a.search(line) for a in ALLOWLIST)
def scan_text(text: str, origin: str) -> list[tuple[str, int, str]]:
hits = []
for n, line in enumerate(text.splitlines(), 1):
if is_attribution(line):
hits.append((origin, n, line.strip()[:200]))
return hits
def _git(*args: str) -> str:
r = subprocess.run(["git", *args], cwd=ROOT, capture_output=True, text=True)
if r.returncode != 0:
sys.exit(f"check_attribution: git {' '.join(args)} failed: {r.stderr.strip()[:300]}")
return r.stdout
def _skip(rel: str) -> bool:
return rel in SELF_REFERENTIAL or rel.endswith(SKIP_SUFFIXES) or any(d in rel for d in SKIP_DIRS)
def scan_files(paths: list[str]) -> list[tuple[str, int, str]]:
hits = []
for rel in paths:
if _skip(rel):
continue
p = ROOT / rel
if not p.is_file():
continue
try:
text = p.read_text(encoding="utf-8")
except (UnicodeDecodeError, OSError):
continue
hits.extend(scan_text(text, rel))
return hits
def scan_commits(rev_range: str) -> list[tuple[str, int, str]]:
"""Scan commit messages in a range. Merge commits are included: a squash
merge composes its message from the branch commits, so a trailer on any of
them is what lands on main."""
out = _git("log", "--format=%H%x00%B%x00%x00", rev_range)
hits = []
for entry in out.split("\x00\x00"):
if not entry.strip():
continue
sha, _, body = entry.partition("\x00")
sha = sha.strip()
if not sha:
continue
hits.extend(scan_text(body, f"commit {sha[:12]}"))
return hits
def self_test() -> int:
"""Prove the gate is neither vacuous nor over-broad, in both directions, and
that the hook and the gate agree on the same corpus."""
data = json.loads(FIXTURES.read_text(encoding="utf-8"))
bad, good = data["bad"], data["good"]
failures: list[str] = []
print(f"self-test: {len(PATTERNS)} patterns, {len(ALLOWLIST)} allowlist entries")
print(f"self-test: {len(bad)} known-bad and {len(good)} known-good samples\n")
# Direction 1 — the gate must DETECT every known-bad sample. Without this a
# broken regex makes the gate pass everything, silently.
for s in bad:
if not is_attribution(s):
failures.append(f"gate MISSED known-bad sample: {s!r}")
# Direction 2 — the gate must NOT flag any known-good sample. Without this
# the gate could pass direction 1 by flagging literally everything.
for s in good:
if is_attribution(s):
failures.append(f"gate FLAGGED known-good sample: {s!r}")
# Direction 3 + 4 — the hook must strip exactly what the gate flags. This is
# the cross-check that keeps the two implementations honest about the same
# pattern file; without it they can drift in opposite directions and both
# look fine in isolation.
if HOOK.exists():
for s in bad:
if _hook_keeps(s):
failures.append(f"hook did NOT strip known-bad line: {s!r}")
for s in good:
if not _hook_keeps(s):
failures.append(f"hook STRIPPED known-good line: {s!r}")
else:
failures.append(f"hook not found at {HOOK} — cannot cross-check")
if failures:
print("SELF-TEST FAILED")
for f in failures:
print(f" - {f}")
return 1
print("SELF-TEST PASSED")
print(" gate detects every known-bad sample (not vacuous)")
print(" gate flags no known-good sample (not over-broad)")
print(" hook strips exactly what the gate flags (no hook/gate drift)")
return 0
def _hook_keeps(line: str) -> bool:
"""Run the real hook over a message containing `line`; True if it survived."""
import tempfile
with tempfile.NamedTemporaryFile("w", suffix=".msg", delete=False, encoding="utf-8") as fh:
fh.write(f"chore: fixture subject\n\nbody line that must survive\n\n{line}\n")
path = fh.name
try:
subprocess.run(["sh", str(HOOK), path], capture_output=True, text=True, cwd=ROOT)
result = Path(path).read_text(encoding="utf-8")
finally:
Path(path).unlink(missing_ok=True)
if "body line that must survive" not in result:
raise SystemExit(f"hook destroyed real content while processing {line!r}")
return line in result
def main() -> int:
ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
ap.add_argument("--self-test", action="store_true", help="prove the gate works, both directions")
ap.add_argument("--all", action="store_true", help="scan every tracked file")
ap.add_argument("--diff-base", help="scan files changed against this ref")
ap.add_argument("--commits", help="scan commit messages in this rev range")
ap.add_argument("--text-file", action="append", default=[], help="scan a text file (e.g. the PR body)")
args = ap.parse_args()
if args.self_test:
return self_test()
hits: list[tuple[str, int, str]] = []
scanned: list[str] = []
if args.all:
files = [f for f in _git("ls-files").splitlines() if f]
hits += scan_files(files)
scanned.append(f"{len(files)} tracked files")
if args.diff_base:
files = [f for f in _git("diff", "--name-only", f"{args.diff_base}...HEAD").splitlines() if f]
hits += scan_files(files)
scanned.append(f"{len(files)} changed files vs {args.diff_base}")
if args.commits:
hits += scan_commits(args.commits)
n = len([x for x in _git("rev-list", args.commits).splitlines() if x])
scanned.append(f"{n} commit messages in {args.commits}")
for tf in args.text_file:
p = Path(tf)
if p.is_file() and p.stat().st_size > 0:
hits += scan_text(p.read_text(encoding="utf-8"), f"text:{p.name}")
scanned.append(f"text file {p.name}")
if not scanned:
ap.error("nothing to scan — pass --all, --diff-base, --commits, --text-file or --self-test")
# Name the repository that was actually inspected. Every git read below runs
# against the checkout this script lives in, not the caller's cwd, so a run
# launched from a different worktree would otherwise print a confident "OK"
# about a tree it never looked at.
print(f"check_attribution: repo {ROOT}")
print("check_attribution: scanned " + ", ".join(scanned))
if hits:
print(f"\nFAIL — {len(hits)} tool-attribution violation(s):\n")
for origin, n, line in hits:
print(f" {origin}:{n}: {line}")
print(
"\nAiSOC does not attribute work to a development tool or AI assistant.\n"
"Remove the line. If it is a commit trailer, `sh scripts/setup_hooks.sh`\n"
"installs the hook that strips it automatically, then amend the commit.\n"
"If this is a false positive (a contributor whose name collides with a\n"
"vendor string, or neutral prose), add a justified entry to\n"
".githooks/attribution-allowlist.txt so a reviewer sees it in the diff."
)
return 1
print("OK — no tool attribution found.")
return 0
if __name__ == "__main__":
sys.exit(main())