app.parser.registry

  1"""Artifact registry and prompt-loading helpers for forensic parsing.
  2
  3Maintains OS-specific artifact registries that map each supported forensic
  4artifact to its Dissect function name, category, human-readable description,
  5and analysis guidance.  Guidance text is loaded from Markdown files in
  6``prompts/artifact_instructions/`` (Windows) or
  7``prompts/artifact_instructions_linux/`` (Linux) when available, falling back to inline
  8``analysis_hint`` values.
  9
 10Attributes:
 11    WINDOWS_ARTIFACT_REGISTRY: Windows artifact catalogue.
 12    LINUX_ARTIFACT_REGISTRY: Linux artifact catalogue.
 13"""
 14
 15from __future__ import annotations
 16
 17from pathlib import Path
 18
 19from ..os_utils import normalize_os_type
 20
 21__all__ = [
 22    "LINUX_ARTIFACT_REGISTRY",
 23    "WINDOWS_ARTIFACT_REGISTRY",
 24    "get_artifact_registry",
 25]
 26
 27_ARTIFACT_PROMPTS_DIR = Path(__file__).resolve().parents[2] / "prompts" / "artifact_instructions"
 28_LINUX_PROMPTS_DIR = Path(__file__).resolve().parents[2] / "prompts" / "artifact_instructions_linux"
 29
 30
 31def _artifact_prompt_name_candidates(artifact_key: str) -> list[str]:
 32    """Generate candidate file stems for loading an artifact guidance prompt.
 33
 34    Produces variants with dots replaced by underscores and vice-versa so
 35    that ``browser.history`` matches ``browser_history.md``.
 36
 37    Args:
 38        artifact_key: Artifact identifier (e.g. ``"browser.history"``).
 39
 40    Returns:
 41        List of lowercased candidate stems, deduplicated.
 42    """
 43    base = str(artifact_key).strip().lower()
 44    if not base:
 45        return []
 46
 47    candidates: list[str] = []
 48    for value in (base, base.replace(".", "_"), base.replace("_", ".")):
 49        stem = value.strip()
 50        if not stem or stem in candidates:
 51            continue
 52        candidates.append(stem)
 53    return candidates
 54
 55
 56def _load_artifact_guidance_prompt(
 57    artifact_key: str,
 58    prompts_dir: Path | None = None,
 59) -> str:
 60    """Load a Markdown guidance prompt for an artifact from a prompts directory.
 61
 62    Args:
 63        artifact_key: Artifact identifier to look up.
 64        prompts_dir: Directory to search for prompt files.  Defaults to
 65            :data:`_ARTIFACT_PROMPTS_DIR` (Windows prompts).
 66
 67    Returns:
 68        The prompt text, or an empty string if no matching file is found.
 69    """
 70    search_dir = prompts_dir if prompts_dir is not None else _ARTIFACT_PROMPTS_DIR
 71    for prompt_stem in _artifact_prompt_name_candidates(artifact_key):
 72        prompt_path = search_dir / f"{prompt_stem}.md"
 73        try:
 74            if prompt_path.is_file():
 75                prompt_text = prompt_path.read_text(encoding="utf-8").strip()
 76                if prompt_text:
 77                    return prompt_text
 78        except (OSError, UnicodeDecodeError):
 79            continue
 80    return ""
 81
 82
 83def _apply_artifact_guidance_from_prompts(
 84    registry: dict[str, dict[str, str]],
 85    prompts_dir: Path | None = None,
 86) -> None:
 87    """Populate ``artifact_guidance`` on each registry entry from prompt files.
 88
 89    For every artifact, attempts to load a matching Markdown prompt from
 90    the given prompts directory.  Falls back to the inline
 91    ``analysis_instructions`` or ``analysis_hint`` when no file exists.
 92
 93    Args:
 94        registry: The mutable artifact registry dictionary.
 95        prompts_dir: Directory to search for prompt files.  Defaults to
 96            :data:`_ARTIFACT_PROMPTS_DIR` (Windows prompts).
 97    """
 98    for artifact_key, artifact_details in registry.items():
 99        prompt_guidance = _load_artifact_guidance_prompt(artifact_key, prompts_dir)
