Skip to content

armgit / ARES

Public Imported from GitHub
0

ARES - authorized red-team engagement automation with dashboard, campaign scope, module orchestration, OPSEC controls, encrypted vault, and reporting.

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.py
index 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.py
index 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 key
raw["owned_hosts"] = [{"host": raw.get("target", "")}] if self._findings else [] # OUTPUTS key
return self._findings[:], raw
diff --git a/ares/modules/credential/reuse.py b/ares/modules/credential/reuse.py
index 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.py
index 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 credential
self.finding(
diff --git a/ares/normalize/artifacts.py b/ares/normalize/artifacts.py
index 6e31cab..dd57061 100644
--- a/ares/normalize/artifacts.py
+++ b/ares/normalize/artifacts.py
@@ -239,14 +239,24 @@ class CredentialArtifact(NormalizedArtifact):
cracked: bool = False
source_host: str = ""
host: str = "" # alias for source_host
+ target: str = "" # alias for source_host
+ protocol: str = "" # ssh | smb | winrm | rdp etc
privilege: str = "" # domain_admin | service_account | local_admin | user | unknown
def __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_host
if self.host and not self.source_host:
self.source_host = self.host
elif 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.host
if 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] = artifact
return 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 0
def _normalize_users(self, raw: dict, store: ArtifactStore) -> int:
@@ -970,3 +992,38 @@ class ArtifactNormalizer:
count += 1
return 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.py
new file mode 100644
index 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].title
diff --git a/tests/unit/test_artifact_normalizer_pipeline.py b/tests/unit/test_artifact_normalizer_pipeline.py
index 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: ArtifactNormali
assert 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"
+
+
+