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(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.py
index 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.LOW
REQUIRES = []
- 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_STRINGS
do_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 finding
is_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[:], raw
diff --git a/ares/normalize/artifacts.py b/ares/normalize/artifacts.py
index 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 += 1
return 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.py
index 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"
+
+
+