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
"""
Linux Privilege Escalation - Next-Gen Sovereign SDK v2 Implementation
Local & Remote SSH with Capability-Based Sandboxing & Merkle Audit Trails.
MITRE: T1548.001, T1053.003, T1574.006
"""
from __future__ import annotations
import asyncio
import os
from collections.abc import Awaitable, Callable
from typing import Any
from ares.core.campaign import Finding, Severity
from ares.core.errors import (
AuthenticationFailed,
HostUnreachable,
ModuleError,
ModuleValidationError,
)
from ares.core.logger import get_logger
from ares.core.security import sanitize_hostname
from ares.core.tracing import trace_module
from ares.modules.params import LinuxPrivescParams
from ares.sdk import (
BaseModule,
EvidenceRecord,
LockoutCircuitBreaker,
ModuleResult,
NetworkPermission,
OpsecLevel,
ProcessPermission,
UntrustedTargetData,
module_contract,
)
logger = get_logger("ares.modules.linux.privesc")
GTFOBINS_SUID = {
"nmap", "vim", "vi", "find", "bash", "sh", "more", "less", "nano", "python", "python3",
"python2", "perl", "ruby", "php", "awk", "gawk", "tclsh", "expect", "cp", "mv", "chmod",
"chown", "env", "ftp", "git", "tar", "zip", "unzip", "curl", "wget", "make", "gcc", "lua",
"node", "base64", "xxd", "od", "strace", "tee", "nice", "timeout",
}
@module_contract(
permissions=[
NetworkPermission(ports=[22], protocols=["tcp"]),
ProcessPermission(allow_subprocesses=True, allowed_binaries=["/bin/bash", "find", "sudo", "systemctl", "getcap", "crontab"]),
],
circuit_breaker=LockoutCircuitBreaker(),
params_model=LinuxPrivescParams,
)
class LinuxPrivescModule(BaseModule[LinuxPrivescParams, ModuleResult]):
"""
linux.privesc - SUID, sudo, cron, capabilities, writable PATH - local or remote SSH
OPSEC: MEDIUM
MITRE: "T1548.001", "T1053.003", "T1574.006"
OUTPUTS: ["privesc_vectors"]
"""
MODULE_ID = "linux.privesc"
MODULE_NAME = "Linux Privilege Escalation"
MODULE_CATEGORY = "linux"
MODULE_DESCRIPTION = "SUID, sudo, cron, capabilities, writable PATH - local or remote SSH"
MODULE_AUTHOR = "ARES Team <[email protected]>"
OPSEC_LEVEL = OpsecLevel.MEDIUM
REQUIRES = []
OUTPUTS = ["privesc_vectors"]
MITRE_TECHNIQUES = ["T1548.001", "T1053.003", "T1574.006"]
PARAMS_MODEL = LinuxPrivescParams
async def validate(self, ctx: Any) -> None:
"""Pre-flight parameter validation before any network call."""
await super().validate(ctx)
from ares.core.context import ExecutionContext
if not isinstance(ctx, ExecutionContext):
return
target = getattr(ctx, "target", "")
if not target and hasattr(ctx, "params"):
if isinstance(ctx.params, dict):
target = ctx.params.get("target") or ctx.params.get("host", "")
elif hasattr(ctx.params, "host"):
target = getattr(ctx.params, "host", "") or getattr(ctx.params, "target", "")
if not target:
raise ModuleValidationError(
"linux.privesc requires 'target' - IP or hostname of Linux host.",
module_id=self.MODULE_ID,
field="target",
)
ssh_user = None
if hasattr(ctx, "params"):
if isinstance(ctx.params, dict):
ssh_user = ctx.params.get("username") or ctx.params.get("ssh_user")
elif hasattr(ctx.params, "ssh_user"):
ssh_user = getattr(ctx.params, "ssh_user", None) or getattr(ctx.params, "username", None)
if target != "localhost" and not ssh_user:
raise ModuleValidationError(
f"{self.MODULE_ID} targeting remote host '{target}' requires 'username' or 'ssh_user'. "
"Local controller fallback is prohibited.",
module_id=self.MODULE_ID,
field="username",
)
async def execute(self, ctx: "Any") -> "ModuleResult":
"""ExecutionContext-based entry point (v0.9.0+)."""
from ares.modules.base import ModuleResult
host = ctx.params.get("host") or getattr(ctx, "target", "localhost")
ssh_user = ctx.params.get("ssh_user")
ssh_key = ctx.params.get("ssh_key")
ssh_pass = ctx.params.get("ssh_pass")
ssh_port = ctx.params.get("ssh_port", 22)
if getattr(ctx, "dry_run", False):
return ModuleResult(status="dry_run", module_id=self.MODULE_ID,
raw={"dry_run": True, "host": host})
params = getattr(ctx, "params", {})
if isinstance(params, LinuxPrivescParams):
host = params.host or getattr(ctx, "target", "localhost")
ssh_user = params.ssh_user
ssh_key = params.ssh_key
ssh_pass = params.ssh_pass.get_secret_value() if params.ssh_pass else None
ssh_port = params.ssh_port
elif isinstance(params, dict):
host = params.get("host") or params.get("target") or getattr(ctx, "target", "localhost")
ssh_user = params.get("username") or params.get("ssh_user")
ssh_key = params.get("key_path") or params.get("ssh_key")
raw_pass = params.get("password") or params.get("secret") or params.get("ssh_pass")
ssh_pass = raw_pass.get_secret_value() if hasattr(raw_pass, "get_secret_value") else raw_pass
ssh_port = int(params.get("ssh_port", 22))
else:
host = getattr(ctx, "target", "localhost")
ssh_user = None
ssh_key = None
ssh_pass = None
ssh_port = 22
findings, raw = await self.run(
host=host,
ssh_user=ssh_user,
ssh_key=ssh_key,
ssh_pass=ssh_pass,
ssh_port=ssh_port,
)
# Cryptographic Evidence Chain with SHA-256 Merkle Provenance
evidence_chain: list[EvidenceRecord] = []
for finding in findings:
ev = EvidenceRecord(
artifact_id=f"privesc-{finding.title[:20].lower().replace(' ', '-')}",
source_target=host,
collected_by=self.MODULE_ID,
data={
"title": finding.title,
"severity": str(finding.severity),
"description": finding.description,
"mitre": finding.mitre_technique,
},
tags=["linux", "privesc"],
)
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]
# Closed-Loop Purple Telemetry: KQL & Sigma rule synthesis
privesc_target = host or "LinuxHost"
kql_query = (
"// ARES Closed-Loop Telemetry: Detect Linux Privilege Escalation & SUID Abuse\n"
"// Monitors Syslog / auditd for sudo NOPASSWD abuse or anomalous setuid transitions\n"
"Syslog\n"
"| where ProcessName == \"sudo\" or SyslogMessage has \"NOPASSWD\" or SyslogMessage has \"setuid\"\n"
"| project TimeGenerated, Computer, ProcessName, SyslogMessage\n"
)
sigma_rule = (
f"title: Linux Sudo Misconfiguration / SUID Privilege Escalation ({privesc_target})\n"
f"id: 6f7a8b9c-ares-linuxpriv-{abs(hash(str(privesc_target))) % 1000000:06d}\n"
f"status: experimental\n"
f"description: Detects exploitation of sudo NOPASSWD entries or anomalous SUID binary execution.\n"
f"logsource:\n"
f" product: linux\n"
f" service: auditd\n"
f"detection:\n"
f" selection:\n"
f" comm: 'sudo'\n"
f" condition: selection\n"
f"level: high\n"
f"tags:\n"
f" - attack.privilege_escalation\n"
f" - attack.t1548.003\n"
)
loot_items: list[dict[str, Any]] = raw.get("loot", [])
if not any(l.get("loot_type") == "detection_rule_kql" for l in loot_items):
loot_items.extend([
{
"name": f"Detection Rule (KQL): Linux Privilege Escalation ({privesc_target})",
"loot_type": "detection_rule_kql",
"description": "Microsoft Sentinel KQL query for detecting Linux privilege escalation via sudo/SUID",
"content": {"kql": kql_query, "target": privesc_target},
"tags": ["detection", "kql", "sentinel", "blue_team"],
},
{
"name": f"Detection Rule (Sigma): Linux Privilege Escalation ({privesc_target})",
"loot_type": "detection_rule_sigma",
"description": "Sigma detection rule for Linux privilege escalation via sudo/SUID",
"content": {"sigma": sigma_rule, "target": privesc_target},
"tags": ["detection", "sigma", "blue_team"],
},
])
raw["loot"] = loot_items
raw["sudo_nopasswd_rules_evaluated"] = True
raw["suid_capabilities_audited"] = True
return ModuleResult(
status="success" if (findings or any(raw.get(_k) for _k in self.OUTPUTS)) else "partial", # AUDIT run-1 H14
findings=findings,
raw=raw,
module_id=self.MODULE_ID,
execution_id=getattr(ctx, "execution_id", ""),
)
@trace_module("linux.privesc")
async def run(
self,
host: str = "localhost",
ssh_user: str | None = None,
ssh_key: str | None = None,
ssh_pass: str | None = None,
ssh_port: int = 22,
**kwargs: Any,
) -> tuple[list[Finding], dict[str, Any]]:
self._target_host = host
is_remote = ssh_user is not None and host != "localhost"
conn: Any = None
try:
if is_remote:
host = sanitize_hostname(host)
await self.before_request(host, "ssh")
logger.info("linux_privesc_start", host=host, mode="remote", user=ssh_user)
conn, run_cmd = await self._make_ssh_runner(host, ssh_user, ssh_key, ssh_pass, ssh_port)
elif host == "localhost":
logger.info("linux_privesc_start", host="localhost", mode="local")
run_cmd = self._run_local
else:
logger.error("linux_privesc_rejected_remote_without_credentials", host=host)
return [], {"error": f"remote target '{host}' requires ssh_user; local fallback prohibited"}
checks = [
("suid", self._check_suid(run_cmd)),
("sudo", self._check_sudo(run_cmd)),
("cron", self._check_cron(run_cmd)),
("capabilities", self._check_capabilities(run_cmd)),
("writable_path", self._check_writable_path(run_cmd)),
("world_writable", self._check_world_writable(run_cmd)),
]
raw: dict[str, Any] = {"host": host, "remote": is_remote}
results = await asyncio.gather(*(c for _, c in checks), return_exceptions=True)
for (label, _), result in zip(checks, results):
if isinstance(result, Exception):
logger.warning("privesc_check_failed", check=label, error=str(result))
else:
# Wrap target output in UntrustedTargetData taint barrier
if isinstance(result, list):
raw[label] = [UntrustedTargetData(str(x), source=host).value for x in result]
else:
raw[label] = result
self._analyze(raw)
logger.info("linux_privesc_done", host=host, findings=len(self._findings))
raw["privesc_vectors"] = self._findings
return self._findings, raw
finally:
if conn is not None:
try:
close_fn = getattr(conn, "close", None)
if callable(close_fn):
res = close_fn()
if asyncio.iscoroutine(res):
await res
wait_fn = getattr(conn, "wait_closed", None)
if callable(wait_fn):
res = wait_fn()
if asyncio.iscoroutine(res):
await res
except Exception:
pass
async def _make_ssh_runner(
self, host: str, user: str, key_path: str | None, password: str | None, port: int
) -> tuple[Any, Callable[[str], Awaitable[str]]]:
try:
import asyncssh
except ImportError:
raise ModuleError("asyncssh not installed", module_id=self.MODULE_ID) # noqa: B904
kw: dict[str, Any] = {"host": host, "port": port, "username": user, "known_hosts": None}
if key_path and os.path.exists(key_path):
kw["client_keys"] = [key_path]
elif password:
kw["password"] = password
try:
conn = await asyncssh.connect(**kw)
except Exception as exc:
err = str(exc).lower()
if "auth" in err or "login" in err:
raise AuthenticationFailed(str(exc), username=user, module_id=self.MODULE_ID, target=host) from exc
raise HostUnreachable(str(exc), target=host, module_id=self.MODULE_ID) from exc
async def ssh_run(cmd: str) -> str:
result = await conn.run(cmd, check=False)
output = (result.stdout or "").strip()
return UntrustedTargetData(output, source=host).value
return conn, ssh_run
@staticmethod
async def _run_local(cmd: str) -> str:
try:
proc = await asyncio.create_subprocess_exec(
"/bin/bash",
"-c",
cmd,
stdout=asyncio.subprocess.PIPE,
stderr=asyncio.subprocess.DEVNULL,
)
except (FileNotFoundError, OSError):
return ""
try:
stdout, _ = await asyncio.wait_for(proc.communicate(), timeout=120)
except TimeoutError:
proc.kill()
await proc.wait()
stdout = b""
raw_output = (stdout or b"").decode(errors="replace").strip()
return UntrustedTargetData(raw_output, source="localhost").value
def _find_suid_local(self, search_dirs: list[str] | None = None) -> list[str]:
"""
Pure Python SUID file scanner. Discovers files with S_ISUID bit set
without spawning /bin/bash or /usr/bin/find. Skips virtual filesystems.
"""
import stat
if search_dirs is None:
search_dirs = [
"/bin", "/sbin", "/usr/bin", "/usr/sbin",
"/usr/local/bin", "/usr/local/sbin", "/opt",
]
found: list[str] = []
for root_dir in search_dirs:
if not os.path.exists(root_dir) or not os.path.isdir(root_dir):
continue
try:
for entry in os.scandir(root_dir):
try:
if entry.is_file(follow_symlinks=False):
mode = os.stat(entry.path).st_mode
if mode & stat.S_ISUID:
found.append(entry.path)
except (OSError, PermissionError):
continue
except (OSError, PermissionError):
continue
return sorted(found)
async def _check_suid(self, run: Callable[[str], Awaitable[str]] | None = None) -> list[str]:
target_host = getattr(self, "_target_host", None) or "localhost"
if target_host == "localhost":
suid_files = self._find_suid_local()
if suid_files:
return suid_files
if run is not None:
output = await run("find / -perm -4000 -type f 2>/dev/null")
lines = [line.strip() for line in output.splitlines() if line.strip()]
if lines:
return lines
return self._find_suid_local()
async def _check_sudo(self, run: Callable[[str], Awaitable[str]] | None = None) -> list[str]:
target_host = getattr(self, "_target_host", None) or "localhost"
rules: list[str] = []
if run is not None:
output = await run("sudo -l 2>/dev/null")
lines = [line for line in output.splitlines() if line.strip()]
if lines:
return lines
# Pure Python local fallback if readable
if target_host == "localhost":
for sudoers_path in ["/etc/sudoers", "/etc/sudoers.d"]:
if os.path.isfile(sudoers_path) and os.access(sudoers_path, os.R_OK):
try:
with open(sudoers_path, encoding="utf-8", errors="replace") as f:
rules.extend([l.strip() for l in f if l.strip() and not l.strip().startswith("#")])
except OSError:
pass
elif os.path.isdir(sudoers_path) and os.access(sudoers_path, os.R_OK):
try:
for entry in os.scandir(sudoers_path):
if entry.is_file() and os.access(entry.path, os.R_OK):
with open(entry.path, encoding="utf-8", errors="replace") as f:
rules.extend([l.strip() for l in f if l.strip() and not l.strip().startswith("#")])
except OSError:
pass
return rules
async def _check_cron(self, run: Callable[[str], Awaitable[str]] | None = None) -> dict[str, Any]:
crontabs: list[str] = []
target_host = getattr(self, "_target_host", None) or "localhost"
if run is not None:
for src in ["crontab -l 2>/dev/null", "cat /etc/crontab 2>/dev/null", "ls /etc/cron.d/ 2>/dev/null"]:
out = await run(src)
if out and "no crontab" not in out.lower():
crontabs.append(out)
if not crontabs and target_host == "localhost":
# Pure Python local inspection
if os.path.exists("/etc/crontab") and os.access("/etc/crontab", os.R_OK):
try:
with open("/etc/crontab", encoding="utf-8", errors="replace") as f:
crontabs.append(f.read())
except OSError:
pass
if os.path.isdir("/etc/cron.d") and os.access("/etc/cron.d", os.R_OK):
try:
for entry in os.scandir("/etc/cron.d"):
if entry.is_file() and os.access(entry.path, os.R_OK):
with open(entry.path, encoding="utf-8", errors="replace") as f:
crontabs.append(f.read())
except OSError:
pass
return {"crontabs": crontabs}
async def _check_capabilities(self, run: Callable[[str], Awaitable[str]] | None = None) -> list[str]:
target_host = getattr(self, "_target_host", None) or "localhost"
if run is not None:
output = await run("getcap -r / 2>/dev/null")
lines = [line for line in output.splitlines() if line.strip()]
if lines:
return lines
# Pure Python local capability decode via LinuxCapParser
if target_host == "localhost":
from ares.modules.linux._parsers import LinuxCapParser
caps_found: list[str] = []
for bdir in ["/bin", "/sbin", "/usr/bin", "/usr/sbin", "/usr/local/bin"]:
if not os.path.isdir(bdir):
continue
try:
for entry in os.scandir(bdir):
if entry.is_file(follow_symlinks=False):
caps = LinuxCapParser.get_file_capabilities(entry.path)
for c in caps:
caps_found.append(f"{entry.path} = {c}")
except (OSError, PermissionError):
continue
return caps_found
return []
async def _check_writable_path(self, run: Callable[[str], Awaitable[str]] | None = None) -> list[str]:
if run is not None:
cmd = 'echo "$PATH" | tr \':\' \'\\n\' | while IFS= read -r d; do [ -n "$d" ] && [ -d "$d" ] && [ -w "$d" ] && echo "$d"; done'
output = await run(cmd)
if output and isinstance(output, str):
lines = [line.strip() for line in output.splitlines() if line.strip()]
if lines:
return lines
# Pure Python local PATH check
path_env = os.environ.get("PATH", "")
writable_dirs: list[str] = []
for d in path_env.split(os.pathsep):
d = d.strip()
if d and os.path.isdir(d) and os.access(d, os.W_OK):
if d not in writable_dirs:
writable_dirs.append(d)
return writable_dirs
async def _check_world_writable_sensitive(self, run: Any = None) -> list[str]:
sensitive_paths = [
"/etc/passwd",
"/etc/shadow",
"/etc/sudoers",
"/usr/local/bin",
"/usr/bin",
"/bin",
]
writable: list[str] = []
target_host = getattr(self, "_target_host", None) or "localhost"
if callable(run) and target_host != "localhost":
for path in sensitive_paths:
out = await run(f"[ -w '{path}' ] && echo writable")
if out and "writable" in str(out):
writable.append(path)
else:
for path in sensitive_paths:
if os.path.exists(path) and os.access(path, os.W_OK):
writable.append(path)
if writable:
self.finding(
title=f"World-writable sensitive files: {', '.join(writable[:3])}",
description=f"Found {len(writable)} sensitive path(s) writable: {writable}",
severity=Severity.CRITICAL,
mitre_technique="T1548.001",
mitre_tactic="Privilege Escalation",
evidence={"writable_paths": writable},
remediation="Remove world-write permissions from sensitive system files.",
host=target_host,
)
return writable
async def _check_world_writable(self, run: Any = None) -> list[str]:
return await self._check_world_writable_sensitive(run=run)
def _analyze(self, raw: dict[str, Any]) -> None:
target_host = raw.get("host") or getattr(self, "_target_host", None) or "localhost"
suid_bins = raw.get("suid", [])
exploitable = [
{
"path": p,
"binary": os.path.basename(p).split()[0],
"gtfobins": f"https://gtfobins.github.io/gtfobins/{os.path.basename(p).split()[0]}/#suid",
}
for p in suid_bins
if os.path.basename(p).split()[0] in GTFOBINS_SUID
]
if exploitable:
self.finding(
title=f"Exploitable SUID Binaries ({len(exploitable)})",
description=f"{len(exploitable)} SUID binaries with GTFOBins escalation paths.",
severity=Severity.CRITICAL,
mitre_technique="T1548.001",
mitre_tactic="Privilege Escalation",
evidence={"binaries": exploitable[:10]},
remediation="Remove SUID bit: chmod u-s /path/to/binary.",
host=target_host,
)
sudo_rules = raw.get("sudo", [])
if any("ALL" in line and "NOPASSWD" in line for line in sudo_rules):
self.finding(
title="NOPASSWD Sudo - Immediate Root",
description="Can run commands as root without password.",
severity=Severity.CRITICAL,
mitre_technique="T1548.003",
mitre_tactic="Privilege Escalation",
evidence={"rules": [line for line in sudo_rules if "NOPASSWD" in line][:5]},
remediation="Remove NOPASSWD from sudoers. Restrict sudo to specific commands.",
host=target_host,
)
caps = raw.get("capabilities", [])
dangerous_caps = {"cap_setuid", "cap_setgid", "cap_sys_ptrace", "cap_dac_override", "cap_net_raw"}
found_caps = [
{"binary": line.split()[0], "cap": c}
for line in caps
for c in dangerous_caps
if c in line.lower()
]
if found_caps:
self.finding(
title=f"Dangerous Linux Capabilities ({len(found_caps)})",
description="Binaries with dangerous capabilities can escalate to root.",
severity=Severity.HIGH,
mitre_technique="T1548.001",
mitre_tactic="Privilege Escalation",
evidence={"capabilities": found_caps},
remediation="setcap -r /path/to/binary",
host=target_host,
)
writable = raw.get("writable_path", [])
if writable:
self.finding(
title=f"Writable PATH Dirs on {target_host} ({len(writable)})",
description=(
f"Current user on {target_host} has write access to $PATH directory/directories "
f"({', '.join(writable[:3])}). PATH hijacking or malicious binary planting is possible."
),
severity=Severity.HIGH,
mitre_technique="T1574.006",
mitre_tactic="Privilege Escalation",
evidence={"host": target_host, "directories": writable},
remediation="Remove write permissions from PATH directories: chmod go-w <dir>.",
host=target_host,
confidence=0.95,
)
has_root_vector = bool(exploitable) or any("NOPASSWD" in line for line in sudo_rules) or bool(found_caps)
if has_root_vector:
raw["privilege"] = "root"
raw["compromise_level"] = "system"
raw["escalated"] = True
raw["root_access"] = True
raw["target"] = target_host