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
"""
Tests for ARES Dual-Layer Scope Firewall & Egress Network Filter.
Verifies OS-level packet filtering controller, socket-level interception, ContextVar
task isolation, DNS resolution safety, cloud allowlists, and engine integration.
"""
from __future__ import annotations
import asyncio
import socket
from unittest.mock import MagicMock, patch
import pytest
from ares.core.campaign import Campaign, ScopeEntry
from ares.core.config import AresSettings
from ares.core.engine import AresEngine, ModuleStatus, _extract_all_targets
from ares.core.errors import ScopeFirewallBlockError
from ares.core.execution_admission import _mint_test_dispatch_context
from ares.core.scope_firewall import (
OSFirewallController,
ScopeFirewall,
_current_firewall,
get_os_firewall_status,
install_hooks,
scope_firewall_guard,
scope_firewall_sync_guard,
uninstall_hooks,
)
@pytest.fixture
def sample_campaign() -> Campaign:
return Campaign(
name="Firewall Test Campaign",
client="ACME Corp",
scope=[
ScopeEntry(cidr="10.0.0.0/24"),
ScopeEntry(cidr="192.168.1.0/24"),
],
targets=["dc01.acme.local"],
dc="10.0.0.1",
operator="firewall_tester",
)
class TestScopeFirewallCore:
"""Core socket and transport-level firewall interception tests."""
def test_in_scope_allowed(self, sample_campaign: Campaign):
fw = ScopeFirewall(campaign=sample_campaign, module_id="test.module")
assert fw.is_allowed_address(("10.0.0.5", 445)) is True
assert fw.is_allowed_address(("192.168.1.100", 80)) is True
assert fw.is_allowed_address("10.0.0.50") is True
def test_out_of_scope_blocked(self, sample_campaign: Campaign):
fw = ScopeFirewall(campaign=sample_campaign, module_id="test.module")
assert fw.is_allowed_address(("8.8.8.8", 53)) is False
assert fw.is_allowed_address(("10.0.1.5", 445)) is False
assert fw.is_allowed_address(("1.1.1.1", 443)) is False
with pytest.raises(ScopeFirewallBlockError) as exc_info:
fw.assert_allowed_address(("8.8.8.8", 53))
assert exc_info.value.target_host == "8.8.8.8"
assert exc_info.value.target_port == 53
assert exc_info.value.module_id == "test.module"
def test_loopback_allowed(self, sample_campaign: Campaign):
fw = ScopeFirewall(campaign=sample_campaign, module_id="test.module", allow_loopback_ipc=True)
assert fw.is_allowed_address(("127.0.0.1", 5432)) is True
assert fw.is_allowed_address(("localhost", 8000)) is True
assert fw.is_allowed_address(("::1", 9000)) is True
def test_cloud_module_allowlist(self, sample_campaign: Campaign):
cloud_fw = ScopeFirewall(campaign=sample_campaign, module_id="cloud.azure", module_category="cloud")
assert cloud_fw.is_allowed_address(("login.microsoftonline.com", 443)) is True
assert cloud_fw.is_allowed_address(("graph.microsoft.com", 443)) is True
assert cloud_fw.is_allowed_address(("s3.amazonaws.com", 443)) is True
# Non-cloud module trying to access cloud domain outside CIDRs
recon_fw = ScopeFirewall(campaign=sample_campaign, module_id="recon.scan", module_category="recon")
# Assuming login.microsoftonline.com resolves to public IP outside 10.0.0.0/24
assert recon_fw._is_cloud_allowed("login.microsoftonline.com") is False
class TestScopeFirewallInterception:
"""Live socket hook interception and task isolation tests."""
@pytest.mark.asyncio
async def test_socket_connect_intercepted(self, sample_campaign: Campaign):
async with scope_firewall_guard(sample_campaign, module_id="exploit.test"):
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
try:
with pytest.raises(ScopeFirewallBlockError) as exc_info:
s.connect(("8.8.8.8", 443))
assert exc_info.value.target_host == "8.8.8.8"
assert exc_info.value.target_port == 443
finally:
s.close()
@pytest.mark.asyncio
async def test_socket_sendto_intercepted(self, sample_campaign: Campaign):
async with scope_firewall_guard(sample_campaign, module_id="recon.udp"):
s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
try:
with pytest.raises(ScopeFirewallBlockError) as exc_info:
s.sendto(b"ping", ("1.1.1.1", 53))
assert exc_info.value.target_host == "1.1.1.1"
finally:
s.close()
@pytest.mark.asyncio
async def test_socket_connect_ex_intercepted(self, sample_campaign: Campaign):
"""Regression test: connect_ex must be intercepted and raise ScopeFirewallBlockError when out-of-scope."""
async with scope_firewall_guard(sample_campaign, module_id="lateral.ntlm_relay"):
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
try:
with pytest.raises(ScopeFirewallBlockError) as exc_info:
s.connect_ex(("1.1.1.1", 445))
assert exc_info.value.target_host == "1.1.1.1"
assert exc_info.value.target_port == 445
assert exc_info.value.module_id == "lateral.ntlm_relay"
finally:
s.close()
@pytest.mark.asyncio
async def test_socket_sendmsg_intercepted(self, sample_campaign: Campaign):
"""Regression test: sendmsg (if available on platform) must be intercepted."""
if not hasattr(socket.socket, "sendmsg"):
pytest.skip("socket.sendmsg not supported on this platform")
async with scope_firewall_guard(sample_campaign, module_id="recon.sendmsg"):
s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
try:
with pytest.raises(ScopeFirewallBlockError) as exc_info:
s.sendmsg([b"data"], [], 0, ("1.1.1.1", 53))
assert exc_info.value.target_host == "1.1.1.1"
finally:
s.close()
def test_dns_rebinding_address_pinning(self, sample_campaign: Campaign, monkeypatch):
"""Verify that DNS resolution pins the validated IP to prevent DNS rebinding."""
from ares.core.scope_firewall import ScopeFirewall
fw = ScopeFirewall(campaign=sample_campaign, module_id="test.rebinding")
# Mock getaddrinfo to return 10.0.0.99 (in-scope for 10.0.0.0/24)
mock_addrinfo = [
(socket.AF_INET, socket.SOCK_STREAM, 6, "", ("10.0.0.99", 80))
]
monkeypatch.setattr(socket, "getaddrinfo", lambda *args, **kwargs: mock_addrinfo)
allowed, pinned = fw.resolve_and_pin_address(("rebind-target.internal", 80))
assert allowed is True
assert pinned == ("10.0.0.99", 80)
# Subsequent call should return cached pinned IP without re-querying DNS
monkeypatch.setattr(socket, "getaddrinfo", lambda *args, **kwargs: [])
allowed2, pinned2 = fw.resolve_and_pin_address(("rebind-target.internal", 80))
assert allowed2 is True
assert pinned2 == ("10.0.0.99", 80)
@pytest.mark.asyncio
async def test_asyncio_create_connection_intercepted(self, sample_campaign: Campaign):
loop = asyncio.get_running_loop()
async with scope_firewall_guard(sample_campaign, module_id="async.test"):
with pytest.raises(ScopeFirewallBlockError) as exc_info:
await loop.create_connection(asyncio.Protocol, host="8.8.8.8", port=80)
assert exc_info.value.target_host == "8.8.8.8"
@pytest.mark.asyncio
async def test_task_isolation_zero_bleed(self, sample_campaign: Campaign):
"""
Verify that background tasks (e.g. database pool, telemetry) running concurrently
do NOT have firewall restrictions applied to them.
"""
results = {"guarded_blocked": False, "unguarded_success": False}
async def background_unrelated_task():
# Simulated database or internal task
# _current_firewall ContextVar should be None here
fw = _current_firewall.get()
if fw is None:
results["unguarded_success"] = True
async def attack_module_task():
async with scope_firewall_guard(sample_campaign, module_id="lateral.psexec"):
fw = _current_firewall.get()
if fw is not None:
try:
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
s.connect(("8.8.4.4", 80))
s.close()
except ScopeFirewallBlockError:
results["guarded_blocked"] = True
await asyncio.gather(attack_module_task(), background_unrelated_task())
assert results["guarded_blocked"] is True
assert results["unguarded_success"] is True
def test_sync_guard(self, sample_campaign: Campaign):
with scope_firewall_sync_guard(sample_campaign, module_id="sync.test"):
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
try:
with pytest.raises(ScopeFirewallBlockError):
s.connect(("172.217.16.206", 80))
finally:
s.close()
def test_unhook_cleanup(self):
install_hooks()
uninstall_hooks()
# Verify socket.socket.connect is restored and can be invoked without ScopeFirewall
assert _current_firewall.get() is None
class TestEngineIntegration:
"""Engine pre-check and recursive parameter target extraction tests."""
def test_target_extraction(self):
params = {
"target": "10.0.0.1",
"dc": "10.0.0.2",
"rhosts": "10.0.0.3, 10.0.0.4",
"nested": {
"server": "https://10.0.0.5:8443/login",
"other_param": "some_value",
},
"targets": ["10.0.0.6", "10.0.0.7:445"],
}
targets = _extract_all_targets(params)
expected = ["10.0.0.1", "10.0.0.2", "10.0.0.3", "10.0.0.4", "10.0.0.5", "10.0.0.6", "10.0.0.7"]
for exp in expected:
assert exp in targets
@pytest.mark.asyncio
async def test_recon_module_precheck_enforced(self, sample_campaign: Campaign):
settings = AresSettings(
ares_secret_key="test-secret-key-min32-chars-xxxxxx",
ares_encryption_key="test-enc-key-min32-chars-xxxxxxx",
ares_default_admin_password="TestPass123!",
)
engine = AresEngine(settings=settings)
# Mock a recon module in registry
mock_recon_cls = MagicMock()
mock_recon_cls.MODULE_CATEGORY = "recon"
engine.registry["test.recon"] = mock_recon_cls
# Attempt to run recon against out-of-scope target
result = await engine.run_module(
module_id="test.recon",
campaign=sample_campaign,
params={"target": "8.8.8.8"},
actor_role="team_lead",
skip_validation=True,
dispatch_context=_mint_test_dispatch_context(engine, sample_campaign.id, "test.recon"),
)
assert result.status == ModuleStatus.FAILED
assert "not in campaign scope" in (result.error or "")
@pytest.mark.asyncio
async def test_module_firewall_block_audit(self, sample_campaign: Campaign):
settings = AresSettings(
ares_secret_key="test-secret-key-min32-chars-xxxxxx",
ares_encryption_key="test-enc-key-min32-chars-xxxxxxx",
ares_default_admin_password="TestPass123!",
)
engine = AresEngine(settings=settings)
class OutOfScopeAttacker:
MODULE_CATEGORY = "lateral"
def __init__(self, **kwargs):
pass
async def validate(self, ctx):
pass
async def execute(self, ctx):
# Try to connect to out-of-scope IP directly
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
try:
s.connect(("8.8.8.8", 445))
finally:
s.close()
return MagicMock(findings=[], raw={})
engine.registry["lateral.attacker"] = OutOfScopeAttacker
# Pass target that passes pre-check (in scope), but module secretly attacks 8.8.8.8!
result = await engine.run_module(
module_id="lateral.attacker",
campaign=sample_campaign,
params={"target": "10.0.0.5"},
skip_validation=True,
dispatch_context=_mint_test_dispatch_context(engine, sample_campaign.id, "lateral.attacker"),
)
assert result.status == ModuleStatus.FAILED
assert result.outcome == "scope_firewall_blocked"
assert "[ScopeFirewall]" in (result.error or "")
class TestOSFirewallController:
"""Tests for native OS / Kernel packet filtering controller."""
def test_status_reporting(self):
status = get_os_firewall_status()
assert "platform" in status
assert "engine" in status
assert "elevated" in status
assert "fallback_mode" in status
assert status["fallback_mode"] == "In-Process Transport Socket Interception"
def test_unprivileged_fallback_produces_no_errors(self, sample_campaign: Campaign):
with patch.object(OSFirewallController, "is_elevated", return_value=False):
rules = OSFirewallController.apply_rules(sample_campaign, ["10.0.0.0/24"])
assert rules == []
status = OSFirewallController.get_status()
assert status["elevated"] is False
assert status["active_rules_count"] == 0
def test_windows_elevated_rule_application_and_cleanup(self, sample_campaign: Campaign):
OSFirewallController._active_rules.clear()
with (
patch.object(OSFirewallController, "is_elevated", return_value=True),
patch("sys.platform", "win32"),
patch("subprocess.run") as mock_run,
):
mock_run.return_value = MagicMock(returncode=0, stdout="Ok.", stderr="")
rules = OSFirewallController.apply_rules(sample_campaign, ["10.0.0.0/24", "192.168.1.0/24"])
assert len(rules) == 1
assert rules[0].startswith("ARES_SCOPE_WALL_")
assert mock_run.call_count >= 1
all_cmds = [call[0][0] for call in mock_run.call_args_list]
assert any(cmd[0] == "netsh" and "action=block" in cmd for cmd in all_cmds)
# Verify cleanup
mock_run.reset_mock()
removed = OSFirewallController.remove_rules(rules)
assert removed >= 1
del_cmds = [call[0][0] for call in mock_run.call_args_list]
assert any(cmd[0] == "netsh" and "delete" in cmd for cmd in del_cmds)
assert len(OSFirewallController._active_rules) == 0
def test_linux_elevated_rule_application_and_cleanup(self, sample_campaign: Campaign):
OSFirewallController._active_rules.clear()
with (
patch.object(OSFirewallController, "is_elevated", return_value=True),
patch("sys.platform", "linux"),
patch("os.getpid", return_value=12345),
patch("subprocess.run") as mock_run,
):
mock_run.return_value = MagicMock(returncode=0, stdout="", stderr="")
rules = OSFirewallController.apply_rules(sample_campaign, ["172.16.0.0/16"])
assert len(rules) == 1
assert rules[0].startswith("ARES_SCOPE_WALL_")
all_cmds = [call[0][0] for call in mock_run.call_args_list]
assert any(cmd[0] == "iptables" and "-d" in cmd and "172.16.0.0/16" in cmd for cmd in all_cmds)
assert any(cmd[0] == "iptables" and "-j" in cmd and "DROP" in cmd for cmd in all_cmds)
removed = OSFirewallController.remove_rules(rules)
assert removed == 3
assert len(OSFirewallController._active_rules) == 0
def test_scope_firewall_guard_wires_os_firewall(self, sample_campaign: Campaign):
with (
patch.object(OSFirewallController, "apply_rules", return_value=["ARES_SCOPE_WALL_test"]) as mock_apply,
patch.object(OSFirewallController, "remove_rules") as mock_remove,
):
with scope_firewall_sync_guard(sample_campaign, enable_os_firewall=True) as fw:
assert fw is not None
mock_apply.assert_called_once()
mock_remove.assert_called_once_with(["ARES_SCOPE_WALL_test"])
def test_bracketed_ipv6_and_zone_id_parsing(self, sample_campaign: Campaign):
fw = ScopeFirewall(campaign=sample_campaign, module_id="test.ipv6", allow_loopback_ipc=True)
# Bracketed loopback
assert fw.is_allowed_address("[::1]") is True
assert fw.is_allowed_address(("[::1]", 8080)) is True
assert fw.is_allowed_address("[::1]:8080") is True
# Zone index stripping
assert fw.is_allowed_address("[::1%eth0]:9000") is True
# Bracketed out-of-scope IPv6
assert fw.is_allowed_address("[2001:db8::1]") is False
assert fw.is_allowed_address(("[2001:db8::1]", 443)) is False
def test_ipv4_mapped_ipv6_scope_enforcement(self, sample_campaign: Campaign):
fw = ScopeFirewall(campaign=sample_campaign, module_id="test.ipv4_mapped")
# In-scope: 10.0.0.5 is in 10.0.0.0/24
assert fw.is_allowed_address("::ffff:10.0.0.5") is True
assert fw.is_allowed_address(("::ffff:10.0.0.5", 445)) is True
# Out-of-scope: 8.8.8.8 is outside 10.0.0.0/24 and 192.168.1.0/24
assert fw.is_allowed_address("::ffff:8.8.8.8") is False
assert fw.is_allowed_address(("::ffff:8.8.8.8", 53)) is False
def test_proxy_environment_variables_neutralized_during_guard(self, sample_campaign: Campaign, monkeypatch: pytest.MonkeyPatch):
import os
import urllib.request
from ares.core.scope_firewall import _firewall_getproxies
os.environ["HTTP_PROXY"] = "http://127.0.0.1:8080"
os.environ["HTTPS_PROXY"] = "http://127.0.0.1:8443"
try:
# 1. Task-local isolation mode (default: os.environ is NOT mutated to avoid clobbering concurrent tasks)
with scope_firewall_sync_guard(sample_campaign) as fw:
assert fw is not None
# urllib proxy getter hooked to return {} when inside guard
assert _firewall_getproxies() == {}
assert urllib.request.getproxies() == {}
# Unrelated task looking at os.environ directly is not clobbered
assert os.environ.get("HTTP_PROXY") == "http://127.0.0.1:8080"
# 2. Process-global mode (opt-in via ARES_GLOBAL_PROXY_NEUTRALIZE=1)
monkeypatch.setenv("ARES_GLOBAL_PROXY_NEUTRALIZE", "1")
with scope_firewall_sync_guard(sample_campaign) as fw:
assert fw is not None
assert "HTTP_PROXY" not in os.environ
assert "HTTPS_PROXY" not in os.environ
assert urllib.request.getproxies() == {}
# Nested guard must not clobber outer saved proxies
with scope_firewall_sync_guard(sample_campaign) as inner_fw:
assert inner_fw is not None
assert "HTTP_PROXY" not in os.environ
assert "HTTP_PROXY" not in os.environ
# Restored upon exit of global mode
assert os.environ.get("HTTP_PROXY") == "http://127.0.0.1:8080"
assert os.environ.get("HTTPS_PROXY") == "http://127.0.0.1:8443"
finally:
os.environ.pop("HTTP_PROXY", None)
os.environ.pop("HTTPS_PROXY", None)
def test_scope_firewall_dns_failure_fails_closed(self, sample_campaign: Campaign, monkeypatch: pytest.MonkeyPatch):
"""If DNS resolution fails, the address must fail-closed (False) even if hostname is in explicit_hosts."""
fw = ScopeFirewall(campaign=sample_campaign, module_id="test.dns_fail")
def mock_getaddrinfo(*args, **kwargs):
raise socket.gaierror(-2, "Name or service not known")
monkeypatch.setattr(socket, "getaddrinfo", mock_getaddrinfo)
allowed, pinned = fw.resolve_and_pin_address("unresolvable.in-targets.local")
assert allowed is False
def test_compute_out_of_scope_cidrs(self):
"""Mathematical complement must cover all of IPv4 except scope and loopback."""
import ipaddress
from ares.core.scope_firewall import compute_out_of_scope_cidrs
scope = ["10.0.0.0/24"]
comp = compute_out_of_scope_cidrs(scope, allow_loopback=True)
assert len(comp) > 0
# In-scope must NOT be in complement
in_scope = ipaddress.ip_address("10.0.0.45")
assert not any(in_scope in ipaddress.ip_network(c) for c in comp)
# Loopback must NOT be in complement
loopback = ipaddress.ip_address("127.0.0.1")
assert not any(loopback in ipaddress.ip_network(c) for c in comp)
# Out-of-scope MUST be in complement
out_scope = ipaddress.ip_address("8.8.8.8")
assert any(out_scope in ipaddress.ip_network(c) for c in comp)
def test_os_firewall_windows_strict_block_complement(self, monkeypatch: pytest.MonkeyPatch):
"""Windows OS firewall must apply explicit block rules for complement CIDRs."""
import subprocess
import sys
from ares.core.scope_firewall import OSFirewallController
commands_executed: list[list[str]] = []
def mock_run(cmd, *args, **kwargs):
commands_executed.append(list(cmd))
class MockRes:
returncode = 0
stdout = ""
stderr = ""
return MockRes()
monkeypatch.setattr(subprocess, "run", mock_run)
monkeypatch.setattr(OSFirewallController, "is_elevated", lambda: True)
monkeypatch.setattr(sys, "platform", "win32")
rules = OSFirewallController.apply_rules(None, ["10.0.0.0/24"], program="python.exe")
assert len(rules) == 1
rule_name = rules[0]
# Verify that an explicit action=block rule was created for python.exe
assert any(
"netsh" in cmd and "action=block" in cmd and "program=python.exe" in cmd
for cmd in commands_executed
)
# Verify cleanup
commands_executed.clear()
removed = OSFirewallController.remove_rules([rule_name])
assert removed >= 1
assert any("delete" in cmd and "rule" in cmd for cmd in commands_executed)
def test_os_firewall_linux_strict_allowlist_commands(self, monkeypatch: pytest.MonkeyPatch):
"""Linux OS firewall must apply lo ACCEPT, scope ACCEPT, and process DROP rules."""
import subprocess
import sys
from ares.core.scope_firewall import OSFirewallController
commands_executed: list[list[str]] = []
def mock_run(cmd, *args, **kwargs):
commands_executed.append(list(cmd))
class MockRes:
returncode = 0
stdout = ""
stderr = ""
return MockRes()
monkeypatch.setattr(subprocess, "run", mock_run)
monkeypatch.setattr(OSFirewallController, "is_elevated", lambda: True)
monkeypatch.setattr(sys, "platform", "linux")
rules = OSFirewallController.apply_rules(None, ["10.0.0.0/24"], program="/usr/bin/python3")
assert len(rules) == 1
rule_name = rules[0]
# Verify that all 3 rules were applied with distinct comments:
assert any(
"-o" in cmd and "lo" in cmd and "-j" in cmd and "ACCEPT" in cmd and f"{rule_name}_lo" in cmd
for cmd in commands_executed
)
assert any(
"-d" in cmd and "10.0.0.0/24" in cmd and "-j" in cmd and "ACCEPT" in cmd and f"{rule_name}_scope" in cmd
for cmd in commands_executed
)
assert any(
"-j" in cmd and "DROP" in cmd and f"{rule_name}_drop" in cmd
for cmd in commands_executed
)
# Verify exact cleanup
commands_executed.clear()
removed = OSFirewallController.remove_rules([rule_name])
assert removed == 3
assert len([c for c in commands_executed if "iptables" in c and "-D" in c]) == 3
def test_os_firewall_transactional_rollback_on_failure(self, monkeypatch: pytest.MonkeyPatch):
"""If any sub-rule fails during application, all previously applied sub-rules must roll back."""
import subprocess
import sys
from ares.core.scope_firewall import OSFirewallController
applied_commands: list[list[str]] = []
cleanup_commands: list[list[str]] = []
def mock_run(cmd, *args, **kwargs):
cmd_list = list(cmd)
# Fail on the 3rd rule (DROP rule)
if "-j" in cmd_list and "DROP" in cmd_list and "-I" in cmd_list:
class FailRes:
returncode = 1
stdout = ""
stderr = "iptables: Permission denied on DROP"
return FailRes()
if "-D" in cmd_list:
cleanup_commands.append(cmd_list)
else:
applied_commands.append(cmd_list)
class OkRes:
returncode = 0
stdout = ""
stderr = ""
return OkRes()
monkeypatch.setattr(subprocess, "run", mock_run)
monkeypatch.setattr(OSFirewallController, "is_elevated", lambda: True)
monkeypatch.setattr(sys, "platform", "linux")
# Before apply: 0 rules
assert len(OSFirewallController._active_rules) == 0
rules = OSFirewallController.apply_rules(None, ["10.0.0.0/24"])
# Failed transaction must return empty list
assert rules == []
# Active rules must remain 0
assert len(OSFirewallController._active_rules) == 0
# Previously applied sub-rules (lo and scope) must have been rolled back
assert len(cleanup_commands) == 2