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.

15.1 KB
Raw Blame
"""
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