Profile Options Reference

Overview
Profile Location
Basic Structure
Top-Level Options
Pattern Definitions
- Pattern Fields
- Pattern Types
Signature Definitions
Profile Merging
Command Execution
Complete Example
See Also

This document provides a comprehensive reference for all profile configuration options available in sus TOML profile files.

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

Overview

Profiles are TOML configuration files that define how files should be analyzed. They can include:

Pattern matching rules (string, regex, bytes)
YARA-X rules for malware detection
Content decoding options
File size limits
Path include/exclude globs
Custom SQL signatures

Profile Location

By default, sus looks for profile.toml in the current directory. You can specify a different profile with --profile:

sus /data --profile /path/to/custom.toml

Basic Structure

# Include other profiles (optional)
includes = ["base.toml", "security.toml"]

# Content decoding options
decode = ["base64", "hex", "percent-encoding", "html-entity", "unicode-escape-sequences"]

# Maximum file size to analyze (in bytes)
max-file-size = 104857600  # 100 MiB

# Glob patterns for including files
include-path-globs = ["**/*.jar", "**/*.war"]

# Glob patterns for excluding files
exclude-path-globs = ["**/node_modules/**", "**/vendor/**"]

# Default tag for files
tag = "default"

# Pattern definitions
[[patterns]]
  name = "Pattern Name"
  pattern = "pattern-string"
  type = "string"  # or "regex" or "bytes"
  case-insensitive = false  # optional, default: false

# YARA rule directories
yara-x-rules = ["./yara-rules/"]

# Custom SQL signatures
[[signatures]]
  name = "Signature Name"
  query = "SELECT sha256 FROM unique_files WHERE condition"

Top-Level Options

`includes`

Include other profile files, which will be merged with the current profile.

includes = ["base.toml", "security.toml"]

Relative paths are resolved relative to the profile file's directory
Circular dependencies are detected and prevented
All included profiles are merged with automatic deduplication

`decode`

Content decoding options to apply during analysis.

decode = ["base64", "hex", "percent-encoding", "html-entity", "unicode-escape-sequences"]

Value	Description
`base64`	Decode Base64-encoded content
`hex`	Decode hexadecimal-encoded content
`percent-encoding`	Decode URL percent-encoded content (e.g., `%20`)
`html-entity`	Decode HTML entities (e.g., `&`)
`unicode-escape-sequences`	Decode Unicode escape sequences (e.g., `\u0041`)

`max-file-size`

Maximum file size to analyze, in bytes.

max-file-size = 104857600  # 100 MiB

Files larger than this size will be skipped during analysis.

`include-path-globs`

Glob patterns for including files. Only files matching at least one pattern will be analyzed.

include-path-globs = ["**/*.jar", "**/*.war", "**/*.class"]

`exclude-path-globs`

Glob patterns for excluding files. Files matching any pattern will be skipped.

exclude-path-globs = ["**/node_modules/**", "**/vendor/**", "**/.git/**"]

`tag`

Default tag to apply to files analyzed with this profile.

tag = "production"

`yara-x-rules`

Directories containing YARA-X rule files (.yar or .yara extension).

yara-x-rules = ["./yara-rules/", "/shared/yara/"]

Pattern Definitions

Patterns are defined using the [[patterns]] array table syntax.

Pattern Fields

Field	Type	Required	Description
`name`	string	Yes	Human-readable name for the pattern
`pattern`	string	Yes	The pattern to match
`type`	string	Yes	Pattern type: `string`, `regex`, or `bytes`
`case-insensitive`	boolean	No	Case-insensitive matching (default: false)

Pattern Types

String Patterns

Literal string matching:

[[patterns]]
  name = "Private Key Header"
  pattern = "-----BEGIN PRIVATE KEY-----"
  type = "string"

[[patterns]]
  name = "Password Reference"
  pattern = "password"
  type = "string"
  case-insensitive = true

Regex Patterns

Regular expression matching:

[[patterns]]
  name = "AWS Access Key"
  pattern = "AKIA[0-9A-Z]{16}"
  type = "regex"

[[patterns]]
  name = "Email Address"
  pattern = "[a-z0-9._%+-]+@[a-z0-9.-]+\\.[a-z]{2,}"
  type = "regex"
  case-insensitive = true

Bytes Patterns

Hexadecimal byte patterns:

# PDF file signature
[[patterns]]
  name = "PDF Header"
  pattern = "25:50:44:46"  # %PDF in hex
  type = "bytes"

# PNG file signature
[[patterns]]
  name = "PNG Header"
  pattern = "89:50:4E:47:0D:0A:1A:0A"
  type = "bytes"

Signature Definitions

Signatures are custom SQL queries executed against the analysis database.

Signature Fields

Field	Type	Required	Description
`name`	string	Yes	Human-readable name for the signature
`query`	string	Yes	SQL SELECT query to execute

Signature Rules

