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
"""
ARES Data Normalization Layer
Standardized artifact types that all modules produce and consume.
Every module output is normalized into typed artifacts.
This enables:
- Cross-module data flow (kerberoast consumes spn_list from enum_spn)
- Attack graph construction (artifacts become nodes)
- Universal querying ("give me all credentials from this campaign")
- Data deduplication (same host reported by two modules = one node)
Artifact taxonomy:
Host - IP address, hostname, OS, open ports
Domain - AD domain with trust relationships
User - domain/local user account
Credential - NTLM hash, cleartext, ticket, key
Service - SPN-registered service
Permission - ACE (who can do what to whom)
Finding - vulnerability/misconfiguration
Hash - crackable hash (KRB5TGS, KRB5ASREP, NTLM)
Secret - plaintext secret (API key, password, token)
CloudResource - S3 bucket, IAM role, storage account
Usage in a module:
from ares.normalize.artifacts import NormalizedArtifact, User, Host, Credential
# In module.run():
artifacts = [
Host(ip="10.0.0.1", hostname="dc01", os="Windows Server 2022", is_dc=True),
User(username="svc_sql", domain="CORP", spns=["MSSQLSvc/db01:1433"]),
]
return findings, {"artifacts": [a.to_dict() for a in artifacts]}
"""
from __future__ import annotations
import hashlib
import uuid
from dataclasses import dataclass, field
from enum import Enum
from typing import Any
from ares.core.logger import get_logger
logger = get_logger("ares.normalize.artifacts")
# ── Artifact type registry ─────────────────────────────────────────────────────
class ArtifactType(str, Enum):
HOST = "host"
DOMAIN = "domain"
USER = "user"
GROUP = "group"
CREDENTIAL = "credential"
SERVICE = "service"
PERMISSION = "permission"
HASH = "hash"
SECRET = "secret"
CLOUD_RESOURCE = "cloud_resource"
NETWORK_PATH = "network_path"
# ── Base artifact ─────────────────────────────────────────────────────────────
@dataclass
class NormalizedArtifact:
"""
Base class for all normalized artifacts.
Every artifact has:
- type: what it is
- uid: deterministic ID based on content (dedup-friendly)
- source: module that produced it
- campaign_id: which campaign this belongs to
- tags: free-form labels
- raw: original data from module (preserved for graph edges)
"""
artifact_type: ArtifactType = field(default=ArtifactType.HOST, init=True)
source_module: str = ""
campaign_id: str = ""
tags: list[str] = field(default_factory=list)
raw: dict[str, Any] = field(default_factory=dict)
metadata: dict[str, Any] = field(default_factory=dict)
_uid: str | None = field(default=None, repr=False)
@property
def uid(self) -> str:
"""Deterministic UID - same content = same ID (enables deduplication)."""
if self._uid:
return self._uid
key = f"{self.artifact_type.value}:{self._dedup_key()}"
return hashlib.sha256(key.encode()).hexdigest()[:16]
def _dedup_key(self) -> str:
"""Override in subclasses with the fields that make this artifact unique."""
return str(uuid.uuid4())
def to_dict(self) -> dict[str, Any]:
d: dict[str, Any] = {
"uid": self.uid,
"type": self.artifact_type.value,
"source_module": self.source_module,
"campaign_id": self.campaign_id,
"tags": self.tags,
"metadata": self.metadata,
}
d.update(self._to_dict_fields())
return d
def _to_dict_fields(self) -> dict[str, Any]:
return {}
def __hash__(self) -> int:
return hash(self.uid)
def __eq__(self, other: object) -> bool:
return isinstance(other, NormalizedArtifact) and self.uid == other.uid
# ── Concrete artifact types ───────────────────────────────────────────────────
@dataclass
class HostArtifact(NormalizedArtifact):
"""A discovered host on the network."""
ip_address: str = ""
ip: str = "" # convenience alias accepted in constructor
hostname: str = ""
fqdn: str = ""
os: str = ""
os_version: str = ""
domain: str = ""
is_dc: bool = False
domain_controller: bool = False # alias for is_dc
open_ports: list[int] = field(default_factory=list)
services: list[str] = field(default_factory=list)
vulns: list[dict[str, Any]] = field(default_factory=list)
hostnames: list[str] = field(default_factory=list)
def __post_init__(self) -> None:
self.artifact_type = ArtifactType.HOST
# Allow ip= shorthand
if self.ip and not self.ip_address:
self.ip_address = self.ip
elif self.ip_address and not self.ip:
self.ip = self.ip_address
# Allow domain_controller= shorthand
if self.domain_controller and not self.is_dc:
self.is_dc = self.domain_controller
elif self.is_dc and not self.domain_controller:
self.domain_controller = self.is_dc
def _dedup_key(self) -> str:
return f"{self.ip_address}:{self.domain}"
def _to_dict_fields(self) -> dict[str, Any]:
return {
"ip_address": self.ip_address, "hostname": self.hostname,
"fqdn": self.fqdn, "os": self.os, "os_version": self.os_version,
"domain": self.domain, "is_dc": self.is_dc, "open_ports": self.open_ports,
"services": self.services, "vulns": self.vulns, "hostnames": self.hostnames,
}
@dataclass
class DomainArtifact(NormalizedArtifact):
"""An Active Directory domain."""
domain_name: str = ""
netbios_name: str = ""
forest: str = ""
domain_level: int = 0 # 2003=2, 2008=3, 2012=4, 2016=6, 2019=7
trusts: list[str] = field(default_factory=list)
dc_count: int = 0
def __post_init__(self) -> None:
self.artifact_type = ArtifactType.DOMAIN
def _dedup_key(self) -> str:
return self.domain_name.lower()
def _to_dict_fields(self) -> dict[str, Any]:
return {
"domain_name": self.domain_name, "netbios_name": self.netbios_name,
"forest": self.forest, "domain_level": self.domain_level,
"trusts": self.trusts, "dc_count": self.dc_count,
}
@dataclass
class UserArtifact(NormalizedArtifact):
"""A domain or local user account."""
username: str = ""
domain: str = ""
display_name: str = ""
enabled: bool = True
spns: list[str] = field(default_factory=list) # Kerberoastable if non-empty
spn: list[str] = field(default_factory=list) # alias for spns
groups: list[str] = field(default_factory=list) # Group memberships
member_of: list[str] = field(default_factory=list) # alias for groups
is_admin: bool = False
is_service: bool = False
no_preauth: bool = False # ASREPRoastable if True
password_age_days: int = 0
last_logon_days: int = 0
def __post_init__(self) -> None:
self.artifact_type = ArtifactType.USER
# Sync spn ↔ spns
if self.spn and not self.spns:
self.spns = self.spn
elif self.spns and not self.spn:
self.spn = self.spns
# Sync groups ↔ member_of
if self.member_of and not self.groups:
self.groups = self.member_of
elif self.groups and not self.member_of:
self.member_of = self.groups
def _dedup_key(self) -> str:
return f"{self.domain.lower()}\\{self.username.lower()}"
def _to_dict_fields(self) -> dict[str, Any]:
return {
"username": self.username, "domain": self.domain,
"enabled": self.enabled, "spns": self.spns, "member_of": self.member_of,
"is_admin": self.is_admin, "is_service": self.is_service,
"no_preauth": self.no_preauth, "password_age_days": self.password_age_days,
}
@property
def is_kerberoastable(self) -> bool:
return bool(self.spns) and self.enabled
@property
def is_asreproastable(self) -> bool:
return self.no_preauth and self.enabled
@dataclass
class CredentialArtifact(NormalizedArtifact):
"""A captured credential of any type."""
username: str = ""
domain: str = ""
cred_type: str = "" # ntlm | cleartext | kerberos_ticket | api_key | jwt | ssh_key
secret: str = "" # plaintext secret (optional, for test fixtures)
secret_hash: str = "" # SHA-256 of the secret value (for dedup without storing plaintext)
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
has_password: bool = False
note: str = ""
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()
def _dedup_key(self) -> str:
return f"{self.domain}\\{self.username}:{self.cred_type}:{self.source_host}:{self.secret_hash[:8]}"
def _to_dict_fields(self) -> dict[str, Any]:
d = {
"username": self.username, "domain": self.domain,
"cred_type": self.cred_type, "cracked": self.cracked,
"source_host": self.source_host, "privilege": self.privilege,
"protocol": self.protocol, "has_password": self.has_password,
"note": self.note,
}
return d
@dataclass
class HashArtifact(NormalizedArtifact):
"""A crackable hash (Kerberos TGS, AS-REP, NTLM)."""
hash_type: str = "" # krb5tgs_rc4 | krb5tgs_aes | krb5asrep | ntlm
username: str = ""
domain: str = ""
module_id: str = "" # which module produced this hash
hashcat_mode: int = 0
hash_value: str = "" # full hash string (passed to cracker, not logged)
hash_preview: str = "" # first 12 chars for identification only (auto-derived)
nt_hash: str = "" # NT hash specifically (NTLM only)
def __post_init__(self) -> None:
self.artifact_type = ArtifactType.HASH
# Auto-derive hash_preview from hash_value if not set
if self.hash_value and not self.hash_preview:
self.hash_preview = self.hash_value[:12]
def _dedup_key(self) -> str:
return f"{self.hash_type}:{self.domain}\\{self.username}"
def _to_dict_fields(self) -> dict[str, Any]:
return {
"hash_type": self.hash_type, "username": self.username,
"domain": self.domain, "hashcat_mode": self.hashcat_mode,
"hash_preview": self.hash_preview,
}
@property
def crack_command(self) -> str:
return f"hashcat -m {self.hashcat_mode} hashes.txt wordlist.txt -r rules/best64.rule"
@dataclass
class PermissionArtifact(NormalizedArtifact):
"""An ACE (Access Control Entry) - who can do what to whom."""
principal: str = "" # who holds the right
target: str = "" # object the right is on
right: str = "" # GenericAll, WriteDACL, etc.
domain: str = ""
is_dangerous: bool = False
DANGEROUS_RIGHTS = {
"GenericAll", "GenericWrite", "WriteDACL", "WriteOwner",
"AllExtendedRights", "DS-Replication-Get-Changes-All",
}
def __post_init__(self) -> None:
self.artifact_type = ArtifactType.PERMISSION
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}"
def _to_dict_fields(self) -> dict[str, Any]:
return {
"principal": self.principal, "target": self.target,
"right": self.right, "domain": self.domain, "is_dangerous": self.is_dangerous,
}
@dataclass
class CloudResourceArtifact(NormalizedArtifact):
"""A cloud resource (S3, IAM role, storage account, GCS bucket)."""
provider: str = "" # aws | azure | gcp
resource_type: str = "" # s3_bucket | iam_role | storage_container | gcs_bucket
resource_id: str = ""
region: str = ""
is_public: bool = False
permissions: list[str] = field(default_factory=list)
def __post_init__(self) -> None:
self.artifact_type = ArtifactType.CLOUD_RESOURCE
def _dedup_key(self) -> str:
return f"{self.provider}:{self.resource_type}:{self.resource_id}"
def _to_dict_fields(self) -> dict[str, Any]:
return {
"provider": self.provider, "resource_type": self.resource_type,
"resource_id": self.resource_id, "region": self.region,
"is_public": self.is_public, "permissions": self.permissions,
}
# ── Artifact store (in-memory, per-campaign) ──────────────────────────────────
class ArtifactStore:
"""
In-memory artifact store for a single campaign run.
Deduplicates by artifact UID.
Can be serialized to DB or passed between modules.
"""
def __init__(self) -> None:
self._store: dict[str, NormalizedArtifact] = {}
def add(self, artifact: NormalizedArtifact) -> NormalizedArtifact:
"""Add or merge artifact. Returns the canonical (possibly existing) artifact."""
if artifact.uid in self._store:
return self._store[artifact.uid] # dedup
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)
def get(self, artifact_type: ArtifactType) -> list[NormalizedArtifact]:
return [a for a in self._store.values() if a.artifact_type == artifact_type]
def hosts(self) -> list[HostArtifact]:
return [a for a in self._store.values() if isinstance(a, HostArtifact)]
def users(self) -> list[UserArtifact]:
return [a for a in self._store.values() if isinstance(a, UserArtifact)]
def credentials(self) -> list[CredentialArtifact]:
return [a for a in self._store.values() if isinstance(a, CredentialArtifact)]
def hashes(self) -> list[HashArtifact]:
return [a for a in self._store.values() if isinstance(a, HashArtifact)]
def permissions(self) -> list[PermissionArtifact]:
return [a for a in self._store.values() if isinstance(a, PermissionArtifact)]
def kerberoastable(self) -> list[UserArtifact]:
return [u for u in self.users() if u.is_kerberoastable]
def asreproastable(self) -> list[UserArtifact]:
return [u for u in self.users() if u.is_asreproastable]
def to_list(self) -> list[dict[str, Any]]:
return [a.to_dict() for a in self._store.values()]
def stats(self) -> dict[str, int]:
counts: dict[str, int] = {}
for a in self._store.values():
k = a.artifact_type.value
counts[k] = counts.get(k, 0) + 1
return counts
def __len__(self) -> int:
return len(self._store)
def clear(self) -> None:
"""Remove all artifacts from the store."""
self._store.clear()
def total(self) -> int:
"""Return total number of artifacts."""
return len(self._store)
# ── Public aliases ────────────────────────────────────────────────────────────
#: ArtifactNormalizer is the canonical external-facing name for ArtifactStore.
ArtifactNormalizer = ArtifactStore
# ── Artifact Normalizer ───────────────────────────────────────────────────────
class ArtifactNormalizer: # noqa: F811
"""
Auto-normalizes module raw output into typed ArtifactStore entries.
Called by AresEngine after each successful module execution.
Maps module OUTPUTS capability tags to raw output keys → artifact types.
"""
def normalize(
self,
module_id: str,
outputs: list[str],
raw: dict,
store: ArtifactStore,
) -> int:
"""
Normalize raw module output into artifacts.
Returns number of artifacts added.
Args:
module_id: module that produced the output
outputs: module OUTPUTS capability list
raw: raw output dict from the module
store: ArtifactStore to populate
"""
count = 0
for capability in outputs:
try:
added = self._normalize_capability(capability, raw, store)
count += added
except Exception as exc:
logger.warning(
"artifact_normalization_failed",
module_id=module_id,
capability=capability,
error=str(exc),
)
return count
def _normalize_capability(
self, capability: str, raw: dict, store: ArtifactStore
) -> int:
"""Route a capability to its specific normalizer."""
handlers: dict[str, Any] = {
"user_list": self._normalize_users,
"users": self._normalize_users,
"domain_users": self._normalize_users,
"computer_list": self._normalize_computers,
"computers": self._normalize_computers,
"kerberos_hashes": self._normalize_kerberos_hashes,
"asrep_hashes": self._normalize_asrep_hashes,
"ntlm_hashes": self._normalize_ntlm_hashes,
"hashes": self._normalize_ntlm_hashes,
"cached_hashes": self._normalize_ntlm_hashes,
"spn_list": self._normalize_spns,
"spns": self._normalize_spns,
"acl_findings": self._normalize_permissions,
"misconfigs": self._normalize_permissions,
"aws_findings": self._normalize_cloud,
"privesc_vectors": self._normalize_host_vuln,
# P0 Capabilities
"cleartext_credentials": self._normalize_cleartext_credentials,
"credentials": self._normalize_cleartext_credentials,
"browser_passwords": self._normalize_cleartext_credentials,
"cracked_credentials": self._normalize_cracked_credentials,
"laps_passwords": self._normalize_laps_passwords,
"kerberos_tickets": self._normalize_kerberos_tickets,
"kerberos_ticket": self._normalize_kerberos_tickets,
"tickets": self._normalize_kerberos_tickets,
"golden_ticket": self._normalize_kerberos_tickets,
"open_ports": self._normalize_open_ports,
"service_map": self._normalize_open_ports,
# LSA Secrets & Cached Domain Credentials (MOD-028)
"lsa_secrets": self._normalize_lsa_secrets,
"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,
# 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,
# Azure & Azure AD (MOD-066)
"azure_findings": self._normalize_azure,
"azure_ad_findings": self._normalize_azure_ad,
"access_tokens": self._normalize_tokens,
"access_token": self._normalize_tokens,
"oauth_tokens": self._normalize_tokens,
# GCP (MOD-068)
"gcp_findings": self._normalize_gcp,
# Linux Containers & K8s (MOD-040)
"container_escape_vectors": self._normalize_container_vectors,
"k8s_rbac_findings": self._normalize_k8s_rbac,
# Identity Federation (MOD-051)
"federation_trusts": self._normalize_federation_trusts,
"golden_saml_paths": self._normalize_golden_saml,
"pivot_paths": self._normalize_pivot_paths,
# SNMP & Network Discovery (MOD-061 / Recon)
"snmp_findings": self._normalize_snmp_findings,
"system_info": self._normalize_system_info,
"password_policy": self._normalize_password_policy,
# Windows Scheduled Tasks & Registry (MOD-070)
"scheduled_tasks": self._normalize_scheduled_tasks,
"credential_hints": self._normalize_registry_credentials,
# Secrets Scanner & SMB Shares (MOD-074)
"credential_list": self._normalize_secrets_scan,
"discovered_secrets": self._normalize_secrets_scan,
"sensitive_data_found": self._normalize_secrets_scan,
"file_share_list": self._normalize_smb_shares,
"sensitive_file_paths": self._normalize_smb_shares,
}
handler = handlers.get(capability)
if handler:
try:
return handler(raw, store, capability)
except TypeError:
return handler(raw, store)
return 0
def _normalize_users(self, raw: dict, store: ArtifactStore) -> int:
users = raw.get("users") or raw.get("user_list", [])
count = 0
for u in users:
if not isinstance(u, dict):
continue
artifact = UserArtifact(
username = u.get("samAccountName", u.get("username", "")),
domain = u.get("domain", ""),
enabled = u.get("enabled", True),
is_admin = bool(u.get("isAdmin", u.get("is_admin", u.get("adminCount", 0) > 0))),
no_preauth = bool(u.get("noPreauth", u.get("no_preauth", u.get("dont_req_preauth", False)))),
spns = u.get("spns", u.get("spn", [])),
)
store.add(artifact)
count += 1
return count
def _normalize_computers(self, raw: dict, store: ArtifactStore) -> int:
computers = raw.get("computers") or raw.get("computer_list", [])
count = 0
for c in computers:
if not isinstance(c, dict):
continue
artifact = HostArtifact(
ip_address = c.get("ip", c.get("ip_address", "")),
hostname = c.get("dns", c.get("dns_name", c.get("name", ""))),
is_dc = c.get("is_dc", False),
os = c.get("os", ""),
os_version = c.get("os_version", ""),
domain = c.get("domain", ""),
)
store.add(artifact)
count += 1
return count
def _normalize_kerberos_hashes(self, raw: dict, store: ArtifactStore) -> int:
hashes = raw.get("hashes") or raw.get("kerberos_hashes", [])
count = 0
for h in hashes:
if isinstance(h, str):
# Parse username from hash: $krb5tgs$23$*username$DOMAIN$...
parts = h.split("$")
raw_user = parts[3].split("@")[0] if len(parts) > 3 else ""
username = raw_user.lstrip("*")
domain = parts[4].split("@")[0] if len(parts) > 4 else ""
artifact = HashArtifact(
username = username,
domain = domain,
hash_value = h[:120],
hash_type = "krb5tgs",
hashcat_mode = 13100,
)
store.add(artifact)
count += 1
elif isinstance(h, dict):
artifact = HashArtifact(
username = h.get("username", ""),
domain = h.get("domain", ""),
hash_value = (h.get("hash") or h.get("hash_value") or "")[:120],
hash_type = "krb5tgs",
hashcat_mode = 13100,
)
store.add(artifact)
count += 1
return count
def _normalize_asrep_hashes(self, raw: dict, store: ArtifactStore) -> int:
hashes = raw.get("hashes") or raw.get("asrep_hashes", [])
count = 0
for h in hashes:
if isinstance(h, str):
parts = h.split("$")
user_part = parts[3] if len(parts) > 3 else ""
if "@" in user_part:
username, domain = user_part.split("@", 1)
else:
username = user_part
domain = parts[4].split("@")[0] if len(parts) > 4 else ""
artifact = HashArtifact(
username = username,
domain = domain,
hash_value = h[:120],
hash_type = "krb5asrep",
hashcat_mode = 18200,
)
store.add(artifact)
count += 1
elif isinstance(h, dict):
artifact = HashArtifact(
username = h.get("username", ""),
domain = h.get("domain", ""),
hash_value = (h.get("hash") or h.get("hash_value") or "")[:120],
hash_type = "krb5asrep",
hashcat_mode = 18200,
)
store.add(artifact)
count += 1
return count
def _normalize_ntlm_hashes(self, raw: dict, store: ArtifactStore) -> int:
hashes = (
raw.get("hashes")
or raw.get("ntlm_hashes")
or raw.get("sam_hashes")
or []
)
count = 0
for h in hashes:
if isinstance(h, dict):
artifact = HashArtifact(
username = h.get("username", ""),
domain = h.get("domain", ""),
hash_value = h.get("nt_hash") or h.get("hash") or h.get("ntlm", ""),
hash_type = "ntlm",
hashcat_mode = 1000,
)
store.add(artifact)
count += 1
elif isinstance(h, str):
parts = h.split(":")
username = parts[0] if parts else ""
nt_hash = ""
if len(parts) >= 4:
nt_hash = parts[3]
elif len(parts) == 2:
nt_hash = parts[1]
else:
nt_hash = h
artifact = HashArtifact(
username = username,
domain = "",
hash_value = nt_hash,
hash_type = "ntlm",
hashcat_mode = 1000,
)
store.add(artifact)
count += 1
return count
def _normalize_spns(self, raw: dict, store: ArtifactStore) -> int:
spns = raw.get("spns") or raw.get("spn_list", [])
count = 0
for s in spns:
if not isinstance(s, dict):
continue
spn_entries = s.get("spns") or s.get("spn_list") or s.get("spn", [])
if isinstance(spn_entries, str):
spn_entries = [spn_entries]
artifact = UserArtifact(
username = s.get("samAccountName", s.get("name", s.get("username", ""))),
domain = s.get("domain", ""),
enabled = s.get("enabled", True),
is_admin = s.get("is_admin", s.get("isAdmin", False)),
spns = spn_entries,
)
store.add(artifact)
count += 1
return count
def _normalize_permissions(self, raw: dict, store: ArtifactStore) -> int:
misconfigs = raw.get("misconfigs", [])
count = 0
for m in misconfigs:
if not isinstance(m, dict):
continue
artifact = PermissionArtifact(
principal = m.get("trustee_sid", ""),
target = m.get("target", ""),
right = m.get("right", ""),
domain = "",
)
store.add(artifact)
count += 1
return count
def _normalize_cloud(self, raw: dict, store: ArtifactStore) -> int:
count = 0
region = raw.get("region", "")
s3 = raw.get("s3", {})
for bucket in s3.get("public_buckets", []):
artifact = CloudResourceArtifact(
resource_id = bucket.get("name", ""),
resource_type = "s3_bucket",
region = region,
is_public = True,
)
store.add(artifact)
count += 1
for path in raw.get("privesc_paths", []):
if isinstance(path, dict):
res_id = (
path.get("role_arn")
or path.get("policy_name")
or path.get("action")
or path.get("technique")
or "iam_privesc_path"
)
elif isinstance(path, str):
res_id = path
else:
continue
artifact = CloudResourceArtifact(
resource_id = str(res_id),
resource_type = "iam_role",
region = region,
is_public = False,
)
store.add(artifact)
count += 1
return count
def _normalize_host_vuln(self, raw: dict, store: ArtifactStore) -> int:
host = raw.get("target") or raw.get("host", "")
if not host or host == "localhost":
return 0
existing = None
for h in store.hosts():
if h.ip_address == host or h.hostname == host:
existing = h
break
vulns = raw.get("privesc_vectors", [])
parsed_vulns = []
if isinstance(vulns, list):
for v in vulns:
if isinstance(v, dict):
parsed_vulns.append(v)
elif hasattr(v, "evidence") and isinstance(v.evidence, dict):
parsed_vulns.append(v.evidence)
elif isinstance(v, str) and v:
parsed_vulns.append({"vector": v})
if existing:
if parsed_vulns:
existing.vulns.extend(parsed_vulns)
return 1
artifact = HostArtifact(
ip_address = host,
hostname = host,
vulns = parsed_vulns,
)
store.add(artifact)
return 1
# ── P0 Handlers ────────────────────────────────────────────────────────────
def _normalize_cleartext_credentials(self, raw: dict, store: ArtifactStore) -> int:
creds = raw.get("cleartext_credentials") or raw.get("credentials", [])
if isinstance(creds, (dict, str)):
creds = [creds]
elif not isinstance(creds, list):
return 0
count = 0
default_target = raw.get("target") or raw.get("host", "")
for c in creds:
if hasattr(c, "evidence") and isinstance(c.evidence, dict):
ev = c.evidence
username = ev.get("user") or ev.get("username", "")
secret = ev.get("password") or ev.get("secret", "")
domain = ev.get("domain", "")
source_host = ev.get("host") or default_target
privilege = "unknown"
elif isinstance(c, dict):
username = c.get("username") or c.get("user") or c.get("account", "")
domain = c.get("domain", "")
secret = c.get("password") or c.get("secret") or c.get("plaintext", "")
source_host = c.get("host") or c.get("target") or c.get("computer") or default_target
privilege = c.get("privilege", "unknown")
elif isinstance(c, str):
username = "unknown"
domain = ""
secret = c
source_host = default_target
privilege = "unknown"
else:
logger.warning("cleartext_credentials_invalid_entry", type=type(c).__name__)
continue
if not username and not secret:
continue
artifact = CredentialArtifact(
username = username,
domain = domain,
cred_type = "cleartext",
secret = secret,
source_host = source_host,
privilege = privilege,
)
store.add(artifact)
count += 1
return count
def _normalize_cracked_credentials(self, raw: dict, store: ArtifactStore) -> int:
cracked = raw.get("cracked_credentials") or raw.get("cracked_users", [])
count = 0
for c in cracked:
if not isinstance(c, dict):
continue
secret = c.get("plaintext") or c.get("password") or c.get("secret", "")
artifact = CredentialArtifact(
username = c.get("username", ""),
domain = c.get("domain", ""),
cred_type = "cleartext" if secret else (c.get("hash_type") or "ntlm"),
secret = secret,
cracked = True,
source_host = c.get("host") or c.get("target", ""),
privilege = c.get("privilege", "unknown"),
)
store.add(artifact)
count += 1
return count
def _normalize_laps_passwords(self, raw: dict, store: ArtifactStore) -> int:
laps = raw.get("laps_passwords") or raw.get("entries", [])
count = 0
for e in laps:
if not isinstance(e, dict):
continue
comp = e.get("computer") or e.get("computer_name") or e.get("host", "")
pwd = e.get("password", "")
has_pwd = bool(e.get("has_password", False) or pwd)
note = ""
if not pwd and e.get("has_password"):
note = "password stored in vault"
artifact = CredentialArtifact(
username = e.get("username", "Administrator"),
domain = e.get("domain", "") or comp,
cred_type = "laps",
secret = pwd,
source_host = comp,
privilege = "local_admin",
has_password= has_pwd,
note = note,
)
store.add(artifact)
count += 1
return count
def _normalize_kerberos_tickets(self, raw: dict, store: ArtifactStore) -> int:
tickets = (
raw.get("kerberos_tickets")
or raw.get("kerberos_ticket")
or raw.get("tickets")
or []
)
if isinstance(tickets, (str, dict)):
tickets = [tickets]
count = 0
for t in tickets:
if isinstance(t, str):
user = (
raw.get("forged_as")
or raw.get("impersonated")
or raw.get("username")
or "unknown"
)
dom = raw.get("domain") or ""
artifact = CredentialArtifact(
username = user,
domain = dom,
cred_type = "kerberos_ticket",
secret = t,
)
store.add(artifact)
count += 1
elif isinstance(t, dict):
client = (
t.get("client")
or t.get("username")
or t.get("default_principal")
or t.get("principal", "")
)
realm = t.get("realm") or t.get("domain", "")
if "@" in client and not realm:
parts = client.split("@", 1)
client = parts[0]
realm = parts[1]
ticket_path = (
t.get("file_path")
or t.get("ticket_path")
or t.get("ccache_path")
or t.get("path", "")
)
artifact = CredentialArtifact(
username = client,
domain = realm,
cred_type = "kerberos_ticket",
secret = ticket_path,
source_host = t.get("target") or t.get("host", ""),
)
store.add(artifact)
count += 1
return count
def _normalize_open_ports(self, raw: dict, store: ArtifactStore) -> int:
ports_raw = raw.get("open_ports") or raw.get("port_results") or []
ports: list[int] = []
if isinstance(ports_raw, list):
for p in ports_raw:
if isinstance(p, int):
ports.append(p)
elif isinstance(p, dict) and "port" in p and isinstance(p["port"], int):
ports.append(p["port"])
elif str(p).isdigit():
ports.append(int(p))
if "service_map" in raw and isinstance(raw["service_map"], dict):
for k in raw["service_map"]:
if str(k).isdigit():
ports.append(int(k))
ports = sorted(set(ports))
if not ports:
return 0
target = raw.get("target") or raw.get("host", "")
# Look for existing HostArtifact with same target/ip
existing_host = None
if target:
for h in store.hosts():
if h.ip_address == target or h.hostname == target:
existing_host = h
break
if existing_host:
existing_host.open_ports = sorted(set(existing_host.open_ports + ports))
return 1
artifact = HostArtifact(
ip_address = target,
hostname = target,
open_ports = ports,
)
store.add(artifact)
return 1
def _normalize_lsa_secrets(self, raw: dict, store: ArtifactStore) -> int:
"""
Normalize LSA secrets (service accounts, machine account passwords, DPAPI keys)
into CredentialArtifact(cred_type="lsa_secret").
"""
secrets = raw.get("lsa_secrets") or []
if isinstance(secrets, (str, dict)):
secrets = [secrets]
count = 0
target = raw.get("target") or raw.get("host", "")
domain_default = raw.get("domain", "")
for s in secrets:
if isinstance(s, dict):
username = s.get("username") or s.get("name") or s.get("secret_name", "")
domain = s.get("domain") or domain_default
secret_val = s.get("secret") or s.get("value") or s.get("password", "")
source_host = s.get("host") or s.get("target") or target
privilege = s.get("privilege") or ("service_account" if ("$MACHINE.ACC" in username or "_SC_" in username) else "unknown")
elif isinstance(s, str):
s_str = s.strip()
if ":" in s_str:
name_part, val_part = s_str.split(":", 1)
username = name_part.strip()
secret_val = val_part.strip()
else:
username = ""
secret_val = s_str
domain = domain_default
source_host = target
privilege = "service_account" if ("$MACHINE.ACC" in username or "_SC_" in username or "DPAPI" in username) else "unknown"
else:
continue
artifact = CredentialArtifact(
username=username,
domain=domain,
cred_type="lsa_secret",
secret=secret_val,
cracked=False,
source_host=source_host,
privilege=privilege,
)
store.add(artifact)
count += 1
return count
def _normalize_cached_domain_credentials(self, raw: dict, store: ArtifactStore) -> int:
"""
Normalize DCC2 / MSCACHE2 cached domain hashes into CredentialArtifact(cred_type="cached_domain", cracked=False).
"""
cached = raw.get("cached_credentials") or raw.get("cached_creds", [])
if isinstance(cached, (str, dict)):
cached = [cached]
count = 0
target = raw.get("target") or raw.get("host", "")
domain_default = raw.get("domain", "")
for c in cached:
if isinstance(c, dict):
username = c.get("username", "")
domain = c.get("domain") or domain_default
hash_val = c.get("hash") or c.get("secret", "")
source_host = c.get("host") or c.get("target") or target
privilege = c.get("privilege", "user")
elif isinstance(c, str):
c_str = c.strip()
if ":" in c_str:
user_part, hash_part = c_str.split(":", 1)
if "\\" in user_part:
domain, username = user_part.split("\\", 1)
else:
domain = domain_default
username = user_part
hash_val = hash_part.strip()
elif "#" in c_str and ("$DCC2$" in c_str or "$MSCACHE2$" in c_str):
parts = c_str.split("#")
username = parts[1] if len(parts) > 1 else ""
domain = domain_default
hash_val = c_str
else:
username = ""
domain = domain_default
hash_val = c_str
source_host = target
privilege = "user"
else:
continue
artifact = CredentialArtifact(
username=username,
domain=domain,
cred_type="cached_domain",
secret=hash_val,
cracked=False,
source_host=source_host,
privilege=privilege,
)
store.add(artifact)
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
# ── 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] = []
services: list[str] = []
if isinstance(service_versions, dict):
for p_str, info in service_versions.items():
if str(p_str).isdigit():
ports.append(int(p_str))
if isinstance(info, dict) and info.get("service"):
services.append(f"{p_str}:{info['service']}")
elif isinstance(info, str) and info:
services.append(f"{p_str}:{info}")
ports = sorted(set(ports))
vuln_svcs = raw.get("vulnerable_services", [])
parsed_vulns = []
if isinstance(vuln_svcs, list):
for vs in vuln_svcs:
if isinstance(vs, dict):
parsed_vulns.append(vs)
elif hasattr(vs, "evidence") and isinstance(vs.evidence, dict):
parsed_vulns.append(vs.evidence)
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(set(existing.open_ports + ports))
if services:
existing.services = sorted(set(existing.services + services))
if parsed_vulns:
existing.vulns.extend(parsed_vulns)
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,
services=services,
vulns=parsed_vulns,
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 ""
admin_interfaces = raw.get("admin_interfaces", [])
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
if admin_interfaces:
existing.metadata["admin_interfaces"] = admin_interfaces
return 1
artifact = HostArtifact(
ip_address=target,
hostname=target,
os=server,
metadata={"admin_interfaces": admin_interfaces} if admin_interfaces else {},
source_module=capability,
)
store.add(artifact)
return 1
def _normalize_azure(
self, raw: dict, store: ArtifactStore, capability: str = "azure_findings"
) -> int:
"""Normalize Azure recon and attack output into CloudResourceArtifact, PermissionArtifact, UserArtifact."""
count = 0
subscription_id = raw.get("subscription_id", "")
# 1. Storage
storage = raw.get("storage", {})
if isinstance(storage, dict):
for c in storage.get("public_containers", []):
if isinstance(c, dict):
sa = c.get("storage_account", "")
c_name = c.get("container", "")
rg = c.get("resource_group", "")
artifact = CloudResourceArtifact(
provider="azure",
resource_type="storage_container",
resource_id=f"{sa}/{c_name}",
region=rg,
is_public=True,
source_module=capability,
)
store.add(artifact)
count += 1
# 2. RBAC
rbac = raw.get("rbac", {})
if isinstance(rbac, dict):
for o in rbac.get("owner_assignments", []):
if isinstance(o, dict):
p_id = o.get("principal_id", "")
scope = o.get("scope", "") or f"/subscriptions/{subscription_id}"
if p_id:
artifact = PermissionArtifact(
principal=p_id,
target=scope,
right="Owner",
domain=subscription_id,
is_dangerous=True,
source_module=capability,
)
store.add(artifact)
count += 1
for c in rbac.get("contributor_assignments", []):
if isinstance(c, dict):
p_id = c.get("principal_id", "")
scope = c.get("scope", "") or f"/subscriptions/{subscription_id}"
if p_id:
artifact = PermissionArtifact(
principal=p_id,
target=scope,
right="Contributor",
domain=subscription_id,
is_dangerous=True,
source_module=capability,
)
store.add(artifact)
count += 1
for admin in rbac.get("classic_admins", []):
if isinstance(admin, str) and admin:
artifact = PermissionArtifact(
principal=admin,
target=f"/subscriptions/{subscription_id}",
right="ClassicCoAdministrator",
domain=subscription_id,
is_dangerous=True,
source_module=capability,
)
store.add(artifact)
count += 1
# 3. NSG
nsg = raw.get("nsg", {})
if isinstance(nsg, dict):
for rule in nsg.get("open_rules", []):
if isinstance(rule, dict):
nsg_name = rule.get("nsg", "")
r_name = rule.get("rule_name", "")
rg = rule.get("resource_group", "")
artifact = CloudResourceArtifact(
provider="azure",
resource_type="network_security_group",
resource_id=f"{nsg_name}/{r_name}" if r_name else nsg_name,
region=rg,
is_public=True,
source_module=capability,
)
store.add(artifact)
count += 1
# 4. AAD users
aad = raw.get("aad_users", {})
if isinstance(aad, dict):
for u in aad.get("admin_users", []):
if isinstance(u, str) and u:
artifact = UserArtifact(
username=u,
domain="azure_ad",
is_admin=True,
source_module=capability,
)
store.add(artifact)
count += 1
return count
def _normalize_azure_ad(
self, raw: dict, store: ArtifactStore, capability: str = "azure_ad_findings"
) -> int:
"""Normalize Azure AD findings into UserArtifact and PermissionArtifact."""
count = 0
tenant_id = raw.get("tenant_id", "azure_ad")
# 1. Privileged users
for u in raw.get("privileged_users", []):
if isinstance(u, str) and u:
artifact = UserArtifact(
username=u,
domain=tenant_id,
is_admin=True,
source_module=capability,
)
store.add(artifact)
count += 1
# 2. Guests
for g in raw.get("guests", []):
g_name = g.get("userPrincipalName", "") if isinstance(g, dict) else (g if isinstance(g, str) else "")
if g_name:
artifact = UserArtifact(
username=g_name,
domain=tenant_id,
is_admin=False,
source_module=capability,
)
store.add(artifact)
count += 1
# 3. High privilege service principals
for sp in raw.get("high_priv_sps", []):
if isinstance(sp, str) and sp:
artifact = PermissionArtifact(
principal=sp,
target=tenant_id,
right="PrivilegedAppRole",
domain=tenant_id,
is_dangerous=True,
source_module=capability,
)
store.add(artifact)
count += 1
# 4. Service principals list
for sp in raw.get("service_principals", []):
if isinstance(sp, dict) and sp.get("privileged"):
sp_name = sp.get("displayName") or sp.get("appId", "")
if sp_name:
artifact = PermissionArtifact(
principal=sp_name,
target=tenant_id,
right="PrivilegedServicePrincipal",
domain=tenant_id,
is_dangerous=True,
source_module=capability,
)
store.add(artifact)
count += 1
return count
def _normalize_tokens(
self, raw: dict, store: ArtifactStore, capability: str = "access_tokens"
) -> int:
"""Normalize access tokens and OAuth tokens into CredentialArtifact(cred_type='oauth_token')."""
count = 0
tokens = raw.get("access_tokens") or raw.get("oauth_tokens") or raw.get("access_token") or raw.get("tokens")
if not tokens:
return 0
if isinstance(tokens, (str, dict)):
tokens = [tokens]
elif not isinstance(tokens, list):
return 0
tenant = raw.get("tenant_id") or raw.get("domain") or "cloud"
for t in tokens:
if isinstance(t, str):
t_str = t.strip()
if not t_str:
continue
artifact = CredentialArtifact(
username="oauth_bearer",
domain=tenant,
cred_type="oauth_token",
secret=t_str,
source_host=tenant,
privilege="token",
source_module=capability,
)
store.add_credential(artifact)
count += 1
elif isinstance(t, dict):
tok_val = t.get("access_token") or t.get("token") or t.get("secret", "")
if not tok_val:
continue
username = t.get("user") or t.get("username") or t.get("client_id") or "oauth_bearer"
scope = t.get("scope") or t.get("resource", "")
artifact = CredentialArtifact(
username=username,
domain=tenant,
cred_type="oauth_token",
secret=tok_val,
source_host=tenant,
privilege="token",
note=f"scope={scope}" if scope else "",
source_module=capability,
)
store.add_credential(artifact)
count += 1
else:
logger.warning("access_token_invalid_entry", type=type(t).__name__)
return count
def _normalize_gcp(
self, raw: dict, store: ArtifactStore, capability: str = "gcp_findings"
) -> int:
"""Normalize GCP reconnaissance findings into CloudResourceArtifact and PermissionArtifact."""
count = 0
project_id = raw.get("project_id", "gcp")
# 1. GCS public buckets
gcs = raw.get("gcs", {})
if isinstance(gcs, dict):
for b in gcs.get("public_buckets", []):
if isinstance(b, dict):
b_name = b.get("bucket", "")
if b_name:
artifact = CloudResourceArtifact(
provider="gcp",
resource_type="gcs_bucket",
resource_id=b_name,
region=project_id,
is_public=True,
source_module=capability,
)
store.add(artifact)
count += 1
# 2. IAM bindings
iam = raw.get("iam", {})
if isinstance(iam, dict):
for pb in iam.get("public_bindings", []):
if isinstance(pb, str) and " → " in pb:
member, role = pb.split(" → ", 1)
artifact = PermissionArtifact(
principal=member.strip(),
target=project_id,
right=role.strip(),
domain="gcp",
is_dangerous=True,
source_module=capability,
)
store.add(artifact)
count += 1
for ob in iam.get("owner_bindings", []):
if isinstance(ob, str) and ob:
artifact = PermissionArtifact(
principal=ob,
target=project_id,
right="roles/owner",
domain="gcp",
is_dangerous=True,
source_module=capability,
)
store.add(artifact)
count += 1
# 3. Service account keys
sa = raw.get("service_accounts", {})
if isinstance(sa, dict):
for mk in sa.get("many_keys", []):
if isinstance(mk, dict):
email = mk.get("service_account", "")
key_count = mk.get("active_key_count", 0)
if email:
artifact = CredentialArtifact(
username=email,
domain="gcp",
cred_type="service_account_key",
source_host=project_id,
privilege="service_account",
note=f"active_keys={key_count}",
source_module=capability,
)
store.add_credential(artifact)
count += 1
return count
def _normalize_container_vectors(
self, raw: dict, store: ArtifactStore, capability: str = "container_escape_vectors"
) -> int:
"""Normalize container escape vectors into HostArtifact vulns and metadata."""
target = raw.get("target") or raw.get("host") or "container-host"
existing = None
for h in store.hosts():
if h.ip_address == target or h.hostname == target:
existing = h
break
host = existing or HostArtifact(
ip_address=target,
hostname=target,
source_module=capability,
)
count = 0
# Check docker socket
ds = raw.get("docker_socket", {})
if isinstance(ds, dict) and ds.get("writable"):
vuln_entry = {"type": "container_escape", "vector": "docker_socket_writable", "severity": "CRITICAL"}
host.vulns.append(vuln_entry)
host.metadata.setdefault("container_escape_vectors", []).append(vuln_entry)
count += 1
# Check privileged
priv = raw.get("privileged", {})
if isinstance(priv, dict) and priv.get("privileged"):
vuln_entry = {"type": "container_escape", "vector": "privileged_container", "severity": "CRITICAL"}
host.vulns.append(vuln_entry)
host.metadata.setdefault("container_escape_vectors", []).append(vuln_entry)
count += 1
# Check host mounts
hm = raw.get("host_mounts", {})
if isinstance(hm, dict) and hm.get("high"):
vuln_entry = {"type": "container_escape", "vector": "host_mounts_high_risk", "mounts": hm["high"], "severity": "CRITICAL"}
host.vulns.append(vuln_entry)
host.metadata.setdefault("container_escape_vectors", []).append(vuln_entry)
count += 1
# If raw["container_escape_vectors"] has items
vectors = raw.get("container_escape_vectors", [])
if isinstance(vectors, list):
for v in vectors:
if isinstance(v, dict):
host.vulns.append(v)
count += 1
elif hasattr(v, "evidence") and isinstance(v.evidence, dict):
host.vulns.append(v.evidence)
count += 1
if count and not existing:
store.add(host)
return max(count, 1 if count else 0)
def _normalize_k8s_rbac(
self, raw: dict, store: ArtifactStore, capability: str = "k8s_rbac_findings"
) -> int:
"""Normalize Kubernetes RBAC findings into PermissionArtifact."""
findings = raw.get("k8s_rbac_findings") or raw.get("k8s_findings", [])
if not isinstance(findings, list):
return 0
count = 0
for f in findings:
if not isinstance(f, dict):
if hasattr(f, "evidence") and isinstance(f.evidence, dict):
f = f.evidence
else:
continue
principal = f.get("service_account") or f.get("principal") or "system:serviceaccount"
target = f.get("resource") or f.get("target") or "k8s_cluster"
verb = f.get("verb") or f.get("right") or "cluster-admin"
artifact = PermissionArtifact(
principal=principal,
target=target,
right=verb,
domain="k8s",
is_dangerous=True,
source_module=capability,
)
store.add(artifact)
count += 1
return count
def _normalize_federation_trusts(
self, raw: dict, store: ArtifactStore, capability: str = "federation_trusts"
) -> int:
"""Normalize identity federation trusts into CloudResourceArtifact."""
trusts = raw.get("federation_trusts", [])
if isinstance(trusts, (str, dict)):
trusts = [trusts]
elif not isinstance(trusts, list):
return 0
count = 0
for t in trusts:
if isinstance(t, str):
t_str = t.strip()
if not t_str:
continue
if "Azure" in t_str:
provider = "azure"
res_type = "federation_trust"
res_id = t_str.split(":", 1)[1].strip() if ":" in t_str else t_str
elif "AWS" in t_str:
provider = "aws"
res_type = "saml_provider"
res_id = t_str.split(":", 1)[1].strip() if ":" in t_str else t_str
elif "ADFS" in t_str:
provider = "adfs"
res_type = "relying_party"
res_id = t_str.split(":", 1)[1].strip() if ":" in t_str else t_str
else:
provider = "cloud"
res_type = "federation_trust"
res_id = t_str
artifact = CloudResourceArtifact(
provider=provider,
resource_type=res_type,
resource_id=res_id,
is_public=False,
source_module=capability,
)
store.add(artifact)
count += 1
elif isinstance(t, dict):
artifact = CloudResourceArtifact(
provider=t.get("provider", "cloud"),
resource_type=t.get("resource_type", "federation_trust"),
resource_id=t.get("resource_id") or t.get("name", "trust"),
is_public=t.get("is_public", False),
source_module=capability,
)
store.add(artifact)
count += 1
else:
logger.warning("federation_trust_invalid_entry", type=type(t).__name__)
return count
def _normalize_golden_saml(
self, raw: dict, store: ArtifactStore, capability: str = "golden_saml_paths"
) -> int:
"""Normalize Golden SAML paths into PermissionArtifact."""
paths = raw.get("golden_saml_paths", [])
if isinstance(paths, dict):
paths = [paths]
elif not isinstance(paths, list):
return 0
count = 0
for p in paths:
if not isinstance(p, dict):
continue
rps = p.get("relying_parties", [])
for rp in (rps if isinstance(rps, list) else [str(rps)]):
if rp:
artifact = PermissionArtifact(
principal="adfs_token_signing_key",
target=rp,
right="GoldenSAML_AssertionForgery",
domain="federation",
is_dangerous=True,
source_module=capability,
)
store.add(artifact)
count += 1
if not rps:
artifact = PermissionArtifact(
principal="adfs_token_signing_key",
target=p.get("attack", "Golden SAML"),
right="GoldenSAML",
domain="federation",
is_dangerous=True,
source_module=capability,
)
store.add(artifact)
count += 1
return count
def _normalize_pivot_paths(
self, raw: dict, store: ArtifactStore, capability: str = "pivot_paths"
) -> int:
"""Normalize cross-cloud pivot paths into PermissionArtifact."""
paths = raw.get("pivot_paths", [])
if not isinstance(paths, list):
return 0
count = 0
for p in paths:
if not isinstance(p, dict):
continue
path_name = p.get("path") or p.get("name", "cross_cloud_pivot")
tech = p.get("technique", "T1606.002")
artifact = PermissionArtifact(
principal="federated_identity",
target=path_name,
right=tech,
domain="multi_cloud",
is_dangerous=True,
source_module=capability,
)
store.add(artifact)
count += 1
return count
def _normalize_snmp_findings(
self, raw: dict, store: ArtifactStore, capability: str = "snmp_findings"
) -> int:
"""Normalize SNMP enumeration findings into CredentialArtifact and HostArtifact."""
count = 0
target = raw.get("target") or raw.get("host", "")
# Community strings
valid_comms = raw.get("valid_communities", [])
if isinstance(valid_comms, list):
for vc in valid_comms:
comm = vc.get("community", "") if isinstance(vc, dict) else (vc if isinstance(vc, str) else "")
if comm:
artifact = CredentialArtifact(
username="snmp",
secret=comm,
cred_type="snmp_community",
source_host=target,
privilege="local_admin" if comm.lower() in ("private", "write") else "user",
source_module=capability,
)
store.add_credential(artifact)
count += 1
# System info
sys_info = raw.get("system_info", {})
if isinstance(sys_info, dict) and target:
sys_descr = sys_info.get("sysDescr", "")
sys_name = sys_info.get("sysName", "")
existing = None
for h in store.hosts():
if h.ip_address == target or h.hostname == target:
existing = h
break
if existing:
if sys_descr and not existing.os:
existing.os = sys_descr
if sys_name and not existing.hostname:
existing.hostname = sys_name
existing.metadata["snmp_system_info"] = sys_info
else:
h = HostArtifact(
ip_address=target,
hostname=sys_name or target,
os=sys_descr,
metadata={"snmp_system_info": sys_info},
source_module=capability,
)
store.add(h)
count += 1
return count
def _normalize_system_info(
self, raw: dict, store: ArtifactStore, capability: str = "system_info"
) -> int:
"""Normalize generic system_info dict into HostArtifact."""
target = raw.get("target") or raw.get("host", "")
sys_info = raw.get("system_info", {})
if not target and isinstance(sys_info, dict):
target = sys_info.get("sysName") or sys_info.get("hostname", "")
if not target:
return 0
existing = None
for h in store.hosts():
if h.ip_address == target or h.hostname == target:
existing = h
break
if existing:
if isinstance(sys_info, dict):
existing.metadata["system_info"] = sys_info
if sys_info.get("sysDescr") and not existing.os:
existing.os = sys_info["sysDescr"]
return 1
h = HostArtifact(
ip_address=target,
hostname=target,
os=sys_info.get("sysDescr", "") if isinstance(sys_info, dict) else "",
metadata={"system_info": sys_info} if isinstance(sys_info, dict) else {},
source_module=capability,
)
store.add(h)
return 1
def _normalize_password_policy(
self, raw: dict, store: ArtifactStore, capability: str = "password_policy"
) -> int:
"""Normalize AD/cloud password policy into DomainArtifact metadata."""
policy = raw.get("password_policy", {})
if not isinstance(policy, dict) or not policy:
return 0
domain = raw.get("domain", "") or raw.get("dc", "") or "default"
existing_domain = None
for d in store.get(ArtifactType.DOMAIN):
if isinstance(d, DomainArtifact) and d.domain_name.lower() == domain.lower():
existing_domain = d
break
if existing_domain:
existing_domain.metadata["password_policy"] = policy
return 1
d_artifact = DomainArtifact(
domain_name=domain,
metadata={"password_policy": policy},
source_module=capability,
)
store.add(d_artifact)
return 1
def _normalize_scheduled_tasks(
self, raw: dict, store: ArtifactStore, capability: str = "scheduled_tasks"
) -> int:
"""Normalize scheduled tasks into PermissionArtifact and HostArtifact metadata."""
count = 0
target = raw.get("target") or raw.get("host", "")
seen_tasks: set[str] = set()
for key in ("writable_path_tasks", "high_priv_tasks", "all_tasks"):
tasks = raw.get(key, [])
if isinstance(tasks, list):
for t in tasks:
if isinstance(t, dict):
task_name = t.get("task") or t.get("name", "")
if task_name and task_name not in seen_tasks:
seen_tasks.add(task_name)
run_as = t.get("run_as", "SYSTEM")
artifact = PermissionArtifact(
principal=run_as,
target=task_name,
right="ExecuteScheduledTask",
domain=target,
is_dangerous=bool(t.get("writable_indicator") or key == "writable_path_tasks"),
source_module=capability,
)
store.add(artifact)
count += 1
if target:
for h in store.hosts():
if h.ip_address == target or h.hostname == target:
h.metadata["scheduled_tasks_count"] = raw.get("total_tasks", count)
break
return count
def _normalize_registry_credentials(
self, raw: dict, store: ArtifactStore, capability: str = "credential_hints"
) -> int:
"""Normalize registry credential hits (AutoLogon, VNC, PuTTY) into CredentialArtifact."""
count = 0
target = raw.get("target") or raw.get("host", "")
# 1. Credential hits (AutoLogon, VNC, etc.)
hits = raw.get("credential_hits", [])
if isinstance(hits, list):
for h in hits:
if not isinstance(h, dict):
continue
vals = h.get("values", {})
if not isinstance(vals, dict):
continue
path = h.get("path", "")
if "Winlogon" in path:
user = vals.get("DefaultUserName", "")
pwd = vals.get("DefaultPassword", "")
dom = vals.get("DefaultDomainName", "") or target
if pwd and isinstance(pwd, str):
artifact = CredentialArtifact(
username=user.strip("\x00"),
domain=dom.strip("\x00"),
cred_type="cleartext",
secret=pwd.strip("\x00"),
source_host=target,
privilege="local_admin",
note="registry_autologon",
source_module=capability,
)
store.add_credential(artifact)
count += 1
elif "VNC" in path:
pwd = vals.get("Password", "")
if pwd:
artifact = CredentialArtifact(
username="vnc",
domain=target,
cred_type="vnc_password",
secret=str(pwd),
source_host=target,
privilege="user",
note=f"registry_{path}",
source_module=capability,
)
store.add_credential(artifact)
count += 1
# 2. PuTTY sessions
putty = raw.get("putty_sessions", [])
if isinstance(putty, list):
for s in putty:
if isinstance(s, dict):
u = s.get("user_name", "")
h_name = s.get("host_name", "")
s_name = s.get("session_name", "")
if u or h_name:
artifact = CredentialArtifact(
username=u or "unknown",
domain=h_name,
cred_type="putty_session",
source_host=target,
note=f"session={s_name} remote={h_name}",
source_module=capability,
)
store.add_credential(artifact)
count += 1
return count
def _normalize_secrets_scan(
self, raw: dict, store: ArtifactStore, capability: str = "discovered_secrets"
) -> int:
"""Normalize secrets scanner findings into CredentialArtifact."""
count = 0
target = raw.get("target") or raw.get("host", "")
secrets = raw.get("discovered_secrets") or []
if isinstance(secrets, list):
for s in secrets:
if not isinstance(s, dict):
continue
sec_val = s.get("secret_value") or s.get("extracted_secret") or ""
pattern = s.get("pattern", "secret")
fpath = s.get("file", "")
line = s.get("line", 0)
if sec_val:
artifact = CredentialArtifact(
username=pattern,
secret=sec_val,
cred_type=pattern,
source_host=target,
privilege="unknown",
note=f"{fpath}:{line}",
source_module=capability,
)
store.add_credential(artifact)
count += 1
cred_list = raw.get("credential_list", [])
if target and (cred_list or raw.get("sensitive_data_found")):
for h in store.hosts():
if h.ip_address == target or h.hostname == target:
if cred_list:
h.metadata["secret_files"] = cred_list
if raw.get("sensitive_data_found"):
h.metadata["sensitive_data_found"] = True
break
return count
def _normalize_smb_shares(
self, raw: dict, store: ArtifactStore, capability: str = "file_share_list"
) -> int:
"""Normalize SMB shares and sensitive file paths into HostArtifact metadata."""
target = raw.get("target") or raw.get("host", "")
if not target:
return 0
share_list = raw.get("file_share_list", [])
file_paths = raw.get("sensitive_file_paths", [])
existing = None
for h in store.hosts():
if h.ip_address == target or h.hostname == target:
existing = h
break
if existing:
if share_list:
existing.metadata["file_shares"] = share_list
if file_paths:
existing.metadata["sensitive_files"] = file_paths
return 1
h = HostArtifact(
ip_address=target,
hostname=target,
metadata={
"file_shares": share_list,
"sensitive_files": file_paths,
},
source_module=capability,
)
store.add(h)
return 1