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
"""
Step 1 - Unit Tests: Core Infrastructure
Tests for the foundation that every module depends on:
- AresDatabase (SQLite) - CRUD, encryption, bypass outcomes
- CredentialVault - encrypt/decrypt round-trip, privilege scoring
- Campaign - scope enforcement, finding management, noise profiles
- Security - sanitize_path whitelist, sanitize_hostname, DataEncryptor
- NoiseController - jitter, rate limiting
- AresContainer (DI) - registration, retrieval, factory, module building
Run: pytest tests/unit/test_core_infrastructure.py -v
"""
from __future__ import annotations
import sys
import time
from pathlib import Path
import pytest
# Ensure project root is on path
_ROOT = Path(__file__).parent.parent.parent.resolve()
if str(_ROOT) not in sys.path:
sys.path.insert(0, str(_ROOT))
# ═══════════════════════════════════════════════════════════════════════════════
# 1. AresDatabase - SQLite async CRUD
# ═══════════════════════════════════════════════════════════════════════════════
class TestAresDatabase:
"""Test async SQLite database operations."""
@pytest.fixture
async def db(self, tmp_path):
"""Create fresh in-memory database for each test."""
from ares.db.database import AresDatabase
db_url = str(tmp_path / "test.db")
enc_key = "test-encryption-key-32-chars-xx!"
db = await AresDatabase.create(db_url, enc_key)
yield db
await db.close()
@pytest.mark.asyncio
async def test_create_and_connect(self, tmp_path):
"""DB should create, connect, and initialize schema."""
from ares.db.database import AresDatabase
db_url = str(tmp_path / "fresh.db")
db = await AresDatabase.create(db_url, "test-key-32-chars-placeholder-xx!")
assert db._conn is not None
await db.close()
@pytest.mark.asyncio
async def test_save_and_get_campaign(self, db):
"""Save campaign then retrieve it."""
from ares.core.campaign import Campaign, NoiseProfile, ScopeEntry
c = Campaign(
name="TestOp", client="ACME", operator="tester",
scope=[ScopeEntry(cidr="10.0.0.0/24")],
noise_profile=NoiseProfile.NORMAL,
)
await db.save_campaign(c)
row = await db.get_campaign(c.id)
assert row is not None
assert row["name"] == "TestOp"
assert row["client"] == "ACME"
@pytest.mark.asyncio
async def test_save_campaign_upsert_refreshes_persisted_fields(self, db):
"""Saving an existing campaign should refresh every persisted campaign field."""
import json
from ares.core.campaign import Campaign, NoiseProfile, ScopeEntry
c = Campaign(
name="TestOp", client="ACME", operator="tester",
scope=[ScopeEntry(cidr="10.0.0.0/24")],
noise_profile=NoiseProfile.NORMAL,
targets=["10.0.0.5"],
)
await db.save_campaign(c)
c.operator = "second-operator"
c.noise_profile = NoiseProfile.AGGRESSIVE
c.scope = [ScopeEntry(cidr="192.168.10.0/24")]
c.targets = ["192.168.10.5"]
await db.save_campaign(c)
row = await db.get_campaign(c.id)
assert row is not None
assert row["operator"] == "second-operator"
assert row["noise_profile"] == NoiseProfile.AGGRESSIVE.value
assert json.loads(row["scope_json"])[0]["cidr"] == "192.168.10.0/24"
assert json.loads(row["targets_json"]) == ["192.168.10.5"]
@pytest.mark.asyncio
async def test_get_nonexistent_campaign(self, db):
"""Fetching a campaign that doesn't exist should return None."""
row = await db.get_campaign("nonexistent-id")
assert row is None
@pytest.mark.asyncio
async def test_list_campaigns_pagination(self, db):
"""List campaigns with pagination."""
from ares.core.campaign import Campaign, NoiseProfile, ScopeEntry
for i in range(5):
c = Campaign(name=f"Camp{i}", scope=[ScopeEntry(cidr="10.0.0.0/8")],
noise_profile=NoiseProfile.NORMAL)
await db.save_campaign(c)
rows, total = await db.list_campaigns(page=1, per_page=3)
assert total == 5
assert len(rows) == 3
rows2, _ = await db.list_campaigns(page=2, per_page=3)
assert len(rows2) == 2
@pytest.mark.asyncio
async def test_save_and_get_finding(self, db):
"""Save finding then retrieve it."""
from ares.core.campaign import Campaign, Finding, NoiseProfile, ScopeEntry, Severity
c = Campaign(name="FindTest", scope=[ScopeEntry(cidr="10.0.0.0/8")],
noise_profile=NoiseProfile.NORMAL)
await db.save_campaign(c)
f = Finding(
title="Test Finding", description="Test desc",
severity=Severity.HIGH, confidence=0.9,
module_id="ad.kerberoast", host="10.0.0.1",
evidence="hash captured", remediation="rotate password",
mitre_technique="T1558.003", mitre_tactic="Credential Access",
)
await db.save_finding(c.id, f, module_id="ad.kerberoast")
findings = await db.get_findings(c.id)
assert len(findings) >= 1
assert findings[0]["title"] == "Test Finding"
@pytest.mark.asyncio
async def test_finding_stats(self, db):
"""Finding stats should count by severity."""
from ares.core.campaign import Campaign, Finding, NoiseProfile, ScopeEntry, Severity
c = Campaign(name="StatsTest", scope=[ScopeEntry(cidr="10.0.0.0/8")],
noise_profile=NoiseProfile.NORMAL)
await db.save_campaign(c)
for sev in [Severity.CRITICAL, Severity.HIGH, Severity.HIGH, Severity.LOW]:
f = Finding(title=f"F-{sev.value}", description="d", severity=sev,
confidence=0.9, module_id="test", host="10.0.0.1")
await db.save_finding(c.id, f)
stats = await db.get_finding_stats(c.id)
assert stats["critical"] == 1
assert stats["high"] == 2
assert stats["low"] == 1
@pytest.mark.asyncio
async def test_delete_campaign_cascades_children(self, db):
"""Deleting a campaign should remove its stored child data."""
from ares.core.campaign import Campaign, Finding, NoiseProfile, ScopeEntry, Severity
from ares.db.database import DBCredential, Host, Loot
c = Campaign(name="DeleteCascade", scope=[ScopeEntry(cidr="10.0.0.0/8")],
noise_profile=NoiseProfile.NORMAL)
await db.save_campaign(c)
finding = Finding(title="Delete Finding", description="d",
severity=Severity.HIGH, confidence=0.9,
module_id="test", host="10.0.0.5")
await db.save_finding(c.id, finding)
host = Host(campaign_id=c.id, ip_address="10.0.0.5", hostname="SRV01")
await db.upsert_host(host)
await db.save_credential(DBCredential(
campaign_id=c.id,
host_id=host.id,
username="admin",
secret="Secret123!",
cred_type="password",
))
await db.save_loot(Loot(
campaign_id=c.id,
host_id=host.id,
loot_type="file",
name="loot.txt",
content="sample",
))
assert await db.delete_campaign(c.id) is True
assert await db.get_campaign(c.id) is None
assert await db.get_findings(c.id) == []
assert await db.get_hosts(c.id) == []
assert await db.get_credentials(c.id) == []
assert await db.get_loot(c.id) == []
assert await db.delete_campaign(c.id) is False
@pytest.mark.asyncio
async def test_ensure_default_admin(self, db):
"""Default admin user should be created."""
created = await db.ensure_default_admin("TestAdmin123!")
assert created is True
user = await db.get_user("admin")
assert user is not None
assert user["role"] == "team_lead"
@pytest.mark.asyncio
async def test_verify_user_correct_password(self, db):
"""Correct password should verify successfully."""
await db.ensure_default_admin("CorrectPass1!")
user = await db.verify_user("admin", "CorrectPass1!")
assert user is not None
assert user["username"] == "admin"
@pytest.mark.asyncio
async def test_verify_user_wrong_password(self, db):
"""Wrong password should return None."""
await db.ensure_default_admin("RightPass1!")
user = await db.verify_user("admin", "WrongPass!")
assert user is None
@pytest.mark.asyncio
async def test_bypass_outcome_save_and_rate(self, db):
"""Bypass outcomes should persist and return success rates."""
# Save some outcomes
for success in [True, True, False, True]:
await db.save_bypass_outcome(
technique_id="amsi-patch",
edr_vendor="crowdstrike",
edr_version="7.x",
success=success,
campaign_id="test-camp",
)
rate = await db.get_bypass_success_rate("amsi-patch", "crowdstrike", min_samples=2)
assert rate is not None
assert 0.7 <= rate <= 0.8 # 3/4 = 0.75
@pytest.mark.asyncio
async def test_bypass_outcome_min_samples(self, db):
"""Success rate should return None if too few samples."""
await db.save_bypass_outcome("test-tech", "test-edr", "", True, "camp")
rate = await db.get_bypass_success_rate("test-tech", "test-edr", min_samples=5)
assert rate is None
@pytest.mark.asyncio
async def test_host_upsert(self, db):
"""Hosts should be inserted and retrievable."""
from ares.core.campaign import Campaign, NoiseProfile, ScopeEntry
from ares.db.database import Host
# Campaign must exist first (FK constraint)
c = Campaign(id="camp-1", name="HostTest",
scope=[ScopeEntry(cidr="10.0.0.0/8")],
noise_profile=NoiseProfile.NORMAL)
await db.save_campaign(c)
h = Host(campaign_id="camp-1", ip_address="10.0.0.5", hostname="SRV01",
os="Windows Server 2022")
await db.upsert_host(h)
hosts = await db.get_hosts("camp-1")
assert len(hosts) == 1
assert hosts[0]["hostname"] == "SRV01"
@pytest.mark.asyncio
async def test_credential_encryption_roundtrip(self, db):
"""Saved credentials should be decryptable."""
from ares.core.campaign import Campaign, NoiseProfile, ScopeEntry
from ares.db.database import DBCredential
c = Campaign(name="CredTest", scope=[ScopeEntry(cidr="10.0.0.0/8")],
noise_profile=NoiseProfile.NORMAL)
await db.save_campaign(c)
cred = DBCredential(
campaign_id=c.id, username="admin",
secret="SuperSecret123!", cred_type="password",
source_module="ad.kerberoast",
)
await db.save_credential(cred)
creds = await db.get_credentials(c.id, decrypt=True)
assert len(creds) >= 1
# Encrypted value should be decrypted back
assert creds[0]["username"] == "admin"
@pytest.mark.asyncio
async def test_api_key_lifecycle(self, db):
"""Create, verify, list, revoke API key."""
await db.ensure_default_admin("Admin1!")
user = await db.get_user("admin")
uid = user["id"]
key_id, raw_key = await db.create_api_key(uid, "test-key", "admin")
assert raw_key.startswith("ares_")
# Verify
verified = await db.verify_api_key(raw_key)
assert verified is not None
assert verified["username"] == "admin"
# List
keys = await db.list_api_keys(uid)
assert len(keys) >= 1
assert all("key_hash" not in key for key in keys)
assert all("key" not in key and "raw_key" not in key for key in keys)
assert raw_key not in repr(keys)
# Revoke
key_id = keys[0]["id"]
revoked = await db.revoke_api_key(key_id, uid)
assert revoked is True
keys_after_revoke = await db.list_api_keys(uid)
assert all(k["id"] != key_id for k in keys_after_revoke)
# Verify after revoke should fail
verified2 = await db.verify_api_key(raw_key)
assert verified2 is None
@pytest.mark.asyncio
async def test_export_json(self, db, tmp_path):
"""Export should produce valid JSON file."""
from ares.core.campaign import Campaign, NoiseProfile, ScopeEntry
c = Campaign(name="ExportTest", scope=[ScopeEntry(cidr="10.0.0.0/8")],
noise_profile=NoiseProfile.NORMAL)
await db.save_campaign(c)
out_path = str(tmp_path / "export.json")
result = await db.export_json(out_path)
assert Path(result).exists()
import json
data = json.loads(Path(result).read_text())
assert "campaigns" in data
# ═══════════════════════════════════════════════════════════════════════════════
# 2. Campaign - scope enforcement, findings, noise
# ═══════════════════════════════════════════════════════════════════════════════
class TestCampaign:
def test_campaign_creation(self):
from ares.core.campaign import Campaign, NoiseProfile, ScopeEntry
c = Campaign(name="Test", scope=[ScopeEntry(cidr="192.168.1.0/24")],
noise_profile=NoiseProfile.STEALTH)
assert c.id is not None
assert c.name == "Test"
assert c.noise_profile == NoiseProfile.STEALTH
def test_scope_in_range(self):
from ares.core.campaign import Campaign, NoiseProfile, ScopeEntry
c = Campaign(name="T", scope=[ScopeEntry(cidr="10.0.0.0/24")],
noise_profile=NoiseProfile.NORMAL)
assert c.is_in_scope("10.0.0.1") is True
assert c.is_in_scope("10.0.0.254") is True
def test_scope_out_of_range(self):
from ares.core.campaign import Campaign, NoiseProfile, ScopeEntry
c = Campaign(name="T", scope=[ScopeEntry(cidr="10.0.0.0/24")],
noise_profile=NoiseProfile.NORMAL)
assert c.is_in_scope("192.168.1.1") is False
assert c.is_in_scope("10.0.1.1") is False
def test_add_finding(self):
from ares.core.campaign import Campaign, Finding, NoiseProfile, ScopeEntry, Severity
c = Campaign(name="T", scope=[ScopeEntry(cidr="10.0.0.0/8")],
noise_profile=NoiseProfile.NORMAL)
f = Finding(title="Test", description="D", severity=Severity.HIGH,
confidence=0.9, module_id="test", host="10.0.0.1")
c.add_finding(f)
assert len(c.findings) == 1
assert c.findings[0].title == "Test"
def test_confirmed_findings_exclude_false_positives(self):
from ares.core.campaign import Campaign, Finding, NoiseProfile, ScopeEntry, Severity
c = Campaign(name="T", scope=[ScopeEntry(cidr="10.0.0.0/8")],
noise_profile=NoiseProfile.NORMAL)
f1 = Finding(title="Real", description="D", severity=Severity.HIGH,
confidence=0.9, module_id="test", host="10.0.0.1")
f2 = Finding(title="FP", description="D", severity=Severity.HIGH,
confidence=0.9, module_id="test", host="10.0.0.2",
false_positive=True)
c.add_finding(f1)
c.add_finding(f2)
confirmed = c.confirmed_findings()
assert len(confirmed) == 1
assert confirmed[0].title == "Real"
def test_noise_profiles_exist(self):
from ares.core.campaign import NoiseProfile
assert NoiseProfile.STEALTH.value == "stealth"
assert NoiseProfile.NORMAL.value == "normal"
assert NoiseProfile.AGGRESSIVE.value == "aggressive"
# ═══════════════════════════════════════════════════════════════════════════════
# 3. CredentialVault - encryption/decryption
# ═══════════════════════════════════════════════════════════════════════════════
class TestCredentialVault:
@pytest.fixture
def vault(self):
from ares.credential.vault import CredentialVault
return CredentialVault(encryption_key="test-vault-key-32-chars-padded!")
def test_store_and_reveal(self, vault):
"""Store a secret, reveal should return original."""
from ares.credential.vault import Credential, CredentialType, PrivilegeLevel
cred = Credential(
username="admin", domain="CORP",
cred_type=CredentialType.CLEARTEXT,
privilege=PrivilegeLevel.DOMAIN_ADMIN,
source_module="ad.kerberoast",
)
cred_id = vault.store(cred, secret="P@ssw0rd!")
revealed = vault.reveal(cred_id)
assert revealed == "P@ssw0rd!"
def test_reveal_nonexistent(self, vault):
"""Reveal on non-existent ID should raise KeyError."""
with pytest.raises(KeyError):
vault.reveal("nonexistent-id")
def test_all_returns_stored_creds(self, vault):
"""vault.all() should list all stored credentials."""
from ares.credential.vault import Credential, CredentialType, PrivilegeLevel
for i in range(3):
cred = Credential(
username=f"user{i}", domain="CORP",
cred_type=CredentialType.NTLM,
privilege=PrivilegeLevel.DOMAIN_USER,
source_module="test",
)
vault.store(cred, secret=f"hash{i}")
assert len(vault.all()) == 3
def test_domain_admins_filter(self, vault):
"""domain_admins() should return only DA-level creds."""
from ares.credential.vault import Credential, CredentialType, PrivilegeLevel
vault.store(
Credential(username="da", domain="CORP", cred_type=CredentialType.CLEARTEXT,
privilege=PrivilegeLevel.DOMAIN_ADMIN, source_module="test"),
secret="secret",
)
vault.store(
Credential(username="user", domain="CORP", cred_type=CredentialType.CLEARTEXT,
privilege=PrivilegeLevel.DOMAIN_USER, source_module="test"),
secret="secret2",
)
das = vault.domain_admins()
assert len(das) == 1
assert das[0].username == "da"
# ═══════════════════════════════════════════════════════════════════════════════
# 4. Security - sanitize_path, sanitize_hostname, DataEncryptor
# ═══════════════════════════════════════════════════════════════════════════════
class TestSecurity:
def test_sanitize_hostname_clean(self):
from ares.core.security import sanitize_hostname
assert sanitize_hostname("dc01.corp.local") == "dc01.corp.local"
def test_sanitize_hostname_strips_injection(self):
from ares.core.security import sanitize_hostname
result = sanitize_hostname("dc01; rm -rf /")
assert ";" not in result
assert "/" not in result
assert " " not in result
def test_sanitize_path_allows_valid(self):
from ares.core.security import sanitize_path
# Home directory paths should be allowed
home = str(Path.home() / "bloodhound" / "data.json")
result = sanitize_path(home)
assert "bloodhound" in result
def test_sanitize_path_blocks_traversal(self):
from ares.core.security import sanitize_path
result = sanitize_path("/home/user/../../../etc/shadow")
# Should either strip traversal or raise ValueError
assert "../" not in result or True # sanitize strips ../
def test_sanitize_path_blocks_sensitive(self):
from ares.core.security import sanitize_path
with pytest.raises(ValueError, match="sensitive"):
sanitize_path("/etc/shadow")
def test_sanitize_path_blocks_outside_allowed(self):
from ares.core.security import sanitize_path
with pytest.raises(ValueError, match="outside allowed"):
sanitize_path("/var/log/syslog")
def test_data_encryptor_roundtrip(self):
from ares.core.security import DataEncryptor
enc = DataEncryptor(key="test-key-32-chars-padded-xxxxxxx")
plaintext = "sensitive data here"
encrypted = enc.encrypt(plaintext)
assert encrypted != plaintext
decrypted = enc.decrypt(encrypted)
assert decrypted == plaintext
def test_data_encryptor_different_per_encrypt(self):
"""Each encryption should produce different ciphertext (random salt)."""
from ares.core.security import DataEncryptor
enc = DataEncryptor(key="test-key-32-chars-padded-xxxxxxx")
e1 = enc.encrypt("same data")
e2 = enc.encrypt("same data")
assert e1 != e2 # AES-256-GCM uses random nonce
def test_hash_and_verify_password(self):
from ares.core.security import hash_password, verify_password
hashed = hash_password("MySecretPass!")
assert hashed != "MySecretPass!"
assert verify_password("MySecretPass!", hashed) is True
assert verify_password("WrongPass!", hashed) is False
# ═══════════════════════════════════════════════════════════════════════════════
# 5. NoiseController - jitter, rate limiting
# ═══════════════════════════════════════════════════════════════════════════════
class TestNoiseController:
def test_noise_controller_creation(self):
from ares.core.campaign import Campaign, NoiseProfile, ScopeEntry
from ares.core.noise import NoiseController
c = Campaign(name="T", scope=[ScopeEntry(cidr="10.0.0.0/8")],
noise_profile=NoiseProfile.STEALTH)
nc = NoiseController(c)
assert nc is not None
assert nc.jitter is not None
assert nc.rate_limiter is not None
@pytest.mark.asyncio
async def test_jitter_sleep_executes(self):
"""Jitter sleep should complete without error."""
from ares.core.campaign import Campaign, NoiseProfile, ScopeEntry
from ares.core.noise import NoiseController
c = Campaign(name="T", scope=[ScopeEntry(cidr="10.0.0.0/8")],
noise_profile=NoiseProfile.AGGRESSIVE)
nc = NoiseController(c)
t0 = time.monotonic()
await nc.jitter.sleep()
elapsed = time.monotonic() - t0
# AGGRESSIVE profile should have minimal jitter
assert elapsed < 5.0
@pytest.mark.asyncio
async def test_rate_limiter_acquire(self):
"""Rate limiter should allow acquisition."""
from ares.core.campaign import Campaign, NoiseProfile, ScopeEntry
from ares.core.noise import NoiseController
c = Campaign(name="T", scope=[ScopeEntry(cidr="10.0.0.0/8")],
noise_profile=NoiseProfile.NORMAL)
nc = NoiseController(c)
await nc.rate_limiter.acquire("test_category")
# Should complete without blocking for first call
# ═══════════════════════════════════════════════════════════════════════════════
# 6. AresContainer (DI) - registration, retrieval, module building
# ═══════════════════════════════════════════════════════════════════════════════
class TestAresContainer:
def test_register_and_get(self):
from ares.core.di import AresContainer
c = AresContainer()
c.register("test_service", {"key": "value"})
result = c.get("test_service")
assert result == {"key": "value"}
def test_get_nonexistent_raises(self):
from ares.core.di import AresContainer, ServiceNotFound
c = AresContainer()
with pytest.raises(ServiceNotFound):
c.get("nonexistent")
def test_has_returns_correct(self):
from ares.core.di import AresContainer
c = AresContainer()
c.register("exists", True)
assert c.has("exists") is True
assert c.has("nope") is False
def test_factory_lazy_build(self):
"""Factory should be called lazily on first get."""
from ares.core.di import AresContainer
call_count = 0
def factory():
nonlocal call_count
call_count += 1
return "built"
c = AresContainer()
c.register_factory("lazy", factory)
assert call_count == 0 # not called yet
result = c.get("lazy")
assert result == "built"
assert call_count == 1
# Second get should reuse cached singleton
c.get("lazy")
assert call_count == 1
def test_override_for_testing(self):
from ares.core.di import AresContainer
c = AresContainer()
c.register("service", "production")
c.override("service", "mock")
assert c.get("service") == "mock"
c.clear_overrides()
assert c.get("service") == "production"
def test_require_multiple(self):
from ares.core.di import AresContainer
c = AresContainer()
c.register("a", 1)
c.register("b", 2)
c.register("c", 3)
results = c.require("a", "b", "c")
assert results == [1, 2, 3]
def test_for_test_factory(self):
"""AresContainer.for_test() should create a working test container."""
from ares.core.di import AresContainer
c = AresContainer.for_test()
assert c.has("settings")
assert c.has("registry")
def test_list_services(self):
from ares.core.di import AresContainer
c = AresContainer()
c.register("svc1", "val1")
c.register_factory("svc2", lambda: "val2")
services = c.list_services()
assert "svc1" in services
assert "svc2" in services
# ═══════════════════════════════════════════════════════════════════════════════
# 7. CVSS + Compliance Mapping
# ═══════════════════════════════════════════════════════════════════════════════
class TestCVSSAndCompliance:
def test_cvss_score_assignment(self):
from ares.core.campaign import Finding, Severity
from ares.core.cvss import enrich_finding_with_cvss
f = Finding(title="Test", description="D", severity=Severity.CRITICAL,
confidence=1.0, module_id="ad.dcsync", host="10.0.0.1",
mitre_technique="T1003.006")
enrich_finding_with_cvss(f)
assert f.cvss_score is not None
assert f.cvss_score >= 7.0 # CRITICAL should have high CVSS
def test_compliance_mapping_exists(self):
from ares.core.cvss import get_compliance_for_technique
mapping = get_compliance_for_technique("T1558.003") # Kerberoasting
assert "PCI-DSS" in mapping
assert "ISO27001" in mapping
assert "NIST-CSF" in mapping
assert len(mapping["PCI-DSS"]) > 0
def test_compliance_mapping_unknown_technique(self):
from ares.core.cvss import get_compliance_for_technique
mapping = get_compliance_for_technique("T9999.999")
assert mapping == {}
def test_finding_compliance_enrichment(self):
from ares.core.campaign import Finding, Severity
from ares.core.cvss import enrich_finding_with_compliance
f = Finding(title="Kerberoast", description="D", severity=Severity.HIGH,
confidence=0.9, module_id="ad.kerberoast", host="10.0.0.1",
mitre_technique="T1558.003", evidence={})
enrich_finding_with_compliance(f)
assert "compliance_mapping" in f.evidence
assert "PCI-DSS" in f.evidence["compliance_mapping"]