Queries must start with SELECT
Queries must reference at least one valid table: unique_files, files, pattern_matches, or analysis
Dangerous SQL keywords are not allowed: DROP, DELETE, INSERT, UPDATE, ALTER, CREATE, TRUNCATE, EXEC, EXECUTE, PRAGMA

Available Tables for Signatures

`unique_files`

Column	Type	Description
`sha256`	TEXT	SHA-256 hash (primary key)
`sha1`	TEXT	SHA-1 hash
`md5`	TEXT	MD5 hash
`file_size`	INTEGER	File size in bytes
`mime_type_for_content`	TEXT	MIME type based on content
`shannon_entropy`	REAL	Shannon entropy value

`files`

Column	Type	Description
`path`	TEXT	File path (primary key)
`file_name`	TEXT	File name
`sha256`	TEXT	SHA-256 hash
`file_created`	TEXT	Creation timestamp
`file_modified`	TEXT	Modification timestamp
`file_accessed`	TEXT	Access timestamp
`mime_types_from_file_extension`	TEXT	MIME types from extension
`is_symbolic_link`	INTEGER	Whether file is a symlink
`is_extracted_file`	INTEGER	Whether file was extracted
`is_decoded_file`	INTEGER	Whether file was decoded
`tag`	TEXT	Tag assigned to file

`pattern_matches`

Column	Type	Description
`id`	INTEGER	Match ID (primary key)
`sha256`	TEXT	SHA-256 hash of matched file
`pattern_name`	TEXT	Name of matching pattern
`match_type`	TEXT	Type of match
`match`	TEXT	Matched content
`location`	TEXT	Location of match
`length`	INTEGER	Length of match

`analysis`

Column	Type	Description
`sha256`	TEXT	SHA-256 hash (primary key)
`notes`	TEXT	Analysis notes
`is_suspicious`	INTEGER	Whether file is suspicious
`tags`	TEXT	Tags assigned to file

Signature Examples

[[signatures]]
  name = "High Entropy Files"
  query = "SELECT sha256 FROM unique_files WHERE shannon_entropy > 7.5"

[[signatures]]
  name = "Large Suspicious Files"
  query = "SELECT sha256 FROM unique_files WHERE file_size > 1000000 AND sha256 IN (SELECT sha256 FROM analysis WHERE is_suspicious = 1)"

[[signatures]]
  name = "Files with SQL Injection"
  query = "SELECT DISTINCT sha256 FROM pattern_matches WHERE pattern_name = 'SQL Statement'"

[[signatures]]
  name = "Files by Tag"
  query = "SELECT path FROM files WHERE tag = 'production'"

Profile Merging

When multiple profiles are specified, they are merged with automatic deduplication:

Via Command Line

sus /data --profile base.toml --profile security.toml --profile custom.toml

Via Includes

# main.toml
includes = ["base.toml", "security.toml"]

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

Merging Rules

Field	Merge Behavior
`patterns`	Deduplicated based on type, pattern, and case-sensitivity
`yara-x-rules`	Deduplicated by path
`decode`	Unique decode methods are combined
`signatures`	Deduplicated by name and query
`max-file-size`	Uses the minimum value across all profiles
`tag`	Uses the first profile's tag
`include-path-globs`	Uses the first non-empty glob set
`exclude-path-globs`	Uses the first non-empty glob set

Command Execution

Profiles can define command groups to execute during analysis. Each group contains inline commands with shared settings for OS/architecture filtering, error handling, and execution targets.

Basic Command Group

[[commands]]
  name = "System Information"
  ignore-errors = true
    [[commands.commands]]
      command = "uname -a"

Group-Level Options

Option	Type	Description
`name`	String	Human-readable name for the group
`enabled`	Boolean	Whether this group is enabled (default: `true`)
`os`	Array	Operating systems to run on (e.g., `["linux", "windows", "macos"]`)
`arch`	Array	CPU architectures to run on (e.g., `["x86-64", "aarch64"]`)
`ignore-errors`	Boolean	Continue if commands fail (default: `false`)
`target`	String	Execution target: `"local"` (default), `"agent"`, or `"controller"`
`env`	Array	Environment variables as `["KEY", "value"]` pairs
`working-dir`	String	Working directory for command execution
`matrix`	Table	Optional matrix definition for running across combinations

Command Entry Options

Option	Type	Description
`command`	String	The command to execute (required)
`name`	String	Optional name (defaults to command string)
`ignore-errors`	Boolean	Override group's ignore-errors setting
`env`	Array	Additional environment variables (merged with group env)
`working-dir`	String	Override group's working directory

OS and Architecture Filtering

Groups can be filtered by operating system and CPU architecture:

# Windows-only group
[[commands]]
  name = "Windows System Info"
  os = ["windows"]
  ignore-errors = true
    [[commands.commands]]
      command = "systeminfo"

# Linux and macOS group
[[commands]]
  name = "Unix System Info"
  os = ["linux", "macos"]
    [[commands.commands]]
      command = "uname -a"

