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
"""Bounded validation lab using the real browser-cookie authentication contract."""
from __future__ import annotations
import argparse
import base64
import getpass
import hmac
import http.cookiejar
import json
import os
import re
import sys
import time
import uuid
from dataclasses import dataclass, field
from typing import Any
from urllib import error, parse, request
_LOOPBACK_ORIGINS = {
"http://127.0.0.1:5173",
"http://localhost:5173",
}
_CSRF_COOKIE_NAMES = {"__Host-ares-csrf", "ares-dev-csrf"}
_CSRF_PATTERN = re.compile(r"[A-Za-z0-9_-]{43}\Z")
_BLOCKED_DRY_RUN_FORBIDDEN_FIELDS = frozenset(
{
"artifact",
"artifacts",
"credential",
"credentials",
"executed",
"execution",
"execution_result",
"execution_status",
"finding",
"findings",
"output",
"outputs",
"result",
"results",
"succeeded",
"success",
}
)
class ValidationLabError(RuntimeError):
"""Fixed, non-sensitive validation-lab failure."""
def __init__(self, operation: str, *, status: int | None = None) -> None:
self.operation = operation
self.status = status
suffix = "" if status is None else f":status-{status}"
super().__init__(f"validation-lab:{operation}{suffix}")
@dataclass(frozen=True, slots=True, eq=False)
class ApiResult:
status: int
body: Any = field(repr=False)
class _RejectRedirects(request.HTTPRedirectHandler):
"""Turn every redirect into an ordinary fixed-status failure."""
def redirect_request(
self, req: Any, fp: Any, code: int, msg: str, headers: Any, newurl: str
) -> None:
del req, fp, code, msg, headers, newurl
return None
def _canonical_public_origin(value: object, *, allow_remote: bool) -> str:
if not isinstance(value, str) or not value or value != value.strip() or "," in value:
raise ValidationLabError("origin-invalid")
try:
parsed = parse.urlsplit(value)
port = parsed.port
except (TypeError, ValueError):
raise ValidationLabError("origin-invalid") from None
if (
parsed.scheme not in {"http", "https"}
or parsed.hostname is None
or parsed.hostname.endswith(".")
or parsed.username is not None
or parsed.password is not None
or parsed.path
or parsed.query
or parsed.fragment
):
raise ValidationLabError("origin-invalid")
try:
host = parsed.hostname.encode("ascii").decode("ascii").lower()
except UnicodeError:
raise ValidationLabError("origin-invalid") from None
if host != parsed.hostname.lower() or ":" in host:
raise ValidationLabError("origin-invalid")
default_port = 80 if parsed.scheme == "http" else 443
if port == default_port:
raise ValidationLabError("origin-invalid")
authority = host if port is None else f"{host}:{port}"
canonical = f"{parsed.scheme}://{authority}"
if not hmac.compare_digest(canonical, value):
raise ValidationLabError("origin-invalid")
if parsed.scheme == "http" and canonical not in _LOOPBACK_ORIGINS:
raise ValidationLabError("origin-insecure")
if canonical not in _LOOPBACK_ORIGINS and not allow_remote:
raise ValidationLabError("remote-not-authorized")
return canonical
def _is_canonical_csrf(value: object) -> bool:
if not isinstance(value, str) or _CSRF_PATTERN.fullmatch(value) is None:
return False
try:
decoded = base64.urlsafe_b64decode(value + "=")
except (TypeError, ValueError):
return False
canonical = base64.urlsafe_b64encode(decoded).rstrip(b"=").decode("ascii")
return len(decoded) == 32 and hmac.compare_digest(canonical, value)
def _canonical_idempotency_key(value: object) -> str | None:
"""Accept only a non-secret canonical lowercase UUIDv4 header value."""
if value in {None, ""}:
return None
if not isinstance(value, str):
raise ValidationLabError("idempotency-key-invalid")
try:
parsed = uuid.UUID(value)
except (AttributeError, ValueError):
raise ValidationLabError("idempotency-key-invalid") from None
if parsed.version != 4 or str(parsed) != value:
raise ValidationLabError("idempotency-key-invalid")
return value
class ApiClient:
"""Cookie-aware client whose representations never contain credentials."""
def __init__(self, base_url: str, browser_origin: str, *, allow_remote: bool = False) -> None:
canonical_base = _canonical_public_origin(base_url, allow_remote=allow_remote)
canonical_origin = _canonical_public_origin(browser_origin, allow_remote=allow_remote)
if not hmac.compare_digest(canonical_base, canonical_origin):
raise ValidationLabError("origin-mismatch")
self.base_url = canonical_base
self.browser_origin = canonical_origin
self.access_token: str | None = None
self._csrf_cookie_name = (
"ares-dev-csrf"
if canonical_origin in _LOOPBACK_ORIGINS
else "__Host-ares-csrf"
)
self._cookie_jar = http.cookiejar.CookieJar()
self._opener = request.build_opener(
request.HTTPCookieProcessor(self._cookie_jar),
_RejectRedirects(),
)
def _current_csrf(self) -> str:
matches: list[http.cookiejar.Cookie] = []
for cookie in self._cookie_jar:
if cookie.name in _CSRF_COOKIE_NAMES and not cookie.is_expired():
matches.append(cookie)
if len(matches) != 1 or matches[0].name != self._csrf_cookie_name:
raise ValidationLabError("csrf-cookie-invalid")
value = matches[0].value
if not _is_canonical_csrf(value):
raise ValidationLabError("csrf-cookie-invalid")
return value
def request(
self,
method: str,
path: str,
body: Any = None,
form: dict[str, str] | None = None,
expect: set[int] | None = None,
*,
authenticated: bool = True,
browser_headers: bool = False,
empty_body: bool = False,
idempotency_key: str | None = None,
) -> ApiResult:
expected = expect or {200}
url = f"{self.base_url}{path}"
headers: dict[str, str] = {"Accept": "application/json"}
data: bytes | None = b"" if empty_body else None
if form is not None:
data = parse.urlencode(form).encode("utf-8")
headers["Content-Type"] = "application/x-www-form-urlencoded"
elif body is not None:
data = json.dumps(body).encode("utf-8")
headers["Content-Type"] = "application/json"
if browser_headers:
headers["Origin"] = self.browser_origin
if method.upper() != "GET":
headers["X-ARES-CSRF"] = self._current_csrf()
if authenticated:
if self.access_token is None:
raise ValidationLabError("access-authority-missing")
headers["Authorization"] = f"Bearer {self.access_token}"
canonical_key = _canonical_idempotency_key(idempotency_key)
if canonical_key is not None:
headers["Idempotency-Key"] = canonical_key
outgoing = request.Request( # noqa: S310 - URL origin was strictly validated
url, data=data, headers=headers, method=method
)
try:
with self._opener.open(outgoing, timeout=15) as response: # noqa: S310
raw = response.read().decode("utf-8", errors="replace")
result = ApiResult(response.status, _parse_body(raw))
except error.HTTPError as exc:
raw = exc.read().decode("utf-8", errors="replace")
result = ApiResult(exc.code, _parse_body(raw))
except (error.URLError, TimeoutError, OSError):
raise ValidationLabError("request-unavailable") from None
if result.status not in expected:
raise ValidationLabError("request-status", status=result.status)
return result
def bootstrap_csrf(self) -> None:
self.request(
"GET",
"/auth/csrf",
expect={204},
authenticated=False,
browser_headers=True,
)
self._current_csrf()
def login(self, username: str, password: str) -> None:
self.bootstrap_csrf()
result = self.request(
"POST",
"/auth/token",
form={"username": username, "password": password},
authenticated=False,
browser_headers=True,
)
body = result.body
if (
not isinstance(body, dict)
or "refresh_token" in body
or not isinstance(body.get("access_token"), str)
or not body["access_token"]
):
raise ValidationLabError("login-contract-invalid")
self.access_token = body["access_token"]
self._current_csrf()
def refresh(self) -> None:
result = self.request(
"POST",
"/auth/refresh",
expect={200},
authenticated=False,
browser_headers=True,
empty_body=True,
)
body = result.body
if (
not isinstance(body, dict)
or "refresh_token" in body
or not isinstance(body.get("access_token"), str)
or not body["access_token"]
):
raise ValidationLabError("refresh-contract-invalid")
self.access_token = body["access_token"]
self._current_csrf()
def logout(self) -> None:
try:
self.request(
"POST",
"/auth/logout",
expect={204},
authenticated=False,
browser_headers=True,
empty_body=True,
)
finally:
self.access_token = None
def _parse_body(raw: str) -> Any:
if not raw:
return None
try:
return json.loads(raw)
except json.JSONDecodeError:
return None
def _password_from_env_or_prompt() -> str:
password = os.getenv("ARES_LAB_PASSWORD") or os.getenv("ARES_DEFAULT_ADMIN_PASSWORD")
if password:
return password
return getpass.getpass("Validation lab password: ")
def _ok(label: str) -> None:
print(f"[OK] {label}")
def _fail(label: str, exc: Exception) -> None:
if isinstance(exc, ValidationLabError) and exc.status is not None:
print(f"[FAIL] {label} - status={exc.status}")
else:
print(f"[FAIL] {label} - type={type(exc).__name__}")
def _raise_fixed() -> None:
raise ValidationLabError("contract-check-failed")
def _validate_blocked_module_dry_run(value: object) -> None:
"""Require the fixed, side-effect-free response for missing module parameters."""
if not isinstance(value, dict):
_raise_fixed()
missing_params = value.get("missing_params")
if (
value.get("dry_run") is not True
or value.get("status") != "dry_run_blocked"
or value.get("would_execute") is not False
or not isinstance(missing_params, list)
or not missing_params
or any(not isinstance(item, str) or not item for item in missing_params)
):
_raise_fixed()
pending: list[object] = [value]
while pending:
item = pending.pop()
if isinstance(item, dict):
for key, child in item.items():
if (
isinstance(key, str)
and key.casefold() in _BLOCKED_DRY_RUN_FORBIDDEN_FIELDS
):
_raise_fixed()
pending.append(child)
elif isinstance(item, list):
pending.extend(item)
def run_lab(args: argparse.Namespace) -> int:
if not args.browser_origin:
raise ValidationLabError("browser-origin-required")
client = ApiClient(
args.base_url,
args.browser_origin,
allow_remote=bool(args.allow_remote),
)
username = args.username
password = _password_from_env_or_prompt()
failures: list[str] = []
def step(label: str, fn: Any) -> Any:
try:
result = fn()
_ok(label)
return result
except Exception as exc: # noqa: BLE001 - continue bounded independent checks
failures.append(label)
_fail(label, exc)
return None
try:
step(
"health endpoint",
lambda: client.request(
"GET", "/health", authenticated=False
).body.get("status"),
)
step("browser login", lambda: client.login(username, password))
password = ""
step("current profile", lambda: client.request("GET", "/auth/me").body)
step(
"campaign target validation",
lambda: client.request(
"POST",
"/campaigns",
body={
"name": "ARES Validation Bad Target",
"client": "Local Lab",
"targets": ["../not-a-target"],
"scope_cidrs": [],
},
expect={422},
),
)
campaign_id_holder: dict[str, str] = {}
def create_campaign() -> None:
campaign = client.request(
"POST",
"/campaigns",
body={
"name": f"ARES Validation Lab {int(time.time())}",
"client": "Local Lab",
"targets": ["127.0.0.1"],
"scope_cidrs": ["127.0.0.1/32"],
},
).body
campaign_id = campaign.get("id") if isinstance(campaign, dict) else None
if not isinstance(campaign_id, str) or not campaign_id:
_raise_fixed()
campaign_id_holder["id"] = campaign_id
step("create local campaign", create_campaign)
campaign_id = campaign_id_holder.get("id")
if campaign_id:
def campaign_present() -> None:
rows = client.request("GET", "/campaigns").body
if not isinstance(rows, list) or not any(
isinstance(row, dict) and row.get("id") == campaign_id for row in rows
):
_raise_fixed()
step("campaign appears in list", campaign_present)
def plan_dry_run_validation() -> None:
result = client.request(
"POST",
f"/campaigns/{parse.quote(campaign_id)}/run",
body={
"plan": {
"stages": [
{"name": "validation-only", "modules": ["ad.kerberoast"]}
]
},
"global_params": {},
"dry_run": True,
},
idempotency_key=args.idempotency_key,
).body
if (
not isinstance(result, dict)
or result.get("param_validation", {}).get("ok") is not False
):
_raise_fixed()
step("module dry-run validation", plan_dry_run_validation)
def module_param_dry_run_validation() -> None:
result = client.request(
"POST",
"/modules/ad.kerberoast/run",
body={"campaign_id": campaign_id, "params": {}, "dry_run": True},
expect={200},
idempotency_key=args.idempotency_key,
).body
_validate_blocked_module_dry_run(result)
step(
"dry-run blocked missing parameters",
module_param_dry_run_validation,
)
def generate_report() -> None:
result = client.request(
"POST", f"/reports/{parse.quote(campaign_id)}?fmt=html"
).body
filename = result.get("filename") if isinstance(result, dict) else None
if not isinstance(filename, str) or not filename.endswith(".html"):
_raise_fixed()
step("report generation", generate_report)
step(
"report list",
lambda: client.request("GET", f"/reports/{parse.quote(campaign_id)}").body,
)
api_key_id_holder: dict[str, str] = {}
def api_key_create() -> None:
body = client.request(
"POST",
"/auth/api-keys",
body={"name": f"validation-lab-{int(time.time())}", "scopes": "read"},
).body
key_id = body.get("id") if isinstance(body, dict) else None
if not isinstance(key_id, str) or not key_id:
_raise_fixed()
api_key_id_holder["id"] = key_id
step("API key create", api_key_create)
if api_key_id_holder.get("id"):
def api_key_present() -> None:
key_id = api_key_id_holder["id"]
rows = client.request("GET", "/auth/api-keys").body
if not isinstance(rows, list) or not any(
isinstance(row, dict) and row.get("id") == key_id for row in rows
):
_raise_fixed()
step("API key list after create", api_key_present)
step(
"API key delete",
lambda: client.request(
"DELETE",
f"/auth/api-keys/{parse.quote(api_key_id_holder['id'])}",
),
)
def api_key_absent() -> None:
key_id = api_key_id_holder["id"]
rows = client.request("GET", "/auth/api-keys").body
if not isinstance(rows, list) or any(
isinstance(row, dict) and row.get("id") == key_id for row in rows
):
_raise_fixed()
step("API key list after delete", api_key_absent)
if campaign_id:
step(
"campaign delete",
lambda: client.request(
"DELETE", f"/campaigns/{parse.quote(campaign_id)}"
),
)
def campaign_absent() -> None:
rows = client.request("GET", "/campaigns").body
if not isinstance(rows, list) or any(
isinstance(row, dict) and row.get("id") == campaign_id for row in rows
):
_raise_fixed()
step("campaign list after delete", campaign_absent)
finally:
password = ""
if client.access_token is not None:
try:
client.logout()
_ok("browser logout cleanup")
except Exception as exc: # noqa: BLE001 - cleanup failure becomes a fixed gate
failures.append("browser logout cleanup")
_fail("browser logout cleanup", exc)
finally:
client.access_token = None
print()
if failures:
print(f"Validation lab failed: {len(failures)} step(s)")
for item in failures:
print(f" - {item}")
return 1
print("Validation lab passed.")
return 0
def build_parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser(description="Run bounded ARES validation lab checks.")
parser.add_argument("--base-url", default=os.getenv("ARES_LAB_BASE_URL"))
parser.add_argument(
"--browser-origin",
default=os.getenv("ARES_LAB_BROWSER_ORIGIN") or os.getenv("ARES_BROWSER_ORIGIN"),
)
parser.add_argument("--username", default=os.getenv("ARES_LAB_USERNAME", "admin"))
parser.add_argument(
"--idempotency-key",
default=os.getenv("ARES_LAB_IDEMPOTENCY_KEY"),
help="Optional non-secret canonical UUIDv4 for preview requests.",
)
parser.add_argument(
"--allow-remote",
action="store_true",
help="Allow one exact HTTPS origin for an explicitly authorized remote lab.",
)
return parser
def main() -> int:
args = build_parser().parse_args()
if not args.base_url:
raise ValidationLabError("base-url-required")
return run_lab(args)
if __name__ == "__main__":
sys.exit(main())