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.

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.yml
index 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 exists
run: 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.py
diff --git a/.gitignore b/.gitignore
index 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
+*.test
diff --git a/docs/maintenance-2026-10-index.md b/docs/maintenance-2026-10-index.md
index 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.md
index 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-test
deleted file mode 100755
index 81a920c99..000000000
Binary files a/plugins/mttr-widget/go/mttr-widget-test and /dev/null differ
diff --git a/scripts/check_machine_paths.py b/scripts/check_machine_paths.py
new file mode 100644
index 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())