Compound Targets and Module System

• Compound targets/module system
• KAPE target/module compatibility
• Advanced Usage
• Module Format
  • Module Metadata Fields
• Target Format
  • Target Metadata Fields
• Module Resolution
  • Path Resolution Rules
• KAPE Compatibility
  • Named Target Mapping
  • KAPE Target Format Support
• Runtime Module Selection
  • Enable Specific Modules
  • Disable Modules
  • Pattern Matching
• Module Categories
  • browser
  • windows
  • linux
  • memory
  • email
• Creating New Modules
  • Step 1: Create Module File
  • Step 2: Define Module Metadata
  • Step 3: Add Patterns
  • Step 4: Test Module
• Creating Named Targets
  • Step 1: Create Target File
  • Step 2: Define Target
  • Step 3: Use Target
• Performance Considerations
  • Module Loading
  • Priority Levels
  • Selective Loading
  • Compound targets & module system
  • KAPE target/module compatibility
• Best Practices
• Troubleshooting
  • Module Not Found
  • Circular Dependencies
  • Pattern Conflicts
  • Performance Issues
• Future Enhancements
• Migration from Static Profiles
  • Option 1: Convert to Modules
  • Option 2: Reference Modules
• Example Workflows
  • Incident Response Triage
  • Custom Forensic Collection
  • Platform-Specific Collection
• Summary

This document describes the enhanced profile system with dynamic compound targets and module references, inspired by KAPE's target system.

Compound targets/module system

Current State: Profile includes work but are static KAPE Feature: Dynamic compound targets that combine multiple modules Recommendation:

• Enhance profile system with module references
• Allow runtime target selection (e.g., "collect all browser artifacts")
• Support for KAPE target format compatibility

KAPE target/module compatibility

Current State: Custom TOML format KAPE Feature: Standard target/module format Recommendation:

• Import KAPE target definitions
• Convert KAPE modules to sus profiles
• Leverage existing KAPE community targets
• Bidirectional conversion tools

│ ├── security-audit.toml │ └── ... ├── modules/ # Reusable modules (NEW) │ ├── browser/ │ │ ├── chrome.toml │ │ ├── firefox.toml │ │ └── all-browsers.toml │ ├── windows/ │ │ ├── registry.toml │ │ ├── execution.toml │ │ └── event-logs.toml │ └── ... └── targets/ # Named compound targets (NEW) ├── KAPE_Triage.toml ├── Quick_Triage.toml └── KAPE_BrowserHistory.toml

## Usage

### Basic Usage