100        if prompt_guidance:
101            artifact_details["artifact_guidance"] = prompt_guidance
102            continue
103
104        fallback_guidance = str(
105            artifact_details.get("analysis_instructions")
106            or artifact_details.get("analysis_hint")
107            or ""
108        ).strip()
109        if fallback_guidance:
110            artifact_details.setdefault("artifact_guidance", fallback_guidance)
111            artifact_details.setdefault("analysis_instructions", fallback_guidance)
112
113
114WINDOWS_ARTIFACT_REGISTRY: dict[str, dict[str, str]] = {
115    "runkeys": {
116        "name": "Run/RunOnce Keys",
117        "category": "Persistence",
118        "function": "runkeys",
119        "description": (
120            "Registry autorun entries that launch programs at user logon or system boot. "
121            "These keys commonly store malware persistence command lines and loader stubs."
122        ),
123        "analysis_hint": (
124            "Prioritize entries launching from user-writable paths like AppData, Temp, or Public. "
125            "Flag encoded PowerShell, LOLBins, and commands added near the suspected compromise window."
126        ),
127    },
128    "tasks": {
129        "name": "Scheduled Tasks",
130        "category": "Persistence",
131        "function": "tasks",
132        "description": (
133            "Windows Task Scheduler definitions including triggers, actions, principals, and timing. "
134            "Adversaries frequently use tasks for periodic execution and delayed payload launch."
135        ),
136        "analysis_hint": (
137            "Look for newly created or modified tasks with hidden settings, unusual run accounts, or actions "
138            "pointing to scripts/binaries outside Program Files and Windows directories."
139        ),
140    },
141    "services": {
142        "name": "Services",
143        "category": "Persistence",
144        "function": "services",
145        "description": (
146            "Windows service configuration and startup metadata, including image paths and service accounts. "
147            "Malicious services can provide boot persistence and privilege escalation."
148        ),
149        "analysis_hint": (
150            "Investigate auto-start services with suspicious image paths, weakly named binaries, or unexpected "
151            "accounts. Correlate install/start times with process creation and event log artifacts."
152        ),
153    },
154    "cim": {
155        "name": "WMI Persistence",
156        "category": "Persistence",
157        "function": "cim",
158        "description": (
159            "WMI repository data such as event filters, consumers, and bindings used for event-driven execution. "
160            "This is a common stealth persistence mechanism in fileless intrusions."
161        ),
162        "analysis_hint": (
163            "Focus on suspicious __EventFilter, CommandLineEventConsumer, and ActiveScriptEventConsumer objects. "
164            "Flag PowerShell, cmd, or script host commands triggered by system/user logon events."
165        ),
166    },
167    "shimcache": {
168        "name": "Shimcache",
169        "category": "Execution",
170        "function": "shimcache",
171        "description": (
172            "Application Compatibility Cache entries containing executable paths and file metadata observed by the OS. "
173            "Entries provide execution context but do not independently prove a successful run."
174        ),
175        "analysis_hint": (
176            "Use Shimcache to surface suspicious paths, then confirm execution with Prefetch, Amcache, or event logs. "
177            "Pay attention to unsigned tools, archive extraction paths, and deleted binaries."
178        ),
179    },
180    "amcache": {
181        "name": "Amcache",
182        "category": "Execution",
183        "function": "amcache",
184        "description": (
185            "Application and file inventory from Amcache.hve, often including path, hash, compile info, and first-seen data. "
186            "Useful for identifying executed or installed binaries and their provenance."
187        ),
188        "analysis_hint": (
189            "Prioritize recently introduced executables with unknown publishers or rare install locations. "
190            "Compare hashes and file names against threat intelligence and other execution artifacts."
191        ),
192    },
193    "prefetch": {
194        "name": "Prefetch",
195        "category": "Execution",
196        "function": "prefetch",
197        "description": (
198            "Windows Prefetch artifacts recording executable run metadata such as run counts, last run times, and referenced files. "
199            "They are high-value evidence for userland execution on supported systems."
200        ),
201        "analysis_hint": (
202            "Hunt for recently first-run utilities, script hosts, and remote administration tools. "
203            "Review loaded file references for dropped DLLs and staging directories."
204        ),
205    },
206    "bam": {
207        "name": "BAM/DAM",
208        "category": "Execution",
209        "function": "bam",
210        "description": (
211            "Background Activity Moderator and Desktop Activity Moderator execution tracking tied to user SIDs. "
212            "These entries help attribute process activity to specific user contexts."
213        ),
214        "analysis_hint": (
215            "Correlate BAM/DAM timestamps with logons and process events to identify who launched suspicious binaries. "
216            "Highlight administrative tools and scripts executed outside normal business patterns."
217        ),
218    },
219    "userassist": {
220        "name": "UserAssist",
221        "category": "Execution",
222        "function": "userassist",
223        "description": (
224            "Per-user Explorer-driven program execution traces stored in ROT13-encoded registry values. "
225            "Includes run counts and last execution times for GUI-launched applications."
226        ),
227        "analysis_hint": (
228            "Decode and review rarely used programs, renamed binaries, and LOLBins launched through Explorer. "
229            "Use run-count deltas and last-run times to identify unusual user behavior."
230        ),
231    },
232    "evtx": {
233        "name": "Windows Event Logs",
234        "category": "Event Logs",
235        "function": "evtx",
236        "description": (
237            "Windows event channel records covering authentication, process creation, services, policy changes, and system health. "
238            "EVTX is often the backbone for timeline and intrusion reconstruction."
239        ),
240        "analysis_hint": (
241            "Pivot on high-signal event IDs for logon, process creation, service installs, account changes, and log clearing. "
242            "Correlate actor account, host, and parent-child process chains across Security/System channels."
243        ),
244    },
245    "defender.evtx": {
246        "name": "Defender Logs",
247        "category": "Event Logs",
248        "function": "defender.evtx",
249        "description": (
250            "Microsoft Defender event logs describing detections, remediation actions, exclusions, and protection state changes. "
251            "These records show what malware was seen and how protection responded."
252        ),
253        "analysis_hint": (
254            "Identify detection names, severity, and action outcomes (blocked, quarantined, allowed, failed). "
255            "Flag tamper protection events, exclusion changes, and repeated detections of the same path."
256        ),
257    },
258    "mft": {
259        "name": "MFT",
260        "category": "File System",
261        "function": "mft",
262        "description": (
263            "Master File Table metadata for NTFS files and directories, including timestamps, attributes, and record references. "
264            "MFT helps reconstruct file lifecycle and artifact provenance at scale."
265        ),
266        "analysis_hint": (
267            "Focus on executable/script creation in user profile, temp, and startup paths near incident time. "
268            "Check for timestamp anomalies and suspicious rename/move patterns suggesting anti-forensics."
269        ),
270    },
271    "usnjrnl": {
272        "name": "USN Journal",
273        "category": "File System",
274        "function": "usnjrnl",
275        "description": (
276            "NTFS change journal entries capturing create, modify, rename, and delete operations over time. "
277            "USN is valuable for short-lived files that no longer exist on disk."
278        ),
279        "analysis_hint": (
280            "Track rapid create-delete or rename chains involving scripts, archives, and binaries. "
281            "Correlate change reasons and timestamps with execution and network artifacts for full activity flow."
282        ),
283    },
284    "recyclebin": {
285        "name": "Recycle Bin",
286        "category": "File System",
287        "function": "recyclebin",
288        "description": (
289            "Deleted-item metadata including original paths, deletion times, and owning user context. "
290            "Useful for identifying post-activity cleanup and attempted evidence removal."
291        ),
292        "analysis_hint": (
293            "Prioritize deleted tools, scripts, archives, and credential files tied to suspicious users. "
294            "Compare deletion timestamps against detection events and command history."
295        ),
296    },
297    "browser.history": {
298        "name": "Browser History",
299        "category": "User Activity",
300        "function": "browser.history",
301        "description": (
302            "Visited URL records with titles and timestamps from supported web browsers. "
303            "These entries reveal user browsing intent, reconnaissance, and web-based attack paths."
304        ),
305        "analysis_hint": (
306            "Look for phishing domains, file-sharing links, admin portals, and malware delivery infrastructure. "
307            "Align visit times with downloads, process execution, and authentication events."
308        ),
309    },
310    "browser.downloads": {
311        "name": "Browser Downloads",
312        "category": "User Activity",
313        "function": "browser.downloads",
314        "description": (
315            "Browser download records linking source URLs to local file paths and timing. "
316            "This artifact is key for tracing initial payload ingress and user-acquired tools."
317        ),
318        "analysis_hint": (
319            "Flag executable, script, archive, and disk-image downloads from untrusted domains. "
320            "Correlate downloaded file names and times with Prefetch, Amcache, and Defender activity."
321        ),
322    },
323    "powershell_history": {
324        "name": "PowerShell History",
325        "category": "User Activity",
326        "function": "powershell_history",
327        "description": (
328            "PSReadLine command history capturing interactive PowerShell commands entered by users. "
329            "Often exposes attacker tradecraft such as reconnaissance, staging, and command-and-control setup."
330        ),
331        "analysis_hint": (
332            "Hunt for encoded commands, download cradles, credential access, and remote execution cmdlets. "
333            "Note gaps or abrupt truncation that may indicate history clearing or alternate execution methods."
334        ),
335    },
336    "activitiescache": {
337        "name": "Activities Cache",
338        "category": "User Activity",
339        "function": "activitiescache",
340        "description": (
341            "Windows Timeline activity records reflecting user interactions with apps, documents, and URLs. "
342            "Provides broader behavioral context across applications and time."
343        ),
344        "analysis_hint": (
345            "Use it to build user intent timelines around suspicious periods and identify staging behavior. "
346            "Prioritize activity involving remote access tools, cloud storage, and sensitive document paths."
347        ),
348    },
349    "sru.network_data": {
350        "name": "SRUM Network Data",
351        "category": "Network",
352        "function": "sru.network_data",
353        "description": (
354            "System Resource Usage Monitor network telemetry with per-application usage over time. "
355            "Shows which apps consumed network bandwidth and when."
356        ),
357        "analysis_hint": (
358            "Identify unusual outbound-heavy applications, especially unsigned or rarely seen executables. "
359            "Correlate spikes with execution artifacts and possible data exfiltration windows."
360        ),
361    },
362    "sru.application": {
363        "name": "SRUM Application",
364        "category": "Network",
365        "function": "sru.application",
366        "description": (
367            "SRUM application resource usage records that provide process-level activity context across time slices. "
368            "Helpful for spotting persistence or background abuse patterns."
369        ),
370        "analysis_hint": (
371            "Surface low-prevalence applications active during the incident period or outside baseline hours. "
372            "Cross-check with BAM, Prefetch, and network logs to confirm suspicious sustained activity."
373        ),
374    },
375    "shellbags": {
376        "name": "Shellbags",
377        "category": "Registry",
378        "function": "shellbags",
379        "description": (
380            "Registry traces of folders viewed in Explorer, including local, removable, and network paths. "
381            "Shellbags can preserve evidence even after files or folders are deleted."
382        ),
383        "analysis_hint": (
384            "Look for access to hidden folders, USB volumes, network shares, and unusual archive locations. "
385            "Use viewed-path chronology to support staging and collection hypotheses."
386        ),
387    },
388    "usb": {
389        "name": "USB History",
390        "category": "Registry",
391        "function": "usb",
392        "description": (
393            "Registry evidence of connected USB devices, including identifiers and connection history metadata. "
394            "Useful for tracking removable media usage and potential data transfer vectors."
395        ),
396        "analysis_hint": (
397            "Identify unknown devices and compare first/last seen times with suspicious file and user activity. "
398            "Focus on storage-class devices connected near possible exfiltration or staging events."
399        ),
400    },
401    "muicache": {
402        "name": "MUIcache",
403        "category": "Registry",
404        "function": "muicache",
405        "description": (
406            "Cache of executable display strings written when programs are launched via the shell. "
407            "Can provide residual execution clues for binaries no longer present."
408        ),
409        "analysis_hint": (
410            "Hunt for suspicious executable paths and uncommon tool names absent from standard software inventories. "
411            "Correlate entries with UserAssist and Shimcache for stronger execution confidence."
412        ),
413    },
414    "sam": {
415        "name": "SAM Users",
416        "category": "Security",
417        "function": "sam",
418        "description": (
419            "Local Security Account Manager user account records and account state metadata. "
420            "This artifact supports detection of unauthorized local account creation and privilege abuse."
421        ),
422        "analysis_hint": (
423            "Flag newly created, enabled, or reactivated local accounts, especially admin-capable users. "
424            "Correlate account changes with logon events and lateral movement artifacts."
425        ),
426    },
427    "defender.quarantine": {
428        "name": "Defender Quarantine",
429        "category": "Security",
430        "function": "defender.quarantine",
431        "description": (
432            "Metadata about items quarantined by Microsoft Defender, including source path and detection context. "
433            "Indicates which suspicious files were contained and where they originated."
434        ),
435        "analysis_hint": (
436            "Confirm whether detections were successfully quarantined and whether the same paths reappear later. "
437            "Use quarantine artifacts to pivot into file system, execution, and persistence traces."
438        ),
439    },
440}
441
442_apply_artifact_guidance_from_prompts(WINDOWS_ARTIFACT_REGISTRY)
443
444# ---------------------------------------------------------------------------
445# Linux artifact registry
446# ---------------------------------------------------------------------------
447
448LINUX_ARTIFACT_REGISTRY: dict[str, dict[str, str]] = {
449    # -- Persistence --------------------------------------------------------
450    "cronjobs": {
451        "name": "Cron Jobs",
452        "category": "Persistence",
453        "function": "cronjobs",
454        "description": (
455            "Scheduled tasks defined in user crontabs and system-wide /etc/cron.* directories. "
456            "Cron is a common persistence and periodic-execution mechanism on Linux systems."
457        ),
458        "analysis_hint": (
459            "Flag cron entries that download or execute from /tmp, /dev/shm, or user-writable paths. "
460            "Look for base64-encoded commands, reverse shells, and entries added near the incident window."
461        ),
462    },
463    "services": {
464        "name": "Systemd Services",
465        "category": "Persistence",
466        "function": "services",
467        "description": (
468            "Systemd unit files describing services, their startup configuration, and current state. "
469            "Dissect's services function is OS-aware and returns Linux systemd units on Linux targets."
470        ),
471        "analysis_hint": (
472            "Identify services with ExecStart pointing to unusual paths (/tmp, /var/tmp, user home dirs). "
473            "Flag recently created or modified unit files, units set to restart on failure, and masked units."
474        ),
475    },
476    # -- Shell History ------------------------------------------------------
477    "bash_history": {
478        "name": "Bash History",
479        "category": "Shell History",
480        "function": "bash_history",
481        "description": (
482            "Per-user .bash_history files recording interactive shell commands. "
483            "Highest-value artifact on Linux for understanding attacker activity."
484        ),
485        "analysis_hint": (
486            "Hunt for curl/wget downloads, base64 encoding/decoding, reverse shells (bash -i, /dev/tcp), "
487            "credential access (cat /etc/shadow), reconnaissance (id, whoami, uname -a), persistence "
488            "installation (crontab -e, systemctl enable), and log tampering (truncate, shred, rm /var/log). "
489            "Sparse or empty history for active accounts may indicate clearing (history -c, HISTFILE=/dev/null)."
490        ),
491    },
492    "zsh_history": {
493        "name": "Zsh History",
494        "category": "Shell History",
495        "function": "zsh_history",
496        "description": (
497            "Per-user .zsh_history files recording Zsh shell commands with optional timestamps. "
498            "Zsh history may include timing data not present in bash history."
499        ),
500        "analysis_hint": (
501            "Apply the same suspicious-command patterns as bash_history. "
502            "Zsh extended history format includes timestamps — use them for timeline correlation."
503        ),
504    },
505    "fish_history": {
506        "name": "Fish History",
507        "category": "Shell History",
508        "function": "fish_history",
509        "description": (
510            "Per-user Fish shell history stored in YAML-like format with timestamps. "
511            "Less common but may capture activity missed by bash/zsh."
512        ),
513        "analysis_hint": (
514            "Apply the same suspicious-command patterns as bash_history. "
515            "Fish history includes timestamps per command — correlate with login records."
516        ),
517    },
518    "python_history": {
519        "name": "Python History",
520        "category": "Shell History",
521        "function": "python_history",
522        "description": (
523            "Python REPL history from interactive interpreter sessions. "
524            "May reveal attacker use of Python for scripting, exploitation, or data manipulation."
525        ),
526        "analysis_hint": (
527            "Look for import of socket/subprocess/os modules, file read/write operations on "
528            "sensitive paths, and network connection attempts. Python is commonly used for "
529            "exploit development and post-exploitation tooling."
530        ),
531    },
532    # -- Authentication -----------------------------------------------------
533    "wtmp": {
534        "name": "Login Records (wtmp)",
535        "category": "Authentication",
536        "function": "wtmp",
537        "description": (
538            "Successful login/logout records including user, terminal, source IP, and timestamps. "
539            "Linux equivalent of Windows logon events."
540        ),
541        "analysis_hint": (
542            "Flag logins from unexpected IPs, logins at unusual hours, root logins via SSH, "
543            "and logins from accounts that should not be interactive. Cross-check with auth logs "
544            "and shell history. wtmp can be tampered with — missing records or time gaps may "
545            "indicate editing."
546        ),
547    },
548    "btmp": {
549        "name": "Failed Logins (btmp)",
550        "category": "Authentication",
551        "function": "btmp",
552        "description": (
553            "Failed login attempt records including user, source IP, and timestamps. "
554            "High volumes indicate brute-force attacks or credential stuffing."
555        ),
556        "analysis_hint": (
557            "Look for high-frequency failures from single IPs (brute force), failures for "
558            "non-existent accounts (enumeration), and failures immediately before a successful "
559            "wtmp login (successful brute force). Correlate source IPs with successful logins."
560        ),
561    },
562    "lastlog": {
563        "name": "Last Login Records",
564        "category": "Authentication",
565        "function": "lastlog",
566        "description": (
567            "Last login timestamp and source for each user account on the system. "
568            "Provides a quick overview of account usage recency."
569        ),
570        "analysis_hint": (
571            "Identify accounts with recent logins that should be dormant or disabled. "
572            "Compare with wtmp for consistency — discrepancies may indicate log tampering."
573        ),
574    },
575    "users": {
576        "name": "User Accounts",
577        "category": "Authentication",
578        "function": "users",
579        "description": (
580            "User account information parsed from /etc/passwd and /etc/shadow, including "
581            "UIDs, shells, home directories, and password metadata."
582        ),
583        "analysis_hint": (
584            "Flag accounts with UID 0 (root-equivalent), accounts with login shells that "
585            "should have /sbin/nologin, recently created accounts (check shadow dates), and "
586            "accounts with empty password fields."
587        ),
588    },
589    "groups": {
590        "name": "Groups",
591        "category": "Authentication",
592        "function": "groups",
593        "description": (
594            "Group definitions from /etc/group including group members. "
595            "Shows privilege group membership such as sudo, wheel, and docker."
596        ),
597        "analysis_hint": (
598            "Check membership of privileged groups (sudo, wheel, docker, adm, root). "
599            "Flag unexpected users in administrative groups."
600        ),
601    },
602    "sudoers": {
603        "name": "Sudoers Config",
604        "category": "Authentication",
605        "function": "sudoers",
606        "description": (
607            "Sudo configuration from /etc/sudoers and /etc/sudoers.d/, defining which "
608            "users can run which commands with elevated privileges."
609        ),
610        "analysis_hint": (
611            "Flag NOPASSWD entries, overly broad command allowances (ALL), and rules for "
612            "unexpected users. Attackers often modify sudoers for passwordless privilege escalation."
613        ),
614    },
615    # -- Network ------------------------------------------------------------
616    "network.interfaces": {
617        "name": "Network Interfaces",
618        "category": "Network",
619        "function": "network.interfaces",
620        "description": (
621            "Network interface configuration including IP addresses, subnets, and interface names. "
622            "Provides context for understanding the system's network position."
623        ),
624        "analysis_hint": (
625            "Document all configured interfaces and IPs for correlation with login source IPs "
626            "and network artifacts from other systems. Flag unexpected interfaces (tunnels, bridges)."
627        ),
628    },
629    # -- Logs ---------------------------------------------------------------
630    "syslog": {
631        "name": "Syslog",
632        "category": "Logs",
633        "function": "syslog",
634        "description": (
635            "System log entries from /var/log/syslog, /var/log/messages, and /var/log/auth.log. "
636            "Central log source for authentication, service, and kernel events on Linux."
637        ),
638        "analysis_hint": (
639            "Filter for sshd, sudo, su, and PAM messages to reconstruct authentication activity. "
640            "Look for service start/stop events, kernel warnings, and log gaps that may indicate "
641            "tampering or system downtime."
642        ),
643    },
644    "journalctl": {
645        "name": "Systemd Journal",
646        "category": "Logs",
647        "function": "journalctl",
648        "description": (
649            "Structured journal entries from systemd-journald, covering services, kernel, and "
650            "user-session events with rich metadata."
651        ),
652        "analysis_hint": (
653            "Use unit and priority fields to filter for security-relevant events. "
654            "Journal entries complement syslog and may contain structured fields not "
655            "present in plain-text logs."
656        ),
657    },
658    "packagemanager": {
659        "name": "Package History",
660        "category": "Logs",
661        "function": "packagemanager",
662        "description": (
663            "Package installation, removal, and update history from apt, yum, dnf, or other "
664            "package managers. Shows software changes over time."
665        ),
666        "analysis_hint": (
667            "Flag recently installed packages, especially compilers (gcc, make), network tools "
668            "(nmap, netcat, socat), and packages installed outside normal maintenance windows. "
669            "Package removal near incident time may indicate cleanup."
670        ),
671    },
672    # -- SSH ----------------------------------------------------------------
673    "ssh.authorized_keys": {
674        "name": "SSH Authorized Keys",
675        "category": "SSH",
676        "function": "ssh.authorized_keys",
677        "description": (
678            "Per-user authorized_keys files listing public keys allowed for SSH authentication. "
679            "A primary persistence mechanism for SSH-based access."
680        ),
681        "analysis_hint": (
682            "Flag keys added recently or for unexpected accounts. Compare key fingerprints "
683            "across systems to identify lateral movement. Look for command-restricted keys "
684            "and keys with 'from=' options limiting source IPs."
685        ),
686    },
687    "ssh.known_hosts": {
688        "name": "SSH Known Hosts",
689        "category": "SSH",
690        "function": "ssh.known_hosts",
691        "description": (
692            "Per-user known_hosts files recording SSH server fingerprints the user has connected to. "
693            "Reveals outbound SSH connections and lateral movement targets."
694        ),
695        "analysis_hint": (
696            "Identify internal hosts the user SSHed to (lateral movement) and external hosts "
697            "(potential C2 or data exfiltration). Hashed known_hosts entries obscure hostnames "
698            "but IP-based entries may still be readable."
699        ),
700    },
701}
702
703_apply_artifact_guidance_from_prompts(LINUX_ARTIFACT_REGISTRY, _LINUX_PROMPTS_DIR)
704
705
706def get_artifact_registry(os_type: str) -> dict[str, dict[str, str]]:
707    """Return the artifact registry appropriate for the given OS type.
708
709    Uses :func:`~app.os_utils.normalize_os_type` for consistent
710    normalisation across the codebase.
711
712    Args:
713        os_type: Operating system identifier as returned by Dissect's
714            ``target.os`` (e.g. ``"windows"``, ``"linux"``).  The value
715            is normalised to lowercase before comparison.
716
717    Returns:
718        The OS-specific artifact registry dictionary.  Defaults to
719        :data:`WINDOWS_ARTIFACT_REGISTRY` for unrecognised OS types.
720    """
721    if normalize_os_type(os_type) == "linux":
722        return LINUX_ARTIFACT_REGISTRY
723    return WINDOWS_ARTIFACT_REGISTRY