ARES - authorized red-team engagement automation with dashboard, campaign scope, module orchestration, OPSEC controls, encrypted vault, and reporting.
Python active-directorycloud-securitydefensive-validationfastapigood-first-issuemitre-attackopsecreactred-teamreportingsecurity
fix(api): bloodhound ingest sandbox, opt-in graph heuristics, debug-mode gates (run-1 H3/H4/H5) (#70)
kraii_ae2d04d2178f
diff --git a/ares/api/graph.py b/ares/api/graph.pyindex a1ca18c..ebbf47e 100644--- a/ares/api/graph.py+++ b/ares/api/graph.py@@ -136,6 +136,7 @@ def build_campaign_graph(campaign: Any,hosts: list[dict[str, Any]] | None = None,credentials: list[dict[str, Any]] | None = None,+ include_heuristic: bool = False,) -> dict[str, Any]:"""Build the complete campaign graph from Campaign state, durable DB hosts, and credentials.@@ -458,12 +459,39 @@ def build_campaign_graph())host_lookup[tgt_clean] = host_node_id- # ── Perimeter Ingress Gateway ───────────────────────────────────────────+ # ── Real lateral movement from recorded attack history ──────────────────+ # These edges reflect observed, successful module runs (host -> host). They+ # are always included because they are grounded in the campaign's own data.+ for ip, host in host_items:+ attack_history = getattr(host, "attack_history", [])+ for attack in attack_history:+ src_ip = getattr(attack, "from_host", None)+ module = getattr(attack, "module_id", "")+ success = getattr(attack, "success", False)+ if src_ip and success and f"host:{src_ip}" in node_ids:+ edges.append(APIGraphEdge(+ source = f"host:{src_ip}",+ target = f"host:{ip}",+ type = "lateral",+ label = module.split(".")[-1] if module else "lateral",+ color = "#ffffff",+ weight = 2.0,+ data = {"module": module},+ ))++ # ── Heuristic / illustrative topology (opt-in, AUDIT run-1 H4) ───────────+ # The synthetic perimeter firewall node and the hostname-substring pivot+ # chains below are NOT observed attack paths — they are inferred purely from+ # host naming (ws/sql/srv/k8s/...) and a blanket in-scope assumption. They+ # must never ship in the default production response as if real. They are+ # emitted only when the caller explicitly opts in, and every heuristic node+ # and edge is tagged data.source="hostname_heuristic" so consumers can tell+ # them apart from grounded data.all_host_nodes = [nid for nid in node_idsif nid.startswith("host:") and not any(k in nid.lower() for k in ("in-scope", "scope", "none", "target", "firewall"))]- if all_host_nodes and "node:ingress-fw" not in node_ids:+ if include_heuristic and all_host_nodes and "node:ingress-fw" not in node_ids:fw_id = "node:ingress-fw"raw_scope = getattr(campaign, "scope", [])cidr_str = "0.0.0.0/0"@@ -480,6 +508,7 @@ def build_campaign_graph("ip": cidr_str,"hostname": "Perimeter Gateway","compromise_level": "none",+ "source": "hostname_heuristic",},color = "#06b6d4",shape = "square",@@ -493,26 +522,9 @@ def build_campaign_graph(label = "in-scope",color = "#06b6d4",dashed = True,+ data = {"source": "hostname_heuristic"},))- # Edges: lateral movement from session host attack history- for ip, host in host_items:- attack_history = getattr(host, "attack_history", [])- for attack in attack_history:- src_ip = getattr(attack, "from_host", None)- module = getattr(attack, "module_id", "")- success = getattr(attack, "success", False)- if src_ip and success and f"host:{src_ip}" in node_ids:- edges.append(APIGraphEdge(- source = f"host:{src_ip}",- target = f"host:{ip}",- type = "lateral",- label = module.split(".")[-1] if module else "lateral",- color = "#ffffff",- weight = 2.0,- data = {"module": module},- ))-# Natural lateral pivot chains across discovered infrastructuredc_ids = [f"host:{ip}" for ip, h in host_items if getattr(h, "is_dc", False)]member_srv_ids = [@@ -539,7 +551,8 @@ def build_campaign_graph(if ws_id in node_ids and srv_id in node_ids and ws_id != srv_id:edges.append(APIGraphEdge(source=ws_id, target=srv_id,- type="lateral", label="pivot", color="#ffffff", weight=1.5+ type="lateral", label="pivot", color="#ffffff", weight=1.5,+ data={"source": "hostname_heuristic"},))# Lateral: Member Servers -> Domain Controller@@ -548,7 +561,8 @@ def build_campaign_graph(if srv_id in node_ids and dc_id in node_ids and srv_id != dc_id:edges.append(APIGraphEdge(source=srv_id, target=dc_id,- type="lateral", label="domain admin path", color="#ffffff", weight=2.5+ type="lateral", label="domain admin path", color="#ffffff", weight=2.5,+ data={"source": "hostname_heuristic"},))# Ingress -> Cloud Gateway@@ -557,7 +571,8 @@ def build_campaign_graph(if ing_id in node_ids and c_id in node_ids and ing_id != c_id:edges.append(APIGraphEdge(source=ing_id, target=c_id,- type="pivot", label="cloud pivot", color="#ffffff", weight=2.0+ type="pivot", label="cloud pivot", color="#ffffff", weight=2.0,+ data={"source": "hostname_heuristic"},))# ── Credentials from vault or database ──────────────────────────────────diff --git a/ares/api/server.py b/ares/api/server.pyindex 27285fb..420e338 100644--- a/ares/api/server.py+++ b/ares/api/server.py@@ -2554,14 +2554,17 @@ async def run_module(idempotency_key = _require_c_live_idempotency_key(request)has_c_live_override = get_c_live_runtime in getattr(request.app, "dependency_overrides", {})- if has_c_live_override or not get_settings().ares_debug:- if _contains_c_live_raw_secret(raw_params) or _contains_c_live_raw_secret(- validated_params- ):- raise HTTPException(status_code=422, detail="raw_secret_material_forbidden")- descriptor_result = _c_live_descriptor_gate(module_id, actor.role)- if descriptor_result is not None:- return _c_live_unavailable_response(descriptor_result)+ # Raw-secret filter and descriptor/role gate are security controls that must+ # run on every live module run, including when ares_debug is set. Previously+ # both were skipped in debug mode, letting raw secret material through and+ # bypassing the role/eligibility gate. (AUDIT run-1 H5)+ if _contains_c_live_raw_secret(raw_params) or _contains_c_live_raw_secret(+ validated_params+ ):+ raise HTTPException(status_code=422, detail="raw_secret_material_forbidden")+ descriptor_result = _c_live_descriptor_gate(module_id, actor.role)+ if descriptor_result is not None:+ return _c_live_unavailable_response(descriptor_result)if str(campaign.get("status", "")).lower() == "created" and hasattr(db, "update_campaign_status"):try:@@ -3065,16 +3068,12 @@ async def start_autonomous_engagement(None,))- has_c_live_override = get_c_live_runtime in getattr(request.app, "dependency_overrides", {})- if has_c_live_override or not get_settings().ares_debug:- for child in children:- child["decision_ordinal"] = child["stage_ordinal"]- descriptor_result = _c_live_descriptor_gate(child["module_id"], actor.role)- if descriptor_result is not None:- return _c_live_unavailable_response(descriptor_result)- else:- for child in children:- child["decision_ordinal"] = child["stage_ordinal"]+ # Descriptor/role gate must run regardless of ares_debug. (AUDIT run-1 H5)+ for child in children:+ child["decision_ordinal"] = child["stage_ordinal"]+ descriptor_result = _c_live_descriptor_gate(child["module_id"], actor.role)+ if descriptor_result is not None:+ return _c_live_unavailable_response(descriptor_result)whole_intent_digest = canonical_intent_digest({@@ -3852,10 +3851,14 @@ async def get_prometheus(@app.get("/graph/{campaign_id}", tags=["visualization"])async def campaign_graph(campaign_id: str,+ include_heuristic: bool = False,actor: AuthenticatedUser = _api_key_read_dep,engine: AresEngine = Depends(get_engine),db: AresDatabase = Depends(get_db),) -> dict[str, Any]:+ # include_heuristic adds inferred (hostname-substring) pivot chains and a+ # synthetic perimeter node, each tagged data.source="hostname_heuristic".+ # Off by default so the response carries only grounded topology. (H4)from ares.api.graph import build_campaign_graph, merge_durable_attack_graphcampaign = await db.get_campaign(campaign_id)@@ -3869,7 +3872,11 @@ async def campaign_graph(if snapshot is None and getattr(runtime_state, "attack_graph", None) is not None:snapshot = runtime_state.attack_graph.to_d3_json()return merge_durable_attack_graph(- build_campaign_graph(c_obj, hosts=_hosts, credentials=_credentials), snapshot+ build_campaign_graph(+ c_obj, hosts=_hosts, credentials=_credentials,+ include_heuristic=include_heuristic,+ ),+ snapshot,)@@ -4096,11 +4103,11 @@ async def run_campaign_plan())has_c_live_override = get_c_live_runtime in getattr(request.app, "dependency_overrides", {})- if has_c_live_override or not get_settings().ares_debug:- for child in children:- descriptor_result = _c_live_descriptor_gate(child["module_id"], actor.role)- if descriptor_result is not None:- return _c_live_unavailable_response(descriptor_result)+ # Descriptor/role gate must run regardless of ares_debug. (AUDIT run-1 H5)+ for child in children:+ descriptor_result = _c_live_descriptor_gate(child["module_id"], actor.role)+ if descriptor_result is not None:+ return _c_live_unavailable_response(descriptor_result)whole_intent_digest = canonical_intent_digest({@@ -4465,10 +4472,55 @@ class BloodhoundIngestRequest(BaseModel):...,min_length=1,max_length=512,- description="Path to BloodHound JSON file or directory",+ description="BloodHound JSON file or directory, relative to the "+ "campaign's bloodhound ingest folder",)+def _resolve_bloodhound_ingest_path(json_path: str, campaign_id: str) -> Path:+ """Constrain BloodHound ingest to <report_root>/<campaign_id>/bloodhound/.++ The endpoint previously passed the operator-supplied path through the+ general-purpose sanitize_path allowlist (home, /tmp, /opt/ares, /home, ...),+ which let an authenticated operator read arbitrary files under those roots+ and get parse diagnostics reflected back. This resolver pins ingest to a+ per-campaign sandbox directory, rejects path traversal and symlink escape,+ and returns a fixed error detail (no reflection of the offending path).+ (AUDIT run-1 H3 / M18)+ """+ import re as _re++ safe_cid = _re.sub(r"[^\w\-]", "_", campaign_id)[:64].strip("_") or "campaign"+ base = (_report_root() / safe_cid / "bloodhound").resolve()+ base.mkdir(parents=True, exist_ok=True)++ raw = (json_path or "").strip()+ if not raw or "\x00" in raw:+ raise HTTPException(400, "Invalid BloodHound ingest path")++ candidate = Path(raw)+ target = candidate if candidate.is_absolute() else (base / candidate)+ try:+ resolved = target.resolve()+ except (OSError, RuntimeError):+ raise HTTPException(400, "Invalid BloodHound ingest path") from None++ # .resolve() follows symlinks, so an in-sandbox symlink pointing outside is+ # caught here too. Absolute paths outside the sandbox are rejected.+ if not (resolved == base or resolved.is_relative_to(base)):+ logger.warning(+ "bloodhound_ingest_path_rejected",+ campaign_id=campaign_id,+ path=repr(raw),+ )+ raise HTTPException(400, "Invalid BloodHound ingest path")++ if resolved.is_file() and resolved.suffix.lower() not in {".json", ".zip"}:+ raise HTTPException(400, "Invalid BloodHound ingest path")++ return resolved++@app.post("/graph/{campaign_id}/bloodhound", tags=["visualization"])async def ingest_bloodhound(campaign_id: str,@@ -4488,12 +4540,7 @@ async def ingest_bloodhound(raise HTTPException(404, "Campaign not found")await _require_campaign_access(campaign, actor)- from ares.core.security import sanitize_path-- try:- safe_path = sanitize_path(body.json_path)- except ValueError as exc:- raise HTTPException(400, f"Invalid path: {str(exc)[:200]}") # noqa: B904+ safe_path = str(_resolve_bloodhound_ingest_path(body.json_path, campaign_id))try:from ares.graph.attack_graph import AttackGraph@@ -4511,7 +4558,14 @@ async def ingest_bloodhound(graph.build_from_store(runtime_state.artifact_store)result = graph.ingest_bloodhound(safe_path)if result.get("error"):- raise HTTPException(422, result["error"])+ # Do not reflect parse diagnostics (may embed file-content+ # snippets from JSONDecodeError). Log, return a fixed detail.+ logger.warning(+ "bloodhound_ingest_parse_error",+ campaign_id=campaign_id,+ error=str(result["error"])[:500],+ )+ raise HTTPException(422, "BloodHound ingest failed: invalid or unreadable input")# Compute shortest path to DA after ingestda_path = graph.shortest_path_to_da()@@ -4535,7 +4589,8 @@ async def ingest_bloodhound(except HTTPException:raiseexcept Exception as exc:- raise HTTPException(500, f"Bloodhound ingest failed: {str(exc)[:200]}") # noqa: B904+ logger.error("bloodhound_ingest_failed", campaign_id=campaign_id, error=str(exc)[:500])+ raise HTTPException(500, "BloodHound ingest failed") # noqa: B904# ── Startup ───────────────────────────────────────────────────────────────────diff --git a/mypy-baseline.txt b/mypy-baseline.txtindex 3e22e1f..6a3c6c9 100644--- a/mypy-baseline.txt+++ b/mypy-baseline.txt@@ -4,7 +4,7 @@ ares/api/server.py|error: Incompatible return value type (got "JSONResponse", exares/api/server.py|error: Incompatible return value type (got "JSONResponse", expected "dict[str, Any]") [return-value]ares/api/server.py|error: Incompatible types in assignment (expression has type "ApiKeyTicketSource", variable has type "BearerTicketSource | None") [assignment]ares/api/server.py|error: Invalid index type "str" for "str"; expected type "SupportsIndex | slice[SupportsIndex | None, SupportsIndex | None, SupportsIndex | None]" [index]-ares/api/server.py|error: Name "result_rows" already defined on line 4118 [no-redef]+ares/api/server.py|error: Name "result_rows" already defined on line 4125 [no-redef]ares/api/server.py|error: Value of type "dict[str, Any] | Any | str | None" is not indexable [index]ares/cli/mcp_cli_utils.py|error: Unexpected keyword argument "file" for "print" of "Console" [call-arg]ares/cli/mcp_tui.py|error: Module has no attribute "getch" [attr-defined]diff --git a/tests/integration/test_api_post.py b/tests/integration/test_api_post.pyindex 3593e91..c1f3e11 100644--- a/tests/integration/test_api_post.py+++ b/tests/integration/test_api_post.py@@ -335,6 +335,29 @@ class TestCampaignPostEndpoints:run_module.assert_not_awaited()run_plan.assert_not_awaited()+ def test_module_run_rejects_raw_secret_even_in_debug(self, c, token, campaign_id):+ """AUDIT run-1 H5: the raw-secret filter on POST /modules/{id}/run must+ run even when ARES_DEBUG=true (the test env sets it). Previously the+ filter and the descriptor/role gate were skipped in debug mode, so a+ live run could carry raw secret material and bypass role gating.+ """+ import uuid as _uuid++ r = c.post(+ "/modules/ad.enum_users/run",+ json={+ "campaign_id": campaign_id,+ "params": {+ "dc": "10.0.0.1", "username": "svc",+ "password": "raw-secret-should-be-rejected", "domain": "CORP",+ },+ "dry_run": False,+ },+ headers={**_auth(token), "Idempotency-Key": str(_uuid.uuid4())},+ )+ assert r.status_code == 422, r.text+ assert r.json().get("detail") == "raw_secret_material_forbidden"+def test_campaign_not_found_returns_404(self, c, token):r = c.get("/campaigns/nonexistent-xyz-id", headers=_auth(token))assert r.status_code == 404diff --git a/tests/unit/test_api_hardening_run1.py b/tests/unit/test_api_hardening_run1.pynew file mode 100644index 0000000..cf64249--- /dev/null+++ b/tests/unit/test_api_hardening_run1.py@@ -0,0 +1,97 @@+"""Audit run-1 API hardening regressions: H3 (BloodHound ingest path sandbox)+and H4 (graph topology fabrication gated off by default)."""++from unittest.mock import MagicMock++import pytest+from fastapi import HTTPException+++def _mock_campaign():+ campaign = MagicMock()+ campaign.id = "graph-h4-001"+ campaign.name = "Graph H4 Test"+ campaign.scope = [{"cidr": "10.0.0.0/24"}]++ dc = MagicMock()+ dc.compromise_level = MagicMock(value="domain_admin")+ dc.is_dc = True+ dc.hostname = "dc01"+ dc.is_owned = True+ dc.open_ports = [389, 445, 88]+ dc.os_info = "Windows Server 2019"+ dc.attack_history = []+ dc.discovered_from = None++ srv = MagicMock()+ srv.compromise_level = MagicMock(value="local_admin")+ srv.is_dc = False+ srv.hostname = "sql01-srv"+ srv.is_owned = True+ srv.open_ports = [445, 1433]+ srv.os_info = "Windows Server 2022"+ srv.attack_history = []+ srv.discovered_from = "10.0.0.1"++ session = MagicMock()+ session.hosts = {"10.0.0.1": dc, "10.0.0.2": srv}+ session.get_host = lambda ip: session.hosts.get(ip)+ campaign.session = session+ campaign.findings = []+ campaign.vault = None+ return campaign+++# ── H4: heuristic topology must be opt-in ───────────────────────────────────++def _edge_sources(graph):+ return [e.get("data", {}).get("source") for e in graph["edges"]]+++def test_graph_default_has_no_fabricated_topology():+ from ares.api.graph import build_campaign_graph++ graph = build_campaign_graph(_mock_campaign())+ assert not any(n["type"] == "firewall" for n in graph["nodes"])+ assert "hostname_heuristic" not in _edge_sources(graph)+++def test_graph_heuristic_opt_in_is_tagged():+ from ares.api.graph import build_campaign_graph++ graph = build_campaign_graph(_mock_campaign(), include_heuristic=True)+ fw = [n for n in graph["nodes"] if n["type"] == "firewall"]+ assert fw, "perimeter node should appear when include_heuristic=True"+ assert fw[0]["data"].get("source") == "hostname_heuristic"+ heuristic_edges = [e for e in graph["edges"]+ if e.get("data", {}).get("source") == "hostname_heuristic"]+ assert heuristic_edges, "heuristic pivot edges should appear when opted in"+++# ── H3: BloodHound ingest path must stay inside the campaign sandbox ─────────++def test_bloodhound_ingest_rejects_traversal():+ from ares.api.server import _resolve_bloodhound_ingest_path++ with pytest.raises(HTTPException) as ei:+ _resolve_bloodhound_ingest_path("../../../../etc/passwd", "camp-h3")+ assert ei.value.status_code == 400+ assert ei.value.detail == "Invalid BloodHound ingest path"+++def test_bloodhound_ingest_rejects_absolute_outside_sandbox():+ from ares.api.server import _resolve_bloodhound_ingest_path++ outside = "C:/Windows/win.ini" if __import__("os").name == "nt" else "/etc/hostname"+ with pytest.raises(HTTPException) as ei:+ _resolve_bloodhound_ingest_path(outside, "camp-h3")+ assert ei.value.status_code == 400+++def test_bloodhound_ingest_accepts_relative_json_in_sandbox():+ from ares.api.server import _report_root, _resolve_bloodhound_ingest_path++ resolved = _resolve_bloodhound_ingest_path("sharphound.json", "camp-h3")+ sandbox = (_report_root() / "camp-h3" / "bloodhound").resolve()+ assert resolved.is_relative_to(sandbox)+ assert resolved.name == "sharphound.json"diff --git a/tests/unit/test_scope_contamination.py b/tests/unit/test_scope_contamination.pyindex d2707cb..48bc867 100644--- a/tests/unit/test_scope_contamination.py+++ b/tests/unit/test_scope_contamination.py@@ -52,13 +52,20 @@ async def test_engine_persist_runtime_hosts_blocks_out_of_scope(tmp_path):@pytest.mark.asyncio-async def test_server_auto_upsert_host_blocks_out_of_scope(tmp_path):+async def test_server_auto_upsert_host_blocks_out_of_scope(tmp_path, monkeypatch):"""NEW-03 Reproduction:Verify that when a module runs via server.py and reports an out-of-scopetarget IP in raw_output, server.py does NOT upsert it into the campaignhosts table."""+ # This test drives the debug/test execution path (FakeEngine) with a synthetic+ # recon.mock module. Make that deterministic instead of relying on ambient+ # suite state: force ares_debug=True so the dev short-circuit runs, and bypass+ # the now-always-enforced C-live descriptor gate via its documented test seam+ # (recon.mock has no real descriptor). (AUDIT run-1 H5)+ monkeypatch.setattr(get_settings(), "ares_debug", True)+ monkeypatch.setattr("ares.api.server._c_live_descriptor_gate", lambda *a, **k: None)db_file = tmp_path / "test_scope_server.db"db = AresDatabase(str(db_file))await db.connect()