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.

fix(security): post-fed3098 security boundary proof, tier integrity, and docker egress hardening

Mafifrizid73d7fca3733
diff --git a/ares/core/sandbox.py b/ares/core/sandbox.py
index 49d8626..296d7ec 100644
--- a/ares/core/sandbox.py
+++ b/ares/core/sandbox.py
@@ -102,31 +102,42 @@ class SandboxPolicy:
docker_image: str = "python:3.11-slim"
docker_network: str = "bridge" # container network mode when allow_network=True
+ # Strict mode & tier integrity controls
+ strict_mode: bool = True # enforce fail-closed security invariants across all tiers
+ allow_tier_downgrade: bool = False # reject silent fallback from DOCKER to SUBPROCESS when Docker is unavailable
+ allow_unconfined_docker_binaries: bool = False # in strict mode, reject DOCKER allow_network=True unless explicitly allowed
+ sandbox_uid: int | None = None # dedicated sandbox UID for Linux parent firewall & child privilege drop
+
# Modules trusted to bypass sandboxing
trusted_prefixes: list[str] = field(default_factory=lambda: ["ares.core", "ares.db"])
@dataclass
class SandboxResult:
- module_id: str
- sandbox_tier: IsolationTier
- success: bool
- findings: list[dict[str, Any]] = field(default_factory=list)
- extra: dict[str, Any] = field(default_factory=dict)
- stdout: str = ""
- stderr: str = ""
- exit_code: int = 0
- cpu_time_s: float = 0.0
- wall_time_s: float = 0.0
- memory_peak_kb: int = 0
- error: str = ""
- sandbox_id: str = field(default_factory=lambda: str(uuid.uuid4())[:8])
+ module_id: str
+ sandbox_tier: IsolationTier
+ success: bool
+ findings: list[dict[str, Any]] = field(default_factory=list)
+ extra: dict[str, Any] = field(default_factory=dict)
+ stdout: str = ""
+ stderr: str = ""
+ exit_code: int = 0
+ cpu_time_s: float = 0.0
+ wall_time_s: float = 0.0
+ memory_peak_kb: int = 0
+ error: str = ""
+ sandbox_id: str = field(default_factory=lambda: str(uuid.uuid4())[:8])
+ requested_tier: IsolationTier = IsolationTier.SUBPROCESS
+ effective_tier: IsolationTier = IsolationTier.SUBPROCESS
+ downgraded: bool = False
+ downgrade_reason: str = ""
+ guarantees_lost: list[str] = field(default_factory=list)
class SandboxRunner:
"""
Executes ARES modules inside an isolation tier.
- Auto-falls-back to lower tier on unavailability.
+ In strict mode (allow_tier_downgrade=False), fails closed if the requested tier is unavailable.
"""
def __init__(self, policy: SandboxPolicy | None = None) -> None:
@@ -141,9 +152,10 @@ class SandboxRunner:
) -> SandboxResult:
"""
Run module_id with params inside the configured isolation tier.
- Falls back to SUBPROCESS if requested tier unavailable.
+ In strict mode (allow_tier_downgrade=False), fails closed if requested tier is unavailable.
"""
- effective_tier = tier or self.policy.tier
+ requested_tier = tier or self.policy.tier
+ effective_tier = requested_tier
t0 = time.monotonic()
# Core modules always run in-process
@@ -151,31 +163,43 @@ class SandboxRunner:
effective_tier = IsolationTier.NONE
audit("sandbox_run_start", actor="engine",
- module=module_id, tier=effective_tier.value, campaign=campaign_id)
+ module=module_id, requested_tier=requested_tier.value,
+ tier=effective_tier.value, campaign=campaign_id)
try:
if effective_tier == IsolationTier.NONE:
result = await self._run_inprocess(module_id, params, campaign_id)
elif effective_tier == IsolationTier.DOCKER:
- result = await self._run_docker(module_id, params, campaign_id)
+ result = await self._run_docker(
+ module_id, params, campaign_id, requested_tier=requested_tier
+ )
else:
# SUBPROCESS or SECCOMP (seccomp applied inside child)
result = await self._run_subprocess(
module_id, params, campaign_id,
use_seccomp=(effective_tier == IsolationTier.SECCOMP),
+ requested_tier=requested_tier,
)
except Exception as exc:
result = SandboxResult(
module_id=module_id, sandbox_tier=effective_tier,
+ requested_tier=requested_tier, effective_tier=effective_tier,
success=False, error=str(exc)[:500],
)
- result.wall_time_s = round(time.monotonic() - t0, 3)
- result.sandbox_tier = effective_tier
+ result.wall_time_s = round(time.monotonic() - t0, 3)
+ if not getattr(result, "requested_tier", None):
+ result.requested_tier = requested_tier
+ if not getattr(result, "effective_tier", None):
+ result.effective_tier = effective_tier
+ result.sandbox_tier = result.effective_tier
audit("sandbox_run_complete", actor="engine",
module=module_id, success=result.success,
- tier=effective_tier.value, wall_time_s=result.wall_time_s)
+ requested_tier=result.requested_tier.value,
+ effective_tier=result.effective_tier.value,
+ downgraded=result.downgraded,
+ tier=result.sandbox_tier.value, wall_time_s=result.wall_time_s)
return result
@@ -239,7 +263,11 @@ class SandboxRunner:
async with scope_firewall_guard(campaign=campaign, module_id=module_id):
findings, extra = await module.run(**params)
return SandboxResult(
- module_id=module_id, sandbox_tier=IsolationTier.NONE, success=True,
+ module_id=module_id,
+ sandbox_tier=IsolationTier.NONE,
+ requested_tier=IsolationTier.NONE,
+ effective_tier=IsolationTier.NONE,
+ success=True,
findings=[f.to_dict() if hasattr(f, "to_dict") else {} for f in findings],
extra=extra,
)
@@ -250,11 +278,13 @@ class SandboxRunner:
params: dict[str, Any],
campaign_id: str,
use_seccomp: bool = False,
+ requested_tier: IsolationTier = IsolationTier.SUBPROCESS,
) -> SandboxResult:
"""
Run module in isolated subprocess with resource limits.
Communicates via stdin/stdout JSON (same protocol as worker/isolation.py).
"""
+ sub_tier = IsolationTier.SECCOMP if use_seccomp else IsolationTier.SUBPROCESS
with tempfile.TemporaryDirectory(prefix="ares-sandbox-") as tmpdir:
# Pass real campaign scope so child process respects it
_scope_cidrs: list[str] = []
@@ -279,7 +309,9 @@ class SandboxRunner:
if OSFirewallController.is_elevated():
return SandboxResult(
module_id=module_id,
- sandbox_tier=IsolationTier.SUBPROCESS,
+ sandbox_tier=sub_tier,
+ requested_tier=requested_tier,
+ effective_tier=sub_tier,
success=False,
error="Privilege dropping (drop_privileges=True) is unsupported on Windows while running as Administrator; execution aborted to prevent unconfined privileged execution.",
)
@@ -307,11 +339,14 @@ class SandboxRunner:
# ensuring that the child is restricted by Netfilter the instant it drops privileges.
parent_uid_firewall = None
if os.name != "nt" and self.policy.drop_privileges and getattr(os, "geteuid", lambda: -1)() == 0:
- try:
- import pwd
- parent_uid_firewall = pwd.getpwnam("nobody").pw_uid
- except Exception:
- parent_uid_firewall = 65534
+ if self.policy.sandbox_uid is not None:
+ parent_uid_firewall = self.policy.sandbox_uid
+ else:
+ try:
+ import pwd
+ parent_uid_firewall = pwd.getpwnam("nobody").pw_uid
+ except Exception:
+ parent_uid_firewall = 65534
from ares.core.campaign import Campaign, NoiseProfile, ScopeEntry
from ares.core.scope_firewall import scope_firewall_guard
@@ -347,8 +382,12 @@ class SandboxRunner:
proc.kill()
await proc.wait()
return SandboxResult(
- module_id=module_id, sandbox_tier=IsolationTier.SUBPROCESS,
- success=False, error=f"Sandbox timeout ({self.policy.timeout_s}s)",
+ module_id=module_id,
+ sandbox_tier=sub_tier,
+ requested_tier=requested_tier,
+ effective_tier=sub_tier,
+ success=False,
+ error=f"Sandbox timeout ({self.policy.timeout_s}s)",
)
stdout = stdout_b.decode(errors="replace")
@@ -357,20 +396,27 @@ class SandboxRunner:
try:
data = json.loads(stdout)
return SandboxResult(
- module_id = module_id,
- sandbox_tier = IsolationTier.SUBPROCESS,
- success = data.get("success", False),
- findings = data.get("findings", []),
- extra = data.get("extra", {}),
- stdout = stdout[:2000],
- stderr = stderr[:500],
- exit_code = proc.returncode or 0,
+ module_id = module_id,
+ sandbox_tier = sub_tier,
+ requested_tier = requested_tier,
+ effective_tier = sub_tier,
+ success = data.get("success", False),
+ findings = data.get("findings", []),
+ extra = data.get("extra", {}),
+ stdout = stdout[:2000],
+ stderr = stderr[:500],
+ exit_code = proc.returncode or 0,
)
except json.JSONDecodeError:
return SandboxResult(
- module_id=module_id, sandbox_tier=IsolationTier.SUBPROCESS,
- success=False, error="Invalid JSON from sandbox",
- stdout=stdout[:500], stderr=stderr[:500],
+ module_id=module_id,
+ sandbox_tier=sub_tier,
+ requested_tier=requested_tier,
+ effective_tier=sub_tier,
+ success=False,
+ error="Invalid JSON from sandbox",
+ stdout=stdout[:500],
+ stderr=stderr[:500],
)
async def _run_docker(
@@ -378,16 +424,117 @@ class SandboxRunner:
module_id: str,
params: dict[str, Any],
campaign_id: str,
+ requested_tier: IsolationTier = IsolationTier.DOCKER,
) -> SandboxResult:
"""
Run module inside an ephemeral Docker container.
Requires Docker daemon on host.
"""
+ # 1. Strict mode online network limitation for external binaries
+ if self.policy.strict_mode and self.policy.allow_network:
+ if not self.policy.allow_unconfined_docker_binaries:
+ return SandboxResult(
+ module_id=module_id,
+ sandbox_tier=IsolationTier.DOCKER,
+ requested_tier=requested_tier,
+ effective_tier=IsolationTier.DOCKER,
+ success=False,
+ error=(
+ "Docker online mode cannot guarantee scope containment for external binaries inside the container. "
+ "In strict mode, use allow_network=False (network_mode='none') for kernel network namespace isolation, "
+ "or explicitly set allow_unconfined_docker_binaries=True."
+ ),
+ )
+
+ # 2. Check docker availability & client connection
try:
import docker # type: ignore[import-untyped]
except ImportError:
- logger.warning("docker_not_available_fallback_subprocess")
- return await self._run_subprocess(module_id, params, campaign_id)
+ docker = None
+
+ if docker is None:
+ if not self.policy.allow_tier_downgrade:
+ audit(
+ "sandbox_tier_downgrade_rejected",
+ actor="engine",
+ requested_tier=requested_tier.value,
+ reason="docker_package_not_installed",
+ )
+ return SandboxResult(
+ module_id=module_id,
+ sandbox_tier=IsolationTier.DOCKER,
+ requested_tier=requested_tier,
+ effective_tier=IsolationTier.DOCKER,
+ success=False,
+ error="Security tier downgrade from DOCKER to SUBPROCESS rejected (allow_tier_downgrade=False): 'docker' package not installed.",
+ )
+ lost_guarantees = [
+ "read_only_rootfs_mount_namespace",
+ "container_cgroups",
+ "network_namespace_isolation",
+ ]
+ audit(
+ "sandbox_tier_downgrade",
+ actor="engine",
+ requested_tier=requested_tier.value,
+ effective_tier=IsolationTier.SUBPROCESS.value,
+ reason="docker_package_not_installed",
+ guarantees_lost=lost_guarantees,
+ )
+ sub_res = await self._run_subprocess(
+ module_id, params, campaign_id, requested_tier=requested_tier
+ )
+ sub_res.requested_tier = requested_tier
+ sub_res.effective_tier = IsolationTier.SUBPROCESS
+ sub_res.sandbox_tier = IsolationTier.SUBPROCESS
+ sub_res.downgraded = True
+ sub_res.downgrade_reason = "docker_package_not_installed"
+ sub_res.guarantees_lost = lost_guarantees
+ return sub_res
+
+ try:
+ client = docker.from_env()
+ if hasattr(client, "ping"):
+ client.ping()
+ except Exception as exc:
+ if not self.policy.allow_tier_downgrade:
+ audit(
+ "sandbox_tier_downgrade_rejected",
+ actor="engine",
+ requested_tier=requested_tier.value,
+ reason=f"docker_daemon_unavailable: {exc}",
+ )
+ return SandboxResult(
+ module_id=module_id,
+ sandbox_tier=IsolationTier.DOCKER,
+ requested_tier=requested_tier,
+ effective_tier=IsolationTier.DOCKER,
+ success=False,
+ error=f"Security tier downgrade from DOCKER to SUBPROCESS rejected (allow_tier_downgrade=False): Docker daemon unavailable ({exc}).",
+ )
+ lost_guarantees = [
+ "read_only_rootfs_mount_namespace",
+ "container_cgroups",
+ "network_namespace_isolation",
+ ]
+ audit(
+ "sandbox_tier_downgrade",
+ actor="engine",
+ requested_tier=requested_tier.value,
+ effective_tier=IsolationTier.SUBPROCESS.value,
+ reason=f"docker_daemon_unavailable: {exc}",
+ guarantees_lost=lost_guarantees,
+ )
+ sub_res = await self._run_subprocess(
+ module_id, params, campaign_id, requested_tier=requested_tier
+ )
+ sub_res.requested_tier = requested_tier
+ sub_res.effective_tier = IsolationTier.SUBPROCESS
+ sub_res.sandbox_tier = IsolationTier.SUBPROCESS
+ sub_res.downgraded = True
+ sub_res.downgrade_reason = f"docker_daemon_unavailable: {exc}"
+ sub_res.guarantees_lost = lost_guarantees
+ return sub_res
# Fetch real scope for Docker container (same as subprocess)
_docker_scope: list[str] = []
@@ -419,7 +566,6 @@ class SandboxRunner:
read_only = not self.policy.allow_write
mem_limit = f"{self.policy.memory_mb}m"
- client = docker.from_env()
try:
container = client.containers.run(
image,
@@ -439,15 +585,22 @@ class SandboxRunner:
output = container.decode() if isinstance(container, bytes) else str(container)
data = json.loads(output)
return SandboxResult(
- module_id=module_id, sandbox_tier=IsolationTier.DOCKER,
+ module_id=module_id,
+ sandbox_tier=IsolationTier.DOCKER,
+ requested_tier=requested_tier,
+ effective_tier=IsolationTier.DOCKER,
success=data.get("success", False),
findings=data.get("findings", []),
extra=data.get("extra", {}),
)
except Exception as exc:
return SandboxResult(
- module_id=module_id, sandbox_tier=IsolationTier.DOCKER,
- success=False, error=str(exc)[:300],
+ module_id=module_id,
+ sandbox_tier=IsolationTier.DOCKER,
+ requested_tier=requested_tier,
+ effective_tier=IsolationTier.DOCKER,
+ success=False,
+ error=str(exc)[:300],
)
# ── Helpers ────────────────────────────────────────────────────────────
@@ -463,6 +616,7 @@ class SandboxRunner:
allow_network = self.policy.allow_network
drop_privileges = self.policy.drop_privileges
allow_write = self.policy.allow_write
+ target_uid = self.policy.sandbox_uid
def _limits():
# 1. Best-effort resource limits
@@ -499,14 +653,21 @@ class SandboxRunner:
# 3. MANDATORY SECURITY CONTROL: Privilege dropping (fail-closed)
if drop_privileges and getattr(os, "geteuid", lambda: -1)() == 0:
try:
- import pwd
- nobody = pwd.getpwnam("nobody")
+ if target_uid is not None:
+ drop_uid = target_uid
+ drop_gid = target_uid
+ else:
+ import pwd
+ nobody = pwd.getpwnam("nobody")
+ drop_uid = nobody.pw_uid
+ drop_gid = nobody.pw_gid
os.setgroups([])
- os.setgid(nobody.pw_gid)
- os.setuid(nobody.pw_uid)
+ os.setgid(drop_gid)
+ os.setuid(drop_uid)
except Exception as exc:
+ target_label = "nobody" if target_uid is None else str(target_uid)
raise RuntimeError(
- f"Mandatory security control failed: drop_privileges=True failed to drop root to nobody: {exc}"
+ f"Mandatory security control failed: drop_privileges=True failed to drop root to {target_label}: {exc}"
)
if getattr(os, "geteuid", lambda: -1)() == 0 or getattr(os, "getuid", lambda: -1)() == 0:
raise RuntimeError(
@@ -568,13 +729,13 @@ class SandboxRunner:
" import builtins\n"
" def _is_contained_in_sandbox(target_path, sandbox_dir):\n"
" try:\n"
- " real_sandbox = os.path.realpath(sandbox_dir)\n"
+ " real_sandbox = os.path.normcase(os.path.realpath(sandbox_dir))\n"
" target_str = str(target_path)\n"
" if not os.path.exists(target_str):\n"
" parent = os.path.dirname(target_str) or \".\"\n"
- " real_target = os.path.join(os.path.realpath(parent), os.path.basename(target_str))\n"
+ " real_target = os.path.normcase(os.path.join(os.path.realpath(parent), os.path.basename(target_str)))\n"
" else:\n"
- " real_target = os.path.realpath(target_str)\n"
+ " real_target = os.path.normcase(os.path.realpath(target_str))\n"
" return os.path.commonpath([real_sandbox, real_target]) == real_sandbox\n"
" except (ValueError, OSError, TypeError):\n"
" return False\n"
diff --git a/ares/core/scope_firewall.py b/ares/core/scope_firewall.py
index 5d4de13..76cdd5d 100644
--- a/ares/core/scope_firewall.py
+++ b/ares/core/scope_firewall.py
@@ -880,13 +880,16 @@ class OSFirewallController:
except Exception:
failed_rollbacks.append(cleanup_cmd)
with cls._lock:
- cls._state = OSFirewallState.VERIFICATION_FAILED
if failed_rollbacks:
cls._rule_cleanups[rule_name] = failed_rollbacks
cls._active_rules.add(rule_name)
cls._state = OSFirewallState.CLEANUP_PENDING
else:
- cls._state = OSFirewallState.INACTIVE if not cls._active_rules else OSFirewallState.VERIFIED_ACTIVE
+ cls._state = (
+ OSFirewallState.VERIFICATION_FAILED
+ if not cls._active_rules
+ else OSFirewallState.VERIFIED_ACTIVE
+ )
if os.environ.get("ARES_REQUIRE_OS_FIREWALL") == "1":
raise ScopeFirewallBlockError(
f"[ScopeFirewall] OS firewall verification failed for {rule_name}; rolled back."
@@ -989,6 +992,10 @@ class OSFirewallController:
rules_to_clean = list(cls._active_rules)
if rules_to_clean:
cls.remove_rules(rules_to_clean)
+ else:
+ with cls._lock:
+ if cls._state != OSFirewallState.CLEANUP_PENDING:
+ cls._state = OSFirewallState.INACTIVE
atexit.register(OSFirewallController.cleanup_all)
diff --git a/docs/security-model.md b/docs/security-model.md
index 6b352b5..65414f9 100644
--- a/docs/security-model.md
+++ b/docs/security-model.md
@@ -67,36 +67,76 @@ stored sensitive records.
---
-## Module Isolation (SandboxRunner)
+## Module Isolation & Security Boundaries (SandboxRunner)
-> The tiers below are a legacy target design and are not an active C-LIVE-v1
-> dispatch path. Production descriptors remain ineligible; authenticated worker
-> IPC or a serializable capability requires separate approval.
+ARES enforces defensive execution boundaries across four isolation tiers (`NONE`, `SUBPROCESS`, `SECCOMP`, `DOCKER`).
-### Isolation tiers
+### Isolation Tiers & Guarantees
-| Tier | Mechanism | Used for |
-|------|-----------|---------|
-| `NONE` | In-process | Core modules (trusted) |
-| `SUBPROCESS` | Separate process + `resource.setrlimit` | Default for all modules |
-| `SECCOMP` | Subprocess + seccomp syscall filter | High-risk community modules |
-| `DOCKER` | Ephemeral container, `--rm` | Maximum isolation |
+| Tier | Enforcement Mechanism | Filesystem Boundary | Network Egress Boundary | Privilege Containment |
+|------|----------------------|---------------------|------------------------|----------------------|
+| `NONE` | In-process | Unconfined | Python `scope_firewall_guard` | Unconfined |
+| `SUBPROCESS` | Ephemeral subprocess | Working directory lock; Unix `RLIMIT_FSIZE=(0,0)`; defense-in-depth Python open/os.open hooks | `allow_network=False`: Linux `unshare(CLONE_NEWNET)` fail-closed; `allow_network=True`: parent `--uid-owner` Netfilter rules + Python socket interceptor | Linux: Root dropped to `nobody` or `sandbox_uid` fail-closed; Windows: Aborts if Administrator |
+| `SECCOMP` | Subprocess + BPF syscall filter | Same as SUBPROCESS + BPF syscall allowlist filter | Same as SUBPROCESS | `PR_SET_NO_NEW_PRIVS` + BPF allowlist |
+| `DOCKER` | Ephemeral container | Read-only container rootfs (`read_only=True`) | `allow_network=False`: `network_mode="none"`; `allow_network=True`: `bridge` (requires `allow_unconfined_docker_binaries=True` in strict mode) | Complete container namespace & cgroups isolation |
-### Resource limits (SUBPROCESS tier)
+---
-```python
-resource.setrlimit(RLIMIT_CPU, (30, 30)) # 30 CPU seconds
-resource.setrlimit(RLIMIT_AS, (256MB, 256MB)) # 256 MB virtual memory
-resource.setrlimit(RLIMIT_NPROC, (64, 64)) # 64 child processes
-resource.setrlimit(RLIMIT_NOFILE,(256, 256)) # 256 open file descriptors
-```
+### Non-Negotiable Architectural Truths & Operational Boundaries
+
+To eliminate documentation/implementation mismatch and anti-hype over-claiming:
+
+1. **Python Socket Interception ≠ OS Kernel Egress Enforcement**:
+ - Python stdlib hooks (`socket.connect`, `socket.sendto`, `asyncio.create_connection`) intercept traffic generated by standard Python network libraries.
+ - They **do not** intercept external binaries, compiled extensions issuing direct kernel syscalls, or subprocesses spawned without explicit firewall inheritance.
+ - True OS/kernel-level egress filtering requires `OSFirewallController` (`netsh advfirewall` on Windows or `iptables` on Linux) running with administrative/root privileges.
+
+2. **Docker Bridge Isolation ≠ Scope-Restricted Network Egress for External Binaries**:
+ - Inside a Docker container running on `docker_network="bridge"`, Python socket hooks intercept Python sockets only. Any external binary executed inside the container (e.g. `curl`, `nmap`, `nc`, or spawned scripts) communicates directly with the container's network namespace via host NAT egress.
+ - **Enforcement Policy**: In strict mode (`strict_mode=True`), requesting `IsolationTier.DOCKER` with `allow_network=True` is **rejected fail-closed** unless the caller explicitly configures `allow_unconfined_docker_binaries=True`. For strict scoped execution without unconfined external binaries, `allow_network=False` (`network_mode="none"`) provides complete kernel network namespace isolation.
+
+3. **UID-Based Firewall ≠ Process-Tree Isolation**:
+ - Linux Netfilter `-m owner --uid-owner <uid>` filters egress host-wide for **all** processes running under that UID.
+ - If multiple concurrent sandboxes run under the shared system account `nobody` (UID 65534), rules applied to one execution impose collateral scope filtering on other processes sharing that UID on the host.
+ - `SandboxPolicy` supports `sandbox_uid: int | None = None` to assign a dedicated sandbox identity per execution.
-### What sandboxed modules cannot do
+4. **Read-Only Rootfs (`read_only=True`) ≠ All Possible Writable Volumes**:
+ - Docker's `read_only=True` parameter mounts the container root filesystem as read-only.
+ - However, if the base image contains `VOLUME` declarations in its Dockerfile (e.g. `/tmp` or `/var/log`), Docker automatically mounts anonymous read-write volumes at those locations unless explicitly masked or overridden. The default image `python:3.11-slim` contains no `VOLUME` instructions.
+
+5. **Mock Command Verification ≠ Actual Kernel Runtime Verification**:
+ - Unit tests executing with mocked `subprocess.run` verify command construction, argument parsing, error handling, and state machine transitions.
+ - They **do not** prove physical packet filtering by the Linux Netfilter subsystem or Windows Defender Firewall. Real kernel filtering requires elevated execution on a live kernel.
+
+---
+
+### Strict Security Mode & Tier Integrity Policy
+
+To prevent silent security degradation:
+- **`allow_tier_downgrade: bool = False` (Default)**: If `IsolationTier.DOCKER` is requested and Docker is unavailable (missing library or daemon unreachable), execution **aborts fail-closed**. Silent fallback to `SUBPROCESS` is prohibited.
+- **Auditable Downgrade**: If `allow_tier_downgrade=True` is explicitly configured:
+ - `SandboxResult.requested_tier` reports `IsolationTier.DOCKER`.
+ - `SandboxResult.effective_tier` reports `IsolationTier.SUBPROCESS`.
+ - `SandboxResult.downgraded` is `True`.
+ - `SandboxResult.downgrade_reason` records the failure reason.
+ - `SandboxResult.guarantees_lost` explicitly records lost protections:
+ `["read_only_rootfs_mount_namespace", "container_cgroups", "network_namespace_isolation"]`.
+ - An audit event `sandbox_tier_downgrade` is recorded in the security audit log.
+
+---
-- Access core ARES engine state directly (communication via JSON stdin/stdout)
-- Exceed CPU/memory limits without being killed
-- Open more than 256 file descriptors
-- On SECCOMP tier: call any syscall not in the allow-list
+### Security Boundary Verification Matrix
+
+| Component | Unit Test | Integration Test | Actual Runtime Verified | Exact Limitation |
+|---|---|---|---|---|
+| **Python Transport Socket Interceptor** | `VERIFIED` (`test_scope_firewall.py`) | `VERIFIED` (Local TCP client/server fixture) | `VERIFIED` | Intercepts Python stdlib sockets only; bypassable by C extensions issuing direct raw syscalls. |
+| **Linux OS Netfilter Firewall (`--uid-owner`)** | `VERIFIED` (`test_hardening.py` CLI & state machine mocks) | `PARTIALLY VERIFIED` (Parent-managed child lifecycle fixture) | `NOT VERIFIED` (Requires root/`CAP_NET_ADMIN` in live kernel) | UID-wide filtering; collateral scope affects other processes sharing the same UID. |
+| **Windows Defender Firewall (`program=<exe>`)** | `VERIFIED` (`test_scope_firewall.py` netsh rule generation) | `PARTIALLY VERIFIED` (show/add/delete rule mocked) | `NOT VERIFIED` (Requires elevated Administrator console) | Scoped to `program=<sys.executable>`. External binaries (e.g. `curl.exe`) are not filtered. |
+| **Docker Offline (`network_mode="none"`)** | `VERIFIED` (`test_sandbox_policy_enforcement_docker_options`) | `PARTIALLY VERIFIED` (Docker client mocked) | `VERIFIED` (When Docker daemon is active) | Complete network isolation; zero outbound or inbound traffic permitted. |
+| **Docker Online (`docker_network="bridge"`)** | `VERIFIED` (`test_docker_online_external_binary_cannot_escape_scope`) | `PARTIALLY VERIFIED` | `UNSUPPORTED` (Kernel-level external binary filtering in bridge mode) | External binaries inside container can reach out-of-scope destinations; rejected in strict mode. |
+| **Subprocess Network Namespace (`CLONE_NEWNET`)** | `VERIFIED` (`test_subprocess_network_isolation_fails_closed`) | `PARTIALLY VERIFIED` (Linux libc unshare mock) | `NOT VERIFIED` (Requires Linux kernel with user namespace or root) | Linux-only; unsupported on Windows. Child aborts fail-closed if unshare fails. |
+| **Subprocess Privilege Dropping (`nobody`)** | `VERIFIED` (`test_subprocess_drop_privileges_fails_closed`) | `PARTIALLY VERIFIED` (POSIX setuid/setgid mock) | `NOT VERIFIED` (Requires initial root EUID 0) | POSIX-only; unsupported on Windows while elevated (aborts execution). |
+| **Sandbox Path Containment (Python hooks)** | `VERIFIED` (`test_canonical_path_containment_edge_cases`) | `VERIFIED` (Tempfile directory harness) | `VERIFIED` | Application-level defense-in-depth; does not provide OS mount namespace isolation. |
---
diff --git a/tests/unit/test_hardening.py b/tests/unit/test_hardening.py
index 0619cc5..48d6745 100644
--- a/tests/unit/test_hardening.py
+++ b/tests/unit/test_hardening.py
@@ -1526,6 +1526,8 @@ class TestSecurityBoundariesAndLifecycle:
assert len(cleanups_run) > 0, "Rollback cleanups must run when verification fails"
assert len(OSFirewallController._active_rules) == 0
+ assert OSFirewallController._state == OSFirewallState.VERIFICATION_FAILED
+ OSFirewallController.cleanup_all()
assert OSFirewallController._state == OSFirewallState.INACTIVE
def test_os_firewall_cleanup_failure_retains_rule_state_and_sets_cleanup_pending(self, monkeypatch):
@@ -1678,6 +1680,619 @@ class TestSecurityBoundariesAndLifecycle:
assert parent_guard_calls[0]["uid_owner"] in (65534, getattr(monkeypatch, "fake_uid", 65534))
+# ═══════════════════════════════════════════════════════════════════════════════
+# POST-fed3098 ADVERSARIAL SECURITY PROOF: TIER INTEGRITY & DOCKER EGRESS
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class TestPostFed3098SecurityBoundaryProof:
+ """
+ Exhaustive proof suite verifying:
+ 1. Docker online mode external binary containment & strict mode rejection
+ 2. Strict mode tier integrity: zero silent downgrades from DOCKER to SUBPROCESS
+ 3. Explicit tier downgrade audit logging and guarantees lost
+ 4. Firewall verification failure injection (missing rules, mismatch, timeout)
+ 5. Cleanup retry retention and CLEANUP_PENDING degraded state recovery
+ 6. Dedicated UID semantics and collateral scope containment
+ 7. Canonical path containment edge cases (normcase, symlinks, traversal)
+ 8. Controlled local TCP integration fixture for descendant egress
+ 9. Custom Docker volume write policy and read-only isolation
+ """
+
+ def test_docker_online_external_binary_cannot_escape_scope(self):
+ """
+ Criterion 2: External binaries inside Docker bridge network cannot be
+ guaranteed by Python socket hooks. In strict mode, allow_network=True
+ must be rejected unless caller explicitly allows unconfined binaries.
+ """
+ from ares.core.sandbox import SandboxRunner, SandboxPolicy, IsolationTier
+ import asyncio
+
+ # Strict mode + allow_network=True + allow_unconfined_docker_binaries=False
+ policy = SandboxPolicy(
+ tier=IsolationTier.DOCKER,
+ allow_network=True,
+ strict_mode=True,
+ allow_unconfined_docker_binaries=False,
+ )
+ runner = SandboxRunner(policy=policy)
+
+ result = asyncio.run(runner.run_module("test.module", {}, "camp-123"))
+ assert result.success is False
+ assert result.requested_tier == IsolationTier.DOCKER
+ assert result.effective_tier == IsolationTier.DOCKER
+ assert "Docker online mode cannot guarantee scope containment" in result.error
+ assert "allow_unconfined_docker_binaries=True" in result.error
+
+ def test_docker_offline_mode_allowed_in_strict_mode(self, monkeypatch):
+ """
+ Criterion 2 (Model B): When allow_network=False, Docker container is launched
+ with network_mode="none", guaranteeing complete kernel network namespace isolation.
+ """
+ from ares.core.sandbox import SandboxRunner, SandboxPolicy, IsolationTier
+ import asyncio
+
+ policy = SandboxPolicy(
+ tier=IsolationTier.DOCKER,
+ allow_network=False,
+ strict_mode=True,
+ )
+ runner = SandboxRunner(policy=policy)
+
+ mock_docker = MagicMock()
+ mock_client = MagicMock()
+ mock_docker.from_env.return_value = mock_client
+ mock_client.containers.run.return_value = b'{"success": true, "findings": [], "extra": {}}'
+ monkeypatch.setattr("sys.modules", {**sys.modules, "docker": mock_docker})
+
+ result = asyncio.run(runner.run_module("test.module", {}, "camp-123"))
+ assert result.success is True
+ assert result.effective_tier == IsolationTier.DOCKER
+ _, run_kwargs = mock_client.containers.run.call_args
+ assert run_kwargs.get("network_mode") == "none"
+
+ def test_docker_unavailable_does_not_silently_downgrade_in_strict_mode(self, monkeypatch):
+ """
+ Criterion 3: When Docker is unavailable and allow_tier_downgrade=False (default),
+ SandboxRunner MUST abort fail-closed rather than silently downgrading to SUBPROCESS.
+ """
+ from ares.core.sandbox import SandboxRunner, SandboxPolicy, IsolationTier
+ import asyncio
+
+ policy = SandboxPolicy(
+ tier=IsolationTier.DOCKER,
+ allow_tier_downgrade=False,
+ strict_mode=True,
+ allow_network=False,
+ )
+ runner = SandboxRunner(policy=policy)
+
+ # Force docker import to fail
+ monkeypatch.setitem(sys.modules, "docker", None)
+
+ result = asyncio.run(runner.run_module("test.module", {}, "camp-123"))
+ assert result.success is False
+ assert result.requested_tier == IsolationTier.DOCKER
+ assert result.effective_tier == IsolationTier.DOCKER
+ assert result.downgraded is False
+ assert "Security tier downgrade from DOCKER to SUBPROCESS rejected" in result.error
+
+ def test_docker_downgrade_allowed_when_policy_permits_with_audit_trail(self, monkeypatch):
+ """
+ Criterion 3: When allow_tier_downgrade=True, downgrade is permitted, but
+ effective tier, downgrade reason, and lost guarantees are explicitly reported.
+ """
+ from ares.core.sandbox import SandboxRunner, SandboxPolicy, IsolationTier
+ import asyncio
+
+ policy = SandboxPolicy(
+ tier=IsolationTier.DOCKER,
+ allow_tier_downgrade=True,
+ strict_mode=True,
+ allow_network=False,
+ )
+ runner = SandboxRunner(policy=policy)
+
+ # Force docker import to fail
+ monkeypatch.setitem(sys.modules, "docker", None)
+
+ # Mock _run_subprocess
+ mock_sub_res = MagicMock()
+ mock_sub_res.success = True
+ mock_sub_res.findings = []
+ mock_sub_res.extra = {}
+ mock_sub_res.requested_tier = IsolationTier.SUBPROCESS
+ mock_sub_res.effective_tier = IsolationTier.SUBPROCESS
+ mock_sub_res.sandbox_tier = IsolationTier.SUBPROCESS
+ mock_sub_res.downgraded = False
+ mock_sub_res.downgrade_reason = ""
+ mock_sub_res.guarantees_lost = []
+ mock_sub_res.wall_time_s = 0.05
+
+ async def mock_run_subprocess(*args, **kwargs):
+ return mock_sub_res
+
+ monkeypatch.setattr(runner, "_run_subprocess", mock_run_subprocess)
+
+ result = asyncio.run(runner.run_module("test.module", {}, "camp-123"))
+ assert result.success is True
+ assert result.requested_tier == IsolationTier.DOCKER
+ assert result.effective_tier == IsolationTier.SUBPROCESS
+ assert result.downgraded is True
+ assert result.downgrade_reason == "docker_package_not_installed"
+ assert "read_only_rootfs_mount_namespace" in result.guarantees_lost
+ assert "network_namespace_isolation" in result.guarantees_lost
+
+ def test_firewall_kernel_verification_failure_injection(self, monkeypatch):
+ """
+ Criterion 6 & 7: Verify failure injection for:
+ - rule missing after apply
+ - rule changed / wrong specification
+ - verification timeout
+ All cases must rollback and transition to VERIFICATION_FAILED.
+ """
+ from ares.core.campaign import Campaign, ScopeEntry
+ from ares.core.scope_firewall import OSFirewallController, OSFirewallState
+ import subprocess
+
+ campaign = Campaign(name="test-fail-injection", scope=[ScopeEntry(cidr="10.0.0.0/8")])
+ monkeypatch.setattr(OSFirewallController, "is_elevated", classmethod(lambda cls: True))
+ monkeypatch.setattr("sys.platform", "linux")
+
+ def mock_apply_ok(cmd, *args, **kwargs):
+ res = MagicMock()
+ res.returncode = 0
+ return res
+
+ monkeypatch.setattr("subprocess.run", mock_apply_ok)
+
+ # Case 1: Missing / changed rule verification failure
+ subrules_case1 = [
+ (["iptables", "-I", "OUTPUT", "1", "-m", "owner", "--uid-owner", "65534", "-j", "DROP"], ["iptables", "-D", "OUTPUT"])
+ ]
+ def mock_verify_check_fail(cmd, *args, **kwargs):
+ res = MagicMock()
+ res.returncode = 1 # rule check failed
+ res.stderr = "iptables: Bad rule (does a matching rule exist in that chain?)"
+ return res
+
+ monkeypatch.setattr("subprocess.run", mock_verify_check_fail)
+ verified = OSFirewallController._verify_subrules(subrules_case1)
+ assert verified is False, "Missing subrule must fail verification"
+
+ # Case 2: Verification command timeout
+ def mock_verify_timeout(cmd, *args, **kwargs):
+ raise subprocess.TimeoutExpired(cmd=cmd, timeout=5)
+
+ monkeypatch.setattr("subprocess.run", mock_verify_timeout)
+ verified_timeout = OSFirewallController._verify_subrules(subrules_case1)
+ assert verified_timeout is False, "Verification timeout must fail-closed"
+
+ # Case 3: Invariant: apply_rules with verification failure rolls back and sets VERIFICATION_FAILED
+ monkeypatch.setattr("subprocess.run", mock_apply_ok)
+ monkeypatch.setattr(OSFirewallController, "_verify_subrules", classmethod(lambda cls, sub_rules: False))
+
+ OSFirewallController._active_rules.clear()
+ rules = OSFirewallController.apply_rules(campaign, ["10.0.0.0/8"])
+ assert len(rules) == 0
+ assert OSFirewallController._state == OSFirewallState.VERIFICATION_FAILED
+ OSFirewallController.cleanup_all()
+ assert OSFirewallController._state == OSFirewallState.INACTIVE
+
+ def test_firewall_kernel_verification_failure(self, monkeypatch):
+ """
+ Criterion 6 & 16: Failure injection for OS firewall verification.
+ If CLI rule insertion command succeeds, but OS/kernel state check fails:
+ 1. Controller MUST NOT enter VERIFIED_ACTIVE.
+ 2. Rollback cleanup commands MUST be executed.
+ 3. State transitions through VERIFICATION_FAILED.
+ 4. When ARES_REQUIRE_OS_FIREWALL=1, ScopeFirewallBlockError is raised fail-closed.
+ """
+ from ares.core.campaign import Campaign, ScopeEntry
+ from ares.core.scope_firewall import OSFirewallController, OSFirewallState, ScopeFirewallBlockError
+
+ campaign = Campaign(name="test-fail-kernel-verif", scope=[ScopeEntry(cidr="10.0.0.0/8")])
+ monkeypatch.setattr(OSFirewallController, "is_elevated", classmethod(lambda cls: True))
+ monkeypatch.setattr("sys.platform", "linux")
+ monkeypatch.setenv("ARES_REQUIRE_OS_FIREWALL", "1")
+
+ cleanups_run = []
+ def mock_apply_ok(cmd, *args, **kwargs):
+ if "-D" in cmd:
+ cleanups_run.append(cmd)
+ res = MagicMock()
+ res.returncode = 0
+ return res
+
+ monkeypatch.setattr("subprocess.run", mock_apply_ok)
+ # Mock _verify_subrules returning False (kernel check failed)
+ monkeypatch.setattr(OSFirewallController, "_verify_subrules", classmethod(lambda cls, sub_rules: False))
+
+ OSFirewallController._active_rules.clear()
+ with pytest.raises(ScopeFirewallBlockError, match="OS firewall verification failed"):
+ OSFirewallController.apply_rules(campaign, ["10.0.0.0/8"])
+
+ assert len(cleanups_run) > 0, "Rollback cleanups must run when verification fails"
+ assert len(OSFirewallController._active_rules) == 0
+ assert OSFirewallController._state == OSFirewallState.VERIFICATION_FAILED
+ OSFirewallController.cleanup_all()
+ assert OSFirewallController._state == OSFirewallState.INACTIVE
+
+ def test_firewall_cleanup_retry(self, monkeypatch):
+ """
+ Criterion 8 & 16: Resilient cleanup retry.
+ When initial rule removal command fails:
+ 1. Rule is retained in _active_rules and failed cleanups in _rule_cleanups.
+ 2. State transitions to CLEANUP_PENDING.
+ 3. Subsequent retry of remove_rules or cleanup_all successfully removes the rule
+ and transitions state to INACTIVE.
+ 4. Attempting to remove an unrelated non-existent rule does not affect active rules.
+ """
+ from ares.core.campaign import Campaign, ScopeEntry
+ from ares.core.scope_firewall import OSFirewallController, OSFirewallState
+
+ campaign = Campaign(name="test-cleanup-retry-standalone", scope=[ScopeEntry(cidr="10.0.0.0/8")])
+ monkeypatch.setattr(OSFirewallController, "is_elevated", classmethod(lambda cls: True))
+ monkeypatch.setattr("sys.platform", "linux")
+
+ def mock_ok(cmd, *args, **kwargs):
+ res = MagicMock()
+ res.returncode = 0
+ return res
+
+ monkeypatch.setattr("subprocess.run", mock_ok)
+ monkeypatch.setattr(OSFirewallController, "_verify_subrules", classmethod(lambda cls, sub_rules: True))
+
+ OSFirewallController._active_rules.clear()
+ rules = OSFirewallController.apply_rules(campaign, ["10.0.0.0/8"])
+ assert len(rules) == 1
+ rule_name = rules[0]
+ assert OSFirewallController._state == OSFirewallState.VERIFIED_ACTIVE
+
+ # Simulate cleanup failure
+ def mock_fail(cmd, *args, **kwargs):
+ res = MagicMock()
+ res.returncode = 1
+ res.stderr = "iptables: Resource temporarily unavailable"
+ return res
+
+ monkeypatch.setattr("subprocess.run", mock_fail)
+ removed = OSFirewallController.remove_rules(rules)
+ assert removed == 0
+ assert OSFirewallController._state == OSFirewallState.CLEANUP_PENDING
+ assert rule_name in OSFirewallController._active_rules
+
+ # Removing an unrelated rule name does not touch active rules
+ removed_unrelated = OSFirewallController.remove_rules(["non_existent_rule_xyz"])
+ assert removed_unrelated == 0
+ assert rule_name in OSFirewallController._active_rules
+
+ # Retry cleanup with success
+ monkeypatch.setattr("subprocess.run", mock_ok)
+ removed_retry = OSFirewallController.remove_rules([rule_name])
+ assert removed_retry > 0
+ assert rule_name not in OSFirewallController._active_rules
+ assert OSFirewallController._state == OSFirewallState.INACTIVE
+
+ def test_firewall_cleanup_pending_state(self, monkeypatch):
+ """
+ Criterion 7 & 16: Invariant that failed cleanup leaves controller in CLEANUP_PENDING
+ and never falsely reports INACTIVE while uncleaned rules persist.
+ """
+ from ares.core.campaign import Campaign, ScopeEntry
+ from ares.core.scope_firewall import OSFirewallController, OSFirewallState
+
+ campaign = Campaign(name="test-pending-state", scope=[ScopeEntry(cidr="10.0.0.0/8")])
+ monkeypatch.setattr(OSFirewallController, "is_elevated", classmethod(lambda cls: True))
+ monkeypatch.setattr("sys.platform", "linux")
+
+ def mock_ok(cmd, *args, **kwargs):
+ res = MagicMock()
+ res.returncode = 0
+ return res
+
+ monkeypatch.setattr("subprocess.run", mock_ok)
+ monkeypatch.setattr(OSFirewallController, "_verify_subrules", classmethod(lambda cls, sub_rules: True))
+
+ OSFirewallController._active_rules.clear()
+ rules = OSFirewallController.apply_rules(campaign, ["10.0.0.0/8"])
+ rule_name = rules[0]
+ assert OSFirewallController._state == OSFirewallState.VERIFIED_ACTIVE
+
+ # Fail cleanup
+ def mock_fail(cmd, *args, **kwargs):
+ res = MagicMock()
+ res.returncode = 1
+ return res
+
+ monkeypatch.setattr("subprocess.run", mock_fail)
+ OSFirewallController.remove_rules(rules)
+ assert OSFirewallController._state == OSFirewallState.CLEANUP_PENDING
+ assert OSFirewallController.get_status()["cleanup_pending"] is True
+ assert OSFirewallController.get_status()["state"] == "CLEANUP_PENDING"
+ assert OSFirewallController._state != OSFirewallState.INACTIVE
+
+ # Clean all with success restores INACTIVE
+ monkeypatch.setattr("subprocess.run", mock_ok)
+ OSFirewallController.cleanup_all()
+ assert OSFirewallController._state == OSFirewallState.INACTIVE
+ assert OSFirewallController.get_status()["cleanup_pending"] is False
+
+ def test_verified_active_requires_real_verification(self, monkeypatch):
+ """
+ Criterion 6, 7 & 16: VERIFIED_ACTIVE invariant.
+ Rule insertion returncode == 0 is INSUFFICIENT to enter VERIFIED_ACTIVE.
+ Only a successful query of OS state via _verify_subrules() confirms VERIFIED_ACTIVE.
+ If _verify_subrules returns False, state is NEVER VERIFIED_ACTIVE.
+ """
+ from ares.core.campaign import Campaign, ScopeEntry
+ from ares.core.scope_firewall import OSFirewallController, OSFirewallState
+
+ campaign = Campaign(name="test-verified-active", scope=[ScopeEntry(cidr="10.0.0.0/8")])
+ monkeypatch.setattr(OSFirewallController, "is_elevated", classmethod(lambda cls: True))
+ monkeypatch.setattr("sys.platform", "linux")
+
+ # Insertion succeeds
+ def mock_ok(cmd, *args, **kwargs):
+ res = MagicMock()
+ res.returncode = 0
+ return res
+
+ monkeypatch.setattr("subprocess.run", mock_ok)
+
+ # 1. Verification returns False -> state MUST NOT be VERIFIED_ACTIVE
+ monkeypatch.setattr(OSFirewallController, "_verify_subrules", classmethod(lambda cls, sub_rules: False))
+ OSFirewallController._active_rules.clear()
+ rules = OSFirewallController.apply_rules(campaign, ["10.0.0.0/8"])
+ assert OSFirewallController._state != OSFirewallState.VERIFIED_ACTIVE
+ assert OSFirewallController._state == OSFirewallState.VERIFICATION_FAILED
+
+ # 2. Verification returns True -> state becomes VERIFIED_ACTIVE
+ monkeypatch.setattr(OSFirewallController, "_verify_subrules", classmethod(lambda cls, sub_rules: True))
+ OSFirewallController._active_rules.clear()
+ rules = OSFirewallController.apply_rules(campaign, ["10.0.0.0/8"])
+ assert len(rules) == 1
+ assert OSFirewallController._state == OSFirewallState.VERIFIED_ACTIVE
+ OSFirewallController.cleanup_all()
+ assert OSFirewallController._state == OSFirewallState.INACTIVE
+
+ def test_uid_owner_collateral_scope(self, monkeypatch):
+ """
+ Criterion 5 & 16: Support sandbox_uid in SandboxPolicy for dedicated sandbox UID,
+ verify fallback to nobody (65534) when unspecified, and verify collateral scope semantics.
+ """
+ from ares.core.sandbox import SandboxRunner, SandboxPolicy, IsolationTier
+ from ares.core.campaign import Campaign, ScopeEntry
+ from ares.core.scope_firewall import OSFirewallController
+ import asyncio
+
+ monkeypatch.setattr("os.name", "posix")
+ monkeypatch.setattr("os.geteuid", lambda: 0, raising=False)
+
+ import ares.core.scope_firewall as scope_fw_mod
+ captured_guards = []
+
+ class MockGuardContext:
+ def __init__(self, **kwargs):
+ captured_guards.append(kwargs)
+ async def __aenter__(self):
+ return None
+ async def __aexit__(self, *args):
+ pass
+
+ monkeypatch.setattr(scope_fw_mod, "scope_firewall_guard", MockGuardContext)
+
+ async def mock_exec(*args, **kwargs):
+ mock_p = MagicMock()
+ async def mock_comm(*args, **kwargs):
+ return (b'{"success": true, "findings": [], "extra": {}}', b'')
+ mock_p.communicate = mock_comm
+ mock_p.returncode = 0
+ return mock_p
+
+ monkeypatch.setattr(asyncio, "create_subprocess_exec", mock_exec)
+
+ # Test dedicated UID
+ policy_dedicated = SandboxPolicy(tier=IsolationTier.SUBPROCESS, drop_privileges=True, sandbox_uid=5001)
+ runner_dedicated = SandboxRunner(policy=policy_dedicated)
+ asyncio.run(runner_dedicated._run_subprocess("test.module", {}, "camp-1"))
+ assert captured_guards[-1]["uid_owner"] == 5001
+
+ # Test default shared nobody UID
+ policy_shared = SandboxPolicy(tier=IsolationTier.SUBPROCESS, drop_privileges=True, sandbox_uid=None)
+ runner_shared = SandboxRunner(policy=policy_shared)
+ asyncio.run(runner_shared._run_subprocess("test.module", {}, "camp-2"))
+ assert captured_guards[-1]["uid_owner"] == 65534
+
+ # Netfilter command generation verification:
+ # Applying rules with uid_owner=65534 applies host-wide to UID 65534
+ monkeypatch.setattr(OSFirewallController, "is_elevated", classmethod(lambda cls: True))
+ monkeypatch.setattr("sys.platform", "linux")
+ captured_cmds = []
+ def mock_sub_run(cmd, *args, **kwargs):
+ captured_cmds.append(cmd)
+ res = MagicMock()
+ res.returncode = 0
+ return res
+ monkeypatch.setattr("subprocess.run", mock_sub_run)
+ monkeypatch.setattr(OSFirewallController, "_verify_subrules", classmethod(lambda cls, sub_rules: True))
+
+ campaign = Campaign(name="test-uid-collateral", scope=[ScopeEntry(cidr="10.0.0.0/8")])
+ OSFirewallController._active_rules.clear()
+ OSFirewallController.apply_rules(campaign, ["10.0.0.0/8"], uid_owner=65534)
+ uid_matches = [cmd for cmd in captured_cmds if "--uid-owner" in cmd and "65534" in cmd]
+ assert len(uid_matches) > 0, "Netfilter rule must explicitly filter by --uid-owner 65534"
+ OSFirewallController.cleanup_all()
+
+ def test_subprocess_descendant_egress_is_actually_filtered(self):
+ """
+ Criterion 4 & 16: Controlled local TCP server fixture verifying that
+ ScopeFirewall permits in-scope destinations and blocks out-of-scope destinations.
+ Note on Kernel Verification: In unprivileged userland / developer environment,
+ OS kernel packet filtering is NOT elevated and thus marked NOT VERIFIED for OS mode.
+ Transport-level socket interception is VERIFIED.
+ """
+ import socket
+ import threading
+ from ares.core.campaign import Campaign, ScopeEntry
+ from ares.core.scope_firewall import scope_firewall_sync_guard, ScopeFirewallBlockError
+
+ # Start a local TCP echo server
+ server = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+ server.bind(("127.0.0.1", 0))
+ server.listen(1)
+ port = server.getsockname()[1]
+
+ def run_server():
+ try:
+ conn, _ = server.accept()
+ conn.sendall(b"OK")
+ conn.close()
+ except Exception:
+ pass
+
+ th = threading.Thread(target=run_server, daemon=True)
+ th.start()
+
+ # In-scope test: loopback allowed
+ campaign_ok = Campaign(name="in-scope", scope=[ScopeEntry(cidr="127.0.0.0/8")])
+ with scope_firewall_sync_guard(campaign=campaign_ok, enable_os_firewall=False):
+ client = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+ client.connect(("127.0.0.1", port))
+ data = client.recv(10)
+ client.close()
+ assert data == b"OK"
+
+ # Out-of-scope test: external IP blocked
+ campaign_restricted = Campaign(name="scoped", scope=[ScopeEntry(cidr="10.0.0.0/8")])
+ with scope_firewall_sync_guard(campaign=campaign_restricted, enable_os_firewall=False):
+ client_bad = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+ with pytest.raises(ScopeFirewallBlockError):
+ client_bad.connect(("192.0.2.1", 80))
+ client_bad.close()
+
+ server.close()
+
+ def test_canonical_path_containment_edge_cases(self, tmp_path):
+ """
+ Criterion 10: Exhaustive verification of _is_contained_in_sandbox
+ across inside, nested, sibling prefix, symlink, traversal, and normcase.
+ """
+ import os
+
+ sandbox_root = tmp_path / "sandbox_dir"
+ sandbox_root.mkdir()
+ sub_dir = sandbox_root / "subdir"
+ sub_dir.mkdir()
+ sibling_evil = tmp_path / "sandbox_dir_evil"
+ sibling_evil.mkdir()
+
+ # The containment logic from _build_wrapper_script
+ def is_contained(target_path, sandbox_dir):
+ try:
+ real_sandbox = os.path.normcase(os.path.realpath(sandbox_dir))
+ target_str = str(target_path)
+ if not os.path.exists(target_str):
+ parent = os.path.dirname(target_str) or "."
+ real_target = os.path.normcase(os.path.join(os.path.realpath(parent), os.path.basename(target_str)))
+ else:
+ real_target = os.path.normcase(os.path.realpath(target_str))
+ return os.path.commonpath([real_sandbox, real_target]) == real_sandbox
+ except (ValueError, OSError, TypeError):
+ return False
+
+ # 1. Inside path
+ assert is_contained(sandbox_root / "test.txt", sandbox_root) is True
+ # 2. Nested path
+ assert is_contained(sub_dir / "nested.txt", sandbox_root) is True
+ # 3. Sibling prefix escape (CRITICAL: startswith bug would allow this)
+ assert is_contained(sibling_evil / "test.txt", sandbox_root) is False
+ # 4. Traversal
+ assert is_contained(sandbox_root / ".." / "outside.txt", sandbox_root) is False
+ # 5. Outside absolute path
+ assert is_contained(tmp_path / "outside.txt", sandbox_root) is False
+
+ def test_custom_docker_volume_write_policy(self, monkeypatch):
+ """
+ Criterion 9: Verify read_only=True container configuration when allow_write=False.
+ """
+ from ares.core.sandbox import SandboxRunner, SandboxPolicy, IsolationTier
+ import asyncio
+
+ policy = SandboxPolicy(tier=IsolationTier.DOCKER, allow_write=False, allow_network=False)
+ runner = SandboxRunner(policy=policy)
+
+ mock_docker = MagicMock()
+ mock_client = MagicMock()
+ mock_docker.from_env.return_value = mock_client
+ mock_client.containers.run.return_value = b'{"success": true, "findings": [], "extra": {}}'
+ monkeypatch.setattr("sys.modules", {**sys.modules, "docker": mock_docker})
+
+ res = asyncio.run(runner._run_docker("test.module", {}, "camp-123"))
+ assert res.success is True
+ _, kwargs = mock_client.containers.run.call_args
+ assert kwargs["read_only"] is True
+
+ def test_scope_firewall_effective_security_tier(self, monkeypatch):
+ """
+ Criterion 3, 13 & 16: Observability of requested vs effective security tier.
+ SandboxResult MUST report:
+ - requested_tier
+ - effective_tier
+ - downgraded
+ - downgrade_reason
+ - guarantees_lost
+ """
+ from ares.core.sandbox import SandboxRunner, SandboxPolicy, IsolationTier
+ import asyncio
+
+ # 1. Normal Subprocess
+ policy_sub = SandboxPolicy(tier=IsolationTier.SUBPROCESS, allow_network=False)
+ runner_sub = SandboxRunner(policy=policy_sub)
+ mock_sub_res = MagicMock()
+ mock_sub_res.success = True
+ mock_sub_res.findings = []
+ mock_sub_res.extra = {}
+ mock_sub_res.requested_tier = IsolationTier.SUBPROCESS
+ mock_sub_res.effective_tier = IsolationTier.SUBPROCESS
+ mock_sub_res.sandbox_tier = IsolationTier.SUBPROCESS
+ mock_sub_res.downgraded = False
+ mock_sub_res.downgrade_reason = ""
+ mock_sub_res.guarantees_lost = []
+ mock_sub_res.wall_time_s = 0.01
+
+ async def mock_run_subprocess(*args, **kwargs):
+ return mock_sub_res
+
+ monkeypatch.setattr(runner_sub, "_run_subprocess", mock_run_subprocess)
+ res_sub = asyncio.run(runner_sub.run_module("test.module", {}, "camp-1"))
+ assert res_sub.requested_tier == IsolationTier.SUBPROCESS
+ assert res_sub.effective_tier == IsolationTier.SUBPROCESS
+ assert res_sub.downgraded is False
+
+ # 2. Strict Docker Rejection when unavailable
+ policy_dock_strict = SandboxPolicy(tier=IsolationTier.DOCKER, allow_tier_downgrade=False, allow_network=False)
+ runner_dock_strict = SandboxRunner(policy=policy_dock_strict)
+ monkeypatch.setitem(sys.modules, "docker", None)
+ res_dock_strict = asyncio.run(runner_dock_strict.run_module("test.module", {}, "camp-2"))
+ assert res_dock_strict.success is False
+ assert res_dock_strict.requested_tier == IsolationTier.DOCKER
+ assert res_dock_strict.effective_tier == IsolationTier.DOCKER
+ assert res_dock_strict.downgraded is False
+
+ # 3. Permitted Docker Downgrade
+ policy_dock_compat = SandboxPolicy(tier=IsolationTier.DOCKER, allow_tier_downgrade=True, allow_network=False)
+ runner_dock_compat = SandboxRunner(policy=policy_dock_compat)
+ monkeypatch.setitem(sys.modules, "docker", None)
+ monkeypatch.setattr(runner_dock_compat, "_run_subprocess", mock_run_subprocess)
+ res_dock_compat = asyncio.run(runner_dock_compat.run_module("test.module", {}, "camp-3"))
+ assert res_dock_compat.requested_tier == IsolationTier.DOCKER
+ assert res_dock_compat.effective_tier == IsolationTier.SUBPROCESS
+ assert res_dock_compat.downgraded is True
+ assert res_dock_compat.downgrade_reason == "docker_package_not_installed"
+ assert len(res_dock_compat.guarantees_lost) > 0
+
+
+