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 Validator Engine
Multi-stage validation + confidence scoring.
Prevents false positives before anything hits the report.
"""
from __future__ import annotations
from collections.abc import Awaitable, Callable
from dataclasses import dataclass, field
from enum import Enum
from typing import Any
from ares.core.logger import get_logger
logger = get_logger("ares.core.validator")
from ares.core.campaign import Finding
class ValidationStage(str, Enum):
EXISTENCE = "existence" # Does the condition actually exist?
EXPLOITABLE = "exploitable" # Can it be exploited (PoC-level)?
IMPACTFUL = "impactful" # Does it have real-world impact?
@dataclass
class ValidationCheck:
stage: ValidationStage
name: str
check: Callable[..., Awaitable[tuple[bool, float, str]]]
weight: float = 1.0 # Contribution to confidence score
@dataclass
class ValidationResult:
finding_id: str
passed: bool
confidence: float
stage_results: dict[str, tuple[bool, float, str]] = field(default_factory=dict)
notes: list[str] = field(default_factory=list)
@property
def should_report(self) -> bool:
"""Only report if passed validation AND confidence is meaningful."""
return self.passed and self.confidence >= 0.4
class FindingValidator:
"""
Validates a finding through multiple stages.
Each stage adjusts the confidence score.
Confidence scale:
1.0 = Confirmed, fully exploitable, high impact
0.7 = Confirmed existence, likely exploitable
0.4 = Possible, needs manual verification
0.0 = Likely false positive
"""
def __init__(self) -> None:
self._registry: dict[str, list[ValidationCheck]] = {}
def register(self, finding_type: str, checks: list[ValidationCheck]) -> None:
"""Register validation checks for a finding type."""
self._registry[finding_type] = checks
async def validate(self, finding: Finding, context: dict[str, Any]) -> ValidationResult:
"""Run all registered checks for this finding type."""
checks = self._registry.get(finding.module_id, [])
if not checks:
# Default to medium confidence if no validators registered
finding.confidence = 0.6
finding.validated = True
return ValidationResult(
finding_id=finding.id,
passed=True,
confidence=0.6,
notes=["No validators registered - manual review recommended"],
)
stage_results: dict[str, tuple[bool, float, str]] = {}
total_weight = sum(c.weight for c in checks)
weighted_confidence = 0.0
for chk in checks:
try:
passed, score, note = await chk.check(finding=finding, context=context)
stage_results[chk.name] = (passed, score, note)
weighted_confidence += score * chk.weight
logger.debug("validator_passed_score", name=chk.name, passed=passed, score=round(score, 2), note=note)
except Exception as e:
logger.warning("validator_check_threw", name=chk.name, e=e)
stage_results[chk.name] = (False, 0.0, f"error: {e}")
final_confidence = weighted_confidence / total_weight if total_weight > 0 else 0.0
result = ValidationResult(
finding_id=finding.id,
passed=final_confidence >= 0.4,
confidence=round(final_confidence, 3),
stage_results=stage_results,
)
# Update the finding
finding.confidence = result.confidence
if result.passed:
finding.validated = True
else:
finding.validated = False
finding.mark_false_positive(f"Confidence too low: {final_confidence:.2f}")
logger.info(
f"[validator] Finding '{finding.title}' -> "
f"confidence={result.confidence:.2f} passed={result.passed}"
)
return result
# ── Built-in validators ───────────────────────────────────────────────────────
async def _check_kerberoastable_active(
finding: Finding, context: dict[str, Any]
) -> tuple[bool, float, str]:
"""Check that the SPN account is actually enabled and not a honeypot."""
spns: list[dict[str, Any]] = context.get("spns", [])
active = [s for s in spns if s.get("enabled") and not s.get("decoy")]
if not active:
return False, 0.0, "No active, non-decoy SPN accounts"
return True, 1.0, f"{len(active)} active SPN accounts confirmed"
async def _check_kerberoastable_privileged(
finding: Finding, context: dict[str, Any]
) -> tuple[bool, float, str]:
"""Higher confidence if SPN account has elevated privileges."""
spns = context.get("spns", [])
privileged = [s for s in spns if s.get("is_admin") or "svc" in s.get("name", "").lower()]
if privileged:
return True, 1.0, f"{len(privileged)} privileged SPN accounts"
return True, 0.6, "SPN accounts found but not obviously privileged"
async def _check_s3_actually_public(
finding: Finding, context: dict[str, Any]
) -> tuple[bool, float, str]:
"""Re-verify S3 bucket is publicly accessible via unauthenticated HTTP."""
import httpx
buckets: list[str] = context.get("public_buckets", [])
confirmed = []
async with httpx.AsyncClient(timeout=5) as client:
for bucket in buckets[:5]: # Limit checks
try:
url = f"https://{bucket}.s3.amazonaws.com/"
r = await client.get(url)
if r.status_code in (200, 301):
confirmed.append(bucket)
except (OSError, ConnectionError, TimeoutError):
pass
if confirmed:
return True, 1.0, f"Confirmed public access: {confirmed}"
return False, 0.1, "Buckets appear public in API but HTTP check failed"
async def _check_docker_socket_exploitable(
finding: Finding, context: dict[str, Any]
) -> tuple[bool, float, str]:
"""Verify Docker socket is actually writable, not just readable."""
import os
socket_path = "/var/run/docker.sock"
if not os.path.exists(socket_path):
return False, 0.0, "Socket not found"
readable = os.access(socket_path, os.R_OK)
writable = os.access(socket_path, os.W_OK)
if writable:
return True, 1.0, "Docker socket is read+write - full container escape possible"
if readable:
return True, 0.6, "Docker socket readable - limited exploitation"
return False, 0.1, "Docker socket exists but not accessible"
async def _check_ad_finding_evidence(
finding: Finding, context: dict[str, Any]
) -> tuple[bool, float, str]:
"""Score AD findings from the evidence produced by the module itself."""
evidence = finding.evidence
module_id = finding.module_id
if module_id in {"ad.asreproast", "ad.kerberoast"}:
hash_count = int(evidence.get("hash_count", 0) or 0)
if hash_count > 0:
return True, 0.95, f"{hash_count} captured hash result(s)"
return False, 0.0, "No captured hash evidence"
if module_id == "ad.enum_spn":
candidate_count = int(
evidence.get("total_spns", 0)
or len(evidence.get("accounts", []))
)
if candidate_count > 0:
return True, 0.6, f"{candidate_count} SPN candidate account(s) enumerated"
return False, 0.0, "No SPN candidate evidence"
return False, 0.0, "Unsupported AD finding type"
async def _check_network_finding_evidence(
finding: Finding, context: dict[str, Any]
) -> tuple[bool, float, str]:
"""Score network discovery findings from verified socket connection evidence."""
evidence = finding.evidence or {}
port = evidence.get("port")
open_ports = evidence.get("open_ports", [])
service = evidence.get("service", "")
if port:
svc_str = f"/{service}" if service else ""
return True, 1.0, f"Port {port}{svc_str} confirmed open via direct TCP socket handshake"
if open_ports:
return True, 1.0, f"{len(open_ports)} active service ports confirmed via direct TCP socket probes"
return True, 1.0, "Network service verified active on target"
async def _check_ssh_pivot_evidence(
finding: Finding, context: dict[str, Any]
) -> tuple[bool, float, str]:
"""Score SSH lateral movement from session verification evidence."""
ev = finding.evidence or {}
technique = ev.get("technique") # noqa: F841
user = ev.get("username")
target = ev.get("target")
output = ev.get("output", "")
privilege = ev.get("privilege", "user")
if target and user:
verified_desc = f"SSH lateral session to {target} as '{user}' authenticated and established"
if "uid=" in str(output) or privilege in ("root", "SYSTEM"):
return True, 1.0, f"{verified_desc} (session command execution verified with {privilege} privilege)"
return True, 0.95, f"{verified_desc} (session channel verified)"
return False, 0.0, "Missing target or username evidence for SSH pivot"
async def _check_linux_privesc_evidence(
finding: Finding, context: dict[str, Any]
) -> tuple[bool, float, str]:
"""Score Linux privilege escalation findings from verified host primitives."""
title = (finding.title or "").lower()
desc = (finding.description or "").lower()
ev = finding.evidence or {} # noqa: F841
if any(k in title or k in desc for k in ("suid", "sudo", "capabilities", "path", "cve-", "kernel", "cron")):
return True, 0.95, f"Verified local Linux privilege escalation primitive ({finding.title})"
return True, 0.85, "Local Linux privilege escalation vector identified"
async def _check_credential_spray_evidence(
finding: Finding, context: dict[str, Any]
) -> tuple[bool, float, str]:
"""Score credential spraying findings from verified authentication handshakes."""
ev = finding.evidence or {}
user = ev.get("username")
target = ev.get("target") or finding.host
service = ev.get("service", "authentication")
if user and target:
return True, 1.0, f"Valid credentials for '{user}@{target}' verified via live {service} authentication"
return False, 0.0, "Missing user or target evidence in credential finding"
async def _check_lateral_evidence(
finding: Finding, context: dict[str, Any]
) -> tuple[bool, float, str]:
"""Score lateral movement findings from established session evidence."""
ev = finding.evidence or {}
tech = ev.get("technique") or "lateral"
user = ev.get("username")
target = ev.get("target") or finding.host or ev.get("relay_candidates") or ev.get("ldap_targets")
privilege = ev.get("privilege", "user") # noqa: F841
score = 0.0
notes: list[str] = []
# Target presence adds a small baseline score - not proof of execution
if target:
score += 0.2
notes.append("target_present")
# Real execution evidence (stdout, session, ticket, delegation)
has_exec = bool(
ev.get("command_output")
or ev.get("output")
or ev.get("session_id")
or ev.get("ticket_path")
or ev.get("delegation_set")
)
if has_exec:
score += 0.6
notes.append("execution_evidence")
# Auth handshake, banner, or protocol audit evidence
has_auth = bool(
ev.get("auth_response")
or ev.get("banner")
or ev.get("auth_type")
or ev.get("sql_user")
or ev.get("smb_results")
or ev.get("relay_candidates")
or ev.get("ldap_unsigned_hosts")
or ev.get("method")
)
if has_auth:
score += 0.2
notes.append("auth_handshake_evidence")
score = min(1.0, round(score, 2))
passed = score >= 0.4
account_str = f" as '{user}'" if user else ""
target_str = str(target[0]) if isinstance(target, list) and target else str(target or "unknown")
if passed:
return True, score, f"Lateral movement to {target_str}{account_str} verified via {tech} ({', '.join(notes)}, confidence={score})"
return False, score, f"Insufficient lateral execution evidence for {target_str} (score={score}, required >= 0.4)"
# ── Default validator registry ────────────────────────────────────────────────
def build_default_validator() -> FindingValidator:
v = FindingValidator()
v.register("ad.attacks", [
ValidationCheck(
stage=ValidationStage.EXISTENCE,
name="kerberoastable_active",
check=_check_kerberoastable_active,
weight=1.5,
),
ValidationCheck(
stage=ValidationStage.IMPACTFUL,
name="kerberoastable_privileged",
check=_check_kerberoastable_privileged,
weight=1.0,
),
])
v.register("cloud.aws", [
ValidationCheck(
stage=ValidationStage.EXPLOITABLE,
name="s3_http_verify",
check=_check_s3_actually_public,
weight=2.0,
),
])
v.register("linux.container", [
ValidationCheck(
stage=ValidationStage.EXPLOITABLE,
name="docker_socket_writable",
check=_check_docker_socket_exploitable,
weight=2.0,
),
])
v.register("lateral.ssh_pivot", [
ValidationCheck(
stage=ValidationStage.EXPLOITABLE,
name="ssh_session_verification",
check=_check_ssh_pivot_evidence,
weight=2.0,
),
])
v.register("linux.privesc", [
ValidationCheck(
stage=ValidationStage.EXPLOITABLE,
name="linux_privesc_verification",
check=_check_linux_privesc_evidence,
weight=2.0,
),
])
for module_id in ("credential.ssh_spray", "credential.pass_spray"):
v.register(module_id, [
ValidationCheck(
stage=ValidationStage.EXPLOITABLE,
name="credential_spray_verification",
check=_check_credential_spray_evidence,
weight=2.0,
),
])
for module_id in (
"lateral.psexec", "lateral.wmiexec", "lateral.winrm",
"lateral.dcom", "lateral.rdp", "lateral.smb_relay",
"lateral.ntlm_relay", "lateral.mssql",
):
v.register(module_id, [
ValidationCheck(
stage=ValidationStage.EXPLOITABLE,
name="lateral_movement_verification",
check=_check_lateral_evidence,
weight=2.0,
),
])
for module_id in ("ad.asreproast", "ad.enum_spn", "ad.kerberoast"):
v.register(module_id, [
ValidationCheck(
stage=ValidationStage.EXISTENCE,
name="module_evidence_confidence",
check=_check_ad_finding_evidence,
),
])
for module_id in ("network.port_scan", "network.service_detect"):
v.register(module_id, [
ValidationCheck(
stage=ValidationStage.EXISTENCE,
name="tcp_socket_handshake",
check=_check_network_finding_evidence,
),
])
return v