```bash
# Use a named target
sus /path --target KAPE_Triage

# Use multiple targets
sus /path --target Quick_Triage --target KAPE_BrowserHistory

# Combine target with profile
sus /path --profile base/malware.toml --target browser/chrome

# List available targets
sus --list-targets

# Show target details
sus --show-target KAPE_Triage

Advanced Usage

# Enable specific modules
sus /path --target KAPE_Triage --enable-module windows/registry

# Disable modules
sus /path --target KAPE_Triage --disable-module browser/*

# Pattern matching for modules
sus /path --target windows/*

# Combine with collection
sus /path --target KAPE_Triage --collect --output-dir ./triage

Module Format

Modules extend the standard profile TOML format with metadata:

# modules/browser/chrome.toml

[module]
name = "Chrome Browser Artifacts"
description = "Chrome/Chromium history, cookies, login data"
category = "browser"
platform = ["windows", "linux", "macos"]
priority = "high"

# Optional: Dependencies on other modules
dependencies = [
  "common/sqlite-databases"
]

# Standard profile settings
decode = ["base64", "percent-encoding"]

[[patterns]]
  name = "Chrome History"
  pattern = "Chrome.*History"
  type = "regex"

# ... more patterns

Module Metadata Fields

• name - Display name for the module
• description - Brief description of what the module collects
• category - Module category (browser, windows, linux, memory, etc.)
• platform - Supported platforms (windows, linux, macos)
• priority - Loading priority (critical, high, medium, low)
• dependencies (optional) - Other modules required

Target Format

Targets define compound collections with module references:

# targets/KAPE_Triage.toml

[target]
name = "KAPE_Triage"
description = "Comprehensive forensic triage"
category = "triage"
priority = "critical"

# Modules to load (can be selectively enabled/disabled)
modules = [
  "windows/registry",
  "windows/execution",
  "browser/all-browsers"
]

# Optional modules (loaded only if explicitly enabled)
modules_optional = [
  "windows/event-logs"
]

# Static includes (always loaded)
includes = [
  "../base/malware.toml",
  "../base/credentials.toml"
]

# Target-specific patterns
[[patterns]]
  name = "Triage Marker"
  pattern = "triage"
  type = "string"

[[signatures]]
  name = "High Value Artifacts"
  query = "SELECT sha256 FROM pattern_matches WHERE ..."

Target Metadata Fields

• name - Target name (used with --target flag)
• description - What this target collects
• category - Target category
• priority - Execution priority
• modules - List of module paths to include
• modules_optional - Modules loaded only when explicitly enabled
• includes - Static profile includes

Module Resolution

When a target or module is specified:

1. Resolve path - Convert browser/chrome to profiles/modules/browser/chrome.toml
2. Load dependencies - Recursively load any dependencies
3. Merge patterns - Combine all patterns with deduplication
4. Apply filters - Honor --enable-module and --disable-module flags
5. Compile - Build pattern matchers and YARA rules

Path Resolution Rules

• Relative paths are relative to profiles/modules/
• Glob patterns supported: browser/*, windows/event-*
• Named targets searched in profiles/targets/
• Fallback to profiles/ for backward compatibility

KAPE Compatibility

Named Target Mapping

KAPE Target Format Support

Future enhancement: Support loading KAPE .tkape files directly:

# Load KAPE target file (planned)
sus /path --kape-target path/to/target.tkape

Runtime Module Selection

Enable Specific Modules

# Enable only Chrome browser artifacts
sus /path --target KAPE_Triage --enable-module browser/chrome

# Enable multiple modules
sus /path --target KAPE_Triage \
  --enable-module browser/chrome \
  --enable-module browser/firefox

Disable Modules

# Disable event logs to speed up collection
sus /path --target KAPE_Triage --disable-module windows/event-logs

# Disable all browser modules
sus /path --target KAPE_Triage --disable-module browser/*

Pattern Matching

# All Windows modules
sus /path --target windows/*

# All browser modules
sus /path --target browser/*

# Specific pattern
sus /path --target windows/event-*

Module Categories

browser

• chrome.toml - Chrome/Chromium artifacts
• firefox.toml - Firefox artifacts
• edge.toml - Microsoft Edge artifacts
• safari.toml - Safari artifacts (macOS)
• all-browsers.toml - All browser artifacts

windows

• registry.toml - Registry hives and keys
• execution.toml - Execution artifacts (Prefetch, ShimCache, BAM/DAM)
• event-logs.toml - Event log files (.evtx)
• ntfs.toml - NTFS artifacts (planned)
• persistence.toml - Persistence mechanisms (planned)

linux

• logs.toml - System logs (planned)
• bash-history.toml - Shell history (planned)
• systemd.toml - Systemd artifacts (planned)

memory

• dumps.toml - Memory dumps (planned)
• hibernation.toml - Hibernation files (planned)

email

• outlook.toml - Outlook PST/OST (planned)
• thunderbird.toml - Thunderbird artifacts (planned)

Creating New Modules

Step 1: Create Module File

# Create module in appropriate category
mkdir -p profiles/modules/email
touch profiles/modules/email/outlook.toml

Step 2: Define Module Metadata

[module]
name = "Outlook Email Artifacts"
description = "Microsoft Outlook PST/OST files"
category = "email"
platform = ["windows"]
priority = "medium"

Step 3: Add Patterns

[[patterns]]
  name = "PST File"
  pattern = "\\.pst$"
  case-insensitive = true
  type = "regex"

Step 4: Test Module

# Test module standalone
sus /test/email --target email/outlook

# Test in combination
sus /test --target email/outlook --target browser/chrome

Creating Named Targets

Step 1: Create Target File

touch profiles/targets/My_Custom_Target.toml

Step 2: Define Target

[target]
name = "My_Custom_Target"
description = "Custom forensic collection"
category = "custom"
priority = "high"

modules = [
  "browser/all-browsers",
  "windows/execution"
]

includes = [
  "../base/malware.toml"
]

[[patterns]]
  name = "Custom Pattern"
  pattern = "custom"
  type = "string"

Step 3: Use Target

sus /path --target My_Custom_Target --collect

Performance Considerations

Module Loading

• Modules are loaded on-demand
• Dependencies resolved recursively
• Pattern compilation happens once
• Deduplication prevents redundant patterns

Priority Levels

Modules with higher priority load first:

• critical - Essential system artifacts
• high - Important forensic data
• medium - Standard artifacts
• low - Supplementary data

Selective Loading

# Load only high-priority modules
sus /path --target KAPE_Triage --priority-threshold high

# Load platform-specific modules only
sus /path --target KAPE_Triage --platform windows

Compound targets & module system

Current State: Profile includes work but are static KAPE Feature: Dynamic compound targets that combine multiple modules Recommendation:

• Enhance profile system with module references
• Allow runtime target selection (e.g., "collect all browser artifacts")
• Support for KAPE target format compatibility

KAPE target/module compatibility

Current State: Custom TOML format KAPE Feature: Standard target/module format Recommendation:

• Import KAPE target definitions
• Convert KAPE modules to sus profiles
• Leverage existing KAPE community targets
• Bidirectional conversion tools

Best Practices

1. Keep modules focused - One artifact type per module
2. Use descriptive names - Clear module and target names
3. Document patterns - Explain what each pattern matches
4. Test combinations - Verify modules work together
5. Set proper priorities - Critical artifacts first
6. Mark platform requirements - Specify supported platforms
7. Avoid circular dependencies - Keep dependency graph acyclic

Troubleshooting

Module Not Found

# Check module path
sus --show-module browser/chrome

# List all modules
sus --list-modules

Circular Dependencies

Error: Circular module dependency detected: browser/chrome -> common/sqlite -> browser/chrome

Solution: Refactor to break the cycle

Pattern Conflicts

Multiple modules may define similar patterns. Sus handles this by:

1. Pattern name uniqueness enforced
2. Duplicate patterns deduplicated
3. Last loaded takes precedence

Performance Issues

If loading is slow:

1. Reduce number of modules
2. Increase priority threshold
3. Disable unused modules
4. Use simpler patterns

Future Enhancements

• KAPE .tkape file support - Direct loading of KAPE target files
• Module versioning - Track module versions and compatibility
• Module repository - Central repository for community modules
• Dependency resolver - Automatic dependency management
• Interactive TUI - Terminal UI for module selection
• Module profiling - Performance analysis per module
• Module marketplace - Share and discover modules

Migration from Static Profiles

Existing profiles continue to work. To use modules:

Option 1: Convert to Modules

Split large profiles into focused modules:

# Old: security-audit.toml with everything
# New: Multiple focused modules + target

Option 2: Reference Modules

Add module references to existing profiles:

# existing-profile.toml
includes = [
  "other-profile.toml"
]

# NEW: Add module references
modules = [
  "browser/chrome",
  "windows/execution"
]

[[patterns]]
  name = "Existing Pattern"
  pattern = "..."
  type = "regex"

Example Workflows

Incident Response Triage

# Quick triage
sus /compromised-system --target Quick_Triage --collect

# Comprehensive triage
sus /compromised-system --target KAPE_Triage --collect

# Browser-focused investigation
sus /user/profile --target KAPE_BrowserHistory --collect

Custom Forensic Collection

# Combine multiple targets
sus /evidence --target KAPE_EvidenceOfExecution \
              --target KAPE_BrowserHistory \
              --collect

# Selective module loading
sus /evidence --target KAPE_Triage \
              --enable-module browser/chrome \
              --enable-module windows/registry \
              --disable-module windows/event-logs

Platform-Specific Collection

# Windows artifacts only
sus /windows --target windows/* --collect

# Browser artifacts across platforms
sus /users --target browser/all-browsers --collect

Summary

The module and target system provides:

✅ Modular design - Reusable, focused components ✅ Runtime flexibility - Choose modules at execution time ✅ KAPE compatibility - Familiar naming and concepts ✅ Easy extensibility - Simple to add new modules ✅ Performance optimization - Load only what's needed ✅ Backward compatible - Existing profiles still work

This enhancement makes sus more powerful and flexible for forensic investigations while maintaining ease of use.