# Architecture-specific group
[[commands]]
  name = "x86_64 Only"
  arch = ["x86-64"]
    [[commands.commands]]
      command = "echo 'Running on x86_64'"

Environment Variables and Working Directory

Group-level env vars are inherited by all commands. Per-command env vars are merged on top.

[[commands]]
  name = "Custom Environment"
  os = ["linux", "macos"]
  env = [["MY_VAR", "custom_value"]]
  working-dir = "/tmp"
  ignore-errors = true
    [[commands.commands]]
      command = "echo $MY_VAR"
    [[commands.commands]]
      command = "printenv MY_VAR"
      env = [["EXTRA_VAR", "extra"]]

Inline Command Groups

Related commands are naturally grouped together within a [[commands]] entry:

[[commands]]
  name = "Hardware Info"
  os = ["linux"]
  ignore-errors = true
    [[commands.commands]]
      command = "lscpu"
    [[commands.commands]]
      command = "free -h"
    [[commands.commands]]
      command = "df -h"

Command Matrix

Define a matrix to run all commands in the group across multiple parameter combinations:

[[commands]]
  name = "Cross-Platform Check"
  ignore-errors = true
    [commands.matrix]
      os = ["linux", "windows"]
      arch = ["x86-64", "aarch64"]
    [[commands.commands]]
      command = "echo 'Platform-specific check'"
    [[commands.commands]]
      command = "hostname"

Execution Targets

Commands can target different execution environments:

# Run locally (default)
[[commands]]
  name = "Local Analysis"
  target = "local"
    [[commands.commands]]
      command = "python analyze.py"

# Run on remote agent
[[commands]]
  name = "Agent Collection"
  target = "agent"
    [[commands.commands]]
      command = "collect-logs.sh"

# Run on controller
[[commands]]
  name = "Controller Aggregation"
  target = "controller"
    [[commands.commands]]
      command = "aggregate-results.sh"

Complete Command Example

# Cross-platform hostname
[[commands]]
  name = "Hostname"
  ignore-errors = true
    [[commands.commands]]
      command = "hostname"

# Linux-specific diagnostics
[[commands]]
  name = "Linux Diagnostics"
  os = ["linux"]
  ignore-errors = true
    [[commands.commands]]
      command = "lscpu"
    [[commands.commands]]
      command = "free -h"
    [[commands.commands]]
      command = "df -h"

# macOS-specific diagnostics
[[commands]]
  name = "macOS Diagnostics"
  os = ["macos"]
  ignore-errors = true
    [[commands.commands]]
      command = "sysctl -n machdep.cpu.brand_string"
    [[commands.commands]]
      command = "df -h"

# Matrix-based diagnostics
[[commands]]
  name = "Cross-Platform Matrix"
  ignore-errors = true
    [commands.matrix]
      os = ["linux"]
      arch = ["x86-64", "aarch64"]
    [[commands.commands]]
      command = "uname -m"
    [[commands.commands]]
      command = "echo 'Platform check'"

Complete Example

# security-audit.toml - Complete security audit profile

includes = ["base.toml"]

decode = ["base64", "hex", "percent-encoding"]

max-file-size = 52428800  # 50 MiB

include-path-globs = ["**/*.java", "**/*.py", "**/*.js", "**/*.rb"]
exclude-path-globs = ["**/node_modules/**", "**/vendor/**", "**/.git/**"]

tag = "security-audit"

yara-x-rules = ["./yara-rules/malware/", "./yara-rules/credentials/"]

# AWS Credentials
[[patterns]]
  name = "AWS Access Key"
  pattern = "AKIA[0-9A-Z]{16}"
  type = "regex"

[[patterns]]
  name = "AWS Secret Key"
  pattern = "(?i)aws(.{0,20})?['\"][0-9a-zA-Z/+]{40}['\"]"
  type = "regex"

# Private Keys
[[patterns]]
  name = "RSA Private Key"
  pattern = "-----BEGIN RSA PRIVATE KEY-----"
  type = "string"

[[patterns]]
  name = "Generic Private Key"
  pattern = "-----BEGIN PRIVATE KEY-----"
  type = "string"

# Passwords
[[patterns]]
  name = "Password Assignment"
  pattern = "(password|passwd|pwd)\\s*=\\s*['\"][^'\"]+['\"]"
  type = "regex"
  case-insensitive = true

# API Keys
[[patterns]]
  name = "Generic API Key"
  pattern = "api[_-]?key\\s*=\\s*['\"][^'\"]+['\"]"
  type = "regex"
  case-insensitive = true

# Signatures
[[signatures]]
  name = "High Entropy Files (Possible Encrypted/Compressed)"
  query = "SELECT sha256 FROM unique_files WHERE shannon_entropy > 7.5"

[[signatures]]
  name = "Large Files with Pattern Matches"
  query = "SELECT DISTINCT u.sha256 FROM unique_files u JOIN pattern_matches p ON u.sha256 = p.sha256 WHERE u.file_size > 100000"

Keyboard shortcuts

sus - Systematic Universal Scanner - Documentation