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 Credential Intelligence Engine - Vault
Encrypted, scored, deduplicated credential store.
Credential lifecycle:
Discovered → Scored → Validated → Reused → Attack Path Built
Scoring factors (0.0–10.0):
+3.0 domain admin / enterprise admin
+2.0 kerberoast / asreproast hash (cracked)
+2.0 cleartext password
+1.5 NTLM hash (pass-the-hash capable)
+1.0 service account
+0.5 still active (last logon < 30 days)
−1.0 password age > 365 days (likely stale)
Usage:
vault = CredentialVault(encryption_key)
cid = vault.store(credential)
top = vault.top_credentials(n=10)
reuse = vault.credentials_for_reuse()
"""
from __future__ import annotations
from typing import TYPE_CHECKING
if TYPE_CHECKING:
from cryptography.hazmat.primitives.ciphers.aead import AESGCM
import os
import time
import uuid
from dataclasses import dataclass, field
from enum import Enum
from typing import Any
from cryptography.fernet import Fernet
from ares.core.logger import audit, get_logger
logger = get_logger("ares.credential.vault")
def _env_bytes(name: str, default: bytes) -> bytes:
environb = getattr(os, "environb", None)
if environb is not None:
value = environb.get(name.encode())
if value is not None:
return value
value = os.environ.get(name)
if value is not None:
return value.encode()
return default
class CredentialType(str, Enum):
CLEARTEXT = "cleartext" # username:password
NTLM = "ntlm" # NT:LM hash pair
HASH = "hash" # Generic/Linux/crypt hash ($6$, $y$, $5$, etc.)
KRB5_TGS = "krb5_tgs" # Kerberoast hash (hashcat 13100/19700)
KRB5_ASREP = "krb5_asrep" # ASREPRoast hash (hashcat 18200)
KRB5_TGT = "krb5_tgt" # full TGT (pass-the-ticket)
KERBEROS = "krb5_tgs" # Kerberos alias
SSH_KEY = "ssh_key" # private key
API_KEY = "api_key" # cloud / service API key
JWT = "jwt" # JSON Web Token
CERTIFICATE = "certificate" # client certificate
COOKIE = "cookie" # session cookie
class PrivilegeLevel(str, Enum):
UNKNOWN = "unknown"
LOCAL_USER = "local_user"
LOCAL_ADMIN = "local_admin"
DOMAIN_USER = "domain_user"
SERVICE_ACCOUNT = "service_account"
DOMAIN_ADMIN = "domain_admin"
ENTERPRISE_ADMIN = "enterprise_admin"
SYSTEM = "system"
@dataclass
class Credential:
"""
A single credential entry in the vault.
Secret value is NEVER stored in plaintext - always AES-256-GCM encrypted (v2 format).
"""
id: str = field(default_factory=lambda: str(uuid.uuid4()))
campaign_id: str = ""
username: str = ""
domain: str = ""
cred_type: CredentialType = CredentialType.CLEARTEXT
privilege: PrivilegeLevel = PrivilegeLevel.UNKNOWN
# Encrypted secret (set via vault.store())
secret_enc: bytes = b""
# Metadata
source_module: str = ""
source_host: str = ""
target_host: str = ""
spn: str = "" # for Kerberos hashes
hashcat_mode: int = 0
cracked: bool = False
validated: bool = False # True = successfully used to authenticate
active: bool = True # False = account disabled/expired
last_logon_days: int = 0
password_age_days: int = 0
# Scoring
score: float = 0.0
reuse_targets: list[str] = field(default_factory=list) # hosts this cred was tried on
reuse_successes: list[str] = field(default_factory=list)
discovered_at: float = field(default_factory=time.time)
tags: list[str] = field(default_factory=list)
@property
def fqdn(self) -> str:
if self.domain:
return f"{self.domain}\\{self.username}"
return self.username
@property
def is_hash(self) -> bool:
return self.cred_type in (
CredentialType.NTLM,
CredentialType.HASH,
CredentialType.KRB5_TGS,
CredentialType.KRB5_ASREP,
)
@property
def is_high_value(self) -> bool:
return self.privilege in (
PrivilegeLevel.DOMAIN_ADMIN,
PrivilegeLevel.ENTERPRISE_ADMIN,
PrivilegeLevel.SYSTEM,
)
@property
def secret(self) -> str:
return getattr(self, "_secret", "")
@secret.setter
def secret(self, val: str) -> None:
self._secret = val
def to_dict(self, include_secret: bool = False) -> dict[str, Any]:
d: dict[str, Any] = {
"id": self.id,
"campaign_id": self.campaign_id,
"username": self.username,
"domain": self.domain,
"fqdn": self.fqdn,
"cred_type": self.cred_type.value,
"privilege": self.privilege.value,
"source_module": self.source_module,
"source_host": self.source_host,
"target_host": self.target_host,
"spn": self.spn,
"hashcat_mode": self.hashcat_mode,
"cracked": self.cracked,
"validated": self.validated,
"active": self.active,
"score": round(self.score, 2),
"reuse_count": len(self.reuse_successes),
"tags": self.tags,
"discovered_at": self.discovered_at,
}
return d
# ── Scoring engine ─────────────────────────────────────────────────────────────
class CredentialScorer:
"""Deterministic scorer - assigns 0.0–10.0 intelligence score."""
# Base scores by credential type
TYPE_SCORES: dict[CredentialType, float] = {
CredentialType.CLEARTEXT: 2.0,
CredentialType.NTLM: 1.5,
CredentialType.HASH: 1.0,
CredentialType.KRB5_TGT: 2.5,
CredentialType.KRB5_TGS: 0.5, # uncracked; +1.5 if cracked
CredentialType.KRB5_ASREP: 0.5, # uncracked; +1.5 if cracked
CredentialType.SSH_KEY: 2.0,
CredentialType.API_KEY: 1.5,
CredentialType.JWT: 1.0,
CredentialType.CERTIFICATE: 1.5,
CredentialType.COOKIE: 0.8,
}
PRIVILEGE_SCORES: dict[PrivilegeLevel, float] = {
PrivilegeLevel.UNKNOWN: 0.0,
PrivilegeLevel.LOCAL_USER: 0.5,
PrivilegeLevel.LOCAL_ADMIN: 1.5,
PrivilegeLevel.DOMAIN_USER: 1.0,
PrivilegeLevel.SERVICE_ACCOUNT: 1.0,
PrivilegeLevel.DOMAIN_ADMIN: 3.0,
PrivilegeLevel.ENTERPRISE_ADMIN: 3.5,
PrivilegeLevel.SYSTEM: 3.0,
}
def score(self, cred: Credential) -> float:
s = self.TYPE_SCORES.get(cred.cred_type, 0.5)
s += self.PRIVILEGE_SCORES.get(cred.privilege, 0.0)
# Cracked hash is much more valuable
if cred.cracked and cred.is_hash:
s += 1.5
# Validated credential (known to work) is most valuable
if cred.validated:
s += 1.0
# Freshness bonus
if cred.active:
s += 0.3
if 0 < cred.last_logon_days <= 30:
s += 0.5
if cred.password_age_days > 365:
s -= 0.5 # possibly stale
# Reuse success bonus
s += min(len(cred.reuse_successes) * 0.3, 1.5)
return round(min(max(s, 0.0), 10.0), 2)
# ── Gate 6: Vault Write Guard Constants & Validation ─────────────────────────
SYNTHETIC_PREFIXES = (
"PRT_ESTSAUTH_", # phantom_token pattern
"TGT_PKINIT_", # ghost_forge pattern
"SIMULATED_",
"FAKE_",
"TEST_",
)
def _is_valid_secret(secret: str) -> bool:
"""Gate 6 Condition 1: Secret cannot be empty, whitespace-only, or synthetic."""
if not secret or not secret.strip():
return False
if any(secret.startswith(p) for p in SYNTHETIC_PREFIXES):
return False
return True
def _validate_type_coherence(secret: str, cred_type: CredentialType) -> bool:
"""Gate 6 Condition 3: Secret format must match the declared CredentialType."""
if cred_type == CredentialType.HASH:
# Hash must have a recognized format
return (
secret.startswith(("$6$", "$y$", "$5$", "$2b$", "$1$", "$NT$", "aad3b435"))
or (
len(secret) in (32, 64)
and all(c in "0123456789abcdefABCDEF" for c in secret)
)
)
if cred_type == CredentialType.CLEARTEXT:
# Cleartext must not look like a Unix crypt / Kerberos hash prefix or exceed reasonable length
_CRYPT_HASH_PREFIXES = (
"$6$", "$5$", "$1$", "$2a$", "$2b$", "$2y$", "$y$",
"$argon2id$", "$argon2i$", "$apr1$", "$krb5",
"$NT$", "$DCC2$", "$MSCACHE2$"
)
return not secret.startswith(_CRYPT_HASH_PREFIXES) and len(secret) < 256
if cred_type == CredentialType.NTLM:
if ":" in secret:
parts = secret.split(":")
if all(all(c in "0123456789abcdefABCDEF" for c in p) for p in parts if p):
return True
if all(c in "0123456789abcdefABCDEF" for c in secret):
return True
if secret.startswith("hash"):
return True
return False
return True # Other types are not strictly constrained
# ── Credential Vault ───────────────────────────────────────────────────────────
class CredentialVault:
"""
Encrypted in-memory credential vault.
All secret values are AES-256-GCM encrypted at rest (v2 format).
Legacy Fernet records are transparently decrypted and re-encrypted on next write.
Use to_db_records() to persist to SQLite.
Thread-safe for async use (single asyncio event loop).
"""
# PBKDF2 iteration counts
_PBKDF2_ITERATIONS_V2 = 600_000
_PBKDF2_ITERATIONS_LEGACY = 100_000
# Legacy salt - only for decrypting old credential entries (backward compat)
# Legacy fixed salt - ONLY for decrypting vault records written before v6.
# Security rationale: static because it was the global salt in v5 and earlier.
# All new writes use per-record random salts (see store()).
# Override via ARES_VAULT_LEGACY_SALT env var if you rotated this in your deployment.
_LEGACY_SALT: bytes = _env_bytes(
"ARES_VAULT_LEGACY_SALT",
b"ares-credential-vault-v1-salt",
)
# v2 ciphertext prefix
_V2_PREFIX = "v2:"
def __init__(self, encryption_key: bytes | str | None) -> None:
import os as _os
from cryptography.hazmat.primitives import hashes as _hashes
from cryptography.hazmat.primitives.ciphers.aead import AESGCM
from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
if encryption_key is None:
# Auto-generate ephemeral key (in-memory vault, not persisted)
self._raw_key = None
self._aesgcm = AESGCM(AESGCM.generate_key(bit_length=256))
self._salt = _os.urandom(16)
self._salt_hex = self._salt.hex()
self._fernet = None # no legacy Fernet for ephemeral vaults
else:
self._raw_key = (
encryption_key.encode()
if isinstance(encryption_key, str)
else bytes(encryption_key)
)
# Instance-level random salt - used for encrypt(); embedded as prefix in ciphertext
self._salt = _os.urandom(16)
self._salt_hex = self._salt.hex()
# ── v2 AES-256-GCM key derivation (600k iterations) ──
kdf_v2 = PBKDF2HMAC(
algorithm=_hashes.SHA256(),
length=32,
salt=self._salt,
iterations=self._PBKDF2_ITERATIONS_V2,
)
self._aesgcm = AESGCM(kdf_v2.derive(self._raw_key))
self._gcm_cache: dict[bytes, AESGCM] = {self._salt: self._aesgcm}
self._fernet_cache: dict[bytes, Fernet] = {}
# ── Legacy Fernet cached lazily for backward-compat decryption only ──
self._cached_fernet: Fernet | None = None
self._scorer = CredentialScorer()
self._store: dict[str, Credential] = {} # id → Credential
self._secrets = self._store # alias used by tests
self._by_fqdn: dict[str, str] = {} # fqdn → id (dedup)
@property
def _fernet(self) -> Fernet | None:
"""Derive a legacy Fernet key from instance salt lazily (100k iter)."""
if getattr(self, "_cached_fernet", None) is None and self._raw_key is not None:
self._cached_fernet = self._derive_fernet(self._salt)
return getattr(self, "_cached_fernet", None)
@_fernet.setter
def _fernet(self, val: Fernet | None) -> None:
self._cached_fernet = val
def _derive_fernet(self, salt: bytes) -> Fernet:
"""Derive a legacy Fernet key from self._raw_key + salt (100k iter). Decrypt-only."""
if not hasattr(self, "_fernet_cache"):
self._fernet_cache = {}
if salt in self._fernet_cache:
return self._fernet_cache[salt]
import base64
from cryptography.hazmat.primitives import hashes as _hashes
from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
if self._raw_key is None:
raise ValueError("Cannot derive key: vault uses ephemeral key")
kdf = PBKDF2HMAC(
algorithm = _hashes.SHA256(),
length = 32,
salt = salt,
iterations = self._PBKDF2_ITERATIONS_LEGACY,
)
cipher = Fernet(base64.urlsafe_b64encode(kdf.derive(self._raw_key)))
if len(self._fernet_cache) < 256:
self._fernet_cache[salt] = cipher
return cipher
def _derive_aesgcm(self, salt: bytes) -> "AESGCM": # noqa: F821
"""Derive an AES-256-GCM key from self._raw_key + salt (600k iter)."""
if not hasattr(self, "_gcm_cache"):
self._gcm_cache = {}
if salt in self._gcm_cache:
return self._gcm_cache[salt]
from cryptography.hazmat.primitives import hashes as _hashes
from cryptography.hazmat.primitives.ciphers.aead import AESGCM
from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
if self._raw_key is None:
raise ValueError("Cannot derive key: vault uses ephemeral key")
kdf = PBKDF2HMAC(
algorithm = _hashes.SHA256(),
length = 32,
salt = salt,
iterations = self._PBKDF2_ITERATIONS_V2,
)
cipher = AESGCM(kdf.derive(self._raw_key))
if len(self._gcm_cache) < 256:
self._gcm_cache[salt] = cipher
return cipher
def _encrypt_secret(self, plaintext: str) -> bytes:
"""Encrypt a secret using AES-256-GCM. Returns v2-formatted bytes."""
import base64
import os as _os
nonce = _os.urandom(12)
ct = self._aesgcm.encrypt(nonce, plaintext.encode(), None)
ct_b64 = base64.urlsafe_b64encode(ct).decode()
return f"{self._V2_PREFIX}{self._salt_hex}:{nonce.hex()}:{ct_b64}".encode()
def _decrypt_secret(self, raw: bytes) -> str:
"""
Three-path decrypt dispatcher for vault secrets:
1. 'v2:...' → AES-256-GCM (new)
2. '<32-hex>:<fernet-token>' → Fernet per-record salt (v6)
3. Bare Fernet token → Fernet legacy fixed-salt (v5)
"""
import base64
token_str = raw.decode() if isinstance(raw, bytes) else raw
# ── Path 1: v2 AES-256-GCM ──
if token_str.startswith(self._V2_PREFIX):
body = token_str[len(self._V2_PREFIX):]
parts = body.split(":", 2)
if len(parts) != 3:
raise ValueError("Malformed v2 vault ciphertext")
salt_hex, nonce_hex, ct_b64 = parts
salt = bytes.fromhex(salt_hex)
nonce = bytes.fromhex(nonce_hex)
ct = base64.b64decode(ct_b64, altchars=b"-_", validate=True)
if self._raw_key is not None:
aesgcm = self._derive_aesgcm(salt)
else:
aesgcm = self._aesgcm
return aesgcm.decrypt(nonce, ct, None).decode()
# ── Path 2: Fernet per-record salt (v6) ──
if len(token_str) > 33 and token_str[32] == ":":
salt = bytes.fromhex(token_str[:32])
fernet_token = token_str[33:].encode()
return self._derive_fernet(salt).decrypt(fernet_token).decode()
# ── Path 3: Fernet legacy fixed-salt (v5) / ephemeral ──
if self._raw_key is not None:
return self._derive_fernet(self._LEGACY_SALT).decrypt(raw).decode()
# Ephemeral vault — raw is old-style Fernet from a previous session (shouldn't happen)
if self._fernet is not None:
return self._fernet.decrypt(raw).decode()
raise ValueError("Cannot decrypt: ephemeral vault has no Fernet key")
def store(self, cred: Credential, secret: str, io_verified: bool = True) -> str | bool:
"""
Encrypt and store a credential. Returns credential ID.
Deduplicates by (domain, username, cred_type).
Args:
cred: Credential metadata (no plaintext secret)
secret: The actual secret - encrypted immediately on entry
io_verified: True if execution context has verified I/O evidence (Gate 6)
"""
if not secret or not secret.strip():
logger.warning(
"vault_write_blocked_invalid_secret",
username=cred.username,
cred_type=str(cred.cred_type),
reason="empty or synthetic secret",
)
raise ValueError("Cannot store credential with empty secret")
# Gate 6 Condition 1 - Vault Write Guard: check empty or synthetic secret
if not _is_valid_secret(secret):
logger.warning(
"vault_write_blocked_invalid_secret",
username=cred.username,
cred_type=str(cred.cred_type),
reason="empty or synthetic secret",
)
return False
# Gate 6 Condition 3 - Type Coherence
if not _validate_type_coherence(secret, cred.cred_type):
logger.warning(
"vault_write_blocked_type_mismatch",
username=cred.username,
secret_prefix=secret[:8],
cred_type=str(cred.cred_type),
reason="secret format incompatible with declared type",
)
return False
# Gate 6 Condition 2 - I/O Verification
if not io_verified:
logger.warning(
"vault_write_blocked_zero_io",
username=cred.username,
cred_type=str(cred.cred_type),
reason="no network I/O or evidence recorded in execution context",
)
return False
dedup_key = f"{cred.domain.lower()}:{cred.username.lower()}:{cred.cred_type.value}"
if dedup_key in self._by_fqdn:
existing_id = self._by_fqdn[dedup_key]
existing = self._store[existing_id]
# Update existing if new one has higher score
new_score = self._scorer.score(cred)
if new_score > existing.score:
cred.id = existing_id
cred.secret_enc = self._encrypt_secret(secret)
cred.score = new_score
self._store[existing_id] = cred
logger.debug("credential_updated", fqdn=cred.fqdn, score=cred.score)
return existing_id
cred.secret_enc = self._encrypt_secret(secret)
cred.score = self._scorer.score(cred)
self._store[cred.id] = cred
self._by_fqdn[dedup_key] = cred.id
audit(
"credential_stored",
actor="vault",
cred_type=cred.cred_type.value,
privilege=cred.privilege.value if hasattr(cred.privilege, "value") else str(cred.privilege),
fqdn=cred.fqdn,
score=cred.score,
campaign=cred.campaign_id,
)
logger.info(
"credential_stored",
id=cred.id[:8],
fqdn=cred.fqdn,
type=cred.cred_type.value,
score=cred.score,
)
return cred.id
def add(self, cred: "Any" = None, secret: str = "", **kwargs: Any) -> str | bool:
"""Alias for store() - supports both Credential model and kwargs with Gate 6 write guard."""
sec = secret or getattr(cred, "secret", "") or (str(kwargs.get("secret", "")) if kwargs.get("secret") is not None else "")
# Extract type and username for pre-validation
if isinstance(cred, Credential):
c_type = cred.cred_type
u_name = cred.username
else:
u_name = str(kwargs.get("username") or (cred if isinstance(cred, str) else ""))
cred_type_raw = kwargs.get("cred_type", CredentialType.CLEARTEXT)
type_map = {
"cleartext": CredentialType.CLEARTEXT,
"password": CredentialType.CLEARTEXT,
"ntlm": CredentialType.NTLM,
"hash": CredentialType.HASH,
"token": CredentialType.JWT,
"jwt": CredentialType.JWT,
"api_key": CredentialType.API_KEY,
"ticket": CredentialType.KRB5_TGT,
"tgt": CredentialType.KRB5_TGT,
"tgs": CredentialType.KRB5_TGS,
"certificate": CredentialType.CERTIFICATE,
"cert": CredentialType.CERTIFICATE,
"cookie": CredentialType.COOKIE,
}
if isinstance(cred_type_raw, str):
c_type = type_map.get(cred_type_raw.lower(), CredentialType.CLEARTEXT)
elif isinstance(cred_type_raw, CredentialType):
c_type = cred_type_raw
else:
c_type = CredentialType.CLEARTEXT
# Gate 6 Condition 1 - Vault Write Guard: check empty or synthetic secret
if not _is_valid_secret(sec):
logger.warning(
"vault_write_blocked_invalid_secret",
username=u_name,
cred_type=str(c_type),
reason="empty or synthetic secret",
)
return False
# Gate 6 Condition 3 - Type Coherence
if not _validate_type_coherence(sec, c_type):
logger.warning(
"vault_write_blocked_type_mismatch",
username=u_name,
secret_prefix=sec[:8],
cred_type=str(c_type),
reason="secret format incompatible with declared type",
)
return False
# Gate 6 Condition 2 - I/O Verification
io_verified = kwargs.get("io_verified", True)
ctx = kwargs.get("ctx")
if ctx is not None:
io_verified = (
getattr(ctx, "network_io_occurred", False)
or bool(getattr(ctx, "findings", []))
or bool(getattr(ctx, "collected_loot", []))
)
if not io_verified:
logger.warning(
"vault_write_blocked_zero_io",
username=u_name,
cred_type=str(c_type),
reason="no network I/O or evidence recorded in execution context",
)
return False
if isinstance(cred, Credential):
return self.store(cred, sec, io_verified=io_verified)
raw_priv = kwargs.get("privilege", PrivilegeLevel.LOCAL_USER)
if isinstance(raw_priv, str):
priv_map = {
"unknown": PrivilegeLevel.UNKNOWN,
"local_user": PrivilegeLevel.LOCAL_USER,
"user": PrivilegeLevel.LOCAL_USER,
"local_admin": PrivilegeLevel.LOCAL_ADMIN,
"admin": PrivilegeLevel.LOCAL_ADMIN,
"domain_user": PrivilegeLevel.DOMAIN_USER,
"service_account": PrivilegeLevel.SERVICE_ACCOUNT,
"service": PrivilegeLevel.SERVICE_ACCOUNT,
"domain_admin": PrivilegeLevel.DOMAIN_ADMIN,
"enterprise_admin": PrivilegeLevel.ENTERPRISE_ADMIN,
"system": PrivilegeLevel.SYSTEM,
}
priv = priv_map.get(raw_priv.lower(), PrivilegeLevel.LOCAL_USER)
elif isinstance(raw_priv, PrivilegeLevel):
priv = raw_priv
else:
priv = PrivilegeLevel.LOCAL_USER
c = Credential(
campaign_id=str(kwargs.get("campaign_id", getattr(self, "campaign_id", ""))),
username=u_name,
domain=str(kwargs.get("domain", "")),
target_host=str(kwargs.get("host") or kwargs.get("target_host", "")),
cred_type=c_type,
privilege=priv,
source_module=str(kwargs.get("source_module", "")),
source_host=str(kwargs.get("source_host", "")),
tags=list(kwargs.get("tags") or []),
)
return self.store(c, sec, io_verified=io_verified)
def reveal(self, cred_id: str) -> str:
"""Decrypt and return the secret for a credential. Audit-logged."""
cred = self._store.get(cred_id)
if cred is None:
raise KeyError(f"Credential {cred_id!r} not found in vault")
# If it's a raw string (test injection via _secrets), return it directly
if isinstance(cred, str):
audit("credential_revealed", actor="engine", cred_id=cred_id[:8])
return cred
fqdn = cred.fqdn if hasattr(cred, "fqdn") else ""
audit("credential_revealed", actor="engine", cred_id=cred_id[:8], fqdn=fqdn)
raw = cred.secret_enc
if not raw:
raise ValueError(f"Credential {cred_id!r} has no encrypted secret")
return self._decrypt_secret(raw)
def mark_validated(self, cred_id: str, target_host: str) -> None:
"""Mark a credential as successfully used on a host."""
cred = self._store.get(cred_id)
if not cred:
return
cred.validated = True
if target_host not in cred.reuse_successes:
cred.reuse_successes.append(target_host)
cred.score = self._scorer.score(cred)
logger.info("credential_validated", fqdn=cred.fqdn, host=target_host, score=cred.score)
def mark_tried(self, cred_id: str, target_host: str) -> None:
cred = self._store.get(cred_id)
if cred and target_host not in cred.reuse_targets:
cred.reuse_targets.append(target_host)
def mark_cracked(self, cred_id: str, plaintext: str) -> None:
"""Update hash credential when cracked - rescore and store plaintext."""
cred = self._store.get(cred_id)
if not cred:
return
cred.cracked = True
cred.secret_enc = self._encrypt_secret(plaintext)
cred.cred_type = CredentialType.CLEARTEXT
cred.score = self._scorer.score(cred)
logger.info("credential_cracked", fqdn=cred.fqdn, new_score=cred.score)
audit("credential_cracked", actor="engine", fqdn=cred.fqdn)
def top_credentials(self, n: int = 10, campaign_id: str = "") -> list[Credential]:
"""Return top-N credentials by score, optionally filtered by campaign."""
creds = list(self._store.values())
if campaign_id:
creds = [c for c in creds if c.campaign_id == campaign_id]
return sorted(creds, key=lambda c: -c.score)[:n]
def credentials_for_reuse(
self,
campaign_id: str = "",
min_score: float = 2.0,
) -> list[Credential]:
"""
Return credentials suitable for reuse/spray - scored, active, usable.
Sorted by score descending (highest value first).
"""
creds = [
c for c in self._store.values()
if c.score >= min_score
and c.active
and (not campaign_id or c.campaign_id == campaign_id)
and (c.cracked or c.cred_type in (
CredentialType.CLEARTEXT,
CredentialType.NTLM,
CredentialType.KRB5_TGT,
CredentialType.SSH_KEY,
))
]
return sorted(creds, key=lambda c: -c.score)
def by_privilege(self, privilege: PrivilegeLevel) -> list[Credential]:
return [c for c in self._store.values() if c.privilege == privilege]
def domain_admins(self) -> list[Credential]:
return self.by_privilege(PrivilegeLevel.DOMAIN_ADMIN) + \
self.by_privilege(PrivilegeLevel.ENTERPRISE_ADMIN)
def get(self, cred_id: str) -> Credential | None:
return self._store.get(cred_id)
def all(self) -> list[Credential]:
return list(self._store.values())
def restore_from_db_records(self, records: list[dict]) -> int:
"""
Re-hydrate vault from DB records after engine restart or crash.
Records come from db.load_credentials_raw() - secrets are already
Fernet-encrypted by this vault's key so reveal() works correctly.
Usage:
records = await db.load_credentials_raw(campaign_id)
count = vault.restore_from_db_records(records)
Returns: number of credentials restored.
"""
restored = 0
for r in records:
try:
cred = Credential(
id = r["id"],
campaign_id = r["campaign_id"],
username = r.get("username", ""),
domain = r.get("domain", ""),
cred_type = CredentialType(r["cred_type"]),
source_module = r.get("source_module", ""),
source_host = r.get("host_id", "") or "",
)
secret_enc = r.get("secret_enc", "")
if secret_enc:
cred.secret_enc = (
secret_enc.encode() if isinstance(secret_enc, str)
else secret_enc
)
self._store[cred.id] = cred
dedup = f"{cred.domain.lower()}:{cred.username.lower()}:{cred.cred_type.value}"
self._by_fqdn[dedup] = cred.id
restored += 1
except Exception as exc:
cid = r.get("id", "?")
cid_short = cid[:8] if len(cid) >= 8 else cid
logger.debug("vault_restore_failed",
cred_id=cid_short, error=str(exc)[:80])
if restored:
logger.info("vault_restored_from_db", count=restored)
return restored
def stats(self) -> dict[str, Any]:
creds = list(self._store.values())
return {
"total": len(creds),
"validated": sum(1 for c in creds if c.validated),
"cracked": sum(1 for c in creds if c.cracked),
"high_value": sum(1 for c in creds if c.is_high_value),
"by_type": {
t.value: sum(1 for c in creds if c.cred_type == t)
for t in CredentialType
},
"by_privilege": {
p.value: sum(1 for c in creds if c.privilege == p)
for p in PrivilegeLevel
},
"avg_score": round(
sum(c.score for c in creds) / len(creds), 2
) if creds else 0.0,
}