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.

11.2 KB
Raw Blame
"""
Campaign - tracks engagements, findings, scope, and audit trail.
"""
from __future__ import annotations

import ipaddress
import uuid
from datetime import UTC, datetime
from enum import Enum
from typing import Any

from pydantic import BaseModel, Field, PrivateAttr, field_validator

from ares.core.scope import CloudScope


class Severity(str, Enum):
    CRITICAL = "critical"
    HIGH = "high"
    MEDIUM = "medium"
    LOW = "low"
    INFO = "info"

    @property
    def score(self) -> int:
        return {"critical": 5, "high": 4, "medium": 3, "low": 2, "info": 1}[self.value]


class NoiseProfile(str, Enum):
    STEALTH = "stealth"
    NORMAL = "normal"
    AGGRESSIVE = "aggressive"


class Finding(BaseModel):
    id: str = Field(default_factory=lambda: str(uuid.uuid4()))
    title: str = Field(..., min_length=1, max_length=200)
    description: str = Field(..., min_length=1)
    severity: Severity
    confidence: float = Field(default=1.0, ge=0.0, le=1.0)
    mitre_technique: str | None = None
    mitre_tactic: str | None = None
    evidence: dict[str, Any] = Field(default_factory=dict)

    @field_validator("evidence", mode="before")
    @classmethod
    def _coerce_evidence(cls, v: Any) -> dict:
        if isinstance(v, str):
            return {"raw": v}
        return v if isinstance(v, dict) else {}
    remediation: str = ""
    false_positive: bool = False
    validated: bool = False
    discovered_at: datetime = Field(default_factory=lambda: datetime.now(UTC))

    @field_validator("discovered_at", mode="after")
    @classmethod
    def _ensure_tz_aware(cls, v: datetime) -> datetime:
        if isinstance(v, datetime) and v.tzinfo is None:
            return v.replace(tzinfo=UTC)
        return v
    host:        str | None = None
    module_id:   str = ""
    cvss_score:  float = Field(default=0.0, ge=0.0, le=10.0,
                               description="CVSS v3.1 Base Score (0.0–10.0)")
    cvss_vector: str = Field(default="",
                              description="CVSS v3.1 vector string")
    trace_id:    str = ""  # OpenTelemetry trace ID for correlation

    @property
    def risk_score(self) -> float:
        """
        Weighted risk = severity.score × confidence.

        This is the legacy/operational metric - higher means more urgent.
        It is used by the AttackPlanner to prioritize suggested next steps
        and in CLI/dashboard summaries.

        For compliance reporting, use Finding.cvss_score (CVSS v3 Base Score, 0–10).
        The HTML/JSON report uses cvss_score as the authoritative risk number.

        Rule of thumb:
          - risk_score  → "what should I attack next?" (engine / planner)
          - cvss_score  → "how bad is this?" (report / compliance)
        """
        return self.severity.score * self.confidence

    def ensure_cvss(self) -> "Finding":
        """Auto-compute CVSS score if not already set. Returns self."""
        from ares.core.cvss import enrich_finding_with_cvss
        return enrich_finding_with_cvss(self)

    def to_dict(self) -> dict:
        """Serialize to dict - compatible with sandbox/engine code that calls .to_dict()."""
        return self.model_dump(mode="json")

    def mark_false_positive(self, reason: str) -> None:
        self.false_positive = True
        self.evidence["fp_reason"] = reason


class CampaignStatus(str, Enum):
    CREATED = "created"
    RUNNING = "running"
    PAUSED = "paused"
    COMPLETED = "completed"
    ARCHIVED = "archived"


class ScopeEntry(BaseModel):
    """Defines what is in-scope for a campaign."""
    cidr: str
    description: str = ""

    @field_validator("cidr")
    @classmethod
    def validate_cidr(cls, v: str) -> str:
        try:
            ipaddress.ip_network(v, strict=False)
        except ValueError as e:
            raise ValueError(f"Invalid CIDR: {v}") from e
        return v


class AuditEntry(BaseModel):
    """Immutable audit log entry - tracks every action."""
    id: str = Field(default_factory=lambda: str(uuid.uuid4()))
    timestamp: datetime = Field(default_factory=lambda: datetime.now(UTC))
    actor: str = "system"
    action: str
    detail: str = ""
    module_id: str | None = None


class ScopeEntryList(list):
    """List of ScopeEntry items supporting .cloud_scope attribute access."""

    def __init__(self, iterable: Any = (), cloud_scope: CloudScope | None = None) -> None:
        super().__init__(iterable)
        self.cloud_scope = cloud_scope if cloud_scope is not None else CloudScope()


