ARES - authorized red-team engagement automation with dashboard, campaign scope, module orchestration, OPSEC controls, encrypted vault, and reporting.
ARES Engine Design
Version: 1.0.0 | Status: C-LIVE-v1 safety wiring; descriptors inactive
Overview
The engine retains goal, module, and state-management components, but the pre-C-LIVE adaptive execution design documented below is inactive in C-LIVE-v1. Reachable effects require the sealed coordinator described in C-LIVE-v1 engine ownership; public engine calls and production Goal/Strategy planning fail closed while descriptors are ineligible.
Core Components
AresEngine
├─ AresContainer (dependency injection)
├─ ModuleRegistry (module catalog + validation)
├─ GoalEngine (backward-chaining planner)
├─ AttackPlanner (AI-scored next-technique suggester)
├─ AdaptiveAttackStrategy (fallback chain on failure)
├─ ClusterController (task distribution to workers)
├─ OperatorSession (attack state: hosts, creds, history)
├─ CredentialVault (encrypted credential store)
├─ TelemetryCollector (metrics, alerting)
├─ CampaignGuardrail (scope enforcement, safety gate)
└─ ScopeFirewall (transport socket egress firewall)
Legacy execution lifecycle (inactive in C-LIVE-v1)
Every module execution follows this exact sequence:
Operator / API
│
▼
CampaignGuardrail.check(module_id, target)
│ out-of-scope → ABORT immediately
▼
AttackPlanner.suggest() ← AI picks best next technique
│ or operator specifies module directly
▼
AresContainer.build_context() ← builds ExecutionContext
│ injects: vault, session, telemetry, settings
▼
BaseModule.validate(ctx) ← parameter + context check
│ ModuleValidationError → ABORT
▼
CampaignGuardrail.check() ← second check (context has real target)
│
▼
ScopeFirewall.guard() ← transport-level socket egress firewall
│ fail-closed interception of out-of-scope traffic
▼
SandboxRunner.run_module(ctx) ← capability-enforced execution
│ subprocess isolation + resource limits
▼
BaseModule.execute(ctx) ← module runs, returns ModuleResult
│
▼
ModuleResult processing:
├─ findings → campaign.add_finding()
├─ credentials → vault.store()
├─ new_hosts → session.discover_host()
└─ artifacts → ArtifactStore.add()
│
▼
ArtifactCorrelationEngine.correlate() ← find new attack paths
│
▼
AttackPlanner.suggest() ← re-score next steps
│
▼
TelemetryCollector.record_execution() ← metrics + alerting
│
▼
CheckpointManager.save() ← durable state snapshot
Module Registry
The registry is populated by PluginLoader at startup:
Source 1: builtin ares/modules/**/*.py always loaded, full trust
Source 2: entrypoint pip packages with community trust
[ares.modules] entry points
Source 3: external ~/.ares/plugins/*.py external trust
ARES_PLUGIN_DIR env var
Security controls at load time:
- Signature verification (
ModuleVerifier) - configurable viaARES_PLUGIN_SIGNING_POLICY - Capability enforcement (
CapabilityPolicy) - module can only declare allowed caps for trust level - Metadata validation (
validate_module_class) - all required attrs present - Duplicate detection - existing module_id from builtin takes priority
Dependency Injection (AresContainer)
All services are resolved through AresContainer - never instantiated directly in engine code:
# Production setup (CLI / API startup)
container = AresContainer.production(settings)
engine = container.engine()
# Testing setup (no network, no disk)
container = AresContainer.for_test()
container.override("vault", MockVault())
Services registered by name:
| Key | Type | Notes |
|---|---|---|
settings |
AresSettings | Loaded from env / config |
registry |
ModuleRegistry | Lazily populated by loader |
engine |
AresEngine | Core orchestrator |
db |
AresDatabase | SQLite async |
vault |
CredentialVault | AES-256-GCM encrypted |
telemetry |
TelemetryCollector | In-process metrics |
cluster |
ClusterController | Redis or in-process queue |
guardrail |
CampaignGuardrail | Scope + safety enforcement |
scope_firewall |
ScopeFirewall | Transport socket firewall |
sandbox |
SandboxRunner | Subprocess/seccomp/Docker |
kb |
AttackKnowledgeBase | Technique library |
ExecutionContext
A single typed object passed to every module. Replaces scattered **kwargs:
@dataclass
class ExecutionContext:
# Identity
execution_id: str # UUID per execution
campaign_id: str
module_id: str
operator: str
# Target
target: str # IP or hostname
domain: str # AD domain (CORP.LOCAL)
port: int
# Parameters
params: dict # module-specific params
# Credentials (ordered by score)
credentials: list[Credential]
primary_credential: Credential | None
# Shared state (references - mutations visible to engine)
session: OperatorSession
vault: CredentialVault
# Engine references
settings: AresSettings
telemetry: TelemetryCollector
noise: NoiseController
# OpSec
opsec_profile: str # stealth | normal | aggressive
timeout_s: int
# Safety
dry_run: bool # True = simulate, no real network calls
Context lifecycle:
Engine builds context
→ module.validate(ctx) # raises ModuleValidationError if bad
→ module.execute(ctx) # runs, returns ModuleResult
→ module.report(result) # formats for report engine
→ engine updates session state
Error Handling
All errors are typed and carry an engine action hint:
AresError
├─ ModuleError → action: retry
│ ├─ ModuleValidationError → abort
│ └─ ModuleTimeoutError → retry with backoff
├─ NetworkError → retry with jitter
│ ├─ ConnectionRefused → fallback module
│ ├─ HostUnreachable → skip target
│ └─ RateLimited → pause + increase jitter
├─ CredentialError → try next credential in vault
│ ├─ AuthenticationFailed → retry with next cred
│ └─ AccountLocked → ABORT all attempts (lockout risk)
├─ ScopeError → abort immediately (never retry)
├─ OpsecError → pause / escalate stealth
│ ├─ DetectionSignal → escalate opsec profile
│ └─ HoneypotDetected → abort campaign
└─ InsufficientPrivilege → suggest privesc module
Engine error dispatch:
try:
result = await module.execute(ctx)
except AresError as e:
action = e.action # "retry" | "skip" | "fallback" | "abort" | "pause"
if action == "retry":
task_queue.requeue(task)
elif action == "fallback":
next_mod = adaptive_strategy.next_alternative(module_id, target)
elif action == "abort":
raise
Legacy GoalEngine/AttackPlanner design (production inactive)
GoalEngine (ares/goal/engine.py) - deterministic backward chaining:
- Operator sets
Goal.DOMAIN_ADMIN - Engine looks at
GOAL_DEFINITIONSto find required outputs - Finds modules that produce those outputs
- Topological sort →
ExecutionPlanwith ordered stages
AttackPlanner (ares/goal/planner.py) - probabilistic AI scoring:
- Scores ALL candidate modules against current session state
- 6-factor weighted score: prereqs, credentials, technique value, artifact match, novelty, opsec
- Returns ranked
Suggestionlist with rationale - Re-runs after each execution (adapts to discovered state)
The following sequence is historical and is not a production C-LIVE-v1 path:
GoalEngine.plan() → initial deterministic chain
→ executes stage 1
→ AttackPlanner.suggest() → re-ranks remaining candidates
→ executes best suggestion
→ repeat until goal reached or plan exhausted
Legacy AdaptiveAttackStrategy (production inactive)
When a module fails, the engine doesn't stop - it pivots:
lateral.psexec → FAIL (EDR blocked)
↓
AdaptiveAttackStrategy.next_alternative("lateral.psexec", target)
↓
lateral.wmiexec → FAIL (WMI restricted)
↓
lateral.winrm → SUCCESS
Fallback graph is defined in ares/goal/adaptive.py:
FALLBACK_GRAPH = {
"lateral.psexec": ["lateral.wmiexec", "lateral.winrm", "lateral.ssh"],
"ad.kerberoast": ["ad.asreproast", "ad.enum_acl"],
"ad.dcsync": ["ad.enum_acl", "ad.privesc"],
...
}
EDR-blocked modules are permanently disabled for the session. Conditions (port open, creds available) gated before selecting fallback.
State Management
OperatorSession
├─ hosts{} # ip → HostState
│ ├─ compromise_level # none | recon | user | local_admin | system | domain_admin
│ ├─ is_dc # True if Domain Controller
│ ├─ open_ports[]
│ ├─ attack_history[] # ModuleExecution records
│ └─ credentials_found[]
├─ outputs{} # set of produced capabilities (feeds prereq check)
└─ attack_graph # networkx DiGraph (hosts + credential flows)
Compromise level never downgrades. Once domain_admin, always domain_admin.
Persistence via CheckpointManager:
- AES-256-GCM encrypted
.ares_ckptfiles - Plaintext secrets never written to disk
save(state)→ encrypted JSONload(campaign_id)→ decrypts + deserializespurge_old(keep_last=5)→ cleanup
Campaign Graph
At any point, the engine can generate a full attack graph for visualization:
GET /graph/{campaign_id} → {nodes: [...], edges: [...], stats: {...}}
Node types: host, dc, credential, finding, pivot
Edge types: lateral, compromise, credential, discovery, pivot
Frontend renders with D3.js or Cytoscape.js.
C-LIVE-v1 engine ownership
The engine no longer owns admission or implicit retries. A coordinator must
first obtain exact APPLIED results for admission, queue, dispatch, and running,
then pass a sealed single-use context to the engine. The engine prepares a
sanitized result; persistence/publication is released only after the V3 terminal
commit succeeds. Exact admission or terminal replay never enters the engine.
Plan occurrences retain stage/module ordinals, including repeated module IDs. Retry attempts use deterministic child identities and repeat principal revalidation before queueing. Timeout, disconnect, cancellation, or an ordinary exception is not by itself settlement proof. Uncertain work is parked without automatic redispatch; INDETERMINATE recovery remains P1-F.