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(qa): re-apply the two live-QA fixes lost in the branch consolidation (#1096)

Beenu Arora7ec2dbe1eaab
diff --git a/Makefile b/Makefile
index 47a1946c9..431980312 100644
--- a/Makefile
+++ b/Makefile
@@ -106,7 +106,8 @@ up: env _ports _refresh
@$(MAKE) --no-print-directory _wait
@echo ""
@echo " Console: $(console_url)"
- @echo " API: http://localhost:8000/api/docs"
+ @echo " API: http://localhost:8000 (spec: docs/openapi.yaml; interactive"
+ @echo " docs are off in this production-class stack)"
@echo ""
@echo "Prove the pipeline works: make smoke"
@$(MAKE) --no-print-directory bootstrap
@@ -155,7 +156,8 @@ up-dev: env _ports _refresh
@$(MAKE) --no-print-directory _wait
@echo ""
@echo " Console: $(console_url)"
- @echo " API: http://localhost:8000/api/docs"
+ @echo " API: http://localhost:8000 (spec: docs/openapi.yaml; interactive"
+ @echo " docs are off in this production-class stack)"
@echo ""
@echo " Anonymous access is ON. This overlay is for a laptop, not a host"
@echo " anyone else can reach."
@@ -167,7 +169,8 @@ up-full: env _ports _refresh
@$(MAKE) --no-print-directory _wait PROFILE=full
@echo ""
@echo " Console: $(console_url)"
- @echo " API: http://localhost:8000/api/docs"
+ @echo " API: http://localhost:8000 (spec: docs/openapi.yaml; interactive"
+ @echo " docs are off in this production-class stack)"
@echo ""
@echo "Prove the pipeline works: make smoke"
@$(MAKE) --no-print-directory bootstrap
diff --git a/PARITY_PROGRESS.md b/PARITY_PROGRESS.md
index c07d7e5f4..1239e3fcc 100644
--- a/PARITY_PROGRESS.md
+++ b/PARITY_PROGRESS.md
@@ -470,3 +470,21 @@ The console role-assignment UI is not built and is recorded as outstanding.
copilot), 3.7 (signed evidence bundles), 4.2 (console MFA), 4.3's console
UI, 4.4 (tenant audit views), 4.5 (operator pages), 4.6 (i18n), and all of
Phases 5 and 6.
+
+## Live QA fixes, re-applied (2026-10-02)
+
+Both were found by live QA, shipped on their own branch, and **lost** when
+that branch was closed as superseded: the combined phase-2-to-4 branch was
+built from the phase-4 tip, and the QA branch was never in that chain. A
+second live run against merged `main` found the graph 401 storm back at
+five per alert, which is how the loss was caught rather than assumed.
+
+| Defect | Fix |
+|---|---|
+| `make up`, `install.sh` and the README advertised `http://localhost:8000/api/docs`, which **404s** because `make up` starts a production-class stack where the API disables its interactive docs | All five surfaces point at `docs/openapi.yaml`. The pre-existing test that *required* the README to advertise a docs URL was rewritten: the invariant spanning both eras is "advertise one only if the documented path serves one" |
+| Every auto-triage emitted **four 401s per alert** on `graph/neighbors` and `graph/blast-radius` | `ContextBundleBuilder()` is constructed with no token and those routes authenticate a *user*, which a background worker has none of; on CORE there is no Neo4j behind them either. Reported once as "the entity graph runs in the `full` profile and is not part of this deployment" |
+
+One 401 per alert remains on `incident-context`, same root cause, recorded
+open: a guard there broke six tests that exercise the enabled path, and the
+proper fix is a service principal the API accepts, which belongs with 4.1's
+outstanding half.
diff --git a/README.md b/README.md
index d3c65c816..9f0dd8bd8 100644
--- a/README.md
+++ b/README.md
@@ -73,10 +73,10 @@ $ make smoke
[PASS] alert is retrievable by id from the API
```
-Open **http://localhost:3000** and sign in with the credentials `make up` printed (API docs at
-**http://localhost:8000/api/docs**). On a server, set `AISOC_CONSOLE_URL` in `.env` — `make up` then
-prints that address rather than localhost, which is the one people can browse to. Stuck?
-`make doctor`.
+Open **http://localhost:3000** and sign in with the credentials `make up` printed. The API is at
+**http://localhost:8000**; its spec is [`docs/openapi.yaml`](docs/openapi.yaml), because interactive
+docs are off in this production-class stack. On a server set `AISOC_CONSOLE_URL` in `.env`, and
+`make up` prints that address rather than localhost. Stuck? `make doctor`.
## Try it without connecting anything
diff --git a/install.sh b/install.sh
index 4c0dbbe03..886c2653a 100755
--- a/install.sh
+++ b/install.sh
@@ -876,7 +876,9 @@ print_success() {
${C_BOLD}${C_GREEN}AiSOC is up and running${C_RESET}${C_GREEN}, and a real event reached the API.${C_RESET}
${C_BOLD}Web console:${C_RESET} http://localhost:3000
- ${C_BOLD}API + Swagger:${C_RESET} http://localhost:8000/api/docs
+ ${C_BOLD}API:${C_RESET} http://localhost:8000
+ ${C_BOLD}API spec:${C_RESET} docs/openapi.yaml (interactive docs are off in
+ this production-class stack, which is the posture to keep)
${C_BOLD}Realtime WS:${C_RESET} ws://localhost:8086
${C_BOLD}Sign in as:${C_RESET} ${AISOC_ADMIN_EMAIL:[email protected]}
diff --git a/services/agents/app/tools/graph.py b/services/agents/app/tools/graph.py
index 494ac73cc..a13147fa6 100644
--- a/services/agents/app/tools/graph.py
+++ b/services/agents/app/tools/graph.py
@@ -20,6 +20,49 @@ _API_URL = os.getenv("API_SERVICE_URL", "http://api:8000")
_TIMEOUT = float(os.getenv("AGENTS_API_TIMEOUT", "10.0"))
+#: Whether the entity graph is part of this deployment. Neo4j is a `full`
+#: profile service, so on CORE there is no graph to read and every call
+#: below would fail regardless of credentials.
+_GRAPH_ENABLED = os.getenv("AISOC_GRAPH_ENABLED", "").strip().lower() in ("1", "true", "yes")
+
+#: A set rather than a module-level bool with `global`. CodeQL reads the
+#: bool as an unused global because every read and write happens inside the
+#: function, and a mutable container needs no `global` statement at all.
+_UNAVAILABLE_LOGGED: set[str] = set()
+
+
+def graph_unavailable_reason(api_token: str | None) -> str | None:
+ """Why a graph read cannot be made, or None if it can.
+
+ Two reasons, and telling them apart matters to whoever reads the log.
+
+ The graph routes on the API authenticate with `get_current_user`, which
+ validates a **user** JWT. A background worker has no user, so a service
+ token does not open them: before this, `ContextBundleBuilder()` was
+ constructed with no token on the production path and every graph read
+ during auto-triage answered 401, four warnings per alert, on every
+ entity. That reads like a broken integration rather than a capability
+ that is not present.
+
+ And on CORE there is no graph at all. Neo4j runs in the `full` profile,
+ so the honest answer there is "not in this deployment", not an
+ authentication error.
+ """
+ if not _GRAPH_ENABLED:
+ return "the entity graph runs in the `full` profile and is not part of this deployment"
+ if not api_token:
+ return "no user credential is available on this path; the graph routes authenticate a user and a background worker has none"
+ return None
+
+
+def _note_unavailable(reason: str) -> None:
+ """Say it once per reason per process, not once per entity per alert."""
+ if reason in _UNAVAILABLE_LOGGED:
+ return
+ _UNAVAILABLE_LOGGED.add(reason)
+ logger.info("graph.unavailable", reason=reason)
+
+
def _headers(api_token: str | None) -> dict[str, str]:
return {"Authorization": f"Bearer {api_token}"} if api_token else {}
@@ -30,6 +73,14 @@ async def get_attack_path(
max_depth: int = 6,
) -> dict[str, Any]:
"""Return the Case → Alert → Host/User → IOC → Technique attack path."""
+ unavailable = graph_unavailable_reason(api_token)
+ if unavailable:
+ _note_unavailable(unavailable)
+ # "could not check" with a reason, which is what the agent
+ # prompt renders. An empty result would read to the model as
+ # "this entity has no neighbours", which is a different and
+ # much worse claim.
+ return {"error": unavailable, "available": False}
try:
async with httpx.AsyncClient(timeout=_TIMEOUT) as client:
resp = await client.get(
@@ -56,6 +107,14 @@ async def get_blast_radius(
hops: int = 3,
) -> dict[str, Any]:
"""Compute the blast radius starting from a Host/User/IOC/Alert node."""
+ unavailable = graph_unavailable_reason(api_token)
+ if unavailable:
+ _note_unavailable(unavailable)
+ # "could not check" with a reason, which is what the agent
+ # prompt renders. An empty result would read to the model as
+ # "this entity has no neighbours", which is a different and
+ # much worse claim.
+ return {"error": unavailable, "available": False}
try:
async with httpx.AsyncClient(timeout=_TIMEOUT) as client:
resp = await client.get(
@@ -89,6 +148,14 @@ async def get_entity_neighbors(
api_token: str | None = None,
) -> dict[str, Any]:
"""Return all nodes directly connected (depth 1) to the specified entity."""
+ unavailable = graph_unavailable_reason(api_token)
+ if unavailable:
+ _note_unavailable(unavailable)
+ # "could not check" with a reason, which is what the agent
+ # prompt renders. An empty result would read to the model as
+ # "this entity has no neighbours", which is a different and
+ # much worse claim.
+ return {"error": unavailable, "available": False}
try:
async with httpx.AsyncClient(timeout=_TIMEOUT) as client:
resp = await client.get(
diff --git a/services/api/tests/test_readme_api_docs_url.py b/services/api/tests/test_readme_api_docs_url.py
index 679a4b453..79858d47d 100644
--- a/services/api/tests/test_readme_api_docs_url.py
+++ b/services/api/tests/test_readme_api_docs_url.py
@@ -1,12 +1,21 @@
-"""The README's API-docs URL has to be the one the app serves.
+"""The README advertises an API-docs URL only when the stack serves one.
-The quick start told a new user to open `http://localhost:8000/docs`. FastAPI
-is mounted with `docs_url="/api/docs"`, so that URL returned
-`{"detail":"Not Found"}` on a freshly-started stack — the second link in the
-quick start, 404 on arrival.
+Two eras, and the invariant spans both.
-Pinned as a test rather than fixed once because the two live in different
-files and neither mentions the other.
+Originally the quick start told a new user to open
+`http://localhost:8000/docs` while FastAPI mounted `/api/docs`, so the
+second link in the quick start was a 404 on arrival.
+
+Then `make up` became production-class, and the API disables its
+interactive docs there by design. The corrected URL started returning 404
+too, for a completely different reason, and live QA found `make up`,
+`install.sh` and the README all still printing it.
+
+So the rule is not "advertise the mounted URL". It is: **advertise one
+only if the documented path serves one**, and if it does, advertise the
+one it serves. Pinned as a test rather than fixed twice because the
+document and the mount live in different files and neither mentions the
+other.
"""
from __future__ import annotations
@@ -14,12 +23,34 @@ from __future__ import annotations
import pathlib
import re
-from app.core.config import settings
from app.main import create_application
REPO = pathlib.Path(__file__).resolve().parents[3]
README = REPO / "README.md"
+#: The three URLs that exist only when the interactive docs are mounted.
+_INTERACTIVE_DOC_PATHS = frozenset({"/docs", "/redoc", "/openapi.json", "/api/docs", "/api/redoc", "/api/openapi.json"})
+
+
+def _make_up_sets_production() -> bool:
+ """Whether the stack `make up` starts runs in a production posture.
+
+ Read from the compose file rather than from this process's settings,
+ because the question is what a reader following the README gets, not
+ what the test runner happens to be configured as.
+ """
+ compose = (REPO / "docker-compose.yml").read_text()
+ # `ENVIRONMENT: ${ENVIRONMENT:-production}`, not a bare literal. It was
+ # a bare literal once, which meant `.env` was ignored and setting
+ # production did nothing; the default form is what the tree ships.
+ return bool(
+ re.search(r"^\s+ENVIRONMENT:\s*\$\{ENVIRONMENT:-production\}\s*$", compose, re.M)
+ or re.search(r"^\s+ENVIRONMENT:\s*production\s*$", compose, re.M)
+ )
+
+
+_MAKE_UP_IS_PRODUCTION = _make_up_sets_production()
+
# Everything else that prints this URL at a user. The README was corrected on
# its own and these were not, so `make up` went on telling every new user to
# open a 404 — the fix reached the document and not the tool.
@@ -34,16 +65,28 @@ TOOL_OUTPUT = (
)
-def test_the_readme_points_at_the_url_the_app_mounts() -> None:
+def test_the_readme_advertises_only_what_the_documented_path_serves() -> None:
app = create_application()
- assert not settings.is_production, "this test asserts the dev-mode mount"
- docs_url = app.docs_url
- assert docs_url, "docs are unmounted; the README should not advertise them"
-
text = README.read_text()
advertised = set(re.findall(r"http://localhost:8000(/[\w/.-]*)", text))
- assert advertised, "README no longer advertises an API docs URL"
+ # `make up` starts a production-class stack. What this test is really
+ # asking is what a reader following the README would get, so the
+ # production posture is the one that matters even though the test
+ # process itself may not be in it.
+ docs_are_served_on_the_documented_path = not _MAKE_UP_IS_PRODUCTION
+
+ if not docs_are_served_on_the_documented_path:
+ offenders = {p for p in advertised if p in _INTERACTIVE_DOC_PATHS}
+ assert not offenders, (
+ "`make up` starts a production-class stack where the API disables its "
+ f"interactive docs, and the README still advertises {sorted(offenders)}. "
+ "A reader following the quick start gets a 404."
+ )
+ return
+
+ docs_url = app.docs_url
+ assert docs_url, "docs are unmounted; the README should not advertise them"
for path in advertised:
assert path in {docs_url, app.openapi_url, app.redoc_url, "/health"}, (
f"README advertises http://localhost:8000{path}, which the app does not serve (docs are at {docs_url})"