class Campaign(BaseModel):
    id: str = Field(default_factory=lambda: str(uuid.uuid4()))
    name: str = Field(..., min_length=1, max_length=100)
    client: str = Field(default="Internal", max_length=100)
    targets: list[str] = Field(default_factory=list)

    @field_validator("targets", mode="before")
    @classmethod
    def sanitize_targets(cls, v: list) -> list[str]:
        """Sanitize targets when Campaign is loaded from DB or created directly."""
        if not v:
            return []
        from ares.core.security import sanitize_hostname
        result: list[str] = []
        for entry in v:
            if isinstance(entry, str) and entry.strip():
                clean = sanitize_hostname(entry.strip())
                result.append(clean if clean else entry.strip())
        return result
    scope: list[ScopeEntry] = Field(default_factory=list)
    cloud_scope: CloudScope = Field(default_factory=CloudScope)
    status: CampaignStatus = CampaignStatus.CREATED
    noise_profile: NoiseProfile = NoiseProfile.STEALTH

    @field_validator("noise_profile", mode="before")
    @classmethod
    def normalize_noise_profile(cls, v: Any) -> Any:
        if isinstance(v, str):
            return v.strip().lower()
        return v

    findings: list[Finding] = Field(default_factory=list)
    audit_log: list[AuditEntry] = Field(default_factory=list)
    notes: str = ""
    operator: str = "unknown"
    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
    updated_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
    metadata: dict[str, Any] = Field(default_factory=dict)
    # ── AD campaign context ───────────────────────────────────────────────────
    domain:  str = Field(default="", description="Active Directory domain (e.g. corp.local)")
    dc:      str = Field(default="", description="Domain controller IP or hostname")
    _scope_cache: dict[str, bool] = PrivateAttr(default_factory=dict)

    def model_post_init(self, __context: Any) -> None:
        """Initialize scope wrapper and warn if operator is still default 'unknown'."""
        if not isinstance(self.scope, ScopeEntryList):
            self.scope = ScopeEntryList(self.scope, cloud_scope=self.cloud_scope)
        else:
            self.scope.cloud_scope = self.cloud_scope

        if self.operator == "unknown":
            import logging as _logging
            _logging.getLogger("ares.campaign").warning(
                "campaign_operator_not_set: campaign %r was created with operator='unknown'. "
                "Set operator= when creating Campaign to ensure accurate audit logs.",
                self.name,
            )

    def add_finding(self, finding: Finding) -> None:
        if not finding.false_positive:
            # Auto-mark as validated when added by operator
            if not finding.validated:
                finding = finding.model_copy(update={"validated": True})
            self.findings.append(finding)
            self.updated_at = datetime.now(UTC)
            self._audit("finding_added", f"[{finding.severity.value.upper()}] {finding.title}", finding.module_id)

    def _audit(self, action: str, detail: str = "", module_id: str | None = None) -> None:
        self.audit_log.append(AuditEntry(
            actor=self.operator,
            action=action,
            detail=detail,
            module_id=module_id,
        ))

    def is_in_scope(self, ip: str) -> bool:
        """
        Check if an IP address or hostname is within defined campaign scope.

        For hostnames: attempts DNS resolution to obtain the IP, then checks
        the resolved IP against scope CIDRs. If DNS fails, the check FAILS
        CLOSED (returns False) to prevent accidental out-of-scope execution.
        Falls back to explicitly declared targets/dc/domain for offline labs.
        """
        if not self.scope:
            return False  # No scope = nothing is in scope (safe default)

        normalized = ip.strip().lower()
        if not normalized:
            return False

        if normalized in self._scope_cache:
            return self._scope_cache[normalized]

        res = self._check_scope_uncached(normalized)
        if len(self._scope_cache) < 1024:
            self._scope_cache[normalized] = res
        return res

    def _check_scope_uncached(self, target: str) -> bool:
        try:
            addr = ipaddress.ip_address(target)
            return any(addr in ipaddress.ip_network(s.cidr, strict=False) for s in self.scope)
        except ValueError:
            pass

        explicit_hosts = {
            entry.strip().lower()
            for entry in [*self.targets, self.dc, self.domain]
            if entry and entry.strip()
        }

        # Attempt DNS resolution first to verify resolved IP is in CIDR scope
        import logging as _logging
        import socket as _socket
        _log = _logging.getLogger("ares.campaign")
        try:
            import concurrent.futures as _cf
            _pool = _cf.ThreadPoolExecutor(max_workers=1)
            try:
                results = _pool.submit(
                    _socket.getaddrinfo, target, None,
                    _socket.AF_INET, _socket.SOCK_STREAM
                ).result(timeout=0.4)
            finally:
                _pool.shutdown(wait=False, cancel_futures=True)

            if results:
                resolved_ip = results[0][4][0]
                addr = ipaddress.ip_address(resolved_ip)
                in_scope = any(addr in ipaddress.ip_network(s.cidr, strict=False) for s in self.scope)
                if not in_scope:
                    _log.warning(
                        "scope_check_hostname_out_of_scope: %r resolved to %s which is NOT in scope %s",
                        target, resolved_ip, [s.cidr for s in self.scope],
                    )
                    return False
                return True
        except (_socket.gaierror, TimeoutError, Exception):
            pass

        # If DNS resolution failed (offline test lab / local dev): allow ONLY if explicitly declared in targets/dc/domain
        if target in explicit_hosts:
            return True

        return False

    def check(self, ip: str) -> bool:
        """Alias for is_in_scope - used by guardrail consumers."""
        return self.is_in_scope(ip)

    def summary(self) -> dict[str, int]:
        counts: dict[str, int] = {s.value: 0 for s in Severity}
        for f in self.findings:
            if not f.false_positive:
                counts[f.severity.value] += 1
        return counts

    def confirmed_findings(self) -> list[Finding]:
        return [f for f in self.findings if f.validated and not f.false_positive]

    def risk_score(self) -> float:
        if not self.findings:
            return 0.0
        return sum(f.risk_score for f in self.confirmed_findings())