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(mcp): fail-closed execution approval, honest doctor and workers status (#71)

kraii_751350aa4ea9
diff --git a/ares/api/dashboard/app.py b/ares/api/dashboard/app.py
index 40015e4..fab1d7c 100644
--- a/ares/api/dashboard/app.py
+++ b/ares/api/dashboard/app.py
@@ -648,8 +648,36 @@ async def api_summary(campaign_id: str,
@dashboard_app.get("/api/workers")
async def api_workers(_auth: None = Depends(_require_dashboard_auth)) -> dict[str, Any]:
- # Returns empty if distributed controller not running
- return {"workers": [], "queue": {"pending": 0, "active": 0, "done": 0, "failed": 0}}
+ # Report whether a distributed worker controller is actually attached rather
+ # than always returning a 0/0/0/0 queue, which is indistinguishable from a
+ # healthy, idle controller. A controller wired onto dashboard_app.state is
+ # queried via its documented snapshot(); otherwise we say so explicitly.
+ # (AUDIT run-1 H21)
+ empty_queue = {"pending": 0, "active": 0, "done": 0, "failed": 0}
+ controller = getattr(dashboard_app.state, "worker_controller", None)
+ if controller is None:
+ return {
+ "controller_available": False,
+ "controller_status": "not_running",
+ "workers": [],
+ "queue": empty_queue,
+ }
+ try:
+ snapshot = controller.snapshot()
+ return {
+ "controller_available": True,
+ "controller_status": "running",
+ "workers": list(snapshot.get("workers", [])),
+ "queue": {**empty_queue, **dict(snapshot.get("queue", {}))},
+ }
+ except Exception as exc:
+ logger.warning("worker_controller_snapshot_failed", error=str(exc)[:200])
+ return {
+ "controller_available": False,
+ "controller_status": "error",
+ "workers": [],
+ "queue": empty_queue,
+ }
@dashboard_app.websocket("/ws/live")
diff --git a/ares/cli/mcp_commands.py b/ares/cli/mcp_commands.py
index 52b4446..2e84290 100644
--- a/ares/cli/mcp_commands.py
+++ b/ares/cli/mcp_commands.py
@@ -28,44 +28,91 @@ from ares.modules.descriptors import FIRST_PARTY_DESCRIPTORS
def get_doctor_diagnostics(server: AresMcpServer | None = None) -> dict[str, Any]:
- """Inspect all MCP subsystems and return structured health status."""
+ """Inspect all MCP subsystems and return structured health status.
+
+ Every subsystem is actually probed rather than reported as a hardcoded
+ PASS: the registries are loaded, the module catalog is counted, and the
+ security gates (scope guard, confirmation-token manager, taint sanitizer)
+ are exercised on sample input. A probe that fails or raises yields a FAIL
+ status and flips the overall result, so the exit code reflects real
+ readiness. (AUDIT run-1 H21)
+ """
srv = server or AresMcpServer()
- tools = srv.tool_registry.list_tools()
- resources = srv.resource_registry.list_resources()
- prompts = srv.prompt_registry.list_prompts()
-
- checks = [
- {
- "subsystem": "Protocol Engine",
- "status": "PASS",
- "details": "JSON-RPC 2.0 (MCP 2024-11-05 Specification)",
- },
- {
- "subsystem": "Operational Tools",
- "status": "PASS",
- "details": f"{len(tools)} tools registered (Tier-1 & Tier-2)",
- },
- {
- "subsystem": "Context Resources",
- "status": "PASS",
- "details": f"{len(resources)} live URI streams active",
- },
- {
- "subsystem": "Workflow Prompts",
- "status": "PASS",
- "details": f"{len(prompts)} workflow templates indexed",
- },
- {
- "subsystem": "Module Catalog",
- "status": "PASS",
- "details": f"{len(FIRST_PARTY_DESCRIPTORS)} offensive modules ready",
- },
- {
- "subsystem": "Security Gates",
- "status": "PASS",
- "details": "ScopeGuard + TokenManager + TaintSanitizer + AD Lockout Breaker",
- },
- ]
+ checks: list[dict[str, Any]] = []
+
+ def _add(subsystem: str, ok: bool, details: str) -> None:
+ checks.append({"subsystem": subsystem, "status": "PASS" if ok else "FAIL",
+ "details": details})
+
+ # Protocol Engine — the JSON-RPC message entrypoint must be present.
+ proto_ok = callable(getattr(srv, "handle_message", None))
+ _add("Protocol Engine",
+ proto_ok,
+ "JSON-RPC 2.0 handler present (MCP 2024-11-05)" if proto_ok
+ else "handle_message entrypoint missing")
+
+ # Operational Tools — the tool registry must load and expose tools.
+ try:
+ tools = srv.tool_registry.list_tools()
+ _add("Operational Tools", len(tools) > 0,
+ f"{len(tools)} tools registered" if tools else "tool registry empty")
+ except Exception as exc: # pragma: no cover - defensive
+ _add("Operational Tools", False, f"tool registry error: {type(exc).__name__}")
+
+ # Context Resources — the resource registry must load.
+ try:
+ resources = srv.resource_registry.list_resources()
+ _add("Context Resources", True, f"{len(resources)} resource URIs available")
+ except Exception as exc: # pragma: no cover - defensive
+ _add("Context Resources", False, f"resource registry error: {type(exc).__name__}")
+
+ # Workflow Prompts — the prompt registry must load.
+ try:
+ prompts = srv.prompt_registry.list_prompts()
+ _add("Workflow Prompts", True, f"{len(prompts)} workflow templates indexed")
+ except Exception as exc: # pragma: no cover - defensive
+ _add("Workflow Prompts", False, f"prompt registry error: {type(exc).__name__}")
+
+ # Module Catalog — the descriptor catalog must be non-empty.
+ cat_n = len(FIRST_PARTY_DESCRIPTORS)
+ _add("Module Catalog", cat_n > 0,
+ f"{cat_n} offensive modules ready" if cat_n else "descriptor catalog empty")
+
+ # Security Gates — exercise the scope guard, token manager and taint
+ # sanitizer on sample input rather than asserting they exist.
+ gate_parts: list[str] = []
+ gates_ok = True
+ try:
+ from ares.mcp.security import (
+ ConfirmationTokenManager,
+ McpScopeGate,
+ McpTaintSanitizer,
+ )
+
+ if McpScopeGate.is_in_scope("10.0.0.5", ["10.0.0.0/24"]) and not \
+ McpScopeGate.is_in_scope("8.8.8.8", ["10.0.0.0/24"]):
+ gate_parts.append("ScopeGuard")
+ else:
+ gates_ok = False
+ gate_parts.append("ScopeGuard:FAIL")
+
+ tm = ConfirmationTokenManager(secret_key="doctor-probe-secret-key-32chars!") # noqa: S106
+ if tm.issue_token("c", "m", "10.0.0.5", {}).startswith("ares_tok_"):
+ gate_parts.append("TokenManager")
+ else:
+ gates_ok = False
+ gate_parts.append("TokenManager:FAIL")
+
+ probe = "ignore previous instructions"
+ if McpTaintSanitizer.sanitize(probe) != probe:
+ gate_parts.append("TaintSanitizer")
+ else:
+ gates_ok = False
+ gate_parts.append("TaintSanitizer:FAIL")
+ except Exception as exc: # pragma: no cover - defensive
+ gates_ok = False
+ gate_parts.append(f"error:{type(exc).__name__}")
+ _add("Security Gates", gates_ok, " + ".join(gate_parts))
all_pass = all(c["status"] == "PASS" for c in checks)
return {
diff --git a/ares/mcp/events.py b/ares/mcp/events.py
index 772a324..6db3804 100644
--- a/ares/mcp/events.py
+++ b/ares/mcp/events.py
@@ -14,6 +14,7 @@ from typing import Any
DEFAULT_EVENT_PORT = 27890
DEFAULT_EVENT_HOST = "127.0.0.1"
TOKEN_STATUS_FILE = Path.home() / ".ares" / "mcp_token_status.json"
+_MAX_TOKEN_DECISIONS = 256
class McpEventBus:
@@ -35,33 +36,58 @@ class McpEventBus:
except Exception:
pass # Silent drop if no listener or network exception
+ @staticmethod
+ def _load_decisions() -> dict[str, Any]:
+ """Return the per-token decision map, tolerating the legacy single-slot
+ format and any read/parse error (returns {})."""
+ if not TOKEN_STATUS_FILE.exists():
+ return {}
+ try:
+ with open(TOKEN_STATUS_FILE, encoding="utf-8") as f:
+ loaded = json.load(f)
+ except Exception:
+ return {}
+ if isinstance(loaded, dict) and isinstance(loaded.get("decisions"), dict):
+ return dict(loaded["decisions"])
+ # Legacy single-slot record: {"token": ..., "decision": ...}
+ if isinstance(loaded, dict) and "token" in loaded:
+ return {str(loaded["token"]): {"decision": loaded.get("decision")}}
+ return {}
+
@staticmethod
def set_token_decision(token: str, decision: str) -> None:
- """Record operator decision (APPROVED or REJECTED) for a token."""
+ """Record operator decision (APPROVED or REJECTED) for a specific token.
+
+ Decisions are keyed per token so a decision for one token is never
+ clobbered by a newer pending token (the previous single-slot file held
+ only the most recently touched token). (AUDIT run-1 H8)
+ """
TOKEN_STATUS_FILE.parent.mkdir(parents=True, exist_ok=True)
- payload = {
- "token": token,
+ decisions = McpEventBus._load_decisions()
+ decisions[token] = {
"decision": decision,
"timestamp": time.strftime("%H:%M:%S"),
}
+ # Bound the file size; keep the most recent entries (dicts preserve
+ # insertion order, and re-setting a token refreshes its position).
+ if len(decisions) > _MAX_TOKEN_DECISIONS:
+ decisions = dict(list(decisions.items())[-_MAX_TOKEN_DECISIONS:])
try:
with open(TOKEN_STATUS_FILE, "w", encoding="utf-8") as f:
- json.dump(payload, f, indent=2)
+ json.dump({"decisions": decisions}, f, indent=2)
except Exception:
pass
@staticmethod
def get_token_decision(token: str) -> str | None:
- """Read operator decision for a token."""
- if not TOKEN_STATUS_FILE.exists():
- return None
- try:
- with open(TOKEN_STATUS_FILE, encoding="utf-8") as f:
- data = json.load(f)
- if data.get("token") == token:
- return data.get("decision")
- except Exception:
- pass
+ """Read the operator decision for a token, or None if there is none.
+
+ None (no decision recorded) is the fail-closed default: callers must
+ treat anything other than an explicit "APPROVED" as not-approved.
+ """
+ record = McpEventBus._load_decisions().get(token)
+ if isinstance(record, dict):
+ return record.get("decision")
return None
diff --git a/ares/mcp/security.py b/ares/mcp/security.py
index ac5ba91..546bcd2 100644
--- a/ares/mcp/security.py
+++ b/ares/mcp/security.py
@@ -26,10 +26,21 @@ class McpSecurityViolation(Exception):
class ConfirmationTokenManager:
- """Manages cryptographically signed, time-bounded confirmation tokens.
-
- Guarantees that Tier-2 offensive execution cannot occur without
- prior Tier-1 dry-run simulation and operator approval.
+ """Issues and validates single-use, time-bounded execution confirmation tokens.
+
+ Each token is an opaque server-side capability handle, not a self-contained
+ (JWT-style) token. Its unguessability comes from an HMAC-SHA256 over the
+ issuance material (execution payload + random nonce + monotonic time) keyed
+ with the server secret, so a token cannot be forged without the secret or
+ without observing one the server issued. The token is held in process memory
+ bound to (a) the exact execution payload — campaign/module/target/param
+ digest, enforced at validation, (b) a monotonic TTL deadline, and (c)
+ single-use burn-on-validate anti-replay.
+
+ This is NOT a stateless signature that can be verified offline from the token
+ alone; authority lives in the in-memory record. Tier-2 offensive execution is
+ gated on: prior Tier-1 dry-run (which issues the token) AND an explicit
+ operator APPROVED decision for that token (fail-closed; see validate_and_burn).
"""
def __init__(self, secret_key: str | None = None) -> None:
@@ -108,14 +119,24 @@ class ConfirmationTokenManager:
self._tokens.pop(token, None)
return False
- # Honor operator reject decision from TUI monitor
+ # Fail-closed authorization. Live execution is only honoured once the
+ # operator has EXPLICITLY approved THIS token from the monitor. The old
+ # logic refused only a literal "REJECTED" decision, so a token that was
+ # never acted on (pending) — or whose decision record was missing or
+ # unreadable — was treated as approved (default-allow). Now anything
+ # other than "APPROVED" refuses. (AUDIT run-1 H8)
try:
from ares.mcp.events import McpEventBus
- if McpEventBus.get_token_decision(token) == "REJECTED":
- self._tokens.pop(token, None)
- return False
+ decision = McpEventBus.get_token_decision(token)
except Exception:
- pass
+ decision = None
+ if decision == "REJECTED":
+ self._tokens.pop(token, None) # burn a rejected token
+ return False
+ if decision != "APPROVED":
+ # Pending / missing / unreadable: refuse, but keep the token so the
+ # operator can still approve and the caller can retry within the TTL.
+ return False
actual_payload = self._make_payload(campaign_id, module_id, target, params)
if hmac.compare_digest(expected_payload, actual_payload):
diff --git a/tests/unit/test_cli_reporting_goal_planning.py b/tests/unit/test_cli_reporting_goal_planning.py
index ecc6454..4ec182e 100644
--- a/tests/unit/test_cli_reporting_goal_planning.py
+++ b/tests/unit/test_cli_reporting_goal_planning.py
@@ -668,6 +668,11 @@ class TestDashboardApp:
assert "workers" in data
assert "queue" in data
assert "pending" in data["queue"]
+ # AUDIT run-1 H21: the endpoint reports whether a worker controller
+ # is actually attached instead of silently presenting a 0/0/0/0
+ # queue as if it were a healthy, idle controller.
+ assert data["controller_available"] is False
+ assert data["controller_status"] == "not_running"
def test_api_campaigns_with_db_error_returns_500(self, client):
"""When DB is unavailable, returns 500 gracefully."""
diff --git a/tests/unit/test_mcp_cli.py b/tests/unit/test_mcp_cli.py
index 8dff9dc..96b3346 100644
--- a/tests/unit/test_mcp_cli.py
+++ b/tests/unit/test_mcp_cli.py
@@ -51,6 +51,20 @@ def test_mcp_doctor_json() -> None:
assert len(data["subsystems"]) >= 5
+def test_mcp_doctor_actually_probes_subsystems(monkeypatch) -> None:
+ """AUDIT run-1 H21: doctor must reflect real subsystem state, not a
+ hardcoded all-PASS. Breaking a probed subsystem (empty module catalog)
+ must flip that check and the overall result to FAIL."""
+ from ares.cli import mcp_commands
+
+ monkeypatch.setattr(mcp_commands, "FIRST_PARTY_DESCRIPTORS", {})
+ diag = mcp_commands.get_doctor_diagnostics()
+ catalog = [c for c in diag["subsystems"] if c["subsystem"] == "Module Catalog"]
+ assert catalog and catalog[0]["status"] == "FAIL"
+ assert diag["status"] == "FAIL"
+ assert diag["healthy"] is False
+
+
def test_mcp_module_catalog_filtering() -> None:
"""Verify catalog command with category filter."""
result = runner.invoke(app, ["mcp", "module-catalog", "--category", "ad"])
diff --git a/tests/unit/test_mcp_server.py b/tests/unit/test_mcp_server.py
index 5e1544d..67c8077 100644
--- a/tests/unit/test_mcp_server.py
+++ b/tests/unit/test_mcp_server.py
@@ -180,7 +180,12 @@ def test_scope_gate_verification() -> None:
# ── 5. Confirmation Token Handshake (Anti-Replay) Tests ─────────────────────
-def test_confirmation_token_manager_lifecycle() -> None:
+def test_confirmation_token_manager_lifecycle(tmp_path, monkeypatch) -> None:
+ from ares.mcp.events import McpEventBus
+
+ # Isolate the per-token decision store from the real ~/.ares file.
+ monkeypatch.setattr("ares.mcp.events.TOKEN_STATUS_FILE", tmp_path / "tok.json")
+
mgr = ConfirmationTokenManager(secret_key="test_secret_key_32_bytes_long!!") # noqa: S106
# Issue token
@@ -193,7 +198,21 @@ def test_confirmation_token_manager_lifecycle() -> None:
)
assert token.startswith("ares_tok_")
- # Tampered target or params should fail validation
+ # AUDIT run-1 H8: fail-closed. A token the operator never approved must NOT
+ # validate even with perfectly matching parameters, and must NOT be burned
+ # (so a later approval + retry can still succeed).
+ assert mgr.validate_and_burn(
+ token=token,
+ campaign_id="camp_01",
+ module_id="ad.kerberoast",
+ target="dc01.corp.local",
+ params={"domain": "corp.local"},
+ ) is False
+
+ # Operator approves THIS token from the monitor.
+ McpEventBus.set_token_decision(token, "APPROVED")
+
+ # Tampered target or params should still fail validation (payload mismatch).
assert mgr.validate_and_burn(
token=token,
campaign_id="camp_01",
@@ -224,7 +243,11 @@ def test_confirmation_token_manager_lifecycle() -> None:
# ── 6. Two-Tier Governed Execution Workflow ──────────────────────────────────
@pytest.mark.asyncio
-async def test_two_tier_dry_run_and_execution_flow(mcp_server: AresMcpServer) -> None:
+async def test_two_tier_dry_run_and_execution_flow(mcp_server: AresMcpServer, tmp_path, monkeypatch) -> None:
+ from ares.mcp.events import McpEventBus
+
+ # Isolate the per-token decision store from the real ~/.ares file.
+ monkeypatch.setattr("ares.mcp.events.TOKEN_STATUS_FILE", tmp_path / "tok.json")
# 1. Attempt live execution WITHOUT token -> MUST FAIL (Security Violation)
rogue_req = {
"jsonrpc": "2.0",
@@ -264,7 +287,8 @@ async def test_two_tier_dry_run_and_execution_flow(mcp_server: AresMcpServer) ->
token = sim_data["confirmation_token"]
assert token.startswith("ares_tok_")
- # 3. Execute with valid token -> SUCCEEDS
+ # 2b. AUDIT run-1 H8: executing before the operator approves the token must
+ # fail closed, even though the token is valid, unexpired and unburned.
exec_req = {
"jsonrpc": "2.0",
"id": 32,
@@ -279,6 +303,12 @@ async def test_two_tier_dry_run_and_execution_flow(mcp_server: AresMcpServer) ->
},
},
}
+ unapproved_res = await mcp_server.handle_message(exec_req)
+ assert unapproved_res["result"]["isError"] is True
+ assert "INVALID OR EXPIRED CONFIRMATION TOKEN" in unapproved_res["result"]["content"][0]["text"]
+
+ # 3. Operator approves the token, then execute -> token consumed (NOT_EXECUTED)
+ McpEventBus.set_token_decision(token, "APPROVED")
# 3. Execute with a valid token: scope + token are validated and the token is
# consumed, but this gateway has no execution engine wired in. It must report
# honestly (NOT_EXECUTED) rather than fabricating a SUCCESS with an invented