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
fix: no tracked file may name one computer's filesystem (#1312)
Beenu Aroraaa68e1fd5a44
diff --git a/.github/workflows/comment-paths.yml b/.github/workflows/comment-paths.ymlindex cd2ebdd6e..a1ece97be 100644--- a/.github/workflows/comment-paths.yml+++ b/.github/workflows/comment-paths.yml@@ -91,3 +91,13 @@ jobs:- name: Every repository path named in a comment existsrun: python3 scripts/check_comment_paths.py++ # Same job, because it is the same question asked the other way round:+ # that gate checks a path in a comment resolves inside the repository,+ # this one checks no path escapes it. Unconditional on push, so a+ # machine path cannot land through a file type the filters above miss.+ - name: Prove the machine-path gate still detects what it claims to+ run: python3 scripts/check_machine_paths.py --self-test++ - name: No tracked file names one computer's filesystem+ run: python3 scripts/check_machine_paths.pydiff --git a/.gitignore b/.gitignoreindex 88f9407c3..276908425 100644--- a/.gitignore+++ b/.gitignore@@ -160,3 +160,12 @@ schemas/graph-schema-current.yaml# Generated by scripts/resolve_port_conflicts.py when a host port AiSOC# publishes is already in use. Machine-specific by definition.docker-compose.ports.yml++# Compiled Go test binaries. `go test -c` drops one beside the source named+# after its directory, and one was committed in May 2026: 4.2 MB of Mach-O+# arm64 that nothing referenced, carrying the absolute build paths of the+# machine that produced it. A binary cannot be reviewed, is wrong for every+# architecture but one, and embeds whatever directory its author happened to+# work in.+plugins/*/go/*-test+*.testdiff --git a/docs/maintenance-2026-10-index.md b/docs/maintenance-2026-10-index.mdindex 88158e44b..a3b477345 100644--- a/docs/maintenance-2026-10-index.md+++ b/docs/maintenance-2026-10-index.md@@ -1,8 +1,10 @@# AiSOC maintenance docs — Oct 2026 live session-Working documentation for the deployment on `10.200.0.69`-(`/home/ubuntu/AiSOC`, compose project `aisoc`), covering the Oct 2026-diagnose-and-fix session. Code fixes: branch+Working documentation from the Oct 2026 diagnose-and-fix session, carried+out against a self-hosted deployment (compose project `aisoc`, repo at+`$AISOC_ROOT`). The host address and path are deliberately not recorded:+they were one contributor's, and naming them made a general runbook read+as if it only applied there. Code fixes: branch`fix/aisoc-live-session-2026-10` on https://github.com/alexmateescu/AiSOC.| File | Purpose |diff --git a/docs/ops-runbook.md b/docs/ops-runbook.mdindex 43428822b..46898eea2 100644--- a/docs/ops-runbook.md+++ b/docs/ops-runbook.md@@ -1,7 +1,14 @@# AiSOC ops runbook — live deployment-Host: `10.200.0.69` (SSH `ubuntu@`, key `~/.ssh/c8r-tech-key`)-Repo/compose project: `/home/ubuntu/AiSOC` (compose project name `aisoc`)+Host: your deployment's address (SSH user and key are yours)+Repo/compose project: `$AISOC_ROOT`, wherever you cloned it (compose+project name `aisoc`)++> The commands below use `$AISOC_ROOT` rather than a literal path. Set it+> once — `export AISOC_ROOT="$(git rev-parse --show-toplevel)"` — and they+> run on any host. This file previously named one contributor's home+> directory and private IP, which read as instructions and worked on+> exactly one machine.Origin: `https://github.com/beenuar/AiSOC` · Fork: `https://github.com/alexmateescu/AiSOC`## Service map (container → host port → role)diff --git a/plugins/mttr-widget/go/mttr-widget-test b/plugins/mttr-widget/go/mttr-widget-testdeleted file mode 100755index 81a920c99..000000000Binary files a/plugins/mttr-widget/go/mttr-widget-test and /dev/null differdiff --git a/scripts/check_machine_paths.py b/scripts/check_machine_paths.pynew file mode 100644index 000000000..b62fcaa5e--- /dev/null+++ b/scripts/check_machine_paths.py@@ -0,0 +1,303 @@+#!/usr/bin/env python3+"""No tracked file may carry an absolute path from the machine that wrote it.++A clone is the product. A path like ``/Users/someone/Desktop/AiSOC-d9surf``+resolves on exactly one computer in the world, so a script carrying one runs+for its author and fails for everybody else -- and it fails *late*, after the+reader has already trusted the file enough to run it.++Two real instances motivated this gate, and they are different shapes:++* A deploy script opened with ``ROOT="/Users/<someone>/Desktop/AgenticSOC"``+ and then ``cd "$ROOT"``. Nobody else could run it.+* A 4.2 MB compiled Go test binary was committed in May 2026. Nothing+ referenced it, it was wrong for every architecture but one, and ``strings``+ showed the absolute build paths of the machine that produced it. A binary+ also cannot be reviewed, which is why this gate refuses executables in the+ source tree rather than only scanning text.++What a script should do instead is derive its own root::++ ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"++and in Python, ``pathlib.Path(__file__).resolve().parents[N]``.++Exit codes: 0 clean, 1 findings, 2 nothing scanned (a scope that collects no+files is a gate that cannot fail, which is worse than no gate because its+presence implies coverage).++Usage::++ python3 scripts/check_machine_paths.py+ python3 scripts/check_machine_paths.py --self-test+"""++from __future__ import annotations++import argparse+import re+import subprocess+import sys+from dataclasses import dataclass, field+from pathlib import Path++# `scripts/` is on sys.path when this file runs 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 # noqa: E402++# Resolved through `git rev-parse`, not from `__file__`. Two levels above this+# script is whatever happens to be there — and `scripts/` copied into an empty+# repository is exactly that, which is how the first version of this gate+# reported 253 files clean without ever seeing the product.+REPO = repo_root()++#: A home directory alone is not the defect, and assuming it was is how the+#: first draft of this gate produced 288 findings that were all correct+#: content: detection rules matching `/home/*/.bashrc`, synthetic telemetry+#: carrying user home paths, and a benchmark corpus. Security software is+#: *supposed* to contain strings that look like someone's home directory.+#:+#: What breaks a clone is narrower and has a signature: a home-rooted path+#: that also names **a checkout of this repository**. That is a path the+#: tooling depends on to run, and it resolves on exactly one computer.+_HOME_ROOT = r"(?:/Users/[A-Za-z0-9._-]+|/home/[A-Za-z0-9._-]+|[A-Za-z]:\\{1,2}Users\\{1,2}[A-Za-z0-9._-]+)"++#: Directory names that mean "a checkout of this project".+_CHECKOUT = r"(?:[Aa]gentic[Ss][Oo][Cc]|[Aa]i[Ss][Oo][Cc])"++#: A separator may be a slash, one backslash, or the doubled backslash a+#: JSON or Go string literal carries.+_MACHINE_PATH = re.compile(rf"{_HOME_ROOT}[/\\\\]{{1,2}}(?:[A-Za-z0-9._-]+[/\\\\]{{1,2}})*?{_CHECKOUT}[A-Za-z0-9._-]*")++#: Home-rooted strings that are not a machine path leaking into the product.+#: Each needs a reason, and the list is checked in both directions so an entry+#: nothing needs any more fails the build instead of sitting there looking+#: like coverage.+ALLOWED: dict[str, str] = {+ # Empty, and that is the correct state rather than an oversight.+ #+ # The first draft of this gate matched any home directory and needed+ # exemptions for `/home/runner`, `/Users/runner` and the devcontainer+ # users. Narrowing the pattern to "a home path that also names a checkout+ # of this repository" made every one of them unnecessary: a CI runner's+ # `/home/runner/.cache` no longer matches at all.+ #+ # `/home/runner/work/AiSOC/AiSOC` would still match, because it does name+ # a checkout. No tracked file contains it today. If a workflow ever needs+ # to, add it here **with the reason** -- the list is checked in both+ # directions, so an entry nothing needs fails the build rather than+ # sitting there looking like coverage.+}++#: Extensions that are never source and should not be committed at all. A+#: compiled artefact cannot be reviewed and is wrong for every architecture+#: but the one it was built on.+BINARY_SUFFIXES: tuple[str, ...] = (".test", ".exe", ".dylib", ".so", ".a", ".o")++#: This gate's own self-test corpus is the one place a machine path is+#: deliberate: it is the thing being detected. Skipping the file keeps the+#: fixtures readable as real strings rather than obfuscated to dodge the+#: checker they exist to exercise.+SKIP_FILES: tuple[str, ...] = ("scripts/check_machine_paths.py",)++SKIP_DIRECTORIES: tuple[str, ...] = (+ "plans/", # historical prototype, kept verbatim as a reference+ ".git/",+ "node_modules/",+)+++@dataclass+class Finding:+ kind: str+ detail: str+++@dataclass+class Scan:+ findings: list[Finding] = field(default_factory=list)+ scanned: int = 0+++def tracked_files(root: Path) -> list[str]:+ """Every tracked path. Untracked files are not what a clone receives."""+ out = subprocess.run(+ ["git", "-C", str(root), "ls-files", "-z"],+ capture_output=True,+ text=True,+ check=False,+ )+ return [p for p in out.stdout.split("\0") if p]+++def is_allowed(line: str, match: str) -> bool:+ return any(line.startswith(prefix) or match.startswith(prefix) for prefix in ALLOWED)+++def scan_text(path: Path, relative: str) -> list[Finding]:+ """Machine paths in one text file, with the allowlist applied per match."""+ try:+ content = path.read_text(encoding="utf-8")+ except (UnicodeDecodeError, OSError):+ return []++ findings: list[Finding] = []+ for number, line in enumerate(content.splitlines(), start=1):+ for match in _MACHINE_PATH.finditer(line):+ text = match.group(0)+ if any(text.startswith(prefix) for prefix in ALLOWED):+ continue+ findings.append(+ Finding(+ "machine-path",+ f"{relative}:{number} names {text!r}, which exists on one computer. "+ "Derive the root instead: "+ '`ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"` in bash, '+ "`Path(__file__).resolve().parents[N]` in Python.",+ )+ )+ return findings+++def scan(root: Path | None = None) -> Scan:+ root = root or REPO+ result = Scan()+ used: set[str] = set()++ for relative in tracked_files(root):+ if relative in SKIP_FILES or any(relative.startswith(skip) for skip in SKIP_DIRECTORIES):+ continue+ path = root / relative++ if relative.endswith(BINARY_SUFFIXES):+ result.findings.append(+ Finding(+ "committed-binary",+ f"{relative} is a compiled artefact. It cannot be reviewed, it is wrong "+ "for every architecture but the one it was built on, and it carries the "+ "absolute build paths of the machine that produced it. Build it in CI "+ "and ignore the output.",+ )+ )+ continue++ if not path.is_file():+ continue+ result.scanned += 1+ found = scan_text(path, relative)+ result.findings.extend(found)++ try:+ content = path.read_text(encoding="utf-8")+ except (UnicodeDecodeError, OSError):+ continue+ for prefix in ALLOWED:+ if prefix in content:+ used.add(prefix)++ for prefix in sorted(set(ALLOWED) - used):+ result.findings.append(+ Finding(+ "stale-exemption",+ f"ALLOWED[{prefix!r}] — no tracked file names it any more, so the "+ "exemption is describing a tree that no longer exists. Delete it.",+ )+ )++ return result+++def self_test() -> int:+ """Prove the gate catches each shape, and passes what it must pass.++ Both directions, because a checker that flags everything is as useless as+ one that flags nothing — and `/home/runner` appears in real workflows, so+ an over-broad pattern would red the whole tree on day one.+ """+ cases: list[tuple[str, str, bool]] = [+ # The two real instances this gate was written for.+ ("a checkout under Desktop", 'ROOT="/Users/someone/Desktop/AgenticSOC"', True),+ ("a worktree of it", "cd /Users/someone/Desktop/AiSOC-d9surf", True),+ ("a linux checkout elsewhere", "ROOT=/home/someone/src/aisoc", True),+ ("a windows checkout", r"SET ROOT=C:\\Users\\someone\\AiSOC", True),+ # Security content, which is the whole reason the first draft of this+ # pattern was wrong. A detection rule naming a home directory is doing+ # its job; 288 such findings were produced before this was narrowed.+ ("a detection rule's home glob", "/home/*/.bashrc", False),+ ("a fixture's synthetic user", r"C:\\Users\\Bob\\Documents", False),+ ("a truncated test path", "/home/u/.ssh/authorized_keys", False),+ ("a home path with no checkout in it", "/Users/someone/Downloads/report.pdf", False),+ # Portable forms.+ ("a derived root", 'ROOT="$(cd "$(dirname "$0")/../.." && pwd)"', False),+ ("a repo-relative path", "services/api/app/main.py", False),+ ("an absolute system path", "/usr/local/bin/python3", False),+ ("a container path", "/app/templates", False),+ ]++ failures = 0+ for name, line, should_flag in cases:+ flagged = any(not any(m.group(0).startswith(p) for p in ALLOWED) for m in _MACHINE_PATH.finditer(line))+ ok = flagged == should_flag+ failures += not ok+ print(f" self-test [{'ok' if ok else 'FAIL'}] {name}")++ for suffix in BINARY_SUFFIXES:+ name = f"plugins/x/go/widget{suffix}"+ ok = name.endswith(BINARY_SUFFIXES)+ failures += not ok+ print(f" self-test [{'ok' if ok else 'FAIL'}] a committed {suffix} artefact is refused")++ print(+ f"\ncheck_machine_paths.py: self-test {'OK' if not failures else f'FAILED ({failures})'}"+ f" — {len(cases) + len(BINARY_SUFFIXES)} cases, both directions"+ )+ return 1 if failures else 0+++def main() -> int:+ parser = argparse.ArgumentParser(description=__doc__)+ parser.add_argument("--self-test", action="store_true", help="prove the gate still detects")+ args = parser.parse_args()++ if args.self_test:+ return self_test()++ # Refuse a tree that is not this repository, before scanning it.+ #+ # `scanned == 0` is not a strong enough guard: `scripts/` copied into an+ # empty git repository yields 253 tracked files, and this gate reported+ # them clean — a pass over a corpus that contains none of the product.+ # That is the exact shape `No check may report OK over a repository with+ # no content` exists to catch, and it caught this one.+ #+ # Each required input is somewhere a machine path has actually been found+ # or would land: the services tree, the deployment scripts, and the+ # compose file a self-hoster runs.+ missing = [name for name in ("services", "infra", "docker-compose.yml") if not (REPO / name).exists()]+ if missing:+ print(+ "check_machine_paths: FAILED to read the tree: expected input does not exist: "+ + ", ".join(str(REPO / name) for name in missing),+ file=sys.stderr,+ )+ return 2++ result = scan()+ if not result.scanned:+ print("check_machine_paths: nothing scanned — refusing to report clean", file=sys.stderr)+ return 2++ if result.findings:+ print(f"FAIL — {len(result.findings)} finding(s):")+ for finding in result.findings:+ print(f" [{finding.kind}] {finding.detail}")+ return 1++ print(f"check_machine_paths: OK — {result.scanned} tracked text file(s), no machine-specific path")+ return 0+++if __name__ == "__main__":+ raise SystemExit(main())