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
"""
ARES Plugin Sandbox - Restricted Module Execution
Provides defense-in-depth isolation tiers to protect engine integrity during module execution.
Isolation tiers & security boundaries:
TIER_0 NONE - trusted core modules only, run in-process under ScopeFirewall.
TIER_1 SUBPROCESS - separate Python process:
* Network: allow_network=False enforces Linux network namespace (CLONE_NEWNET)
fail-closed, or deny-all ScopeFirewall socket interception.
allow_network=True enforces ScopeFirewall egress boundary.
* Filesystem: working directory locked to ephemeral temporary directory;
Unix RLIMIT_FSIZE=(0,0) inhibits file enlargement; application-level
open/write hooks provide defense-in-depth within Python. Note: Subprocess
tier does not provide complete OS-level mount namespace isolation.
* Privileges: drop_privileges=True drops root (EUID 0) to 'nobody' on Linux
fail-closed; unsupported on Windows while elevated (aborts execution).
TIER_2 SECCOMP - Linux SUBPROCESS + PR_SET_NO_NEW_PRIVS + BPF syscall allowlist filter.
TIER_3 DOCKER - Complete OS container isolation: read-only root filesystem (allow_write=False),
network namespace isolation ('none' or 'bridge'), CPU & memory cgroups.
Usage:
sandbox = SandboxRunner(tier=IsolationTier.TIER_1)
result = await sandbox.run_module("ad.kerberoast", params, campaign)
"""
from __future__ import annotations
import asyncio
import json
import os
import sys as _sys
if _sys.platform != "win32":
import resource
else:
resource = None # type: ignore[assignment]
import sys
import tempfile
import time
import uuid
from dataclasses import dataclass, field
from enum import Enum
from typing import Any
from ares.core.logger import audit, get_logger
logger = get_logger("ares.sandbox")
# Syscall whitelist for seccomp (Linux only)
_SECCOMP_ALLOWED = {
"read", "write", "open", "openat", "close", "stat", "fstat", "lstat",
"poll", "lseek", "mmap", "mprotect", "munmap", "brk", "rt_sigaction",
"rt_sigprocmask", "ioctl", "pread64", "pwrite64", "readv", "writev",
"access", "pipe", "select", "sched_yield", "mremap", "msync", "mincore",
"madvise", "shmget", "shmat", "shmctl", "dup", "dup2", "pause", "nanosleep",
"getitimer", "alarm", "setitimer", "getpid", "sendfile", "socket", "connect",
"accept", "sendto", "recvfrom", "sendmsg", "recvmsg", "shutdown", "bind",
"listen", "getsockname", "getpeername", "socketpair", "setsockopt", "getsockopt",
"clone", "fork", "vfork", "execve", "exit", "wait4", "kill", "uname",
"fcntl", "flock", "fsync", "fdatasync", "truncate", "ftruncate", "getdents",
"getcwd", "chdir", "rename", "mkdir", "rmdir", "unlink", "readlink", "chmod",
"gettimeofday", "getrlimit", "getrusage", "times", "getuid", "getgid",
"geteuid", "getegid", "setuid", "setgid", "getgroups", "setgroups",
"futex", "sched_setaffinity", "sched_getaffinity", "set_thread_area",
"get_thread_area", "set_tid_address", "exit_group", "epoll_wait", "epoll_ctl",
"epoll_create", "epoll_create1", "getdents64", "clock_gettime", "clock_nanosleep",
"statfs", "fstatfs", "arch_prctl", "prctl", "getrandom", "memfd_create",
"openat2", "newfstatat",
}
class IsolationTier(str, Enum):
NONE = "none" # in-process (core modules only)
SUBPROCESS = "subprocess" # separate process + resource limits
SECCOMP = "seccomp" # subprocess + syscall filter
DOCKER = "docker" # container isolation
@dataclass
class SandboxPolicy:
"""Security policy applied to sandboxed module execution.
Semantic definitions by isolation tier:
allow_network:
- Linux SUBPROCESS: Mandatory network namespace isolation via unshare(CLONE_NEWNET).
- Windows SUBPROCESS: Mandatory deny-all egress via ScopeFirewall socket hooks.
- DOCKER: Container network mode 'none' (kernel namespace isolation).
allow_write:
- DOCKER: Read-only container rootfs (read_only=True via container mount options).
- SUBPROCESS: Ephemeral sandbox working directory, RLIMIT_FSIZE=(0,0) on Unix, and
application-level open/write hooks within Python. NOTE: For complete OS filesystem
isolation, IsolationTier.DOCKER is required.
drop_privileges:
- Linux SUBPROCESS: Drops root (EUID 0) to 'nobody' and verifies non-root UID (mandatory).
- Windows SUBPROCESS: Privilege dropping from Administrator is unsupported; execution aborts if elevated.
"""
tier: IsolationTier = IsolationTier.SUBPROCESS
cpu_time_s: int = 30 # max CPU seconds (RLIMIT_CPU, best-effort)
memory_mb: int = 256 # max virtual memory (RLIMIT_AS, best-effort)
timeout_s: int = 300 # wall-clock timeout
allow_network: bool = True # outbound network allowed within campaign scope
allow_write: bool = False # allow filesystem writes
drop_privileges: bool = True # drop root privileges to nobody on Linux
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
allow_unconfined_subprocess_binaries: bool = False # in strict mode, reject SUBPROCESS allow_network=True without OS boundary
sandbox_uid: int | None = None # dedicated sandbox UID for Linux parent firewall & child privilege drop
sandbox_gid: int | None = None # primary GID for sandbox identity (defaults to primary GID of sandbox_uid)
# 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])
requested_tier: IsolationTier = IsolationTier.SUBPROCESS
effective_tier: IsolationTier = IsolationTier.SUBPROCESS
downgraded: bool = False
downgrade_reason: str = ""
guarantees_lost: list[str] = field(default_factory=list)
security_mode: str = "strict"
active_boundary: str = ""
@dataclass
class PolicyDecision:
"""Canonical security policy decision outcome."""
allowed: bool
effective_tier: IsolationTier
requested_tier: IsolationTier
downgraded: bool = False
downgrade_reason: str = ""
guarantees_lost: list[str] = field(default_factory=list)
active_boundary: str = ""
security_mode: str = "strict"
rejection_reason: str = ""
class SandboxRunner:
"""
Executes ARES modules inside an isolation tier.
In strict mode (allow_tier_downgrade=False), fails closed if the requested tier is unavailable.
"""
def __init__(self, policy: SandboxPolicy | None = None) -> None:
self.policy = policy or SandboxPolicy()
def evaluate_policy(
self,
module_id: str,
tier: IsolationTier | None = None,
has_external_binary: bool = False,
docker_available: bool = True,
has_os_boundary: bool | None = None,
) -> PolicyDecision:
"""
Evaluate canonical security policy decision matrix according to:
requested_tier, network policy, external binary capability, OS boundary, and strict mode.
"""
requested = tier or self.policy.tier
strict = self.policy.strict_mode
sec_mode = "strict" if strict else "compat"
is_trusted = self.is_trusted_module(module_id)
# 1. Trusted core modules
if is_trusted:
if requested == IsolationTier.NONE:
return PolicyDecision(
allowed=True,
effective_tier=IsolationTier.NONE,
requested_tier=requested,
active_boundary="transport_hook",
security_mode=sec_mode,
)
elif strict and not self.policy.allow_tier_downgrade:
effective = requested
else:
return PolicyDecision(
allowed=True,
effective_tier=IsolationTier.NONE,
requested_tier=requested,
downgraded=True,
downgrade_reason="trusted_core_module_runs_in_process",
guarantees_lost=[
"process_isolation",
"filesystem_isolation",
"network_namespace_isolation",
],
active_boundary="transport_hook",
security_mode=sec_mode,
)
else:
effective = requested
# 2. DOCKER tier
if effective == IsolationTier.DOCKER:
docker_downgraded = False
docker_downgrade_reason = ""
docker_guarantees_lost: list[str] = []
if not docker_available:
if strict and not self.policy.allow_tier_downgrade:
return PolicyDecision(
allowed=False,
effective_tier=IsolationTier.DOCKER,
requested_tier=requested,
security_mode=sec_mode,
active_boundary="none",
rejection_reason="Security tier downgrade from DOCKER rejected (allow_tier_downgrade=False): Docker unavailable.",
)
else:
effective = IsolationTier.SUBPROCESS
docker_downgraded = True
docker_downgrade_reason = "docker_unavailable"
docker_guarantees_lost = [
"read_only_rootfs_mount_namespace",
"container_cgroups",
"network_namespace_isolation",
]
if effective == IsolationTier.DOCKER:
if not self.policy.allow_network:
return PolicyDecision(
allowed=True,
effective_tier=IsolationTier.DOCKER,
requested_tier=requested,
active_boundary="container_network_none",
security_mode=sec_mode,
)
else:
if has_external_binary and strict and not self.policy.allow_unconfined_docker_binaries:
return PolicyDecision(
allowed=False,
effective_tier=IsolationTier.DOCKER,
requested_tier=requested,
security_mode=sec_mode,
active_boundary="none",
rejection_reason="Docker online mode cannot guarantee scope containment for external binaries in strict mode.",
)
return PolicyDecision(
allowed=True,
effective_tier=IsolationTier.DOCKER,
requested_tier=requested,
active_boundary="container_bridge",
security_mode=sec_mode,
)
# 3. SUBPROCESS / SECCOMP tiers
if effective in (IsolationTier.SUBPROCESS, IsolationTier.SECCOMP):
sub_name = "seccomp_bpf+" if effective == IsolationTier.SECCOMP else ""
if not self.policy.allow_network:
return PolicyDecision(
allowed=True,
effective_tier=effective,
requested_tier=requested,
downgraded=locals().get("docker_downgraded", False),
downgrade_reason=locals().get("docker_downgrade_reason", ""),
guarantees_lost=locals().get("docker_guarantees_lost", []),
active_boundary=f"{sub_name}network_namespace",
security_mode=sec_mode,
)
else:
if has_os_boundary is None:
has_os_boundary = (
os.name != "nt"
and self.policy.drop_privileges
and getattr(os, "geteuid", lambda: -1)() == 0
)
if has_external_binary and strict and not has_os_boundary and not self.policy.allow_unconfined_subprocess_binaries:
return PolicyDecision(
allowed=False,
effective_tier=effective,
requested_tier=requested,
downgraded=locals().get("docker_downgraded", False),
downgrade_reason=locals().get("docker_downgrade_reason", ""),
guarantees_lost=locals().get("docker_guarantees_lost", []),
security_mode=sec_mode,
active_boundary="none",
rejection_reason="Subprocess online mode cannot guarantee scope containment for external binaries without an OS-level boundary.",
)
active_b = f"{sub_name}os_firewall_uid" if has_os_boundary else f"{sub_name}transport_hook"
return PolicyDecision(
allowed=True,
effective_tier=effective,
requested_tier=requested,
downgraded=locals().get("docker_downgraded", False),
downgrade_reason=locals().get("docker_downgrade_reason", ""),
guarantees_lost=locals().get("docker_guarantees_lost", []),
active_boundary=active_b,
security_mode=sec_mode,
)
# 4. NONE tier
return PolicyDecision(
allowed=True,
effective_tier=IsolationTier.NONE,
requested_tier=requested,
active_boundary="transport_hook",
security_mode=sec_mode,
)
async def run_module(
self,
module_id: str,
params: dict[str, Any],
campaign_id: str = "",
tier: IsolationTier | None = None,
) -> SandboxResult:
"""
Run module_id with params inside the configured isolation tier.
In strict mode (allow_tier_downgrade=False), fails closed if requested tier is unavailable.
"""
requested_tier = tier or self.policy.tier
effective_tier = requested_tier
is_trusted = self.is_trusted_module(module_id)
downgraded = False
downgrade_reason = ""
guarantees_lost: list[str] = []
t0 = time.monotonic()
# Core modules handling (Finding C: Truthful tier accounting)
if is_trusted:
if requested_tier == IsolationTier.NONE:
effective_tier = IsolationTier.NONE
elif self.policy.strict_mode and not self.policy.allow_tier_downgrade:
# In strict mode without downgrade permission, honor the requested sandboxed tier
effective_tier = requested_tier
else:
# Permitted downgrade with truthful accounting
effective_tier = IsolationTier.NONE
downgraded = True
downgrade_reason = "trusted_core_module_runs_in_process"
guarantees_lost = [
"process_isolation",
"filesystem_isolation",
"network_namespace_isolation",
]
audit(
"sandbox_run_start",
actor="engine",
module=module_id,
requested_tier=requested_tier.value,
tier=effective_tier.value,
strict_mode=self.policy.strict_mode,
campaign=campaign_id,
)
try:
if effective_tier == IsolationTier.NONE:
result = await self._run_inprocess(
module_id, params, campaign_id, requested_tier=requested_tier
)
elif effective_tier == IsolationTier.DOCKER:
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,
security_mode="strict" if self.policy.strict_mode else "compat",
success=False, error=str(exc)[:500],
)
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
if downgraded and not result.downgraded:
result.downgraded = True
result.downgrade_reason = downgrade_reason
result.guarantees_lost = guarantees_lost
result.sandbox_tier = result.effective_tier
if not getattr(result, "security_mode", None):
result.security_mode = "strict" if self.policy.strict_mode else "compat"
audit(
"sandbox_run_complete",
actor="engine",
module=module_id,
success=result.success,
requested_tier=result.requested_tier.value,
effective_tier=result.effective_tier.value,
strict_mode=self.policy.strict_mode,
network_policy=self.policy.allow_network,
filesystem_policy=self.policy.allow_write,
privilege_policy=self.policy.drop_privileges,
security_boundary=result.active_boundary,
downgraded=result.downgraded,
downgrade_reason=result.downgrade_reason,
guarantees_lost=result.guarantees_lost,
tier=result.sandbox_tier.value,
wall_time_s=result.wall_time_s,
)
return result
# ── Tier implementations ───────────────────────────────────────────────
async def _run_inprocess(
self,
module_id: str,
params: dict[str, Any],
campaign_id: str,
requested_tier: IsolationTier = IsolationTier.NONE,
) -> SandboxResult:
"""Direct in-process execution. For trusted core modules only."""
from ares.core.campaign import Campaign, NoiseProfile, ScopeEntry
from ares.core.config import AresSettings
from ares.core.noise import NoiseController
from ares.core.plugin.loader import ModuleRegistry
from ares.core.scope_firewall import scope_firewall_guard
registry = ModuleRegistry()
module_cls = registry.get(module_id)
if not module_cls:
return SandboxResult(module_id=module_id, sandbox_tier=IsolationTier.NONE,
success=False, error=f"Module {module_id!r} not registered")
# Look up real campaign scope from DB - same pattern as _run_subprocess.
# Do NOT default to 0.0.0.0/0 (wildcard) as that bypasses scope enforcement.
scope_entries: list[ScopeEntry] = []
try:
import json as _j
from ares.core.config import get_settings as _gs
from ares.db.database import AresDatabase
_s = _gs()
async with await AresDatabase.create(
_s.ares_database_url, _s.encryption_key_value
) as _sdb:
_row = await _sdb.get_campaign(campaign_id)
if _row and _row.get("scope_json"):
scope_entries = [
ScopeEntry(cidr=e["cidr"])
for e in _j.loads(_row["scope_json"])
if e.get("cidr")
]
except Exception:
pass # fallback: empty scope = nothing in scope, fails closed
# If DB lookup failed and no scope found, use empty scope (deny-all).
# Modules will fail validation - this is safer than allowing everything.
if not scope_entries:
logger.warning("sandbox_inprocess_no_scope",
campaign_id=campaign_id, module_id=module_id,
note="No campaign scope found - using deny-all. "
"Pass a valid campaign_id or use subprocess mode.")
scope_entries = []
campaign = Campaign(
id=campaign_id or str(uuid.uuid4()),
name="sandbox-exec",
scope=scope_entries,
noise_profile=NoiseProfile.NORMAL,
)
settings = AresSettings()
noise = NoiseController(campaign)
module = module_cls(settings=settings, campaign=campaign, noise=noise)
async with scope_firewall_guard(
campaign=campaign,
module_id=module_id,
strict_mode=self.policy.strict_mode,
):
findings, extra = await module.run(**params)
return SandboxResult(
module_id=module_id,
sandbox_tier=IsolationTier.NONE,
requested_tier=requested_tier,
effective_tier=IsolationTier.NONE,
security_mode="strict" if self.policy.strict_mode else "compat",
active_boundary="transport_hook",
success=True,
findings=[f.to_dict() if hasattr(f, "to_dict") else {} for f in findings],
extra=extra,
)
async def _run_subprocess(
self,
module_id: str,
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] = []
try:
import json as _j
from ares.core.config import get_settings as _gs
from ares.db.database import AresDatabase
_s = _gs()
async with await AresDatabase.create(
_s.ares_database_url, _s.encryption_key_value
) as _sdb:
_row = await _sdb.get_campaign(campaign_id)
if _row and _row.get("scope_json"):
_scope_cidrs = [
e["cidr"] for e in _j.loads(_row["scope_json"])
if e.get("cidr")
]
except Exception:
pass # fallback handled in wrapper - fails closed
if os.name == "nt" and self.policy.drop_privileges:
from ares.core.scope_firewall import OSFirewallController
if OSFirewallController.is_elevated():
return SandboxResult(
module_id=module_id,
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.",
)
payload = json.dumps({
"module_id": module_id,
"params": params,
"campaign_id": campaign_id,
"use_seccomp": use_seccomp,
"tmpdir": tmpdir,
"scope_cidrs": _scope_cidrs,
"allow_network": self.policy.allow_network,
"allow_write": self.policy.allow_write,
"strict_mode": self.policy.strict_mode,
})
wrapper = self._build_wrapper_script(use_seccomp)
script_path = os.path.join(tmpdir, "runner.py")
with open(script_path, "w", encoding="utf-8") as f:
f.write(wrapper)
preexec = self._make_preexec_fn() if os.name != "nt" else None
# If drop_privileges is requested on Linux while running as root, the parent
# orchestrator installs the UID-based OS firewall rules before spawning the child,
# 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:
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
# Strict mode online network limitation for subprocess external binaries without OS boundary
if self.policy.strict_mode and self.policy.allow_network:
if parent_uid_firewall is None and not self.policy.allow_unconfined_subprocess_binaries:
return SandboxResult(
module_id=module_id,
sandbox_tier=sub_tier,
requested_tier=requested_tier,
effective_tier=sub_tier,
security_mode="strict",
active_boundary="none",
success=False,
error=(
"Subprocess online mode cannot guarantee scope containment for external binaries without an OS-level boundary. "
"In strict mode, run as root with drop_privileges=True (UID-based OS firewall), use allow_network=False, "
"or explicitly set allow_unconfined_subprocess_binaries=True."
),
)
if use_seccomp:
if not self.policy.allow_network:
active_boundary = "seccomp_bpf+network_namespace"
elif parent_uid_firewall is not None:
active_boundary = "seccomp_bpf+os_firewall_uid"
else:
active_boundary = "seccomp_bpf+transport_hook"
else:
if not self.policy.allow_network:
active_boundary = "network_namespace"
elif parent_uid_firewall is not None:
active_boundary = "os_firewall_uid"
else:
active_boundary = "transport_hook"
from ares.core.campaign import Campaign, NoiseProfile, ScopeEntry
from ares.core.scope_firewall import scope_firewall_guard
parent_scope = [ScopeEntry(cidr=c) for c in _scope_cidrs] if self.policy.allow_network else []
parent_campaign = Campaign(
id=campaign_id or str(uuid.uuid4()),
name="sandbox-subprocess-parent",
scope=parent_scope,
noise_profile=NoiseProfile.NORMAL,
)
async with scope_firewall_guard(
campaign=parent_campaign,
enable_os_firewall=(parent_uid_firewall is not None),
uid_owner=parent_uid_firewall,
strict_mode=self.policy.strict_mode,
):
proc = await asyncio.create_subprocess_exec(
sys.executable, script_path,
stdin=asyncio.subprocess.PIPE,
stdout=asyncio.subprocess.PIPE,
stderr=asyncio.subprocess.PIPE,
preexec_fn=preexec,
cwd=tmpdir,
)
try:
stdout_b, stderr_b = await asyncio.wait_for(
proc.communicate(payload.encode()),
timeout=self.policy.timeout_s,
)
except TimeoutError:
proc.kill()
await proc.wait()
return SandboxResult(
module_id=module_id,
sandbox_tier=sub_tier,
requested_tier=requested_tier,
effective_tier=sub_tier,
security_mode="strict" if self.policy.strict_mode else "compat",
active_boundary=active_boundary,
success=False,
error=f"Sandbox timeout ({self.policy.timeout_s}s)",
)
stdout = stdout_b.decode(errors="replace")
stderr = stderr_b.decode(errors="replace")
try:
data = json.loads(stdout)
return SandboxResult(
module_id = module_id,
sandbox_tier = sub_tier,
requested_tier = requested_tier,
effective_tier = sub_tier,
security_mode = "strict" if self.policy.strict_mode else "compat",
active_boundary = active_boundary,
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=sub_tier,
requested_tier=requested_tier,
effective_tier=sub_tier,
security_mode="strict" if self.policy.strict_mode else "compat",
active_boundary=active_boundary,
success=False,
error="Invalid JSON from sandbox",
stdout=stdout[:500],
stderr=stderr[:500],
)
async def _run_docker(
self,
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,
security_mode="strict",
active_boundary="none",
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
except ImportError:
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,
security_mode="strict" if self.policy.strict_mode else "compat",
active_boundary="none",
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,
security_mode="strict" if self.policy.strict_mode else "compat",
active_boundary="none",
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] = []
try:
import json as _dj
from ares.core.config import get_settings as _dgs
from ares.db.database import AresDatabase
_ds = _dgs()
async with await AresDatabase.create(
_ds.ares_database_url, _ds.encryption_key_value
) as _ddb:
_drow = await _ddb.get_campaign(campaign_id)
if _drow and _drow.get("scope_json"):
_docker_scope = [
e["cidr"] for e in _dj.loads(_drow["scope_json"])
if e.get("cidr")
]
except Exception:
pass # fails closed in inline_runner
payload = json.dumps({
"module_id": module_id,
"params": params,
"campaign_id": campaign_id,
"scope_cidrs": _docker_scope,
"allow_network": self.policy.allow_network,
"strict_mode": self.policy.strict_mode,
})
image = self.policy.docker_image
network = "none" if not self.policy.allow_network else self.policy.docker_network
read_only = not self.policy.allow_write
mem_limit = f"{self.policy.memory_mb}m"
active_boundary = "container_network_none" if not self.policy.allow_network else "container_bridge"
try:
container = client.containers.run(
image,
command=["python3", "-c", self._inline_runner()],
environment={"ARES_SANDBOX_PAYLOAD": payload},
mem_limit=mem_limit,
cpu_period=100000,
cpu_quota=50000, # 50% of one CPU
network_mode=network,
read_only=read_only,
remove=True,
stdout=True,
stderr=True,
detach=False,
timeout=self.policy.timeout_s,
)
output = container.decode() if isinstance(container, bytes) else str(container)
data = json.loads(output)
return SandboxResult(
module_id=module_id,
sandbox_tier=IsolationTier.DOCKER,
requested_tier=requested_tier,
effective_tier=IsolationTier.DOCKER,
security_mode="strict" if self.policy.strict_mode else "compat",
active_boundary=active_boundary,
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,
requested_tier=requested_tier,
effective_tier=IsolationTier.DOCKER,
security_mode="strict" if self.policy.strict_mode else "compat",
active_boundary=active_boundary,
success=False,
error=str(exc)[:300],
)
# ── Helpers ────────────────────────────────────────────────────────────
def _make_preexec_fn(self):
"""
Return preexec_fn that applies resource limits and mandatory security privileges.
Executed in the child process immediately after fork() and before exec().
Only called on Unix systems.
"""
cpu_limit = self.policy.cpu_time_s
mem_bytes = self.policy.memory_mb * 1024 * 1024
allow_network = self.policy.allow_network
drop_privileges = self.policy.drop_privileges
allow_write = self.policy.allow_write
target_uid = self.policy.sandbox_uid
target_gid = self.policy.sandbox_gid
strict_mode = self.policy.strict_mode
_parent_pid = os.getpid()
def _limits():
# 1. Best-effort resource limits (only applied in child process after fork)
in_child = (os.getpid() != _parent_pid)
if resource is not None and in_child:
try:
resource.setrlimit(resource.RLIMIT_CPU, (cpu_limit, cpu_limit))
resource.setrlimit(resource.RLIMIT_AS, (mem_bytes, mem_bytes))
resource.setrlimit(resource.RLIMIT_NPROC, (64, 64))
resource.setrlimit(resource.RLIMIT_NOFILE, (256, 256))
if not allow_write:
resource.setrlimit(resource.RLIMIT_FSIZE, (0, 0))
except (OSError, ValueError, AttributeError):
pass # best-effort resource limits
# 2. MANDATORY SECURITY CONTROL: Network isolation (fail-closed)
if not allow_network:
import ctypes
import ctypes.util
libc_name = ctypes.util.find_library("c") or "libc.so.6"
try:
_libc = ctypes.CDLL(libc_name, use_errno=True)
# CLONE_NEWNET = 0x40000000
ret = _libc.unshare(0x40000000)
if ret != 0:
errno_val = ctypes.get_errno()
raise RuntimeError(
f"unshare(CLONE_NEWNET) returned {ret} (errno={errno_val})"
)
except Exception as exc:
raise RuntimeError( # noqa: B904
f"Mandatory security control failed: allow_network=False requires network namespace isolation: {exc}"
)
# 3. MANDATORY SECURITY CONTROL: Privilege dropping (fail-closed)
if drop_privileges and getattr(os, "geteuid", lambda: -1)() == 0:
try:
if target_uid is not None:
drop_uid = target_uid
if target_gid is not None:
drop_gid = target_gid
else:
try:
import pwd
drop_gid = pwd.getpwuid(target_uid).pw_gid
except Exception as e:
if strict_mode:
raise RuntimeError( # noqa: B904
f"Cannot resolve primary GID for UID {target_uid} in strict mode; specify sandbox_gid explicitly: {e}"
)
drop_gid = target_uid
else:
import pwd
nobody = pwd.getpwnam("nobody")
drop_uid = nobody.pw_uid
drop_gid = target_gid if target_gid is not None else nobody.pw_gid
os.setgroups([])
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( # noqa: B904
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(
"Mandatory security control failed: process retains root privileges (uid/euid == 0) after drop"
)
return _limits
@staticmethod
def _build_wrapper_script(use_seccomp: bool) -> str:
"""
Build Python source that runs in the sandbox child process.
When use_seccomp=True, applies PR_SET_NO_NEW_PRIVS (prctl 38) as a
mandatory minimum, preventing the child from ever regaining privileges.
Full BPF syscall allowlist filtering is applied via pyseccomp.
Fails closed with RuntimeError if seccomp enforcement cannot be established.
"""
if use_seccomp:
allowed_list = repr(sorted(_SECCOMP_ALLOWED))
seccomp_preamble = (
"# ── SECCOMP: apply mandatory privilege restrictions ───────────────────\n"
"import ctypes as _ct, ctypes.util as _cu, os as _so, sys as _sys\n"
"try:\n"
" _libc = _ct.CDLL(_cu.find_library('c'), use_errno=True)\n"
" if _libc.prctl(38, 1, 0, 0, 0) != 0:\n"
" raise RuntimeError('prctl PR_SET_NO_NEW_PRIVS returned non-zero')\n"
"except Exception as _pe:\n"
" print(f'[sandbox] prctl failed: {_pe}', file=_sys.stderr)\n"
" raise RuntimeError(f'Seccomp PR_SET_NO_NEW_PRIVS enforcement failed: {_pe}')\n"
"try:\n"
" import seccomp as _sc # pyseccomp\n"
f" _allowed = {allowed_list}\n"
" _f = _sc.SyscallFilter(defaction=_sc.KILL)\n"
" for _sn in _allowed:\n"
" try: _f.add_rule(_sc.ALLOW, _sn)\n"
" except Exception: pass\n"
" _f.load()\n"
"except Exception as _be:\n"
" print(f'[sandbox] BPF filter failed: {_be}', file=_sys.stderr)\n"
" raise RuntimeError(f'IsolationTier.SECCOMP failed to load BPF syscall filter: {_be}')\n"
"# ── end SECCOMP ────────────────────────────────────────────────────────\n"
)
else:
seccomp_preamble = ""
body = (
seccomp_preamble
+ "\nimport sys, json, asyncio, os\n\n"
"payload = json.loads(sys.stdin.read())\n"
"module_id = payload[\"module_id\"]\n"
"params = payload[\"params\"]\n"
"campaign_id = payload.get(\"campaign_id\", \"\")\n"
"\n# ── Defense-in-depth: Python-level write hooks (when allow_write=False) ──\n"
"# Classification: DEFENSE-IN-DEPTH for Python stdlib. Complete filesystem sandboxing\n"
"# requires the DOCKER tier (read_only=True rootfs mount).\n"
"_allow_write = payload.get(\"allow_write\", False)\n"
"_tmpdir = payload.get(\"tmpdir\", \"\")\n"
"if not _allow_write and _tmpdir:\n"
" import builtins\n"
" def _is_contained_in_sandbox(target_path, sandbox_dir):\n"
" try:\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.normcase(os.path.join(os.path.realpath(parent), os.path.basename(target_str)))\n"
" else:\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"
"\n"
" _orig_open = builtins.open\n"
" def _sandboxed_open(file, mode=\"r\", *args, **kwargs):\n"
" if any(m in mode for m in (\"w\", \"a\", \"+\", \"x\")):\n"
" if not _is_contained_in_sandbox(file, _tmpdir):\n"
" raise PermissionError(f\"[Sandbox] Write prohibited outside sandbox directory: {file}\")\n"
" return _orig_open(file, mode, *args, **kwargs)\n"
" builtins.open = _sandboxed_open\n"
"\n"
" _orig_os_open = os.open\n"
" def _sandboxed_os_open(path, flags, *args, **kwargs):\n"
" write_flags = (\n"
" getattr(os, \"O_WRONLY\", 1) |\n"
" getattr(os, \"O_RDWR\", 2) |\n"
" getattr(os, \"O_CREAT\", 64) |\n"
" getattr(os, \"O_TRUNC\", 512) |\n"
" getattr(os, \"O_APPEND\", 1024)\n"
" )\n"
" if flags & write_flags:\n"
" if not _is_contained_in_sandbox(path, _tmpdir):\n"
" raise PermissionError(f\"[Sandbox] os.open write prohibited outside sandbox directory: {path}\")\n"
" return _orig_os_open(path, flags, *args, **kwargs)\n"
" os.open = _sandboxed_os_open\n"
"\n"
"\nasync def run():\n"
" try:\n"
" from ares.core.config import AresSettings\n"
" from ares.core.noise import NoiseController\n"
" from ares.core.campaign import Campaign, NoiseProfile, ScopeEntry\n"
" from ares.core.plugin.loader import ModuleRegistry\n"
" import uuid\n"
"\n"
" registry = ModuleRegistry()\n"
" module_cls = registry.get(module_id)\n"
" if not module_cls:\n"
" return {\"success\": False, \"error\": f\"Module {module_id!r} not found\", \"findings\": [], \"extra\": {}}\n"
"\n"
" _allow_net = payload.get(\"allow_network\", True)\n"
" _scope_cidrs = payload.get(\"scope_cidrs\", [])\n"
" _strict_mode = payload.get(\"strict_mode\", False)\n"
" if not _allow_net:\n"
" campaign = Campaign(\n"
" id=campaign_id or str(uuid.uuid4()),\n"
" name=\"sandbox\",\n"
" scope=[],\n"
" noise_profile=NoiseProfile.NORMAL,\n"
" )\n"
" elif not _scope_cidrs:\n"
" print(json.dumps({\"success\": False, \"error\":\n"
" \"Sandbox scope not provided - refusing to run with unbounded scope\",\n"
" \"findings\": [], \"extra\": {}}))\n"
" return\n"
" else:\n"
" campaign = Campaign(\n"
" id=campaign_id or str(uuid.uuid4()),\n"
" name=\"sandbox\",\n"
" scope=[ScopeEntry(cidr=c) for c in _scope_cidrs],\n"
" noise_profile=NoiseProfile.NORMAL,\n"
" )\n"
" settings = AresSettings()\n"
" noise = NoiseController(campaign)\n"
" module = module_cls(settings=settings, campaign=campaign, noise=noise)\n"
" from ares.core.scope_firewall import scope_firewall_guard\n"
" _current_uid = getattr(os, 'getuid', lambda: None)()\n"
" async with scope_firewall_guard(campaign=campaign, module_id=module_id, enable_os_firewall=False, uid_owner=_current_uid, strict_mode=_strict_mode):\n"
" findings, extra = await module.run(**params)\n"
" return {\n"
" \"success\": True,\n"
" \"findings\": [f.to_dict() if hasattr(f, \"to_dict\") else {} for f in findings],\n"
" \"extra\": extra,\n"
" }\n"
" except Exception as e:\n"
" return {\"success\": False, \"error\": str(e)[:300], \"findings\": [], \"extra\": {}}\n"
"\nresult = asyncio.run(run())\n"
"print(json.dumps(result))\n"
)
return body
@staticmethod
def _inline_runner() -> str:
"""
Python source code that runs inside the Docker container.
Reads ARES_SANDBOX_PAYLOAD env var (JSON: {module_id, params, campaign_id}),
loads the ModuleRegistry, instantiates the module, runs it, and prints
the result as JSON on stdout.
"""
return (
'import sys, json, os, asyncio\n'
'\n'
'payload = json.loads(os.environ.get("ARES_SANDBOX_PAYLOAD", "{}"))\n'
'module_id = payload.get("module_id", "")\n'
'params = payload.get("params", {})\n'
'campaign_id = payload.get("campaign_id", "")\n'
'\n'
'async def _run():\n'
' try:\n'
' from ares.core.plugin.loader import ModuleRegistry\n'
' from ares.core.campaign import Campaign, NoiseProfile, ScopeEntry\n'
' import uuid\n'
' registry = ModuleRegistry()\n'
' module_cls = registry.get(module_id)\n'
' if not module_cls:\n'
' return {"success": False, "error": f"Module {module_id!r} not found",\n'
' "findings": [], "extra": {}}\n'
' _allow_net = payload.get("allow_network", True)\n'
' _scope_cidrs = payload.get("scope_cidrs", [])\n'
' _strict_mode = payload.get("strict_mode", False)\n'
' if not _allow_net:\n'
' campaign = Campaign(\n'
' id=campaign_id or str(uuid.uuid4()),\n'
' name="sandbox", operator="sandbox",\n'
' scope=[],\n'
' noise_profile=NoiseProfile.NORMAL,\n'
' )\n'
' elif not _scope_cidrs:\n'
' return {"success": False,\n'
' "error": "Sandbox scope not provided - refusing to run with unbounded scope",\n'
' "findings": [], "extra": {}}\n'
' else:\n'
' campaign = Campaign(\n'
' id=campaign_id or str(uuid.uuid4()),\n'
' name="sandbox", operator="sandbox",\n'
' scope=[ScopeEntry(cidr=c) for c in _scope_cidrs],\n'
' noise_profile=NoiseProfile.NORMAL,\n'
' )\n'
' try:\n'
' from ares.core.config import AresSettings\n'
' from ares.core.noise import NoiseController\n'
' settings = AresSettings()\n'
' noise = NoiseController(campaign)\n'
' module = module_cls(settings=settings, campaign=campaign, noise=noise)\n'
' except Exception:\n'
' module = module_cls()\n'
' from ares.core.scope_firewall import scope_firewall_guard\n'
' async with scope_firewall_guard(campaign=campaign, module_id=module_id):\n'
' findings, extra = await module.run(**params)\n'
' findings_out = []\n'
' for f in findings:\n'
' if hasattr(f, "model_dump"):\n'
' findings_out.append(f.model_dump(mode="json"))\n'
' elif hasattr(f, "to_dict"):\n'
' findings_out.append(f.to_dict())\n'
' else:\n'
' findings_out.append(str(f))\n'
' return {"success": True, "findings": findings_out, "extra": extra}\n'
' except Exception as exc:\n'
' return {"success": False, "error": str(exc)[:300],\n'
' "findings": [], "extra": {}}\n'
'\n'
'result = asyncio.run(_run())\n'
'print(json.dumps(result))\n'
)
def is_trusted_module(self, module_id: str) -> bool:
return any(
module_id == p or module_id.startswith(f"{p}.")
for p in self.policy.trusted_prefixes
)