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(normalize): snmp vault write (MOD-061) and Group A normalizer handlers (MOD-036, MOD-041, MOD-044, MOD-052, MOD-062)
Mafifrizi5635362050ec
diff --git a/ares/modules/network/snmp_enum.py b/ares/modules/network/snmp_enum.pyindex 6637349..a2cd1f6 100644--- a/ares/modules/network/snmp_enum.py+++ b/ares/modules/network/snmp_enum.py@@ -162,7 +162,7 @@ class SnmpEnumModule(BaseModule):MODULE_AUTHOR = "ARES Team <[email protected]>"OPSEC_LEVEL = OpsecLevel.LOWREQUIRES = []- OUTPUTS = ["snmp_findings", "system_info"]+ OUTPUTS = ["snmp_findings", "system_info", "valid_credentials"]MITRE_TECHNIQUES = ["T1046", "T1590"]PARAMS_MODEL = SNMPEnumParams@@ -208,7 +208,7 @@ class SnmpEnumModule(BaseModule):communities = params.get("communities")extra_params = {k: v for k, v in params.items() if k not in ("target", "port", "snmp_port", "communities")}- kwargs: dict[str, Any] = {"target": target, "port": port, **extra_params}+ kwargs: dict[str, Any] = {"target": target, "port": port, "ctx": ctx, "vault": getattr(ctx, "vault", None), **extra_params}if communities is not None:kwargs["communities"] = communities@@ -287,6 +287,9 @@ class SnmpEnumModule(BaseModule):dry_run = kwargs.get("dry_run", False)communities = kwargs.get("communities") or _COMMUNITY_STRINGSdo_walk = kwargs.get("walk", True) # Walk tables for deeper enum+ vault = kwargs.get("vault")+ ctx = kwargs.get("ctx")+ _vault = vault or getattr(getattr(self, "campaign", None), "_vault", None) or (getattr(ctx, "vault", None) if ctx else None)if not target:return [], {"error": "no_target"}@@ -345,6 +348,22 @@ class SnmpEnumModule(BaseModule):target=target, community=community,sys_name=result.get("sysName", "?"))+ # Store to AresVault if available (Gate 6 compliant)+ if _vault:+ from ares.credential.vault import Credential, CredentialType, PrivilegeLevel+ try:+ cred = Credential(+ username="snmp",+ domain=target,+ cred_type=CredentialType.CLEARTEXT,+ privilege=PrivilegeLevel.LOCAL_ADMIN if community.lower() in ("private", "write") else PrivilegeLevel.LOCAL_USER,+ source_module=self.MODULE_ID,+ target_host=target,+ )+ _vault.store(cred, community)+ except Exception as exc:+ logger.debug("snmp_vault_store_failed", target=target, community=community, error=str(exc)[:60])+# Emit findingis_default = community.lower() in ("public", "private")sev = Severity.HIGH if is_default else Severity.MEDIUM@@ -403,12 +422,30 @@ class SnmpEnumModule(BaseModule):confidence=0.95,)+ valid_creds = [+ {+ "username": "snmp",+ "password": e["community"],+ "target": target,+ "port": port,+ "method": "snmp_community",+ "protocol": "snmp",+ "privilege": "local_admin" if e["community"].lower() in ("private", "write") else "user",+ "domain": target,+ }+ for e in valid_communities+ ]+raw = {"target": target,"port": port,"valid_communities": valid_communities,"system_info": system_info,"communities_tested": len(communities),+ "valid_credentials": valid_creds,}- raw["snmp_findings"] = self._findings # OUTPUTS key+ raw["snmp_findings"] = [+ f.model_dump() if hasattr(f, "model_dump") else (f.dict() if hasattr(f, "dict") else vars(f))+ for f in self._findings+ ]return self._findings[:], rawdiff --git a/ares/normalize/artifacts.py b/ares/normalize/artifacts.pyindex 3406763..be957c3 100644--- a/ares/normalize/artifacts.py+++ b/ares/normalize/artifacts.py@@ -325,7 +325,7 @@ class PermissionArtifact(NormalizedArtifact):def __post_init__(self) -> None:self.artifact_type = ArtifactType.PERMISSION- self.is_dangerous = self.right in self.DANGEROUS_RIGHTS+ self.is_dangerous = self.is_dangerous or (self.right in self.DANGEROUS_RIGHTS)def _dedup_key(self) -> str:return f"{self.principal}→{self.right}→{self.target}"@@ -518,6 +518,25 @@ class ArtifactNormalizer:"cached_domain_credentials": self._normalize_cached_domain_credentials,# Valid Credentials (MOD-033)"valid_credentials": self._normalize_valid_credentials,+ # Kerberos Ticket Conversion (MOD-036)+ "converted_ticket": self._normalize_converted_ticket,+ "converted_ticket_b64": self._normalize_converted_ticket,+ # Samba Secrets & Machine Hashes (MOD-041)+ "samba_secrets": self._normalize_samba_secrets,+ "machine_account_hash": self._normalize_samba_secrets,+ # Linux Keytab Credentials (MOD-044)+ "kerberos_keys": self._normalize_keytab_keys,+ "machine_credentials": self._normalize_keytab_keys,+ # AWS IAM Privesc Paths (MOD-052)+ "iam_privesc_paths": self._normalize_iam_privesc,+ "aws_privesc_paths": self._normalize_iam_privesc,+ # Reconnaissance & Service Fingerprinting (MOD-062)+ "dns_records": self._normalize_dns_records,+ "subdomains": self._normalize_dns_records,+ "service_versions": self._normalize_service_versions,+ "vulnerable_services": self._normalize_service_versions,+ "web_fingerprint": self._normalize_web_fingerprint,+ "admin_interfaces": self._normalize_web_fingerprint,}handler = handlers.get(capability)if handler:@@ -1037,3 +1056,237 @@ class ArtifactNormalizer:count += 1return count+ # ── Group A Handlers (MOD-036, MOD-041, MOD-044, MOD-052, MOD-062) ─────────++ def _normalize_converted_ticket(+ self, raw: dict, store: ArtifactStore, capability: str = "converted_ticket"+ ) -> int:+ """MOD-036: Normalize converted Kerberos ticket (kirbi <-> ccache)."""+ ticket_b64 = raw.get("converted_ticket_b64") or raw.get("converted_ticket")+ if not ticket_b64 or not isinstance(ticket_b64, str):+ return 0+ meta = raw.get("metadata", {})+ is_tgt = meta.get("is_tgt", False)+ target = raw.get("target", "")+ artifact = CredentialArtifact(+ username=meta.get("client") or "converted-user",+ domain=target or meta.get("server") or "",+ cred_type="tgt" if is_tgt else "tgs",+ secret=ticket_b64,+ source_host=target,+ privilege="domain_admin" if is_tgt else "domain_user",+ source_module=capability,+ )+ store.add_credential(artifact)+ return 1++ def _normalize_samba_secrets(+ self, raw: dict, store: ArtifactStore, capability: str = "samba_secrets"+ ) -> int:+ """MOD-041: Normalize Samba secrets.tdb machine account hashes and secrets."""+ secrets = raw.get("samba_secrets") or raw.get("secrets") or raw.get("machine_account_hash")+ if not secrets:+ return 0+ if isinstance(secrets, dict):+ secrets = [secrets]+ elif not isinstance(secrets, list):+ return 0+ count = 0+ target = raw.get("target", "")+ for sec in secrets:+ if not isinstance(sec, dict):+ continue+ username = sec.get("account_name", f"{target}$")+ domain = sec.get("domain", target)+ ntlm = sec.get("ntlm_hash")+ if ntlm:+ h_artifact = HashArtifact(+ username=username,+ domain=domain,+ hash_type="ntlm",+ hash_value=ntlm,+ source_module=capability,+ )+ store.add(h_artifact)+ count += 1+ plain = sec.get("plaintext") or sec.get("password")+ if plain:+ c_artifact = CredentialArtifact(+ username=username,+ domain=domain,+ cred_type="cleartext",+ secret=plain,+ source_host=target,+ privilege="service_account",+ source_module=capability,+ )+ store.add_credential(c_artifact)+ count += 1+ return count++ def _normalize_keytab_keys(+ self, raw: dict, store: ArtifactStore, capability: str = "kerberos_keys"+ ) -> int:+ """MOD-044: Normalize Kerberos keytab extracted entries."""+ entries = raw.get("kerberos_keys") or raw.get("machine_credentials") or raw.get("entries")+ if not entries:+ return 0+ if isinstance(entries, dict):+ entries = [entries]+ elif not isinstance(entries, list):+ return 0+ count = 0+ target = raw.get("target", "")+ for e in entries:+ if not isinstance(e, dict):+ continue+ key_hex = e.get("key_hex", "")+ principal = e.get("principal", f"{target}$")+ realm = e.get("realm", target)+ artifact = CredentialArtifact(+ username=principal,+ domain=realm,+ cred_type="keytab_key",+ secret=key_hex,+ source_host=target,+ privilege="service_account",+ note=f"enctype={e.get('enctype', '')}, kvno={e.get('kvno', '')}",+ source_module=capability,+ )+ store.add_credential(artifact)+ count += 1+ return count++ def _normalize_iam_privesc(+ self, raw: dict, store: ArtifactStore, capability: str = "iam_privesc_paths"+ ) -> int:+ """MOD-052: Normalize AWS IAM privilege escalation paths into PermissionArtifact."""+ paths = raw.get("iam_privesc_paths") or raw.get("aws_privesc_paths", [])+ if not isinstance(paths, list):+ return 0+ count = 0+ target = raw.get("target", "") or raw.get("account_id", "")+ for p in paths:+ if not isinstance(p, dict):+ continue+ artifact = PermissionArtifact(+ principal=p.get("principal") or p.get("user") or p.get("role") or "current_user",+ target=p.get("target") or p.get("resource") or target or "aws_account",+ right=p.get("action") or p.get("privilege") or p.get("technique") or "iam_privesc",+ domain=raw.get("account_id") or raw.get("region") or "aws",+ is_dangerous=True,+ source_module=capability,+ )+ store.add(artifact)+ count += 1+ return count++ def _normalize_dns_records(+ self, raw: dict, store: ArtifactStore, capability: str = "dns_records"+ ) -> int:+ """MOD-062: Normalize DNS reconnaissance records and discovered subdomains."""+ count = 0+ domain = raw.get("domain", "")+ subdomains = raw.get("subdomains", [])+ if isinstance(subdomains, list):+ for sub in subdomains:+ if isinstance(sub, dict):+ fqdn = sub.get("fqdn") or sub.get("subdomain", "")+ ips = sub.get("ips", [])+ ip = ips[0] if ips and isinstance(ips, list) else ""+ elif isinstance(sub, str):+ fqdn = sub+ ip = ""+ else:+ continue+ if fqdn:+ artifact = HostArtifact(+ ip_address=ip or fqdn,+ hostname=fqdn,+ fqdn=fqdn,+ domain=domain,+ source_module=capability,+ )+ store.add(artifact)+ count += 1+ dns_records = raw.get("dns_records", {})+ if isinstance(dns_records, dict):+ for rtype in ("A", "AAAA"):+ ips = dns_records.get(rtype, [])+ if isinstance(ips, list):+ for ip in ips:+ if isinstance(ip, str) and ip:+ artifact = HostArtifact(+ ip_address=ip,+ hostname=domain,+ fqdn=domain,+ domain=domain,+ source_module=capability,+ )+ store.add(artifact)+ count += 1+ return count++ def _normalize_service_versions(+ self, raw: dict, store: ArtifactStore, capability: str = "service_versions"+ ) -> int:+ """MOD-062: Normalize service detect version banners into HostArtifact."""+ target = raw.get("target") or raw.get("host", "")+ if not target:+ return 0+ service_versions = raw.get("service_versions", {})+ ports: list[int] = []+ if isinstance(service_versions, dict):+ for p_str in service_versions:+ if str(p_str).isdigit():+ ports.append(int(p_str))+ ports = sorted(list(set(ports)))+ existing = None+ for h in store.hosts():+ if h.ip_address == target or h.hostname == target:+ existing = h+ break+ if existing:+ if ports:+ existing.open_ports = sorted(list(set(existing.open_ports + ports)))+ if raw.get("os") and not existing.os:+ existing.os = raw.get("os", "")+ return 1+ artifact = HostArtifact(+ ip_address=target,+ hostname=target,+ os=raw.get("os", "") or raw.get("detected_os", ""),+ open_ports=ports,+ source_module=capability,+ )+ store.add(artifact)+ return 1++ def _normalize_web_fingerprint(+ self, raw: dict, store: ArtifactStore, capability: str = "web_fingerprint"+ ) -> int:+ """MOD-062: Normalize web server fingerprint and technologies into HostArtifact."""+ target = raw.get("target") or raw.get("host", "")+ if not target:+ return 0+ web_fp = raw.get("web_fingerprint", {})+ server = web_fp.get("server", "") if isinstance(web_fp, dict) else ""+ existing = None+ for h in store.hosts():+ if h.ip_address == target or h.hostname == target:+ existing = h+ break+ if existing:+ if server and not existing.os:+ existing.os = server+ return 1+ artifact = HostArtifact(+ ip_address=target,+ hostname=target,+ os=server,+ source_module=capability,+ )+ store.add(artifact)+ return 1++diff --git a/tests/unit/test_artifact_normalizer_pipeline.py b/tests/unit/test_artifact_normalizer_pipeline.pyindex fbdd12b..1863d8b 100644--- a/tests/unit/test_artifact_normalizer_pipeline.py+++ b/tests/unit/test_artifact_normalizer_pipeline.py@@ -714,4 +714,226 @@ def test_valid_credentials_skips_invalid_non_dict_entries(assert creds[0].secret == "valid_password"+async def test_snmp_enum_vault_and_valid_credentials_mod_061(+ normalizer: ArtifactNormalizer, store: ArtifactStore+):+ """+ MOD-061: snmp_enum writes valid community strings to AresVault (Gate 6 compliant),+ produces standardized valid_credentials output, and serializes snmp_findings.+ """+ from unittest.mock import patch+ from tests.unit.modules.test_modules import _make_module+ from ares.modules.network.snmp_enum import SnmpEnumModule+ from ares.credential.vault import CredentialVault+ from ares.core.context import ExecutionContext++ mod, _ = _make_module(SnmpEnumModule)+ vault = CredentialVault(encryption_key=None)+ ctx = ExecutionContext(+ target="10.0.0.100",+ vault=vault,+ network_io_occurred=True,+ )++ fake_sys_info = {+ "sysDescr": "Linux router 5.15.0",+ "sysName": "edge-router-01",+ }++ # Mock low-level sync SNMP calls so no real network traffic occurs+ with patch("ares.modules.network.snmp_enum._snmp_get_sync", return_value=fake_sys_info), \+ patch("ares.modules.network.snmp_enum._snmp_walk_sync", return_value=[]):+ findings, raw = await mod.run(+ target="10.0.0.100",+ port=161,+ communities=["public"],+ walk=False,+ vault=vault,+ ctx=ctx,+ )++ # 1. Community string stored directly into vault (Gate 6 passed)+ stored_creds = list(vault._store.values())+ assert len(stored_creds) == 1+ revealed = vault.reveal(stored_creds[0].id)+ assert revealed == "public"++ # 2. raw output has standardized valid_credentials contract+ assert "valid_credentials" in raw+ assert len(raw["valid_credentials"]) == 1+ assert raw["valid_credentials"][0]["username"] == "snmp"+ assert raw["valid_credentials"][0]["password"] == "public"+ assert raw["valid_credentials"][0]["method"] == "snmp_community"+ assert raw["valid_credentials"][0]["protocol"] == "snmp"++ # 3. snmp_findings is serialized (list of dicts, not raw Finding objects)+ assert isinstance(raw["snmp_findings"], list)+ assert len(raw["snmp_findings"]) >= 1+ assert isinstance(raw["snmp_findings"][0], dict)++ # 4. Normalizer pipeline creates CredentialArtifact with cred_type="snmp_community"+ added = normalizer.normalize("network.snmp_enum", ["valid_credentials"], raw, store)+ assert added == 1+ creds = store.credentials()+ assert len(creds) == 1+ assert creds[0].username == "snmp"+ assert creds[0].secret == "public"+ assert creds[0].cred_type == "snmp_community"+ assert creds[0].protocol == "snmp"+ assert creds[0].target == "10.0.0.100"+++def test_converted_ticket_pipeline_mod_036(normalizer: ArtifactNormalizer, store: ArtifactStore):+ """MOD-036: Converted ticket base64 is ingested into CredentialArtifact."""+ raw = {+ "target": "corp.local",+ "converted_ticket_b64": "Y2NhY2hlLXRlc3QtZGF0YQ==",+ "metadata": {+ "client": "[email protected]",+ "server": "krbtgt/CORP.LOCAL",+ "is_tgt": True,+ },+ }+ added = normalizer.normalize("credential.ticket_converter", ["converted_ticket"], raw, store)+ assert added == 1+ creds = store.credentials()+ assert len(creds) == 1+ assert creds[0].username == "[email protected]"+ assert creds[0].domain == "corp.local"+ assert creds[0].cred_type == "tgt"+ assert creds[0].privilege == "domain_admin"+ assert creds[0].secret == "Y2NhY2hlLXRlc3QtZGF0YQ=="+++def test_samba_secrets_pipeline_mod_041(normalizer: ArtifactNormalizer, store: ArtifactStore):+ """MOD-041: Samba secrets are converted to HashArtifact and CredentialArtifact."""+ raw = {+ "target": "fileserver01",+ "samba_secrets": [+ {+ "account_name": "FILESERVER01$",+ "domain": "CORP",+ "ntlm_hash": "aad3b435b51404eeaad3b435b51404ee:31d6cfe0d16ae931b73c59d7e0c089c0",+ "plaintext": "SecretMachinePass123!",+ }+ ],+ }+ added = normalizer.normalize("linux.samba_secrets", ["samba_secrets"], raw, store)+ assert added == 2+ hashes = store.hashes()+ assert len(hashes) == 1+ assert hashes[0].username == "FILESERVER01$"+ assert hashes[0].hash_type == "ntlm"+ assert "31d6cfe0d16ae931b73c59d7e0c089c0" in hashes[0].hash_value++ creds = store.credentials()+ assert len(creds) == 1+ assert creds[0].username == "FILESERVER01$"+ assert creds[0].secret == "SecretMachinePass123!"+++def test_keytab_keys_pipeline_mod_044(normalizer: ArtifactNormalizer, store: ArtifactStore):+ """MOD-044: Kerberos keytab keys are converted to CredentialArtifact with enctype note."""+ raw = {+ "target": "linux01",+ "kerberos_keys": [+ {+ "principal": "host/[email protected]",+ "realm": "CORP.LOCAL",+ "key_hex": "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",+ "enctype": 18,+ "kvno": 2,+ }+ ],+ }+ added = normalizer.normalize("linux.keytab_abuse", ["kerberos_keys"], raw, store)+ assert added == 1+ creds = store.credentials()+ assert len(creds) == 1+ assert creds[0].username == "host/[email protected]"+ assert creds[0].cred_type == "keytab_key"+ assert creds[0].secret.startswith("12345678")+ assert "enctype=18" in creds[0].note+++def test_iam_privesc_pipeline_mod_052(normalizer: ArtifactNormalizer, store: ArtifactStore):+ """MOD-052: AWS IAM privilege escalation paths normalized to PermissionArtifact."""+ raw = {+ "account_id": "123456789012",+ "iam_privesc_paths": [+ {+ "principal": "arn:aws:iam::123456789012:user/dev",+ "action": "iam:PassRole",+ "target": "arn:aws:iam::123456789012:role/AdminRole",+ "technique": "T1548",+ }+ ],+ }+ added = normalizer.normalize("cloud.aws_privesc", ["iam_privesc_paths"], raw, store)+ assert added == 1+ perms = store.permissions()+ assert len(perms) == 1+ assert perms[0].principal == "arn:aws:iam::123456789012:user/dev"+ assert perms[0].target == "arn:aws:iam::123456789012:role/AdminRole"+ assert perms[0].right == "iam:PassRole"+ assert perms[0].is_dangerous is True+++def test_dns_records_and_subdomains_pipeline_mod_062(+ normalizer: ArtifactNormalizer, store: ArtifactStore+):+ """MOD-062: DNS subdomains and A-records normalized to HostArtifact."""+ raw = {+ "domain": "target.corp",+ "subdomains": [+ {"fqdn": "vpn.target.corp", "ips": ["10.10.1.5"]},+ "mail.target.corp",+ ],+ "dns_records": {+ "A": ["10.10.1.1", "10.10.1.2"],+ },+ }+ added = normalizer.normalize("network.dns_enum", ["subdomains", "dns_records"], raw, store)+ assert added >= 4+ hosts = store.hosts()+ hostnames = {h.hostname for h in hosts}+ assert "vpn.target.corp" in hostnames+ assert "mail.target.corp" in hostnames+ assert "target.corp" in hostnames+++def test_service_versions_and_web_fingerprint_pipeline_mod_062(+ normalizer: ArtifactNormalizer, store: ArtifactStore+):+ """MOD-062: Service versions and web fingerprint update HostArtifact."""+ raw_service = {+ "target": "10.10.1.50",+ "service_versions": {+ "80": {"service": "http", "version": "nginx 1.18"},+ "443": {"service": "https", "version": "nginx 1.18"},+ },+ "os": "Ubuntu Linux",+ }+ added_svc = normalizer.normalize("network.service_detect", ["service_versions"], raw_service, store)+ assert added_svc == 1++ hosts = store.hosts()+ assert len(hosts) == 1+ assert hosts[0].ip_address == "10.10.1.50"+ assert hosts[0].open_ports == [80, 443]+ assert hosts[0].os == "Ubuntu Linux"++ raw_web = {+ "target": "10.10.1.50",+ "web_fingerprint": {"server": "nginx/1.18.0 (Ubuntu)"},+ }+ added_web = normalizer.normalize("network.http_fingerprint", ["web_fingerprint"], raw_web, store)+ assert added_web == 1+ # Existing host updated, no duplicate created+ assert len(store.hosts()) == 1+ assert store.hosts()[0].os == "Ubuntu Linux"+++