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 Scope Firewall & Kernel / OS Egress Wall.
Provides dual-layer fail-closed egress boundaries for offensive security operations:
1. Kernel / OS-Level Packet Filtering (OS Mode):
- Windows: Interacts directly with Windows Defender Firewall (`netsh advfirewall`)
to enforce OS-level packet filtering for program egress when running with Administrator privileges.
- Linux: Interacts with Netfilter (`iptables`) scoped to process / cgroups when running as root.
- Includes automatic fail-safe rule teardown on context exit and process shutdown (`atexit`).
2. Transport-Level Socket Interceptor (Process Mode):
- In-process hook for `socket.connect`, `socket.sendto`, and `asyncio.create_connection`.
- Active across all environments (including unprivileged developer mode) with zero external dependencies.
- ContextVar task-isolation: only active within the attack module execution task.
- Windows Proactor IOCP & loopback protection: internal pipes, socketpairs, and loopback are safeguarded.
- DNS resolution re-entrancy lock: prevents recursive interception when resolving hostnames.
- Cloud domain whitelisting: allows legitimate cloud API traffic for cloud modules.
"""
from __future__ import annotations
import asyncio
import atexit
import contextlib
import functools
import ipaddress
import os
import secrets
import socket
import subprocess
import sys
import threading
import urllib.request
from collections.abc import AsyncGenerator, Generator
from contextvars import ContextVar
from enum import Enum
from typing import TYPE_CHECKING, Any
from ares.core.errors import ScopeFirewallBlockError
from ares.core.logger import audit, get_logger
if TYPE_CHECKING:
from ares.core.campaign import Campaign
logger = get_logger("ares.scope_firewall")
# ── Task-Isolated Context Variables ──────────────────────────────────────────
_current_firewall: ContextVar[ScopeFirewall | None] = ContextVar(
"_current_firewall", default=None
)
_in_firewall_resolution: ContextVar[bool] = ContextVar(
"_in_firewall_resolution", default=False
)
# ── Cloud Provider Domain Whitelist ──────────────────────────────────────────
# Permitted domains for modules with MODULE_CATEGORY == "cloud"
CLOUD_DOMAIN_SUFFIXES: tuple[str, ...] = (
# Microsoft / Azure / Entra / M365
".microsoftonline.com",
".microsoft.com",
".windows.net",
".azure.com",
".azure.net",
".office.com",
".live.com",
".msftidentity.com",
".graph.microsoft.com",
# Amazon Web Services
".amazonaws.com",
".aws.amazon.com",
# Google Cloud Platform
".googleapis.com",
".google.com",
".gcp.gvt2.com",
)
# ── Loopback & Local Addresses ───────────────────────────────────────────────
_LOOPBACK_HOSTS: frozenset[str] = frozenset(
{"127.0.0.1", "::1", "localhost", "0.0.0.0"}
)
class ScopeFirewall:
"""Deterministic scope firewall enforcing CIDR & target boundaries at socket layer."""
def __init__(
self,
campaign: Campaign,
module_id: str = "",
module_category: str = "",
allow_loopback_ipc: bool = True,
) -> None:
self.campaign = campaign
self.module_id = module_id
self.module_category = module_category.lower().strip()
self.allow_loopback_ipc = allow_loopback_ipc
# Parse and pre-compile CIDRs into IPv4Network / IPv6Network objects
self._networks: list[ipaddress.IPv4Network | ipaddress.IPv6Network] = []
for scope_entry in getattr(campaign, "scope", []):
cidr_str = getattr(scope_entry, "cidr", "").strip()
if cidr_str:
try:
self._networks.append(ipaddress.ip_network(cidr_str, strict=False))
except ValueError:
logger.warning("invalid_scope_cidr_ignored", cidr=cidr_str)
# Build normalized hostname allowlist from campaign metadata
self._explicit_hosts: set[str] = set()
for raw_target in getattr(campaign, "targets", []):
if isinstance(raw_target, str) and raw_target.strip():
self._explicit_hosts.add(raw_target.strip().lower())
dc = getattr(campaign, "dc", "")
if dc and isinstance(dc, str):
self._explicit_hosts.add(dc.strip().lower())
domain = getattr(campaign, "domain", "")
if domain and isinstance(domain, str):
self._explicit_hosts.add(domain.strip().lower())
# Fast IP lookup cache (bounded to 1024 entries)
self._ip_cache: dict[str, bool] = {}
self._pinned_ip_cache: dict[str, str] = {}
self._blocked_attempts: list[dict[str, Any]] = []
@property
def scope_cidrs(self) -> list[str]:
return [str(net) for net in self._networks]
def _extract_host_and_port(self, address: Any) -> tuple[str, int | None]:
"""Extract sanitized host string and optional port from a socket address."""
if isinstance(address, tuple) and len(address) >= 1:
host = address[0]
port = address[1] if len(address) >= 2 and isinstance(address[1], int) else None
elif isinstance(address, str):
host = address
port = None
elif isinstance(address, bytes):
host = address.decode("utf-8", errors="ignore")
port = None
else:
host = str(address)
port = None
if isinstance(host, bytes):
host = host.decode("utf-8", errors="ignore")
host_str = str(host).strip()
port_val = port
# Handle string forms such as "[::1]:8080" or "10.0.0.1:445"
if port_val is None and ":" in host_str:
if host_str.startswith("[") and "]" in host_str:
parts = host_str.split("]")
host_str = parts[0][1:]
after = parts[1]
if after.startswith(":") and after[1:].isdigit():
port_val = int(after[1:])
elif host_str.count(":") == 1:
h, p = host_str.split(":")
if p.isdigit():
host_str = h
port_val = int(p)
# Strip remaining bracketed IPv6 syntax: "[::1]" -> "::1"
if host_str.startswith("[") and host_str.endswith("]"):
host_str = host_str[1:-1]
# Strip zone identifier: "fe80::1%eth0" -> "fe80::1"
if "%" in host_str:
host_str = host_str.split("%")[0]
return host_str.strip(), port_val
def _is_cloud_allowed(self, host: str) -> bool:
"""Verify if host matches trusted cloud endpoints for cloud modules."""
if self.module_category != "cloud":
return False
lowered = host.lower()
if any(lowered == sfx[1:] or lowered.endswith(sfx) for sfx in CLOUD_DOMAIN_SUFFIXES):
return True
return False
def resolve_and_pin_address(self, address: Any) -> tuple[bool, Any]:
"""Check if destination address is permitted and return pinned address for DNS rebinding protection."""
host, port = self._extract_host_and_port(address)
if not host:
return False, address
lowered_host = host.lower()
# 1. Internal loopback IPC protection
if self.allow_loopback_ipc and lowered_host in _LOOPBACK_HOSTS:
return True, address
# 2. Cloud module domain whitelist (preserves hostname for TLS SNI)
if self._is_cloud_allowed(lowered_host):
return True, address
# 3. Check if host is an IP literal (including IPv4, IPv6, and IPv4-mapped IPv6)
try:
addr = ipaddress.ip_address(lowered_host)
effective_addr = getattr(addr, "ipv4_mapped", None) or addr
if self.allow_loopback_ipc and (addr.is_loopback or effective_addr.is_loopback):
self._ip_cache[lowered_host] = True
return True, address
in_scope = any(
(effective_addr in net if effective_addr.version == net.version else False)
or (addr in net if addr.version == net.version else False)
for net in self._networks
)
if len(self._ip_cache) < 1024:
self._ip_cache[lowered_host] = in_scope
return in_scope, address
except ValueError:
pass # Not an IP literal - proceed to hostname verification
# 4. Check cached pinned resolution
if lowered_host in self._pinned_ip_cache:
pinned_ip = self._pinned_ip_cache[lowered_host]
if isinstance(address, tuple):
if len(address) == 2:
return True, (pinned_ip, address[1])
elif len(address) > 2:
return True, (pinned_ip, address[1], *address[2:])
return True, pinned_ip
if lowered_host in self._ip_cache and not self._ip_cache[lowered_host]:
return False, address
# 5. Hostname DNS resolution with re-entrancy lock
if _in_firewall_resolution.get():
return True, address
_token = _in_firewall_resolution.set(True)
try:
results = socket.getaddrinfo(
lowered_host, port or 0, socket.AF_UNSPEC, socket.SOCK_STREAM
)
if not results:
logger.warning("scope_firewall_dns_empty", host=lowered_host)
if len(self._ip_cache) < 1024:
self._ip_cache[lowered_host] = False
return False, address
# Strict verification: All resolved IPs must be in scope
pinned_ip: str | None = None
for res in results:
raw_ip = res[4][0]
try:
ip_obj = ipaddress.ip_address(raw_ip)
effective_ip = getattr(ip_obj, "ipv4_mapped", None) or ip_obj
in_scope = any(
(effective_ip in net if effective_ip.version == net.version else False)
or (ip_obj in net if ip_obj.version == net.version else False)
for net in self._networks
)
if in_scope:
if pinned_ip is None:
pinned_ip = raw_ip
else:
logger.warning(
"scope_firewall_dns_resolved_out_of_scope",
host=lowered_host,
resolved_ip=raw_ip,
scope=self.scope_cidrs,
)
if len(self._ip_cache) < 1024:
self._ip_cache[lowered_host] = False
return False, address
except ValueError:
if len(self._ip_cache) < 1024:
self._ip_cache[lowered_host] = False
return False, address
if pinned_ip is not None:
if len(self._pinned_ip_cache) < 1024:
self._pinned_ip_cache[lowered_host] = pinned_ip
if len(self._ip_cache) < 1024:
self._ip_cache[lowered_host] = True
if isinstance(address, tuple):
if len(address) == 2:
return True, (pinned_ip, address[1])
elif len(address) > 2:
return True, (pinned_ip, address[1], *address[2:])
return True, pinned_ip
return False, address
except (socket.gaierror, TimeoutError, Exception) as exc:
logger.warning(
"scope_firewall_dns_failed",
host=lowered_host,
error=str(exc)[:100],
)
# Fail closed: If DNS resolution fails, the destination IP cannot be verified or pinned.
return False, address
finally:
_in_firewall_resolution.reset(_token)
def is_allowed_address(self, address: Any) -> bool:
"""Check if destination address is permitted under campaign scope."""
allowed, _ = self.resolve_and_pin_address(address)
return allowed
def assert_allowed_address(self, address: Any) -> Any:
"""Assert address is in scope; raises ScopeFirewallBlockError if not.
Returns pinned address for DNS rebinding protection.
"""
allowed, pinned = self.resolve_and_pin_address(address)
if not allowed:
host, port = self._extract_host_and_port(address)
self._blocked_attempts.append(
{
"host": host,
"port": port,
"module_id": self.module_id,
}
)
audit(
"scope_firewall_blocked",
actor=getattr(self.campaign, "operator", "system"),
campaign=getattr(self.campaign, "id", "")[:8],
module_id=self.module_id,
target=host,
port=port,
scope=self.scope_cidrs,
)
logger.error(
"scope_firewall_blocked_connection",
target=host,
port=port,
module_id=self.module_id,
scope=self.scope_cidrs,
)
raise ScopeFirewallBlockError(
f"[ScopeFirewall] Connection to '{host}:{port or '*'}' BLOCKED: "
f"Destination is outside authorized campaign scope {self.scope_cidrs}.",
target_host=host,
target_port=port,
module_id=self.module_id,
scope_cidrs=self.scope_cidrs,
)
return pinned
# ── Global Socket & Transport Hooks ──────────────────────────────────────────
_orig_socket_connect = socket.socket.connect
_orig_socket_connect_ex = socket.socket.connect_ex
_orig_socket_sendto = socket.socket.sendto
_orig_socket_sendmsg = getattr(socket.socket, "sendmsg", None)
_orig_loop_create_connection = asyncio.base_events.BaseEventLoop.create_connection
_orig_urllib_getproxies = urllib.request.getproxies
_orig_requests_get_environ_proxies: Any = None
_orig_httpx_get_environment_proxies: Any = None
_hooks_installed: bool = False
def _firewall_getproxies() -> dict[str, str]:
if _current_firewall.get() is not None:
return {}
return _orig_urllib_getproxies()
def _firewall_requests_get_environ_proxies(url: Any, no_proxy: Any = None) -> dict[str, str]:
if _current_firewall.get() is not None:
return {}
if _orig_requests_get_environ_proxies is not None:
return _orig_requests_get_environ_proxies(url, no_proxy=no_proxy)
return {}
def _firewall_httpx_get_environment_proxies() -> dict[str, Any]:
if _current_firewall.get() is not None:
return {}
if _orig_httpx_get_environment_proxies is not None:
return _orig_httpx_get_environment_proxies()
return {}
@functools.wraps(_orig_socket_connect)
def _firewall_socket_connect(self: socket.socket, address: Any) -> None:
fw = _current_firewall.get()
target_address = address
if fw is not None and not _in_firewall_resolution.get():
pinned = fw.assert_allowed_address(address)
if pinned is not None:
target_address = pinned
return _orig_socket_connect(self, target_address)
@functools.wraps(_orig_socket_connect_ex)
def _firewall_socket_connect_ex(self: socket.socket, address: Any) -> int:
fw = _current_firewall.get()
target_address = address
if fw is not None and not _in_firewall_resolution.get():
pinned = fw.assert_allowed_address(address)
if pinned is not None:
target_address = pinned
return _orig_socket_connect_ex(self, target_address)
@functools.wraps(_orig_socket_sendto)
def _firewall_socket_sendto(self: socket.socket, data: Any, *args: Any) -> int:
fw = _current_firewall.get()
new_args = list(args)
if fw is not None and not _in_firewall_resolution.get() and new_args:
address = new_args[-1]
if address is not None:
pinned = fw.assert_allowed_address(address)
if pinned is not None:
new_args[-1] = pinned
return _orig_socket_sendto(self, data, *new_args)
if _orig_socket_sendmsg is not None:
@functools.wraps(_orig_socket_sendmsg)
def _firewall_socket_sendmsg(
self: socket.socket, buffers: Any, *args: Any, **kwargs: Any
) -> int:
fw = _current_firewall.get()
if fw is not None and not _in_firewall_resolution.get():
target_addr = kwargs.get("address")
if target_addr is None and len(args) >= 3:
target_addr = args[2]
if target_addr is not None:
pinned = fw.assert_allowed_address(target_addr)
if "address" in kwargs:
kwargs["address"] = pinned
elif len(args) >= 3:
args_list = list(args)
args_list[2] = pinned
args = tuple(args_list)
return _orig_socket_sendmsg(self, buffers, *args, **kwargs)
@functools.wraps(_orig_loop_create_connection)
async def _firewall_loop_create_connection(
self: asyncio.base_events.BaseEventLoop,
protocol_factory: Any,
host: Any = None,
port: Any = None,
*args: Any,
**kwargs: Any,
) -> tuple[asyncio.Transport, asyncio.Protocol]:
fw = _current_firewall.get()
target_host = host
if fw is not None and not _in_firewall_resolution.get() and host is not None:
pinned = fw.assert_allowed_address((host, port or 0))
if isinstance(pinned, tuple) and len(pinned) >= 2:
target_host = pinned[0]
if kwargs.get("ssl") and "server_hostname" not in kwargs and isinstance(host, str):
kwargs["server_hostname"] = host
return await _orig_loop_create_connection(
self, protocol_factory, target_host, port, *args, **kwargs
)
def install_hooks() -> None:
"""Install process-wide socket and event loop interception hooks."""
global _hooks_installed, _orig_requests_get_environ_proxies, _orig_httpx_get_environment_proxies
if _hooks_installed:
return
socket.socket.connect = _firewall_socket_connect # type: ignore[assignment]
socket.socket.connect_ex = _firewall_socket_connect_ex # type: ignore[assignment]
socket.socket.sendto = _firewall_socket_sendto # type: ignore[assignment]
if _orig_socket_sendmsg is not None:
socket.socket.sendmsg = _firewall_socket_sendmsg
asyncio.base_events.BaseEventLoop.create_connection = (
_firewall_loop_create_connection
)
urllib.request.getproxies = _firewall_getproxies
try:
import requests.utils
if _orig_requests_get_environ_proxies is None:
_orig_requests_get_environ_proxies = requests.utils.get_environ_proxies
requests.utils.get_environ_proxies = _firewall_requests_get_environ_proxies
except (ImportError, AttributeError):
pass
try:
import httpx._utils
if _orig_httpx_get_environment_proxies is None:
_orig_httpx_get_environment_proxies = httpx._utils.get_environment_proxies
httpx._utils.get_environment_proxies = _firewall_httpx_get_environment_proxies
except (ImportError, AttributeError):
pass
_hooks_installed = True
logger.debug("scope_firewall_hooks_installed")
def uninstall_hooks() -> None:
"""Restore original socket and event loop functions."""
global _hooks_installed, _orig_requests_get_environ_proxies, _orig_httpx_get_environment_proxies
if not _hooks_installed:
return
socket.socket.connect = _orig_socket_connect
socket.socket.connect_ex = _orig_socket_connect_ex
socket.socket.sendto = _orig_socket_sendto
if _orig_socket_sendmsg is not None:
socket.socket.sendmsg = _orig_socket_sendmsg
asyncio.base_events.BaseEventLoop.create_connection = (
_orig_loop_create_connection
)
urllib.request.getproxies = _orig_urllib_getproxies
if _orig_requests_get_environ_proxies is not None:
try:
import requests.utils
requests.utils.get_environ_proxies = _orig_requests_get_environ_proxies
except (ImportError, AttributeError):
pass
if _orig_httpx_get_environment_proxies is not None:
try:
import httpx._utils
httpx._utils.get_environment_proxies = _orig_httpx_get_environment_proxies
except (ImportError, AttributeError):
pass
_hooks_installed = False
logger.debug("scope_firewall_hooks_uninstalled")
# ── OS / Kernel Network Firewall Controller ───────────────────────────────────
def compute_out_of_scope_cidrs(
scope_cidrs: list[str],
allow_loopback: bool = True,
include_ipv6: bool = True,
) -> list[str]:
"""Calculate the mathematical complement of in-scope CIDRs in IPv4 and IPv6 address space.
Returns a minimal list of CIDR blocks covering all of IPv4 (0.0.0.0/0) and IPv6 (::/0)
EXCEPT for the in-scope CIDRs and (optionally) the loopback networks (127.0.0.0/8 and ::1/128).
Applying explicit BLOCK rules to this complement set enforces an exact dual-stack
deny-by-default allowlist under Windows Defender Firewall without altering global host policy.
"""
excluded_v4: list[ipaddress.IPv4Network] = []
excluded_v6: list[ipaddress.IPv6Network] = []
if allow_loopback:
excluded_v4.append(ipaddress.ip_network("127.0.0.0/8"))
excluded_v6.append(ipaddress.ip_network("::1/128"))
for c in scope_cidrs:
c_str = str(c).strip()
if not c_str:
continue
try:
net = ipaddress.ip_network(c_str, strict=False)
if isinstance(net, ipaddress.IPv4Network):
excluded_v4.append(net)
elif isinstance(net, ipaddress.IPv6Network):
excluded_v6.append(net)
except ValueError:
pass
# IPv4 complement
current_v4 = [ipaddress.ip_network("0.0.0.0/0")]
for ex in excluded_v4:
next_blocks: list[ipaddress.IPv4Network] = []
for blk in current_v4:
if blk.overlaps(ex):
next_blocks.extend(list(blk.address_exclude(ex)))
else:
next_blocks.append(blk)
current_v4 = next_blocks
res = [str(b) for b in ipaddress.collapse_addresses(current_v4)]
# IPv6 complement
if include_ipv6:
current_v6 = [ipaddress.ip_network("::/0")]
for ex in excluded_v6:
next_v6: list[ipaddress.IPv6Network] = []
for blk in current_v6:
if blk.overlaps(ex):
next_v6.extend(list(blk.address_exclude(ex)))
else:
next_v6.append(blk)
current_v6 = next_v6
res.extend([str(b) for b in ipaddress.collapse_addresses(current_v6)])
return res
class OSFirewallState(str, Enum):
UNINITIALIZED = "UNINITIALIZED"
APPLYING = "APPLYING"
VERIFICATION_FAILED = "VERIFICATION_FAILED"
VERIFIED_ACTIVE = "VERIFIED_ACTIVE"
CLEANUP_PENDING = "CLEANUP_PENDING"
INACTIVE = "INACTIVE"
class OSFirewallController:
"""Controls OS-level / Kernel network packet filtering boundaries.
Interacts directly with native OS packet filtering facilities:
- Windows: Windows Defender Firewall (`netsh advfirewall firewall`)
- Linux: Netfilter (`iptables` / `ip6tables`)
Architectural & Operational Scope:
1. Windows Executable-Path Matching:
Windows Defender Firewall rules are applied via `program=<sys.executable>` and remote IP
complements. Because Windows Firewall CLI does not support per-PID matching, rules apply
to any process executing that exact Python executable during the rule's active lifetime.
Transactional teardown (`finally` and `atexit`) ensures zero orphaned rules.
2. Linux UID-Based Matching:
Linux rules use `-m owner --uid-owner <uid>` when `uid_owner` is provided (e.g. unprivileged
module execution as 'nobody'), or fallback to `-m owner --pid-owner <pid>`.
NOTE: `--uid-owner` is a UID-wide firewall boundary affecting all processes sharing that UID,
not process-tree or namespace isolation.
3. Transactional Safety & State Machine:
Transitions: UNINITIALIZED -> APPLYING -> (verify in OS) -> VERIFIED_ACTIVE -> INACTIVE.
If any subrule fails or fails OS verification, all applied rules in that transaction are rolled
back immediately in reverse order. If cleanup of any rule fails, the rule is retained in
state tracking, transitioning to CLEANUP_PENDING rather than falsely claiming INACTIVE.
"""
_active_rules: set[str] = set()
_rule_cleanups: dict[str, list[list[str]]] = {}
_state: OSFirewallState = OSFirewallState.UNINITIALIZED
_lock = threading.Lock()
@classmethod
def is_elevated(cls) -> bool:
"""Check whether the current Python process has administrative/root privileges."""
if sys.platform == "win32":
try:
import ctypes
return bool(ctypes.windll.shell32.IsUserAnAdmin())
except Exception:
return False
elif sys.platform.startswith("linux") or sys.platform == "darwin":
return getattr(os, "geteuid", lambda: -1)() == 0
return False
@classmethod
def get_status(cls) -> dict[str, Any]:
"""Return operational status and capabilities of the OS-level firewall."""
elevated = cls.is_elevated()
with cls._lock:
active_count = len(cls._active_rules)
rule_list = sorted(cls._active_rules)
state_val = cls._state.value
cleanup_pending = cls._state == OSFirewallState.CLEANUP_PENDING
engine = (
"Windows Defender Firewall (netsh)"
if sys.platform == "win32"
else ("Linux Netfilter (iptables)" if sys.platform.startswith("linux") else "Transport Interceptor")
)
return {
"platform": sys.platform,
"engine": engine,
"elevated": elevated,
"state": state_val,
"os_level_active": elevated and active_count > 0 and cls._state == OSFirewallState.VERIFIED_ACTIVE,
"cleanup_pending": cleanup_pending,
"active_rules_count": active_count,
"active_rules": rule_list,
"fallback_mode": "In-Process Transport Socket Interception",
}
@classmethod
def _verify_subrules(cls, sub_rules: list[tuple[list[str], list[str]]]) -> bool:
"""Query kernel/OS packet filter directly to verify that all applied rules exist in kernel state."""
for apply_cmd, _ in sub_rules:
try:
if sys.platform == "win32":
sub_name = None
for arg in apply_cmd:
if arg.startswith("name="):
sub_name = arg.split("=", 1)[1]
break
if not sub_name:
return False
check_cmd = ["netsh", "advfirewall", "firewall", "show", "rule", f"name={sub_name}"]
res = subprocess.run(check_cmd, capture_output=True, text=True, timeout=5)
if res.returncode != 0 or "no rules match" in res.stdout.lower():
logger.warning("os_firewall_verification_failed_windows", sub_rule=sub_name, output=res.stdout.strip())
return False
elif sys.platform.startswith("linux"):
bin_name = apply_cmd[0]
# apply_cmd format: [bin, "-I", "OUTPUT", pos, *spec]
if len(apply_cmd) >= 4 and apply_cmd[1] == "-I":
check_cmd = [bin_name, "-C", apply_cmd[2]] + apply_cmd[4:]
else:
check_cmd = [bin_name, "-C", "OUTPUT"] + apply_cmd[3:]
res = subprocess.run(check_cmd, capture_output=True, text=True, timeout=5)
if res.returncode != 0:
logger.warning("os_firewall_verification_failed_linux", cmd=check_cmd, error=res.stderr.strip() or res.stdout.strip())
return False
except Exception as exc:
logger.warning("os_firewall_verification_exception", error=str(exc))
return False
return True
@classmethod
def apply_rules(
cls,
campaign: Campaign | None,
scope_cidrs: list[str],
program: str | None = None,
uid_owner: int | str | None = None,
) -> list[str]:
"""Apply OS-level firewall rules restricting outbound egress to scope_cidrs.
If campaign is None with no scope_cidrs, or campaign.scope is unconfigured (None), returns empty list.
If process is not elevated, logs an audit notice and returns an empty list (safe fallback).
"""
if campaign is not None and getattr(campaign, "scope", None) is None:
return []
if campaign is None and not scope_cidrs:
return []
if not cls.is_elevated():
if os.environ.get("ARES_REQUIRE_OS_FIREWALL") == "1":
raise ScopeFirewallBlockError(
"OS-level firewall enforcement required (ARES_REQUIRE_OS_FIREWALL=1), "
"but current process lacks administrative/root privileges."
)
logger.info(
"os_firewall_unprivileged_fallback",
platform=sys.platform,
reason="Process lacks Administrator/root privilege. Enforcing via Transport Socket Interceptor.",
)
return []
with cls._lock:
cls._state = OSFirewallState.APPLYING
rule_token = secrets.token_hex(6)
rule_name = f"ARES_SCOPE_WALL_{rule_token}"
prog = program or sys.executable
sub_rules: list[tuple[list[str], list[str]]] = []
if sys.platform == "win32":
out_of_scope = compute_out_of_scope_cidrs(scope_cidrs, allow_loopback=True, include_ipv6=True)
if not out_of_scope:
with cls._lock:
cls._state = OSFirewallState.INACTIVE if not cls._active_rules else OSFirewallState.VERIFIED_ACTIVE
return []
v4_out = [c for c in out_of_scope if ":" not in c]
v6_out = [c for c in out_of_scope if ":" in c]
batch_size = 40
for i in range(0, len(v4_out), batch_size):
batch = v4_out[i : i + batch_size]
sub_name = f"{rule_name}_v4_{i // batch_size}"
apply_cmd = [
"netsh", "advfirewall", "firewall", "add", "rule",
f"name={sub_name}",
"dir=out",
"action=block",
f"program={prog}",
f"remoteip={','.join(batch)}",
"enable=yes",
]
cleanup_cmd = [
"netsh", "advfirewall", "firewall", "delete", "rule",
f"name={sub_name}",
]
sub_rules.append((apply_cmd, cleanup_cmd))
for j in range(0, len(v6_out), batch_size):
batch = v6_out[j : j + batch_size]
sub_name = f"{rule_name}_v6_{j // batch_size}"
apply_cmd = [
"netsh", "advfirewall", "firewall", "add", "rule",
f"name={sub_name}",
"dir=out",
"action=block",
f"program={prog}",
f"remoteip={','.join(batch)}",
"enable=yes",
]
cleanup_cmd = [
"netsh", "advfirewall", "firewall", "delete", "rule",
f"name={sub_name}",
]
sub_rules.append((apply_cmd, cleanup_cmd))
elif sys.platform.startswith("linux"):
pid = str(os.getpid())
owner_match = ["-m", "owner", "--uid-owner", str(uid_owner)] if uid_owner is not None else ["-m", "owner", "--pid-owner", pid]
v4_scope = [c for c in scope_cidrs if ":" not in c]
v6_scope = [c for c in scope_cidrs if ":" in c]
# IPv4 Netfilter rules: allow loopback, allow scope if any, drop all other from this identity
lo_apply = ["iptables", "-I", "OUTPUT", "1"] + owner_match + ["-o", "lo", "-j", "ACCEPT", "-m", "comment", "--comment", f"{rule_name}_lo"]
lo_cleanup = ["iptables", "-D", "OUTPUT", "-m", "comment", "--comment", f"{rule_name}_lo", "-j", "ACCEPT"]
sub_rules.append((lo_apply, lo_cleanup))
if v4_scope:
scope_apply = ["iptables", "-I", "OUTPUT", "2"] + owner_match + ["-d", ",".join(v4_scope), "-j", "ACCEPT", "-m", "comment", "--comment", f"{rule_name}_scope"]
scope_cleanup = ["iptables", "-D", "OUTPUT", "-m", "comment", "--comment", f"{rule_name}_scope", "-j", "ACCEPT"]
sub_rules.append((scope_apply, scope_cleanup))
drop_pos = "3" if v4_scope else "2"
drop_apply = ["iptables", "-I", "OUTPUT", drop_pos] + owner_match + ["-j", "DROP", "-m", "comment", "--comment", f"{rule_name}_drop"]
drop_cleanup = ["iptables", "-D", "OUTPUT", "-m", "comment", "--comment", f"{rule_name}_drop", "-j", "DROP"]
sub_rules.append((drop_apply, drop_cleanup))
# IPv6 Netfilter rules: only install if v6_scope is provided or if scope_cidrs is explicitly empty (deny-all)
if v6_scope or (campaign is not None and not scope_cidrs):
lo6_apply = ["ip6tables", "-I", "OUTPUT", "1"] + owner_match + ["-o", "lo", "-j", "ACCEPT", "-m", "comment", "--comment", f"{rule_name}_lo6"]
lo6_cleanup = ["ip6tables", "-D", "OUTPUT", "-m", "comment", "--comment", f"{rule_name}_lo6", "-j", "ACCEPT"]
sub_rules.append((lo6_apply, lo6_cleanup))
if v6_scope:
scope6_apply = ["ip6tables", "-I", "OUTPUT", "2"] + owner_match + ["-d", ",".join(v6_scope), "-j", "ACCEPT", "-m", "comment", "--comment", f"{rule_name}_scope6"]
scope6_cleanup = ["ip6tables", "-D", "OUTPUT", "-m", "comment", "--comment", f"{rule_name}_scope6", "-j", "ACCEPT"]
sub_rules.append((scope6_apply, scope6_cleanup))
drop6_pos = "3" if v6_scope else "2"
drop6_apply = ["ip6tables", "-I", "OUTPUT", drop6_pos] + owner_match + ["-j", "DROP", "-m", "comment", "--comment", f"{rule_name}_drop6"]
drop6_cleanup = ["ip6tables", "-D", "OUTPUT", "-m", "comment", "--comment", f"{rule_name}_drop6", "-j", "DROP"]
sub_rules.append((drop6_apply, drop6_cleanup))
applied_cleanups: list[list[str]] = []
all_succeeded = True
for apply_cmd, cleanup_cmd in sub_rules:
try:
res = subprocess.run(apply_cmd, capture_output=True, text=True, timeout=5)
if res.returncode == 0:
applied_cleanups.append(cleanup_cmd)
else:
all_succeeded = False
logger.warning("os_firewall_subrule_failed", rule=rule_name, cmd=apply_cmd, error=res.stderr.strip() or res.stdout.strip())
break
except Exception as exc:
all_succeeded = False
logger.warning("os_firewall_apply_exception", rule=rule_name, error=str(exc))
break
if not all_succeeded or len(applied_cleanups) != len(sub_rules):
failed_rollbacks = []
for cleanup_cmd in reversed(applied_cleanups):
try:
cres = subprocess.run(cleanup_cmd, capture_output=True, text=True, timeout=5)
if cres.returncode != 0:
failed_rollbacks.append(cleanup_cmd)
except Exception:
failed_rollbacks.append(cleanup_cmd)
with cls._lock:
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
if os.environ.get("ARES_REQUIRE_OS_FIREWALL") == "1":
raise ScopeFirewallBlockError(
f"[ScopeFirewall] Transactional OS firewall configuration failed for {rule_name}."
)
return []
# Explicit Verification Phase: Query actual kernel/OS firewall state directly
verified = cls._verify_subrules(sub_rules)
if not verified:
logger.error("os_firewall_verification_failed_rolling_back", rule=rule_name)
failed_rollbacks = []
for cleanup_cmd in reversed(applied_cleanups):
try:
cres = subprocess.run(cleanup_cmd, capture_output=True, text=True, timeout=5)
if cres.returncode != 0:
failed_rollbacks.append(cleanup_cmd)
except Exception:
failed_rollbacks.append(cleanup_cmd)
with cls._lock:
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.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."
)
return []
with cls._lock:
cls._active_rules.add(rule_name)
cls._rule_cleanups[rule_name] = applied_cleanups
cls._state = OSFirewallState.VERIFIED_ACTIVE
logger.info(
"os_firewall_transaction_committed",
rule=rule_name,
sub_rules_count=len(applied_cleanups),
platform=sys.platform,
)
return [rule_name]
@classmethod
def remove_rules(cls, rule_ids: list[str]) -> int:
"""Remove previously created OS firewall rules using exact recorded cleanups.
State invariant: Rules and cleanup commands are ONLY removed from internal
tracking after cleanup has succeeded in the OS. If any cleanup command fails,
the rule is retained, state becomes CLEANUP_PENDING, and retry remains possible.
"""
removed = 0
with cls._lock:
rules_to_process = list(rule_ids)
for rule_name in rules_to_process:
with cls._lock:
cleanups = list(cls._rule_cleanups.get(rule_name, []))
failed_cleanups: list[list[str]] = []
if cleanups:
for cleanup_cmd in reversed(cleanups):
try:
res = subprocess.run(cleanup_cmd, capture_output=True, text=True, timeout=5)
if res.returncode == 0:
removed += 1
else:
failed_cleanups.append(cleanup_cmd)
logger.warning(
"os_firewall_cleanup_failed",
rule=rule_name,
cmd=cleanup_cmd,
error=res.stderr.strip() or res.stdout.strip(),
)
except Exception as exc:
failed_cleanups.append(cleanup_cmd)
logger.warning("os_firewall_cleanup_exception", rule=rule_name, cmd=cleanup_cmd, error=str(exc))
else:
try:
if sys.platform == "win32":
cmd = ["netsh", "advfirewall", "firewall", "delete", "rule", f"name={rule_name}"]
res = subprocess.run(cmd, capture_output=True, text=True, timeout=5)
if res.returncode == 0:
removed += 1
else:
failed_cleanups.append(cmd)
elif sys.platform.startswith("linux"):
for suffix in ("_lo", "_scope", "_drop", ""):
comment = f"{rule_name}{suffix}"
for action in ("ACCEPT", "DROP"):
cmd = ["iptables", "-D", "OUTPUT", "-m", "comment", "--comment", comment, "-j", action]
res = subprocess.run(cmd, capture_output=True, text=True, timeout=5)
if res.returncode == 0:
removed += 1
except Exception as exc:
logger.warning("os_firewall_remove_fallback_failed", rule=rule_name, error=str(exc))
with cls._lock:
if failed_cleanups:
cls._rule_cleanups[rule_name] = failed_cleanups
cls._active_rules.add(rule_name)
cls._state = OSFirewallState.CLEANUP_PENDING
logger.warning(
"os_firewall_rule_cleanup_incomplete_retained",
rule=rule_name,
remaining_commands=len(failed_cleanups),
)
else:
cls._rule_cleanups.pop(rule_name, None)
cls._active_rules.discard(rule_name)
if not cls._active_rules:
cls._state = OSFirewallState.INACTIVE
elif cls._state != OSFirewallState.CLEANUP_PENDING:
cls._state = OSFirewallState.VERIFIED_ACTIVE
if removed > 0:
logger.info("os_firewall_rules_removed", count=removed)
return removed
@classmethod
def cleanup_all(cls) -> None:
"""Emergency cleanup handler executed at exit to retry and guarantee zero orphaned OS rules."""
with cls._lock:
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)
def get_os_firewall_status() -> dict[str, Any]:
"""Public helper to inspect OS-level firewall status and active rules."""
return OSFirewallController.get_status()
# ── Context Managers ─────────────────────────────────────────────────────────
_PROXY_KEYS: tuple[str, ...] = (
"HTTP_PROXY",
"HTTPS_PROXY",
"ALL_PROXY",
"http_proxy",
"https_proxy",
"all_proxy",
)
_proxy_lock = threading.Lock()
_proxy_guard_count = 0
_saved_global_proxies: dict[str, str] = {}
def _enter_proxy_neutralization() -> None:
"""Thread-safe proxy neutralization for optional process-global mode."""
if os.environ.get("ARES_GLOBAL_PROXY_NEUTRALIZE") != "1":
return
global _proxy_guard_count
with _proxy_lock:
if _proxy_guard_count == 0:
for k in _PROXY_KEYS:
if k in os.environ:
_saved_global_proxies[k] = os.environ.pop(k)
_proxy_guard_count += 1
def _exit_proxy_neutralization() -> None:
"""Restore proxy environment variables once all active firewall contexts exit."""
if os.environ.get("ARES_GLOBAL_PROXY_NEUTRALIZE") != "1":
return
global _proxy_guard_count
with _proxy_lock:
_proxy_guard_count = max(0, _proxy_guard_count - 1)
if _proxy_guard_count == 0:
for k, v in _saved_global_proxies.items():
os.environ[k] = v
_saved_global_proxies.clear()
@contextlib.asynccontextmanager
async def scope_firewall_guard(
campaign: Campaign | None,
module_id: str = "",
module_category: str = "",
enabled: bool | None = None,
enable_os_firewall: bool | None = None,
uid_owner: int | str | None = None,
strict_mode: bool = False,
) -> AsyncGenerator[ScopeFirewall | None, None]:
"""Async context manager activating dual-layer scope firewall."""
scope_env_disabled = os.environ.get("ARES_SCOPE_FIREWALL_ENABLED", "1").lower() in (
"0",
"false",
"no",
)
if enabled is None:
if strict_mode:
# In strict mode, ARES_SCOPE_FIREWALL_ENABLED=0 cannot disable required scope enforcement
enabled = True
else:
enabled = not scope_env_disabled
elif not enabled and strict_mode:
if campaign is not None and getattr(campaign, "scope", None) is not None:
raise ScopeFirewallBlockError(
"[ScopeFirewall] Cannot disable scope enforcement in strict mode when campaign scope is configured."
)
# Distinguish campaign is None vs campaign.scope is None vs campaign.scope == []
# If campaign is None or campaign.scope is None: no scope configured -> yield None
# If campaign.scope == []: explicit empty scope -> MUST deny all external destinations (fail-closed)
if not enabled or campaign is None or getattr(campaign, "scope", None) is None:
yield None
return
os_env_disabled = os.environ.get("ARES_OS_FIREWALL_ENABLED", "1").lower() in (
"0",
"false",
"no",
)
if enable_os_firewall is None:
if strict_mode:
required_os = (uid_owner is not None) or (os.environ.get("ARES_REQUIRE_OS_FIREWALL") == "1")
if required_os and os_env_disabled:
raise ScopeFirewallBlockError(
"[ScopeFirewall] ARES_OS_FIREWALL_ENABLED=0 cannot disable required OS firewall in strict mode."
)
enable_os_firewall = not os_env_disabled
else:
enable_os_firewall = not os_env_disabled
else:
if strict_mode and enable_os_firewall and os_env_disabled:
raise ScopeFirewallBlockError(
"[ScopeFirewall] ARES_OS_FIREWALL_ENABLED=0 cannot disable required OS firewall in strict mode."
)
install_hooks()
fw = ScopeFirewall(
campaign=campaign,
module_id=module_id,
module_category=module_category,
)
token = _current_firewall.set(fw)
os_rules: list[str] = []
proxy_entered = False
try:
try:
if enable_os_firewall:
os_rules = OSFirewallController.apply_rules(
campaign, fw.scope_cidrs, uid_owner=uid_owner
)
# Neutralize proxy environment variables that could route traffic out-of-scope
_enter_proxy_neutralization()
proxy_entered = True
yield fw
finally:
try:
if proxy_entered:
_exit_proxy_neutralization()
finally:
if os_rules:
OSFirewallController.remove_rules(os_rules)
finally:
_current_firewall.reset(token)
@contextlib.contextmanager
def scope_firewall_sync_guard(
campaign: Campaign | None,
module_id: str = "",
module_category: str = "",
enabled: bool | None = None,
enable_os_firewall: bool | None = None,
uid_owner: int | str | None = None,
strict_mode: bool = False,
) -> Generator[ScopeFirewall | None, None, None]:
"""Sync context manager activating dual-layer scope firewall."""
scope_env_disabled = os.environ.get("ARES_SCOPE_FIREWALL_ENABLED", "1").lower() in (
"0",
"false",
"no",
)
if enabled is None:
if strict_mode:
enabled = True
else:
enabled = not scope_env_disabled
elif not enabled and strict_mode:
if campaign is not None and getattr(campaign, "scope", None) is not None:
raise ScopeFirewallBlockError(
"[ScopeFirewall] Cannot disable scope enforcement in strict mode when campaign scope is configured."
)
if not enabled or campaign is None or getattr(campaign, "scope", None) is None:
yield None
return
os_env_disabled = os.environ.get("ARES_OS_FIREWALL_ENABLED", "1").lower() in (
"0",
"false",
"no",
)
if enable_os_firewall is None:
if strict_mode:
required_os = (uid_owner is not None) or (os.environ.get("ARES_REQUIRE_OS_FIREWALL") == "1")
if required_os and os_env_disabled:
raise ScopeFirewallBlockError(
"[ScopeFirewall] ARES_OS_FIREWALL_ENABLED=0 cannot disable required OS firewall in strict mode."
)
enable_os_firewall = not os_env_disabled
else:
enable_os_firewall = not os_env_disabled
else:
if strict_mode and enable_os_firewall and os_env_disabled:
raise ScopeFirewallBlockError(
"[ScopeFirewall] ARES_OS_FIREWALL_ENABLED=0 cannot disable required OS firewall in strict mode."
)
install_hooks()
fw = ScopeFirewall(
campaign=campaign,
module_id=module_id,
module_category=module_category,
)
token = _current_firewall.set(fw)
os_rules: list[str] = []
proxy_entered = False
try:
try:
if enable_os_firewall:
os_rules = OSFirewallController.apply_rules(
campaign, fw.scope_cidrs, uid_owner=uid_owner
)
# Neutralize proxy environment variables that could route traffic out-of-scope
_enter_proxy_neutralization()
proxy_entered = True
yield fw
finally:
try:
if proxy_entered:
_exit_proxy_neutralization()
finally:
if os_rules:
OSFirewallController.remove_rules(os_rules)
finally:
_current_firewall.reset(token)