Skip to content

armgit / ARES

Public Imported from GitHub
0

ARES - authorized red-team engagement automation with dashboard, campaign scope, module orchestration, OPSEC controls, encrypted vault, and reporting.

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.py
index 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_ids
if 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 infrastructure
dc_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.py
index 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_graph
campaign = 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 ingest
da_path = graph.shortest_path_to_da()
@@ -4535,7 +4589,8 @@ async def ingest_bloodhound(
except HTTPException:
raise
except 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.txt
index 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", ex
ares/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.py
index 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 == 404
diff --git a/tests/unit/test_api_hardening_run1.py b/tests/unit/test_api_hardening_run1.py
new file mode 100644
index 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.py
index 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-scope
target IP in raw_output, server.py does NOT upsert it into the campaign
hosts 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()