Skip to content

armgit / ARES

Public Imported from GitHub
0

ARES - authorized red-team engagement automation with dashboard, campaign scope, module orchestration, OPSEC controls, encrypted vault, and reporting.

docs: align architectural and engine design documentation with Kernel Scope Wall

Mafifrizi9667a4e18868
diff --git a/docs/README.md b/docs/README.md
index 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.md
index 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.md
index 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 check
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
▼
@@ -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 |