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 Operator Session & Target State Engine
Tracks the full operational state of a red team engagement.
State hierarchy:
OperatorSession
├── NetworkState (discovered hosts, subnets)
├── HostState × N (per-host compromise status)
├── CredentialIndex (cross-reference creds to hosts)
└── AttackHistory (what was tried, when, result)
"""
from __future__ import annotations
import time
import uuid
from dataclasses import dataclass, field
from enum import Enum
from typing import Any
from ares.core.logger import get_logger
logger = get_logger("ares.state")
class CompromiseLevel(str, Enum):
NONE = "none"
IDENTIFIED = "identified"
SCANNED = "scanned"
ACCESSED = "accessed"
LOCAL_USER = "local_user"
LOCAL_ADMIN = "local_admin"
SERVICE_ACCOUNT = "service_account"
SYSTEM = "system"
DOMAIN_USER = "domain_user"
DOMAIN_ADMIN = "domain_admin"
# Convenience aliases used in tests
USER = "local_user"
DOMAIN = "domain_user"
ENTERPRISE_ADMIN = "enterprise_admin"
def score(self) -> int:
return {
"none": 0, "identified": 1, "scanned": 2, "accessed": 3,
"local_user": 4, "local_admin": 5, "service_account": 6,
"system": 7, "domain_user": 5, "domain_admin": 9,
"enterprise_admin": 10,
}.get(self.value, 0)
def __gt__(self, other: "CompromiseLevel") -> bool:
return self.score() > other.score()
def __ge__(self, other: "CompromiseLevel") -> bool:
return self.score() >= other.score()
@dataclass
class ServiceEntry:
"""A discovered service on a host."""
port: int
protocol: str = "tcp"
service: str = ""
banner: str = ""
version: str = ""
vulnerable: bool = False
@dataclass
class HostState:
"""Full state of a single target host."""
ip_address: str = ""
ip: str = field(default="", repr=False) # alias - set either ip_address or ip
hostname: str = ""
fqdn: str = ""
domain: str = ""
os: str = ""
os_version: str = ""
is_dc: bool = False
is_in_scope: bool = True
compromise_level: CompromiseLevel = CompromiseLevel.NONE
owned: bool = False
privilege: str = ""
owned_at: float | None = None
owned_via: str = ""
services: list[ServiceEntry] = field(default_factory=list)
open_ports: list[int] = field(default_factory=list)
users: list[str] = field(default_factory=list)
local_admins: list[str] = field(default_factory=list)
shares: list[str] = field(default_factory=list)
valid_credential_ids: list[str] = field(default_factory=list)
reachable_from: list[str] = field(default_factory=list)
can_reach: list[str] = field(default_factory=list)
first_seen: float = field(default_factory=time.time)
last_updated: float = field(default_factory=time.time)
tags: list[str] = field(default_factory=list)
notes: str = ""
os_type: str = "" # e.g. "Windows Server", "Linux"
domain_role: str = "" # e.g. "domain_controller", "member"
attack_history: list[dict] = field(default_factory=list)
security_controls: dict[str, Any] = field(default_factory=dict)
defense_profile: dict[str, Any] = field(default_factory=dict)
def __post_init__(self) -> None:
if self.ip and not self.ip_address:
self.ip_address = self.ip
elif self.ip_address and not self.ip:
self.ip = self.ip_address
if self.domain_role.lower() in ("domain_controller", "dc", "primary_dc"):
self.is_dc = True
elif self.is_dc and not self.domain_role:
self.domain_role = "domain_controller"
def update_defense_profile(self, controls: dict[str, Any] | None = None, **kwargs: Any) -> None:
"""Update or merge detected defense controls and security posture."""
if controls:
self.defense_profile.update(controls)
self.security_controls.update(controls)
if kwargs:
self.defense_profile.update(kwargs)
self.security_controls.update(kwargs)
self.last_updated = time.time()
def has_defense(self, control_name: str) -> bool:
"""Check if a specific security control or defense is active on this host."""
norm = control_name.strip().lower()
for k, v in self.defense_profile.items():
if k.strip().lower() == norm and bool(v):
return True
for k, v in self.security_controls.items():
if k.strip().lower() == norm and bool(v):
return True
return False
@property
def owned_by(self) -> str:
"""Username of the operator/user who owns this host."""
return self.privilege
def is_owned(self) -> bool:
return self.owned
def mark_owned(
self,
level: CompromiseLevel,
via: str = "",
username: str = "",
method: str = "", # alias for via
) -> None:
if method and not via:
via = method
if level > self.compromise_level:
self.compromise_level = level
self.owned_via = via
self.privilege = username
self.last_updated = time.time()
if level >= CompromiseLevel.LOCAL_ADMIN:
self.owned = True
self.owned_at = time.time()
logger.info(
"host_state_updated",
host=self.ip_address or self.hostname,
level=level.value,
via=via,
)
def add_service(self, port: int, service: str, version: str = "") -> None:
if port not in self.open_ports:
self.open_ports.append(port)
existing = next((s for s in self.services if s.port == port), None)
if not existing:
self.services.append(ServiceEntry(port=port, service=service, version=version))
def to_dict(self) -> dict[str, Any]:
return {
"ip_address": self.ip_address,
"hostname": self.hostname,
"fqdn": self.fqdn,
"domain": self.domain,
"os": self.os,
"is_dc": self.is_dc,
"compromise_level": self.compromise_level.value,
"owned": self.owned,
"privilege": self.privilege,
"owned_via": self.owned_via,
"open_ports": self.open_ports,
"services": [
{"port": s.port, "service": s.service, "version": s.version}
for s in self.services
],
"local_admins": self.local_admins,
"valid_credential_ids": self.valid_credential_ids,
"reachable_from": self.reachable_from,
"can_reach": self.can_reach,
"tags": self.tags,
"security_controls": dict(self.security_controls),
"defense_profile": dict(self.defense_profile),
}
@dataclass
class AttackHistoryEntry:
"""Record of a single attack attempt."""
entry_id: str = field(default_factory=lambda: str(uuid.uuid4())[:8])
timestamp: float = field(default_factory=time.time)
module_id: str = ""
technique: str = ""
source_host: str = "operator"
target_host: str = ""
username: str = ""
success: bool = False
finding_ids: list[str] = field(default_factory=list)
output: str = ""
notes: str = ""
def to_dict(self) -> dict[str, Any]:
return {
"entry_id": self.entry_id,
"timestamp": self.timestamp,
"module_id": self.module_id,
"technique": self.technique,
"source": self.source_host,
"target": self.target_host,
"username": self.username,
"success": self.success,
"findings": self.finding_ids,
}
# ── Operator Session ───────────────────────────────────────────────────────────
class OperatorSession:
"""
Full state of an active red team engagement.
Tracks every discovered host, credential, and attack attempt.
"""
def __init__(self, campaign_id: str, operator: str = "unknown") -> None:
self.session_id: str = str(uuid.uuid4())
self.campaign_id: str = campaign_id
self.operator: str = operator
self.started_at: float = time.time()
self._hosts: dict[str, HostState] = {}
self._history: list[AttackHistoryEntry] = []
self._pivot_proxies: list[dict[str, Any]] = []
logger.info("session_created",
session_id=self.session_id[:8],
campaign=campaign_id,
operator=operator)
# ── Host management ────────────────────────────────────────────────────
def add_host(self, ip: str, hostname: str = "", **kwargs: Any) -> HostState:
key = ip or hostname
if key not in self._hosts:
self._hosts[key] = HostState(ip_address=ip, hostname=hostname, **kwargs)
logger.info("session_host_added", host=key)
else:
h = self._hosts[key]
if hostname and not h.hostname:
h.hostname = hostname
for k, v in kwargs.items():
if hasattr(h, k) and v:
setattr(h, k, v)
h.last_updated = time.time()
return self._hosts[key]
def discover_host(self, ip: str, hostname: str = "", **kwargs: Any) -> HostState:
return self.add_host(ip, hostname, **kwargs)
def get_or_create_host(self, ip: str, hostname: str = "", **kwargs: Any) -> HostState:
return self.add_host(ip, hostname, **kwargs)
def get_host(self, ip_or_hostname: str) -> HostState | None:
return self._hosts.get(ip_or_hostname)
def mark_host_owned(
self,
ip_or_hostname: str,
level: CompromiseLevel,
via_module: str = "",
username: str = "",
) -> None:
host = self._hosts.get(ip_or_hostname)
if host:
host.mark_owned(level, via=via_module, username=username)
def mark_owned(
self,
ip_or_hostname: str,
level: CompromiseLevel,
via_module: str = "",
username: str = "",
credentials: list | None = None,
**kwargs: Any,
) -> None:
"""Alias untuk mark_host_owned - auto-create host jika belum ada."""
if ip_or_hostname not in self._hosts:
self.add_host(ip_or_hostname)
self.mark_host_owned(ip_or_hostname, level, via_module=via_module, username=username)
def record_attack(
self,
module_id_or_target: str = "",
target_or_module_id: str = "",
success: bool = False,
technique: str = "",
username: str = "",
module_id: str = "", # explicit kwarg
target_host: str = "", # explicit kwarg
**kwargs: Any,
) -> "AttackHistoryEntry":
"""Record attack attempt. Accepts both positional and keyword args."""
import re
# Resolve explicit kwargs first
if module_id and target_host:
_module_id, _target = module_id, target_host
elif module_id_or_target or target_or_module_id:
# Auto-detect order: if first arg looks like an IP, it's target
if re.match(r"^\d{1,3}\.\d{1,3}", module_id_or_target):
_target = module_id_or_target
_module_id = target_or_module_id
else:
_module_id = module_id_or_target
_target = target_or_module_id
else:
_module_id, _target = "", ""
entry = self.record(module_id=_module_id, target_host=_target,
success=success, technique=technique, username=username)
host = self._hosts.get(_target)
if host:
host.attack_history.append(entry.to_dict())
return entry
def hosts_by_level(self, level: CompromiseLevel) -> list[HostState]:
return [h for h in self._hosts.values() if h.compromise_level >= level]
def owned_hosts(self) -> list[HostState]:
return [h for h in self._hosts.values() if h.owned]
def uncompromised_hosts(self) -> list[HostState]:
return [
h for h in self._hosts.values()
if h.compromise_level == CompromiseLevel.NONE
or h.compromise_level == CompromiseLevel.IDENTIFIED
]
def domain_controllers(self) -> list[HostState]:
return [
h for h in self._hosts.values()
if h.is_dc or h.domain_role.lower() in ("domain_controller", "dc", "primary_dc")
]
# ── Pivot management ──────────────────────────────────────────────────
def add_pivot(self, proxy_config: dict[str, Any]) -> None:
self._pivot_proxies.append({**proxy_config, "added_at": time.time()})
logger.info("session_pivot_added", proxy=proxy_config)
def active_pivots(self) -> list[dict[str, Any]]:
return list(self._pivot_proxies)
# ── History ───────────────────────────────────────────────────────────
def record(
self,
module_id: str,
target_host: str,
success: bool,
technique: str = "",
username: str = "",
finding_ids: list[str] | None = None,
output: str = "",
) -> AttackHistoryEntry:
entry = AttackHistoryEntry(
module_id=module_id, target_host=target_host, success=success,
technique=technique, username=username,
finding_ids=finding_ids or [], output=output[:500],
)
self._history.append(entry)
return entry
def history(self, target_host: str = "", module_id: str = "") -> list[AttackHistoryEntry]:
h = self._history
if target_host:
h = [e for e in h if e.target_host == target_host]
if module_id:
h = [e for e in h if e.module_id == module_id]
return h
def was_tried(self, module_id: str, target_host: str) -> bool:
return any(
e.module_id == module_id and e.target_host == target_host
for e in self._history
)
# ── Snapshot ──────────────────────────────────────────────────────────
def snapshot(self) -> dict[str, Any]:
return {
"session_id": self.session_id,
"campaign_id": self.campaign_id,
"operator": self.operator,
"started_at": self.started_at,
"hosts": {k: v.to_dict() for k, v in self._hosts.items()},
"pivot_proxies": self._pivot_proxies,
"history": [e.to_dict() for e in self._history],
"stats": {
"total_hosts": len(self._hosts),
"owned_hosts": len(self.owned_hosts()),
"total_attempts": len(self._history),
"successful": sum(1 for e in self._history if e.success),
"pivot_count": len(self._pivot_proxies),
},
}
def stats(self) -> dict[str, Any]:
owned = self.owned_hosts()
return {
"total_hosts": len(self._hosts),
"owned_hosts": len(owned),
"dcs_found": len(self.domain_controllers()),
"dcs_owned": sum(1 for h in self.domain_controllers() if h.owned),
"total_attempts": len(self._history),
"successful": sum(1 for e in self._history if e.success),
"pivots": len(self._pivot_proxies),
}
def update_host(self, host: "HostState") -> None:
"""
Upsert a HostState object into the session (replace if same IP exists).
Useful when external code builds a HostState and wants to store it.
"""
self._hosts[host.ip_address] = host
# Mirror by hostname for quick lookup
if host.hostname:
self._hosts[host.hostname] = host
def all_hosts(self) -> list["HostState"]:
"""Return deduplicated list of all tracked hosts."""
seen: set[str] = set()
result: list[HostState] = []
for h in self._hosts.values():
if h.ip_address not in seen:
seen.add(h.ip_address)
result.append(h)
return result
def to_json(self) -> str:
"""JSON-serialise the full session snapshot."""
import json
return json.dumps(self.snapshot(), default=str, indent=2)
@classmethod
def from_snapshot(
cls,
data: dict[str, Any],
) -> "OperatorSession":
"""Reconstruct an OperatorSession from a snapshot dict."""
sess = cls(
campaign_id = data.get("campaign_id", ""),
operator = data.get("operator", "unknown"),
)
sess.session_id = data.get("session_id", sess.session_id)
sess.started_at = data.get("started_at", sess.started_at)
for ip, h in data.get("hosts", {}).items():
level = CompromiseLevel(
h.get("compromise_level", CompromiseLevel.NONE.value)
)
hs = HostState(
ip_address = h.get("ip_address", ip),
hostname = h.get("hostname", ""),
os_type = h.get("os_type", ""),
compromise_level = level,
owned = h.get("owned", level >= CompromiseLevel.LOCAL_ADMIN),
privilege = h.get("privilege", ""),
owned_via = h.get("owned_via", ""),
owned_at = h.get("owned_at"),
attack_history = h.get("attack_history", []),
security_controls = h.get("security_controls", {}),
defense_profile = h.get("defense_profile", {}),
)
sess._hosts[ip] = hs
sess._pivot_proxies = data.get("pivot_proxies", [])
for e in data.get("history", []):
entry = AttackHistoryEntry(
module_id = e.get("module_id", ""),
target_host = e.get("target_host", ""),
success = e.get("success", False),
technique = e.get("technique", ""),
username = e.get("username", ""),
finding_ids = e.get("finding_ids", []),
output = e.get("output", ""),
)
sess._history.append(entry)
return sess
# ── Public aliases (backward compatibility + test convenience) ─────────────────
#: Alias for HostState - used in tests and external tooling that prefer the name TargetHost
TargetHost = HostState