Skip to content

armgit / ARES

Public Imported from GitHub
0

ARES - authorized red-team engagement automation with dashboard, campaign scope, module orchestration, OPSEC controls, encrypted vault, and reporting.

26.0 KB
Raw Blame
"""
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