ARES - authorized red-team engagement automation with dashboard, campaign scope, module orchestration, OPSEC controls, encrypted vault, and reporting.
ARES Architecture
Version: 6.0.0 | Status: C-LIVE-v1 safety wiring; descriptors inactive
Overview
ARES (Automated Red team Engagement System) contains orchestration, campaign state, reporting, and module infrastructure for AD/Windows, Linux/Container, and Cloud environments. C-LIVE-v1 does not activate production module descriptors. The legacy topology and data-flow diagrams below describe a target architecture, not a currently reachable execution path.
ARES is not a C2 framework. It does not include implants, beacons, or persistent agents. It is an orchestration layer for red team techniques executed from the operator's machine.
Legacy target architecture (inactive for C-LIVE-v1 effects)
┌─────────────────────────────────────────────────────────────────┐
│ OPERATOR INTERFACE │
│ CLI (click/rich) REST API (FastAPI) │
└───────────────────────────┬─────────────────────────────────────┘
│
┌───────────────────────────▼─────────────────────────────────────┐
│ ARES ENGINE CORE │
│ AresEngine ──► ExecutionContext ──► BaseModule.execute(ctx) │
│ │ │
│ ├── DI Container (AresContainer) │
│ ├── Goal Engine (backward-chain planner) │
│ ├── Adaptive Strategy (auto-fallback on failure) │
│ ├── Campaign Guardrail (scope + safety checks) │
│ └── Telemetry Collector (metrics, alerts) │
└───────────────────────────┬─────────────────────────────────────┘
│
┌───────────────────────────▼─────────────────────────────────────┐
│ EXECUTION LAYER │
│ ClusterController ──► Redis/In-Process Queue │
│ │ │
│ ├── ClusterWorkerNode (worker process) │
│ │ └── SandboxRunner (subprocess/docker isolation) │
│ └── IsolatedRunner (legacy subprocess worker) │
└───────────────────────────┬─────────────────────────────────────┘
│
┌───────────────────────────▼─────────────────────────────────────┐
│ MODULE LAYER │
│ BaseModule (validate → execute → report) │
│ ├── ares/modules/ad/ (14 modules: 13 active, 1 dis.)│
│ ├── ares/modules/linux/ (10 modules) │
│ ├── ares/modules/cloud/ (7 modules: 6 active, 1 dis.) │
│ ├── ares/modules/lateral/ (9 modules) │
│ ├── ares/modules/windows/ (8 modules: 6 active, 2 dis.) │
│ ├── ares/modules/credential/ (7 modules) │
│ ├── ares/modules/network/ (6 modules) │
│ ├── ares/modules/exfil/ (3 modules) │
│ ├── ares/modules/persistence/(3 modules) │
│ └── ares/modules/{edr,opsec,ai,recon,reporting}/ (6 modules)│
└───────────────────────────┬─────────────────────────────────────┘
│
┌───────────────────────────▼─────────────────────────────────────┐
│ STATE & INTELLIGENCE │
│ OperatorSession ──► HostState, CompromiseLevel │
│ ArtifactStore ──► HostArtifact, CredentialArtifact, etc. │
│ CredentialVault ──► AES-256-GCM encrypted, scored, deduped │
│ NetworkModel ──► Graph, pivot routing │
│ ArtifactCorrelationEngine ──► 7 compound attack rules │
│ ArtifactIntelEngine ──► auto-queue next modules from artifacts │
└───────────────────────────┬─────────────────────────────────────┘
│
┌───────────────────────────▼─────────────────────────────────────┐
│ PERSISTENCE LAYER │
│ AresDatabase (aiosqlite) ──► campaigns, findings, hosts │
│ CheckpointManager ──► encrypted .ares_ckpt files │
│ EvidenceStore ──► command output, screenshots, files │
└─────────────────────────────────────────────────────────────────┘
Core Components
1. ares/core/
| File | Purpose |
|---|---|
engine.py |
AresEngine - async orchestrator, runs ExecutionPlan |
context.py |
ExecutionContext - unified module input object |
errors.py |
Unified error hierarchy (ModuleError, NetworkError, etc.) |
di.py |
AresContainer - dependency injection / service locator |
campaign.py |
Campaign, Finding, ScopeEntry, NoiseProfile |
config.py |
AresSettings (Pydantic), @lru_cache singleton |
noise.py |
NoiseController, JitterEngine, RateLimiter, ScopeGuard |
scope_firewall.py |
ScopeFirewall - transport-level socket & event loop egress firewall |
security.py |
JWT, DataEncryptor (AES-256-GCM), bcrypt, sanitize_* helpers |
logger.py |
structlog NDJSON, sensitive data masking |
sandbox.py |
SandboxRunner - 4-tier module isolation |
chain/chain.py |
AttackChain, Kahn's dependency resolver, ChainAdvisor |
opsec/opsec.py |
UA rotation, beacon scheduler, traffic shaping |
opsec/adaptive.py |
AdaptiveOpsecEngine - sliding window signal detection |
plugin/loader.py |
PluginLoader, ModuleRegistry |
validator.py |
FindingValidator, confidence scoring, FP filtering |
2. ares/modules/base.py - SDK Contract
Every module MUST implement this interface:
class BaseModule(ABC):
# Required metadata
MODULE_ID: str # "ad.kerberoast"
MODULE_NAME: str # "Kerberoasting"
MODULE_CATEGORY: str # "ad"
MODULE_DESCRIPTION: str # one-liner
# Optional metadata
OPSEC_LEVEL: OpsecLevel # SILENT | LOW | MEDIUM | HIGH_NOISE
REQUIRES: list[str] # ["domain_creds", "spn_list"]
OUTPUTS: list[str] # ["kerberos_hashes"]
MITRE_TECHNIQUES: list[str] # ["T1558.003"]
MODULE_AUTHOR: str
# Public SDK (preferred)
async def validate(self, ctx: ExecutionContext) -> None: ...
async def execute(self, ctx: ExecutionContext) -> ModuleResult: ...
def report(self, result: ModuleResult) -> dict: ...
# Legacy (still supported)
async def run(self, **kwargs) -> tuple[list[Finding], dict]: ...
3. ExecutionContext
Single object carrying all runtime state for a module execution:
ctx = ExecutionContext.build(
campaign = campaign,
target = "dc01.corp.local",
module_id = "ad.kerberoast",
params = {"domain": "CORP"},
credentials = vault.credentials_for_reuse(),
session = operator_session,
)
findings, raw = await module.run(**ctx.params) # legacy
result = await module.execute(ctx) # ARES SDK
4. Error Hierarchy
AresError
├── ModuleError (retry)
│ ├── ModuleValidationError (abort)
│ ├── ModuleTimeoutError (retry with backoff)
│ └── ModuleNotFoundError (abort)
├── NetworkError (retry with jitter)
│ ├── ConnectionRefused (fallback)
│ ├── ConnectionTimeout (retry)
│ ├── HostUnreachable (skip)
│ └── RateLimited (pause)
├── CredentialError (try next cred)
│ ├── AuthenticationFailed (try next)
│ ├── AccountLocked (ABORT - never retry)
│ └── CredentialExpired (skip)
├── ExecutionError
│ ├── SandboxError (skip)
│ └── WorkerCrashed (requeue)
├── ScopeError (ABORT - never retry)
│ └── ScopeFirewallBlockError (ABORT - intercepted socket egress)
├── OpsecError (pause/adjust profile)
│ ├── DetectionSignal (escalate profile)
│ └── HoneypotDetected (ABORT campaign)
└── PermissionError (fallback → privesc)
└── InsufficientPrivilege (suggest privesc module)
5. DI Container
# Production
container = AresContainer.production(settings)
engine = container.engine()
# Testing
container = AresContainer.for_test()
container.override("vault", MockVault())
module = container.build_module("ad.kerberoast", campaign)
Legacy data flow (inactive for C-LIVE-v1 effects)
Single Module Execution
CLI: ares module run ad.kerberoast --target dc01
│
▼
AresContainer.build_context(campaign, "dc01", "ad.kerberoast")
│
▼
CampaignGuardrail.check("ad.kerberoast", "dc01")
│ (abort if out of scope)
▼
BaseModule.validate(ctx)
│ (abort if context insufficient)
▼
ClusterController.submit("ad.kerberoast", campaign_id, params)
│
▼
ClusterWorkerNode claims task
│
▼
SandboxRunner.run_module() [TIER_1 subprocess]
│
▼
BaseModule.execute(ctx) → ModuleResult
│
▼
ArtifactIntelEngine.process(artifacts) → queue next modules
│
▼
TelemetryCollector.record_execution(...)
│
▼
CheckpointManager.save(...)
│
▼
BaseModule.report(result) → report fragment
Attack Chain (Goal-Based)
GoalEngine("domain_admin")
│
├── Phase 1: Recon
│ ad.enum_users → ad.enum_spn → ad.enum_computers
│
├── Phase 2: Credential Access
│ ad.kerberoast → credential.crack → vault.mark_cracked()
│ └── FALLBACK: ad.asreproast (AdaptiveAttackStrategy)
│
├── Phase 3: Lateral Movement
│ ArtifactCorrelationEngine finds opportunity
│ lateral.psexec → OperatorSession.mark_owned()
│ └── FALLBACK: lateral.wmiexec (if psexec blocked by EDR)
│
└── Phase 4: DA Escalation
ad.dcsync → vault.add() all domain hashes
Noise / OpSec Profiles
| Profile | Jitter | RPM | Description |
|---|---|---|---|
stealth |
3–15s (Pareto) | 10 | Evade EDR, only SILENT/LOW modules |
normal |
0.5–5s (triangular) | 30 | Balanced (default) |
aggressive |
0–300ms (uniform) | 200 | Speed over stealth |
HIGH_NOISE modules (psexec, dcsync) are automatically blocked in stealth profile.
Security Model
See security-model.md for full details.
Key properties:
- All credentials encrypted at rest (AES-256-GCM)
- All checkpoints encrypted at rest (AES-256-GCM)
- JWT for API authentication
- ScopeGuard prevents out-of-scope operations
- CampaignGuardrail requires operator confirmation for HIGH_RISK modules
- SandboxRunner isolates community modules in subprocess/Docker
- Module signatures required for marketplace plugins
- Audit log for all executions (structlog NDJSON)
Directory Structure
ARES/
├── ares/
│ ├── core/ Engine, context, errors, DI, config, security
│ ├── modules/ AD, Linux, Cloud, Reporting modules
│ ├── lateral/ Lateral movement (psexec/wmiexec/winrm/ssh/rdp)
│ ├── credential/ Vault, reuse engine, cracking pipeline
│ ├── goal/ Goal engine, adaptive attack strategy
│ ├── state/ OperatorSession, HostState, CompromiseLevel
│ ├── artifact_intel/ Rule engine, correlation engine
│ ├── normalize/ ArtifactStore and all artifact types
│ ├── network/ NetworkModel, pivot routing
│ ├── technique/ MITRE ATT&CK library, technique mapper
│ ├── pivot/ PivotManager, tunnel/port-forward management
│ ├── checkpoint/ Campaign pause/resume with encryption
│ ├── telemetry/ Metrics collection, Prometheus export
│ ├── fingerprint/ Environment fingerprinting (OS/EDR/AV)
│ ├── collab/ Multi-operator sessions and role management
│ ├── knowledge/ Attack KB, evidence store, guardrail, obfuscation
│ ├── worker/ Cluster controller, sandbox isolation
│ ├── replay/ Campaign replay (full/simulate/purple/timeline)
│ ├── graph/ Attack graph (NetworkX DiGraph)
│ ├── marketplace/ Plugin installer, signed registry
│ ├── service_intel/ Port scan + service fingerprint
│ ├── api/ FastAPI server + WebSocket dashboard
│ └── cli/ Click commands (campaign/module/report/target/chain)
├── docs/ Architecture, module SDK, API reference, security
├── tests/
│ ├── unit/ pytest unit tests (test_v5 through test_v9)
│ └── integration/ End-to-end campaign tests
└── docker/ Dockerfiles, docker/docker-compose.dev.yml, docker/docker-compose.prod.yml
C-LIVE-v1 coordinator boundary
ares.core.execution_admission is the sole first-party bridge from HTTP
authority and lifecycle admission to an in-process engine effect. It derives
submission, logical-execution, attempt, operation, fan-out, and retry-child UUIDs
with the lifecycle typed-length binding. The resulting dispatch capability is
process-local, nonserializable, bound to its coordinator/engine/store and work
identity, and single-use.
Public engine module/plan calls, SDK helpers, and the real subprocess stdin entrypoint fail closed without that seal. Production Strategy and Goal planning also fail closed while all production descriptors remain ineligible. The certified surface covers reachable first-party product entrypoints; dormant classes that can only be reached through arbitrary Python imports are not an activated worker path.