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
"""ARES Sovereign MCP Security & Governance Layer.
Implements the 7 Unbreakable Security Guarantees:
1. Scope Absolute Invariance (McpScopeGate)
2. Cryptographic Execution Gate (ConfirmationTokenManager)
3. Anti-Prompt-Injection Taint Isolation (McpTaintSanitizer)
4. Active Directory Outage Circuit Breaker
5. Secret Masking & Zero Data Exfiltration (SecretMasker)
6. Cryptographic Network Auth & RBAC (McpAuthGate)
7. Multi-Agent Session Isolation & Rate Limiting (McpRateLimiter)
"""
from __future__ import annotations
import hashlib
import hmac
import ipaddress
import json
import re
import secrets
import time
from typing import Any
class McpSecurityViolation(Exception):
"""Raised when any MCP security guarantee or boundary is breached."""
class ConfirmationTokenManager:
"""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:
self._secret = (secret_key or secrets.token_hex(32)).encode("utf-8")
# Token format: {token: (expires_at, signature_payload)}
self._tokens: dict[str, tuple[float, str]] = {}
def _make_payload(
self,
campaign_id: str,
module_id: str,
target: str,
params: dict[str, Any] | None = None,
) -> str:
param_digest = hashlib.sha256(
json.dumps(params or {}, sort_keys=True, default=str).encode("utf-8")
).hexdigest()
return f"{campaign_id}:{module_id}:{target.strip().lower()}:{param_digest}"
def issue_token(
self,
campaign_id: str,
module_id: str,
target: str,
params: dict[str, Any] | None = None,
ttl_seconds: float = 60.0,
) -> str:
"""Issue a single-use, time-bounded HMAC token for a specific execution."""
payload = self._make_payload(campaign_id, module_id, target, params)
nonce = secrets.token_hex(8)
# Nonce + monotonic time for uniqueness; the outer HMAC is still over
# payload+nonce+monotonic-time, which stays unguessable.
raw_to_sign = f"{payload}:{nonce}:{time.monotonic()}"
sig = hmac.new(self._secret, raw_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()
token = f"ares_tok_{sig[:32]}"
# Monotonic deadline — wall-clock adjustment (NTP step, suspend/resume,
# deliberate rollback via SeSystemtimePrivilege on Windows) must not
# extend the token window. (AUDIT run-1 H10)
expires_at = time.monotonic() + ttl_seconds
self._tokens[token] = (expires_at, payload)
self._purge_expired()
try:
from ares.mcp.events import McpEventBus
McpEventBus.emit("AUTH", {
"call": f"Token issued for {module_id}: #{token[:16]}",
"token": token,
"module": module_id,
"target": target,
"ttl": int(ttl_seconds),
"status": f"PENDING: {int(ttl_seconds)}s",
"style": "yellow",
})
except Exception:
pass
return token
def validate_and_burn(
self,
token: str,
campaign_id: str,
module_id: str,
target: str,
params: dict[str, Any] | None = None,
) -> bool:
"""Validate the token against execution parameters and burn it if valid."""
self._purge_expired()
if not token or token not in self._tokens:
return False
expires_at, expected_payload = self._tokens[token]
# Same monotonic clock as issue_token — see H10 above. Any `time.time()`
# (wall-clock) comparison here would re-open the extendable-TTL hole.
if time.monotonic() > expires_at:
self._tokens.pop(token, None)
return False
# 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
decision = McpEventBus.get_token_decision(token)
except Exception:
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):
self._tokens.pop(token, None) # Burn upon valid use (anti-replay)
return True
return False
def _purge_expired(self) -> None:
now = time.monotonic()
expired = [t for t, (exp, _) in self._tokens.items() if now > exp]
for t in expired:
self._tokens.pop(t, None)
class McpScopeGate:
"""Pre-flight Scope Enforcement for MCP invocations.
Deterministically guarantees that no module execution or simulation
can touch an out-of-scope target.
"""
@staticmethod
def is_in_scope(target: str, scope_rules: list[str]) -> bool:
"""Check if target (IP, CIDR, or Domain) matches any authorized scope rule."""
target = target.strip().lower()
if not target or not scope_rules:
return False
# Extract host if target includes port notation (e.g. "10.0.0.1:445", "[2001:db8::1]:445", or "dc01.corp.local:88")
target_host = target
if target.startswith("[") and "]" in target:
target_host = target[1:target.index("]")]
elif ":" in target and target.count(":") == 1:
target_host = target.split(":")[0].strip()
for rule in scope_rules:
rule = rule.strip().lower()
if not rule:
continue
# Exact match (hostname or IP)
if target == rule or target_host == rule:
return True
# CIDR Subnet Match
if "/" in rule:
try:
net = ipaddress.ip_network(rule, strict=False)
for candidate in (target, target_host):
try:
tgt_ip = ipaddress.ip_address(candidate)
if tgt_ip in net:
return True
except ValueError:
pass
except ValueError:
pass
# Wildcard or Domain Suffix Match (*.corp.local, .corp.local, or corp.local)
if rule.startswith("*."):
domain_suffix = rule[2:]
elif rule.startswith("."):
domain_suffix = rule[1:]
else:
domain_suffix = rule
for candidate in (target, target_host):
if candidate == domain_suffix or candidate.endswith("." + domain_suffix):
return True
return False
@classmethod
def verify_target(cls, target: str, scope_rules: list[str]) -> None:
"""Assert that target is in scope. Raises McpSecurityViolation if not."""
if not cls.is_in_scope(target, scope_rules):
raise McpSecurityViolation(
f"SCOPE VIOLATION [BLOCKED]: Target '{target}' is not in the authorized engagement scope. "
f"Authorized rules: {scope_rules}. Execution aborted before network dispatch."
)
class McpTaintSanitizer:
"""Neutralizes Indirect Prompt Injection (IPI) in target responses.
Neutralizes LLM control sequences and instruction injections.
"""
_INJECTION_PATTERNS = [
re.compile(r"(?i)\b(?:system|assistant|developer)\s*:\s*"),
re.compile(r"(?i)<\|im_start\|>|<\|im_end\|>"),
re.compile(r"(?i)\[INST\]|\[/INST\]"),
re.compile(r"(?i)ignore\s+(?:all\s+)?previous\s+instructions"),
re.compile(r"(?i)disregard\s+(?:all\s+)?prior\s+rules"),
re.compile(r"(?i)bypass\s+(?:guardrails|safety)"),
re.compile(r"(?i)leak\s+(?:api\s+key|vault|password|secret)"),
]
@classmethod
def sanitize(cls, data: Any) -> Any:
"""Recursively sanitize data before serialization to MCP client."""
if isinstance(data, str):
sanitized = data
# Neutralize instruction injection markers
for pattern in cls._INJECTION_PATTERNS:
sanitized = pattern.sub("[SANITIZED_INSTRUCTION_TOKEN]", sanitized)
return sanitized
if isinstance(data, dict):
return {
(cls.sanitize(k) if isinstance(k, str) else k): cls.sanitize(v)
for k, v in data.items()
}
if isinstance(data, (list, tuple, set)):
return [cls.sanitize(item) for item in data]
return data
class SecretMasker:
"""Masks credentials, hashes, and private keys from MCP outputs."""
_SENSITIVE_KEYS = {
"password", "secret", "hash", "ntlm", "ticket",
"private_key", "api_key", "kerberos_key", "token",
"credential", "creds", "session_key", "masterkey", "privatekey",
}
_PRIVATE_KEY_BLOCK_REGEX = re.compile(
r"-----BEGIN (?:RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----[\s\S]+?-----END (?:RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----"
)
@classmethod
def mask(cls, data: Any) -> Any:
"""Recursively mask sensitive values in dictionaries, strings, and structures."""
if isinstance(data, str):
if "-----BEGIN " in data and "PRIVATE KEY-----" in data:
return cls._PRIVATE_KEY_BLOCK_REGEX.sub("[REDACTED_PRIVATE_KEY_BLOCK]", data)
return data
if isinstance(data, dict):
masked: dict[str, Any] = {}
for k, v in data.items():
if any(sensitive in k.lower() for sensitive in cls._SENSITIVE_KEYS):
masked[k] = "***REDACTED***"
else:
masked[k] = cls.mask(v)
return masked
if isinstance(data, list):
return [cls.mask(x) for x in data]
return data
class McpRateLimiter:
"""Token-bucket rate limiter per session to prevent DoS/reasoning loops."""
def __init__(self, rate_per_minute: float = 30.0, burst: int = 10) -> None:
self.rate = rate_per_minute / 60.0
self.burst = float(burst)
self.tokens = float(burst)
self.last_check = time.monotonic()
def allow(self) -> bool:
now = time.monotonic()
elapsed = now - self.last_check
self.last_check = now
self.tokens = min(self.burst, self.tokens + elapsed * self.rate)
if self.tokens >= 1.0:
self.tokens -= 1.0
return True
return False