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
docs: align architectural and engine design documentation with Kernel Scope Wall
Mafifrizi9667a4e18868
diff --git a/docs/README.md b/docs/README.mdindex 9df7ea1..bb8f7e2 100644--- a/docs/README.md+++ b/docs/README.md@@ -70,7 +70,7 @@ ARES decouples policy enforcement, orchestration, data storage, and presentation+-------------------------------------------------------------------------+| ARES CORE ENGINE || AresEngine (orchestration) ExecutionPolicyKernel (gatekeeping) |-| OutcomeKnowledgeBase (learning) ScopeGuard (CIDR enforcement) |+| OutcomeKnowledgeBase (learning) ScopeFirewall (Kernel Egress Wall) |+-------------------------------------------------------------------------+| |+------------------------------+ +---------------------------------+@@ -114,6 +114,7 @@ ARES enforces security controls at the kernel level:- Live campaign streams authenticate using time-limited (30s) single-use tickets verified through atomic Compare-And-Swap (CAS) database transactions.- Tokens and API keys are never transmitted over WebSocket URLs or stored in browser storage.- **Scope and Opsec Boundaries**:+ - **Kernel Scope Wall & Egress Network Firewall**: Low-level transport socket interception (`socket.connect`, `socket.sendto`, `asyncio.create_connection`) drops out-of-scope connections fail-closed before packets reach the wire, with async ContextVar task isolation.- Every network action is strictly validated against user-defined CIDR scope boundaries. Out-of-scope executions are blocked immediately with hard exceptions.- Execution preview mode (`dry_run=True`) validates inputs and schema without dispatching any packets across the network.diff --git a/docs/architecture.md b/docs/architecture.mdindex 820d6e5..252d041 100644--- a/docs/architecture.md+++ b/docs/architecture.md@@ -85,6 +85,7 @@ ARES is **not** a C2 framework. It does not include implants, beacons, or persis| `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 |@@ -160,6 +161,7 @@ AresError│ ├── SandboxError (skip)│ └── WorkerCrashed (requeue)├── ScopeError (ABORT - never retry)+│ └── ScopeFirewallBlockError (ABORT - intercepted socket egress)├── OpsecError (pause/adjust profile)│ ├── DetectionSignal (escalate profile)│ └── HoneypotDetected (ABORT campaign)diff --git a/docs/engine_design.md b/docs/engine_design.mdindex e568721..6a3506c 100644--- a/docs/engine_design.md+++ b/docs/engine_design.md@@ -26,7 +26,8 @@ AresEngine├─ OperatorSession (attack state: hosts, creds, history)├─ CredentialVault (encrypted credential store)├─ TelemetryCollector (metrics, alerting)- └─ CampaignGuardrail (scope enforcement, safety gate)+ ├─ CampaignGuardrail (scope enforcement, safety gate)+ └─ ScopeFirewall (transport socket egress firewall)```---@@ -54,6 +55,9 @@ BaseModule.validate(ctx) ← parameter + context checkCampaignGuardrail.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▼@@ -128,6 +132,7 @@ Services registered by name:| `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 |