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
fix(data): standardize valid_credentials contract + normalizer handler (MOD-033)
Mafifrizie3755ad5e8b1
diff --git a/ares/modules/credential/pass_spray.py b/ares/modules/credential/pass_spray.pyindex 9e4e1e4..2f2ea25 100644--- a/ares/modules/credential/pass_spray.py+++ b/ares/modules/credential/pass_spray.py@@ -778,8 +778,16 @@ class PassSprayModule(BaseModule[PassSprayParams, ModuleResult]):"protocol": protocol,"attempts": attempts,"valid_credentials": [- {"username": c["username"], "domain": c["domain"],- "target": c["target"], "password": "***REDACTED***"}+ {+ "username": c["username"],+ "password": c["password"],+ "target": c["target"],+ "port": ldap_port if protocol == "ldap" else 445,+ "method": "password",+ "protocol": protocol,+ "privilege": "user",+ "domain": c.get("domain") or domain or None,+ }for c in valid_creds],"locked_accounts": locked_accounts,diff --git a/ares/modules/credential/pass_the_hash.py b/ares/modules/credential/pass_the_hash.pyindex c215208..470bd5b 100644--- a/ares/modules/credential/pass_the_hash.py+++ b/ares/modules/credential/pass_the_hash.py@@ -354,6 +354,19 @@ class PassTheHashModule(BaseModule[PassTheHashParams, ModuleResult]):"target": target, "username": f"{domain}\\{username}","success": success, "output": output, "privilege": privilege,}- raw["valid_credentials"] = self._findings # OUTPUTS key+ valid_creds = []+ if success:+ priv_str = "admin" if privilege == "local_admin" else (privilege or "unknown")+ valid_creds.append({+ "username": username,+ "password": nt_hash,+ "target": target,+ "port": 445,+ "method": "hash",+ "protocol": "smb",+ "privilege": priv_str,+ "domain": domain or None,+ })+ raw["valid_credentials"] = valid_creds # OUTPUTS keyraw["owned_hosts"] = [{"host": raw.get("target", "")}] if self._findings else [] # OUTPUTS keyreturn self._findings[:], rawdiff --git a/ares/modules/credential/reuse.py b/ares/modules/credential/reuse.pyindex ad1eae9..3a31aee 100644--- a/ares/modules/credential/reuse.py+++ b/ares/modules/credential/reuse.py@@ -167,7 +167,7 @@ class CredentialReuseModule(BaseModule[CredentialReuseParams, ModuleResult]):data={"username": cred.get("username"),"domain": cred.get("domain"),- "service": cred.get("service"),+ "service": cred.get("protocol") or cred.get("service"),},tags=["credential", "reuse", "spray"],)@@ -283,15 +283,44 @@ class CredentialReuseModule(BaseModule[CredentialReuseParams, ModuleResult]):engine = ReuseEngine(vault=vault)await self.before_request(target, "default")results = await engine.spray(target_hosts=[target])- valid: list[str] = []+ valid: list[dict[str, Any]] = []for attempt in results:if attempt.success:- valid.append(attempt.cred_id)+ cred_id = getattr(attempt, "credential_id", getattr(attempt, "cred_id", ""))+ cred_obj = vault.get(cred_id) if (vault and cred_id) else None+ secret = ""+ if vault and cred_id:+ try:+ secret = vault.reveal(cred_id)+ except Exception:+ secret = ""+ proto_name = str(getattr(attempt.protocol, "value", attempt.protocol)).lower()+ proto_ports = {"smb": 445, "winrm": 5985, "ssh": 22, "ldap": 389, "rdp": 3389, "ftp": 21}+ port = proto_ports.get(proto_name, 0)+ method = "hash" if (cred_obj and cred_obj.is_hash) else "password"+ priv_raw = attempt.privilege or (str(cred_obj.privilege.value) if cred_obj and hasattr(cred_obj.privilege, "value") else "unknown")+ if priv_raw in ("local_admin", "admin", "domain_admin"):+ priv_str = "admin"+ elif priv_raw in ("domain_user", "local_user", "user"):+ priv_str = "user"+ else:+ priv_str = priv_raw or "unknown"++ valid.append({+ "username": attempt.username,+ "password": secret,+ "target": attempt.target_host or target,+ "port": port,+ "method": method,+ "protocol": proto_name,+ "privilege": priv_str,+ "domain": attempt.domain or None,+ })self.finding(title = f"Valid credential reused on {target}",description = (- f"Credential {attempt.cred_id[:8]}… authenticated via "+ f"Credential {cred_id[:8]}… authenticated via "f"{attempt.protocol} on {target}"),severity = Severity.CRITICAL,diff --git a/ares/modules/credential/ssh_spray.py b/ares/modules/credential/ssh_spray.pyindex 6c38607..1b5b0af 100644--- a/ares/modules/credential/ssh_spray.py+++ b/ares/modules/credential/ssh_spray.py@@ -143,7 +143,7 @@ class SSHSprayModule(BaseModule[SSHSprayParams, ModuleResult]):target_users = users or ["root", "admin", "kali", "ubuntu", "kraii"]target_passwords = passwords or ["Password123!", "admin", "root", "toor"]- valid_credentials: list[dict[str, str]] = []+ valid_credentials: list[dict[str, Any]] = []tested_pairs: list[dict[str, Any]] = []loot: list[dict[str, Any]] = []attempts = 0@@ -239,7 +239,11 @@ class SSHSprayModule(BaseModule[SSHSprayParams, ModuleResult]):"username": username,"password": password,"target": target,- "port": str(port),+ "port": int(port),+ "method": "password",+ "protocol": "ssh",+ "privilege": "admin" if username in ("root", "admin", "system") else "user",+ "domain": None,})# Emit finding immediately for discovered credentialself.finding(diff --git a/ares/normalize/artifacts.py b/ares/normalize/artifacts.pyindex 6e31cab..dd57061 100644--- a/ares/normalize/artifacts.py+++ b/ares/normalize/artifacts.py@@ -239,14 +239,24 @@ class CredentialArtifact(NormalizedArtifact):cracked: bool = Falsesource_host: str = ""host: str = "" # alias for source_host+ target: str = "" # alias for source_host+ protocol: str = "" # ssh | smb | winrm | rdp etcprivilege: str = "" # domain_admin | service_account | local_admin | user | unknowndef __post_init__(self) -> None:self.artifact_type = ArtifactType.CREDENTIAL+ if self.target and not self.source_host:+ self.source_host = self.target+ elif self.source_host and not self.target:+ self.target = self.source_hostif self.host and not self.source_host:self.source_host = self.hostelif self.source_host and not self.host:self.host = self.source_host+ if self.target and not self.host:+ self.host = self.target+ elif self.host and not self.target:+ self.target = self.hostif self.secret and not self.secret_hash:self.secret_hash = hashlib.sha256(self.secret.encode("utf-8", errors="ignore")).hexdigest()@@ -254,11 +264,14 @@ class CredentialArtifact(NormalizedArtifact):return f"{self.domain}\\{self.username}:{self.cred_type}:{self.source_host}:{self.secret_hash[:8]}"def _to_dict_fields(self) -> dict[str, Any]:- return {+ d = {"username": self.username, "domain": self.domain,"cred_type": self.cred_type, "cracked": self.cracked,"source_host": self.source_host, "privilege": self.privilege,}+ if self.protocol:+ d["protocol"] = self.protocol+ return d@dataclass@@ -365,6 +378,10 @@ class ArtifactStore:self._store[artifact.uid] = artifactreturn artifact+ def add_credential(self, artifact: CredentialArtifact) -> CredentialArtifact:+ """Add or merge a CredentialArtifact. Returns canonical artifact."""+ return self.add(artifact) # type: ignore[return-value]+def add_many(self, artifacts: list[NormalizedArtifact]) -> None:for a in artifacts:self.add(a)@@ -497,10 +514,15 @@ class ArtifactNormalizer:"windows.lsa_secrets": self._normalize_lsa_secrets,"cached_credentials": self._normalize_cached_domain_credentials,"cached_domain_credentials": self._normalize_cached_domain_credentials,+ # Valid Credentials (MOD-033)+ "valid_credentials": self._normalize_valid_credentials,}handler = handlers.get(capability)if handler:- return handler(raw, store)+ try:+ return handler(raw, store, capability)+ except TypeError:+ return handler(raw, store)return 0def _normalize_users(self, raw: dict, store: ArtifactStore) -> int:@@ -970,3 +992,38 @@ class ArtifactNormalizer:count += 1return count+ def _normalize_valid_credentials(+ self, raw: dict, store: ArtifactStore, capability: str = "valid_credentials"+ ) -> int:+ """+ Normalize standardized valid_credentials output (MOD-033).+ Contract: list[dict] with username, password, target, port, method, protocol, privilege, domain.+ """+ entries = raw.get("valid_credentials", [])+ if not isinstance(entries, list):+ return 0+ count = 0+ for entry in entries:+ if not isinstance(entry, dict):+ logger.warning(+ "valid_credentials_invalid_entry",+ type=type(entry).__name__,+ )+ continue+ artifact = CredentialArtifact(+ username=entry.get("username", ""),+ secret=entry.get("password", ""),+ target=entry.get("target", ""),+ source_host=entry.get("target", ""),+ host=entry.get("target", ""),+ protocol=entry.get("protocol", ""),+ cred_type=entry.get("method", "password"),+ privilege=entry.get("privilege", "unknown"),+ domain=entry.get("domain") or "",+ cracked=False,+ source_module=capability,+ )+ store.add_credential(artifact)+ count += 1+ return count+diff --git a/tests/unit/modules/test_valid_credentials_contract.py b/tests/unit/modules/test_valid_credentials_contract.pynew file mode 100644index 0000000..22da0a5--- /dev/null+++ b/tests/unit/modules/test_valid_credentials_contract.py@@ -0,0 +1,218 @@+from __future__ import annotations++import asyncio+from unittest.mock import AsyncMock, MagicMock, patch+import pytest++from ares.core.config import AresSettings+from ares.core.campaign import Campaign, NoiseProfile, ScopeEntry+from ares.core.noise import NoiseController+from ares.modules.credential.pass_spray import PassSprayModule+from ares.modules.credential.ssh_spray import SSHSprayModule+from ares.modules.credential.pass_the_hash import PassTheHashModule+from ares.modules.credential.reuse import CredentialReuseModule+++def make_module(cls):+ settings = AresSettings()+ campaign = Campaign(+ name="Contract-Test",+ client="TestClient",+ operator="tester",+ scope=[ScopeEntry(cidr="10.0.0.0/8")],+ domain="corp.local",+ targets=["10.0.0.5", "10.0.0.6", "10.0.0.7", "10.0.0.8", "corp.local"],+ noise_profile=NoiseProfile.NORMAL,+ )+ noise = NoiseController(campaign)+ return cls(settings=settings, campaign=campaign, noise=noise)+++def _run(coro):+ return asyncio.run(coro)+++REQUIRED_CONTRACT_FIELDS = {+ "username",+ "password",+ "target",+ "port",+ "method",+ "protocol",+ "privilege",+ "domain",+}+++def test_pass_spray_valid_credentials_contract():+ """credential.pass_spray outputs unmasked password in raw, masks in finding evidence."""+ mod = make_module(PassSprayModule)++ # Mock SMB success+ fake_smb = MagicMock()+ fake_smb_instance = MagicMock()+ fake_smb.return_value = fake_smb_instance++ with patch.dict("sys.modules", {"impacket.smbconnection": MagicMock(SMBConnection=fake_smb)}):+ findings, raw = _run(+ mod.run(+ target="10.0.0.5",+ domain="corp.local",+ users=["alice"],+ passwords=["Winter2026!"],+ delay_seconds=0.0,+ )+ )++ assert len(raw["valid_credentials"]) == 1+ cred = raw["valid_credentials"][0]+ assert set(cred.keys()) == REQUIRED_CONTRACT_FIELDS+ assert cred["username"] == "alice"+ assert cred["password"] == "Winter2026!" # unmasked in raw+ assert cred["target"] == "10.0.0.5"+ assert isinstance(cred["port"], int)+ assert cred["port"] == 445+ assert cred["method"] == "password"+ assert cred["protocol"] == "smb"+ assert cred["privilege"] == "user"+ assert cred["domain"] == "corp.local"++ # Verify Finding evidence is masked+ assert len(findings) == 1+ assert findings[0].evidence["password"] == "***REDACTED***"+++def test_ssh_spray_valid_credentials_contract():+ """credential.ssh_spray matches 8-field contract with int port."""+ mod = make_module(SSHSprayModule)++ fake_client = MagicMock()+ fake_client.connect.return_value = None+ fake_client.close.return_value = None+ fake_paramiko = MagicMock()+ fake_paramiko.SSHClient.return_value = fake_client++ with patch.dict("sys.modules", {"asyncssh": None, "paramiko": fake_paramiko}):+ findings, raw = _run(+ mod.run(+ target="10.0.0.6",+ port=2222,+ users=["admin"],+ passwords=["AdminSecret!"],+ delay_s=0.0,+ )+ )++ assert len(raw["valid_credentials"]) == 1+ cred = raw["valid_credentials"][0]+ assert set(cred.keys()) == REQUIRED_CONTRACT_FIELDS+ assert cred["username"] == "admin"+ assert cred["password"] == "AdminSecret!"+ assert cred["target"] == "10.0.0.6"+ assert cred["port"] == 2222+ assert isinstance(cred["port"], int)+ assert cred["method"] == "password"+ assert cred["protocol"] == "ssh"+ assert cred["privilege"] == "admin"+ assert cred["domain"] is None+ assert len(findings) == 1+++def test_pass_the_hash_valid_credentials_contract():+ """credential.pass_the_hash outputs list[dict], not list[Finding]."""+ mod = make_module(PassTheHashModule)++ fake_smb_instance = MagicMock()+ fake_smb_instance.login.return_value = True+ fake_smb_instance.connectTree.return_value = "tree"+ fake_smb_instance.disconnectTree.return_value = None+ fake_smb_instance.listShares.return_value = [{"shi1_netname": "C$"}]+ fake_smb_cls = MagicMock(return_value=fake_smb_instance)++ with patch.dict("sys.modules", {"impacket.smbconnection": MagicMock(SMBConnection=fake_smb_cls)}):+ findings, raw = _run(+ mod.run(+ target="10.0.0.7",+ username="Administrator",+ domain="corp.local",+ nt_hash="8846f7eaee8fb117ad06bdd830b7586c",+ )+ )++ assert isinstance(raw["valid_credentials"], list)+ assert len(raw["valid_credentials"]) == 1+ cred = raw["valid_credentials"][0]+ assert isinstance(cred, dict)+ assert set(cred.keys()) == REQUIRED_CONTRACT_FIELDS+ assert cred["username"] == "Administrator"+ assert cred["password"] == "8846f7eaee8fb117ad06bdd830b7586c"+ assert cred["target"] == "10.0.0.7"+ assert cred["port"] == 445+ assert isinstance(cred["port"], int)+ assert cred["method"] == "hash"+ assert cred["protocol"] == "smb"+ assert cred["privilege"] == "admin"+ assert cred["domain"] == "corp.local"++ # Finding must still be published+ assert len(findings) == 1+ assert "Pass-the-Hash Successful" in findings[0].title+++def test_reuse_valid_credentials_contract():+ """credential.reuse outputs list[dict], not list[str] IDs."""+ mod = make_module(CredentialReuseModule)++ fake_attempt = MagicMock()+ fake_attempt.success = True+ fake_attempt.cred_id = "cred-12345"+ fake_attempt.credential_id = "cred-12345"+ fake_attempt.username = "db_user"+ fake_attempt.domain = "corp.local"+ fake_attempt.target_host = "10.0.0.8"+ fake_attempt.protocol = "winrm"+ fake_attempt.privilege = "user"++ mock_vault = MagicMock()+ mock_vault.get.return_value = MagicMock(is_hash=False)+ mock_vault.reveal.return_value = "DecryptedSecret!"++ fake_engine = MagicMock()+ fake_engine.spray = AsyncMock(return_value=[fake_attempt])+ fake_engine_cls = MagicMock(return_value=fake_engine)++ with patch.dict(+ "sys.modules",+ {+ "ares.credential.reuse": MagicMock(+ ReuseEngine=fake_engine_cls,+ ReuseProtocol=MagicMock(),+ )+ },+ ):+ findings, raw = _run(+ mod.run(+ target="10.0.0.8",+ vault=mock_vault,+ oauth_audit_func=lambda target: {"device_code_permitted": False},+ )+ )++ assert isinstance(raw["valid_credentials"], list)+ assert len(raw["valid_credentials"]) == 1+ cred = raw["valid_credentials"][0]+ assert isinstance(cred, dict)+ assert set(cred.keys()) == REQUIRED_CONTRACT_FIELDS+ assert cred["username"] == "db_user"+ assert cred["password"] == "DecryptedSecret!"+ assert cred["target"] == "10.0.0.8"+ assert cred["port"] == 5985+ assert isinstance(cred["port"], int)+ assert cred["method"] == "password"+ assert cred["protocol"] == "winrm"+ assert cred["privilege"] == "user"+ assert cred["domain"] == "corp.local"++ # Finding must still be published+ assert len(findings) == 1+ assert "Valid credential reused" in findings[0].titlediff --git a/tests/unit/test_artifact_normalizer_pipeline.py b/tests/unit/test_artifact_normalizer_pipeline.pyindex 05ffa79..156545e 100644--- a/tests/unit/test_artifact_normalizer_pipeline.py+++ b/tests/unit/test_artifact_normalizer_pipeline.py@@ -431,3 +431,84 @@ def test_lsa_secrets_and_cached_creds_dict_structure(normalizer: ArtifactNormaliassert cached_cred.cracked is False+def test_valid_credentials_pipeline_normalizes_to_artifact_store(+ normalizer: ArtifactNormalizer, store: ArtifactStore+):+ """MOD-033: valid_credentials standard contract normalizes into CredentialArtifact."""+ raw = {+ "valid_credentials": [+ {+ "username": "admin",+ "password": "SecretPassword123!",+ "target": "10.0.0.50",+ "port": 22,+ "method": "password",+ "protocol": "ssh",+ "privilege": "admin",+ "domain": None,+ },+ {+ "username": "svc_sql",+ "password": "0123456789abcdef0123456789abcdef",+ "target": "10.0.0.51",+ "port": 445,+ "method": "hash",+ "protocol": "smb",+ "privilege": "user",+ "domain": "CORP",+ },+ ]+ }+ added = normalizer.normalize("credential.ssh_spray", ["valid_credentials"], raw, store)+ assert added == 2+ creds = store.credentials()+ assert len(creds) == 2++ c1 = next(c for c in creds if c.username == "admin")+ assert c1.secret == "SecretPassword123!"+ assert c1.source_host == "10.0.0.50"+ assert c1.target == "10.0.0.50"+ assert c1.protocol == "ssh"+ assert c1.cred_type == "password"+ assert c1.privilege == "admin"+ assert c1.cracked is False++ c2 = next(c for c in creds if c.username == "svc_sql")+ assert c2.secret == "0123456789abcdef0123456789abcdef"+ assert c2.source_host == "10.0.0.51"+ assert c2.protocol == "smb"+ assert c2.cred_type == "hash"+ assert c2.privilege == "user"+ assert c2.domain == "CORP"+ assert c2.cracked is False+++def test_valid_credentials_skips_invalid_non_dict_entries(+ normalizer: ArtifactNormalizer, store: ArtifactStore+):+ """MOD-033: Non-dict entries in valid_credentials are safely skipped."""+ raw = {+ "valid_credentials": [+ "invalid_string_id",+ 12345,+ {+ "username": "valid_user",+ "password": "valid_password",+ "target": "10.0.0.60",+ "port": 445,+ "method": "password",+ "protocol": "smb",+ "privilege": "user",+ "domain": "CORP",+ },+ ]+ }+ added = normalizer.normalize("credential.reuse", ["valid_credentials"], raw, store)+ assert added == 1+ creds = store.credentials()+ assert len(creds) == 1+ assert creds[0].username == "valid_user"+ assert creds[0].secret == "valid_password"+++