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
"""
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())