Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

CLI Options Reference

This document provides a comprehensive reference for all command-line options available in the sus tool.

Note: This documentation is auto-generated from the source code. Run make docs to regenerate.

Usage

sus [OPTIONS] [PATH]

Arguments

ArgumentDescriptionDefault
PATHThe path to search for suspicious files. (current directory)

Options

Pattern Matching

OptionDescription
--string-pattern <PATTERN>String pattern to search for (can be specified multiple times)
--regex-pattern <PATTERN>Regex pattern to search for (can be specified multiple times)
--bytes-regex-pattern <PATTERN>Bytes regex pattern to search for (hex format, can be specified multiple times)

Content Decoding

OptionDescription
-d, --decode <ENCODING>Decode content with the given encoding. Can be specified multiple times. Possible values: base64, hex, percent-encoding, html-entity, unicode-escape-sequences

Output Configuration

OptionDescriptionDefault
-o, --output-dir <PATH>The output directory for analysis results./output
--parent-path <PATH>Parent path to use for the output (joined with the scan path)-

Profile Configuration

OptionDescription
--profile <PATH>Profile file(s) to use in TOML format. Can be specified multiple times to merge multiple profiles. If not specified, looks for profile.toml in the current directory

YARA Rules

OptionDescription
--yara-x-rules <DIR>Directory containing YARA-X rules to use

File Filtering

OptionDescription
--max-file-size <BYTES>Maximum file size to analyze (in bytes)
--include-path-globs <GLOB>Only analyze files matching the given glob pattern (can be specified multiple times)
--exclude-path-globs <GLOB>Exclude files matching the given glob pattern (can be specified multiple times)
--modified-after <TIMESTAMP>Only analyze files modified after this timestamp (ISO 8601, date, or relative like '7d', '30d', '1h')
--modified-before <TIMESTAMP>Only analyze files modified before this timestamp (ISO 8601, date, or relative like '7d', '30d', '1h')

Tagging

OptionDescriptionDefault
--tag-dir <PATH:TAG>Tag directories with format 'path:tag' (e.g., '/server1:production'). Can be specified multiple times for multi-directory tagging
--default-tag <TAG>Default tag for files not matching any tag-dirEmpty string

Server Options

OptionDescription
--no-serverDon't start the web server after analysis
--server-onlyOnly start the web server (skip analysis)
--allow-any-hostAllow network access from any host (not just localhost). Security Warning: This exposes the web interface to network access. Only use in trusted network environments.

Analysis Control

OptionDescription
-v, --verboseEnable verbose output (can be used multiple times for more verbosity)
--force-newForce a new analysis, wiping the existing database
--collectCollect matched artifacts to the output directory, preserving metadata

Targets and Modules

OptionDescription
--target <TARGET>Target(s) to use - can be a module path (e.g., 'browser/chrome') or named target (e.g., 'KAPE_Triage'). Can be specified multiple times
--enable-module <MODULE>Enable specific module(s) when using a target
--disable-module <MODULE>Disable specific module(s) when using a target
--list-modulesList all available modules and exit
--list-targetsList all available targets and exit
--show-module <MODULE>Show details of a specific module and exit
--show-target <TARGET>Show details of a specific target and exit

Timeline Generation

OptionDescription
--generate-timeline <FORMAT>Generate timeline from analyzed files (CSV, JSON, or JSONL format)
--timeline-output <PATH>Timeline output file path (defaults to output_dir/timeline.{format})
--timeline-include-createdInclude file creation timestamps in timeline (default: true)
--timeline-include-modifiedInclude file modification timestamps in timeline (default: true)
--timeline-include-accessedInclude file access timestamps in timeline (default: true)
--timeline-filter-tag <TAG>Filter timeline by tag(s) - can be specified multiple times

System Snapshot

OptionDescription
--system-snapshotCapture system snapshot at analysis start (processes, network connections, modules, etc.)
--system-snapshot-output <PATH>System snapshot output file path (defaults to output_dir/system_snapshot.json)

Windows Registry Parsing

OptionDescription
--parse-registryParse Windows Registry files for forensic artifacts (UserAssist, ShimCache, Amcache, BAM/DAM, etc.)
--registry-artifacts <ARTIFACTS>Registry artifacts to parse (comma-separated). Options: userassist, shimcache, amcache, bam, dam, recentdocs, network, usb. If not specified, all artifacts are parsed
--registry-output <PATH>Registry parsing output file path (defaults to output_dir/registry_artifacts.{format})
--registry-format <FORMAT>Registry output format: csv or json (default: csv)

Windows Event Log Parsing

OptionDescription
--parse-evtxParse Windows Event Log (.evtx) files for forensic analysis
--evtx-event-ids <IDS>Event IDs to filter (comma-separated, e.g., 4624,4625,4634). If not specified, all events are parsed
--evtx-sources <SOURCES>Event sources to filter (comma-separated). If not specified, all sources included
--evtx-levels <LEVELS>Event levels to filter (comma-separated: Critical, Error, Warning, Information, Verbose)
--evtx-output <PATH>Event log parsing output file path (defaults to output_dir/evtx_events.{format})
--evtx-format <FORMAT>Event log output format: csv or json (default: csv)
--evtx-summaryGenerate event log summary report

Triage Reporting

OptionDescription
--triage-reportGenerate triage report with risk scoring
--triage-min-score <SCORE>Minimum triage score to include in report (0-100, default: 0 for all files)
--triage-output <PATH>Triage report output file path (defaults to output_dir/triage_report.json)
--triage-include-allInclude all scores in triage report (not just top 100)

Help and Version

OptionDescription
-h, --helpPrint help information
-V, --versionPrint version information

Examples

Basic Scan

# Scan current directory
sus .

# Scan specific path with custom output
sus /path/to/scan --output-dir ./results

Pattern Matching

# Search for specific patterns
sus /data \
  --regex-pattern "AKIA[0-9A-Z]{16}" \
  --string-pattern "password" \
  --decode base64

Using Profiles

# Use a single profile
sus /data --profile security.toml

# Merge multiple profiles
sus /data --profile base.toml --profile security.toml

Multi-Directory Tagging

# Tag files from different directories
sus /backups \
  --tag-dir /backups/server1:production \
  --tag-dir /backups/server2:staging \
  --default-tag unknown

Forensic Analysis

# Full forensic analysis with timeline and registry parsing
sus /forensic/image \
  --generate-timeline csv \
  --parse-registry \
  --parse-evtx \
  --triage-report \
  --system-snapshot

Using Targets

# List available targets
sus --list-targets

# Use a pre-defined target
sus /data --target KAPE_Triage

# Enable/disable specific modules
sus /data --target KAPE_Triage --disable-module windows/event-logs

See Also