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

sus - Systematic Universal Scanner

A high-performance, multi-threaded file analysis tool written in Rust for detecting suspicious files, extracting content from archives, and identifying security threats through pattern matching, YARA rules, and content analysis.

Overview

sus is a comprehensive file analysis and threat detection tool designed for security professionals, incident responders, and system administrators. It recursively scans directories, extracts content from archives and encoded files, analyzes file content using patterns and YARA rules, and provides a web-based interface for exploring results.

The tool is built for speed and scalability, leveraging Rust's performance and safety guarantees to process large file systems efficiently while maintaining low resource usage.

Key Features

  • Deep File Analysis: Recursively scan directories and automatically extract content from archives (ZIP, TAR, GZIP, BZIP2, XZ, 7Z, RAR), Office documents, PDFs, and EPUBs
  • ELF Analysis: Parse and extract metadata from Linux/Unix executables, shared libraries (.so), and object files including headers, sections, program headers, and symbol tables
  • Portable Executable (PE) Analysis: Parse and extract metadata from Windows executables (.exe, .dll) including headers, sections, imports, and exports
  • Mach-O Analysis: Parse and extract metadata from macOS/iOS executables, dynamic libraries (.dylib), and universal binaries including headers, segments, sections, and symbol tables
  • Windows Registry Analysis: Parse and analyze Windows Registry hive files (SAM, SYSTEM, SOFTWARE, SECURITY, DEFAULT, NTUSER.DAT, UsrClass.dat) without requiring Windows APIs
  • Memory Dump Analysis: Parse and analyze memory dumps from all major operating systems:
    • Windows Minidump files (.dmp) - user-mode and kernel-mode crash dumps
    • Linux ELF core dumps - process crash dumps in ELF format
    • macOS ELF core dumps - process crash dumps in ELF format
  • Forensic Disk Image Analysis:
    • E01/EWF Images: Automatic mounting and analysis with xmount/ewfmount (optional), or metadata extraction with conversion guidance
    • AFF Images: Advanced Forensic Format support with xmount/affmount (optional)
    • VDI Images: VirtualBox disk images with xmount support (optional)
    • VHD Images: Microsoft Virtual Hard Disk format with xmount support (optional)
    • VHDX Images: Microsoft Virtual Hard Disk v2 format with xmount support (optional)
    • VMDK Images: VMware Virtual Machine Disk format with xmount support (optional)
    • QCOW Images: QEMU Copy On Write disk image format with xmount support (optional)
    • Raw Disk Images: Parse and extract partitions from raw disk images (dd output)
    • MBR (Master Boot Record) partition table support
    • GPT (GUID Partition Table) partition table support
    • Automatic partition extraction and analysis
  • Pattern Matching: Search for suspicious patterns using string literals, regular expressions, and byte patterns
  • YARA-X Integration: Run YARA-X rules for advanced threat detection and malware identification
  • Content Decoding: Automatically decode Base64, hex, percent-encoding, HTML entities, and Unicode escape sequences
  • Multi-Directory Tagging: Tag files from different directories in a single analysis run for comparative analysis across servers or environments
  • Entropy Analysis: Calculate Shannon entropy to identify encrypted, compressed, or obfuscated files
  • File Hashing: Generate MD5, SHA1, and SHA256 hashes for all analyzed files
  • SQLite Database: Store analysis results in a structured SQLite database for easy querying and reporting
  • Web Interface: Built-in web server with rich UI for browsing files, viewing matches, and exploring analysis results
  • Command Execution: Execute platform-specific commands during analysis with OS/architecture filtering, command groups, and matrix expansion
  • Agent Mode: Deploy as an agent for remote analysis controlled by a central controller
  • Resumable Analysis: Detect interrupted scans and resume from where you left off
  • Customizable Profiles: Use TOML configuration files to define reusable analysis profiles

Installation

From Source

Requires Rust 1.70 or later:

git clone https://github.com/hisn-io/sus.git
cd sus
cargo build --release

Or use the Makefile:

make build-release

The compiled binaries will be available in target/release/:

  • sus - Main CLI tool
  • sus-agent - Agent for remote deployment
  • sus-controller - Controller for managing multiple agents

Quick Start

# Basic scan of current directory
sus .

# Scan with patterns
sus /path/to/scan --string-pattern "password" --regex-pattern "AKIA[0-9A-Z]{16}"

# Scan with a profile
sus /path/to/scan --profile profile.toml

# Scan without starting web server
sus /path/to/scan --no-server

#... (trimmed here in the docs copy for brevity; full README available at project root)

Profiles library

This directory contains a library of analysis profiles for different security scenarios and usage types. Profiles define patterns, YARA rules, decoding options, and signatures for detecting various security issues.

Directory Structure

profiles/
├── base/              # Base modular profiles
│   ├── credentials.toml       # Credential detection
│   ├── malware.toml           # Malware indicators
│   ├── web.toml               # Web vulnerabilities
│   ├── compliance.toml        # PII and regulated data
│   ├── crypto.toml            # Cryptographic operations
│   ├── network.toml           # Network operations
│   ├── forensics.toml         # Forensic artifacts (NEW)
│   ├── system-artifacts.toml  # System configs and logs (NEW)
│   └── browser-artifacts.toml # Browser history and data (NEW)
├── composite/         # Composite profiles combining base profiles
│   ├── security-audit.toml         # Comprehensive security audit
│   ├── full-scan.toml              # Complete security scan
│   ├── incident-response.toml      # Incident response and threat hunting
│   ├── pci-compliance.toml         # PCI DSS compliance
│   ├── web-app-security.toml       # Web application security
│   ├── cloud-security.toml         # Cloud security (AWS, Azure, GCP)
│   ├── forensic-investigation.toml # Digital forensics (NEW)
│   ├── live-response.toml          # Live response data (NEW)
│   └── windows-forensics.toml      # Windows artifacts (NEW)
├── modules/           # Reusable modules for dynamic targets (NEW)
│   ├── browser/       # Browser-specific modules
│   ├── windows/       # Windows artifact modules
│   ├── linux/         # Linux artifact modules
│   ├── memory/        # Memory analysis modules
│   └── email/         # Email artifact modules
├── targets/           # Named compound targets (KAPE-compatible) (NEW)
│   ├── KAPE_Triage.toml
│   ├── Quick_Triage.toml
│   ├── KAPE_BrowserHistory.toml
│   └── KAPE_EvidenceOfExecution.toml
└── tests/             # Test files for each profile
    ├── credentials/       # Credential pattern test files
    ├── malware/           # Malware pattern test files
    ├── web/               # Web vulnerability test files
    ├── compliance/        # PII detection test files
    ├── crypto/            # Cryptography test files
    ├── network/           # Network operations test files
    ├── forensics/         # Forensic artifacts test files (NEW)
    ├── system-artifacts/  # System artifacts test files (NEW)
    └── browser-artifacts/ # Browser artifacts test files (NEW)

Profile Types

See compound-targets.md for detailed module and target documentation.

Base Profiles

Base profiles are modular, single-purpose profiles that focus on specific security domains. They can be used standalone or combined via composite profiles.

credentials.toml

Detects exposed credentials and secrets including:

  • AWS access keys and secret keys
  • API keys (GitHub, Google, Slack, Stripe, etc.)
  • Private keys (RSA, SSH, PGP)
  • Database connection strings
  • JWT tokens and bearer tokens
  • OAuth tokens and webhooks

Usage:

sus /path/to/scan --profile profiles/base/credentials.toml

malware.toml

Detects malware indicators and suspicious patterns:

  • Reverse shells and command execution
  • PowerShell obfuscation and download-execute patterns
  • Meterpreter and exploit framework references
  • Anti-debugging and anti-VM techniques
  • DLL injection and privilege escalation
  • Credential dumping tools
  • Persistence mechanisms
  • Executable file headers (PE, ELF, Mach-O)

Usage:

sus /path/to/scan --profile profiles/base/malware.toml

web.toml

Detects web application vulnerabilities:

  • SQL injection patterns
  • Cross-site scripting (XSS)
  • Path traversal attacks
  • Command injection
  • LDAP injection
  • XXE (XML External Entity) attacks
  • Server-side template injection
  • Deserialization vulnerabilities
  • SSRF (Server-Side Request Forgery)
  • JSP scriptlets and expressions

Usage:

sus /path/to/scan --profile profiles/base/web.toml

compliance.toml

Detects PII and regulated data for compliance scanning:

  • Email addresses
  • Social Security Numbers (US, UK, Canada)
  • Credit card numbers (Visa, MasterCard, Amex, Discover)
  • Phone numbers (US and international)
  • IP addresses (IPv4, IPv6)
  • MAC addresses
  • Passport numbers
  • IBAN and bank account numbers
  • Medical record numbers
  • Health insurance information

Usage:

sus /path/to/scan --profile profiles/base/compliance.toml

crypto.toml

Detects cryptographic operations and weak crypto:

  • Hash algorithms (MD5, SHA1, SHA256)
  • Encryption algorithms (AES, DES, 3DES, RSA)
  • Cipher modes (ECB, CBC, GCM)
  • Hardcoded encryption keys and IVs
  • Password hashing (PBKDF2, BCrypt, SCrypt, Argon2)
  • Certificate handling
  • SSL/TLS operations
  • Digital signatures

Usage:

sus /path/to/scan --profile profiles/base/crypto.toml

network.toml

Detects network operations and potential data exfiltration:

  • HTTP, FTP, WebSocket URLs
  • Socket connections
  • wget and curl commands
  • Netcat usage
  • DNS queries
  • Proxy configurations
  • Base64 encoded URLs
  • Data exfiltration patterns
  • Remote desktop protocols
  • C2 beacon patterns

Usage:

sus /path/to/scan --profile profiles/base/network.toml

forensics.toml

Detects forensic artifacts and evidence of user activity (inspired by KAPE):

  • Windows artifacts (Event logs, Prefetch, Registry hives, ShimCache, Amcache, SRUM)
  • Browser artifacts (History, Cookies, Cache, Downloads)
  • Unix/Linux artifacts (Bash history, Auth logs, Syslog, Wtmp/Utmp, Lastlog)
  • Timeline artifacts (MFT records, timestamps)
  • Memory dumps (DMP, VMEM, hibernation files, page files)
  • Email artifacts (PST, OST, EML, MBOX)
  • File system artifacts (VSS, Recycle Bin, Thumbs.db, ADS)

Usage:

sus /path/to/scan --profile profiles/base/forensics.toml

system-artifacts.toml

Detects system configuration and administrative artifacts (inspired by UAC):

  • Windows system files (System32, DLLs, INI files, policies, scheduled tasks)
  • Unix/Linux configs (Crontab, Systemd services, Init scripts, Passwd/Shadow)
  • Log files (Application, Event, IIS, Apache/Nginx, Audit logs)
  • User activity (Profiles, Desktop, AppData, Temp directories)
  • Network configuration (Hosts file, interfaces, DNS config)
  • Startup and autorun locations (Registry Run keys, Startup folders)

Usage:

sus /path/to/scan --profile profiles/base/system-artifacts.toml

browser-artifacts.toml

Detects browser history, cookies, and user activity (inspired by KAPE browser modules):

  • Chrome/Chromium (History, Cookies, Login Data, Bookmarks, Extensions, Cache)
  • Firefox (Places, Cookies, Downloads, Logins, Bookmarks, Cache)
  • Edge (History, Cookies, WebCache)
  • Internet Explorer (WebCache, Index.dat)
  • Safari (History, Cookies, Cache)
  • Browser sessions, downloads, search queries
  • Saved passwords, form autofill, credit card data
  • Private browsing indicators

Usage:

sus /path/to/scan --profile profiles/base/browser-artifacts.toml

Composite Profiles

Composite profiles combine multiple base profiles using the includes directive, providing comprehensive analysis for specific use cases.

security-audit.toml

Comprehensive security audit combining credentials, malware, and web security profiles. Ideal for general security assessments.

Includes:

  • credentials.toml
  • malware.toml
  • web.toml

Usage:

sus /path/to/scan --profile profiles/composite/security-audit.toml

full-scan.toml

Complete security scan combining all base profiles. Use this for thorough analysis when you want maximum coverage.

Includes:

  • credentials.toml
  • malware.toml
  • web.toml
  • compliance.toml
  • crypto.toml
  • network.toml

Usage:

sus /path/to/scan --profile profiles/composite/full-scan.toml

incident-response.toml

Focused profile for incident response and threat hunting, emphasizing malware detection, network activity, and credential exposure.

Includes:

  • malware.toml
  • network.toml
  • credentials.toml

Additional patterns:

  • Log deletion and timestamp modification
  • Firewall modifications
  • Account creation
  • Lateral movement techniques

Usage:

sus /compromised/system --profile profiles/composite/incident-response.toml

pci-compliance.toml

Payment Card Industry Data Security Standard (PCI DSS) compliance scanning.

Includes:

  • compliance.toml
  • credentials.toml
  • crypto.toml

Additional patterns:

  • Magnetic stripe data
  • CVV/CVC codes
  • PIN data
  • Primary Account Numbers (PAN)
  • Payment gateway configurations

Usage:

sus /payment/system --profile profiles/composite/pci-compliance.toml

web-app-security.toml

Comprehensive web application vulnerability scanning.

Includes:

  • web.toml
  • credentials.toml
  • crypto.toml

Additional patterns:

  • Hardcoded database credentials
  • Exposed admin panels
  • Default credentials
  • Session tokens in URLs
  • Information disclosure

Usage:

sus /var/www --profile profiles/composite/web-app-security.toml

cloud-security.toml

Cloud-specific security issues for AWS, Azure, and GCP.

Includes:

  • credentials.toml

Additional patterns:

  • AWS ARNs, access keys, S3 buckets
  • Azure storage keys, connection strings, client secrets
  • GCP service account keys, project IDs, cloud storage
  • Terraform state files
  • Kubernetes secrets
  • Docker registry credentials

Usage:

sus /cloud/infrastructure --profile profiles/composite/cloud-security.toml

forensic-investigation.toml

Comprehensive digital forensics investigation profile (inspired by KAPE).

Includes:

  • forensics.toml
  • system-artifacts.toml
  • browser-artifacts.toml
  • malware.toml
  • network.toml

Additional patterns:

  • Evidence files (E01, raw, DD, AFF)
  • Forensic images (VMDK, VHD, VHDX)
  • Timeline files
  • Case files and chain of custody

Usage:

sus /evidence/disk-image --profile profiles/composite/forensic-investigation.toml

live-response.toml

Live response and volatile data collection (inspired by UAC).

Includes:

  • system-artifacts.toml
  • malware.toml
  • network.toml

Additional patterns:

  • Running processes and PIDs
  • Active network connections
  • Logged-in users and system uptime
  • Volatile registry keys (RunMRU, TypedURLs, UserAssist, MUICache)
  • Command history (PowerShell, CMD, Bash)
  • Live malware indicators (suspicious processes, rootkits, code injection)

Usage:

sus /live/system --profile profiles/composite/live-response.toml

windows-forensics.toml

Windows-specific forensic artifact detection (inspired by KAPE Windows targets).

Includes:

  • forensics.toml
  • system-artifacts.toml
  • browser-artifacts.toml

Additional patterns:

  • Registry paths (HKLM, HKCU, HKCR)
  • Registry artifacts (RecentDocs, ComDlg32, MountPoints2)
  • Security Event IDs (4624, 4625, 4672, 4720, 4732)
  • Execution artifacts (Prefetch, AppCompatCache, BAM/DAM, Windows Timeline)
  • NTFS features (ADS, Zone.Identifier, USN Journal)
  • Network profiles and wireless networks
  • Credential Manager and Windows Vault
  • DPAPI master keys and LSA secrets

Usage:

sus /windows/forensics --profile profiles/composite/windows-forensics.toml

Module and Target System (NEW)

The enhanced profile system supports dynamic module loading and KAPE-compatible compound targets.

Using Named Targets

# KAPE-style triage collection
sus /path --target KAPE_Triage --collect

# Quick triage for rapid assessment
sus /path --target Quick_Triage

# Browser history collection
sus /path --target KAPE_BrowserHistory

# Windows execution artifacts
sus /path --target KAPE_EvidenceOfExecution

Using Modules

# Single module
sus /path --target browser/chrome

# Multiple modules
sus /path --target browser/chrome --target browser/firefox

# All modules in a category
sus /path --target windows/*

# Combine with profiles
sus /path --profile base/malware.toml --target browser/all-browsers

Runtime Module Selection

# Enable specific modules
sus /path --target KAPE_Triage --enable-module browser/chrome

# Disable modules
sus /path --target KAPE_Triage --disable-module windows/event-logs

# List available modules
sus --list-modules

# Show module details
sus --show-module browser/chrome

Module Categories

  • browser/ - Chrome, Firefox, Edge, Safari artifacts
  • windows/ - Registry, execution, event logs
  • linux/ - System logs, bash history, user activity
  • memory/ - Memory dumps, hibernation files
  • email/ - Outlook, Thunderbird artifacts

For complete documentation, see:

Profile Features

Pattern Types

  • String: Literal string matching (case-sensitive or case-insensitive)
  • Regex: Regular expression pattern matching
  • Bytes: Hex byte pattern matching

Content Decoding

Profiles can specify which content encodings to decode:

  • base64 - Base64 encoding
  • hex - Hexadecimal encoding
  • percent-encoding - URL percent encoding
  • html-entity - HTML entity encoding
  • unicode-escape-sequences - Unicode escape sequences

File Filtering Options

Path Globs

Include or exclude files based on path patterns:

include-path-globs = ["*.log", "*.txt"]
exclude-path-globs = ["**/node_modules/**", "**/.git/**"]

File Size Limit

Set maximum file size to analyze:

max-file-size = 104857600  # 100 MiB

Directory Tagging

Tag files based on their directory path for comparative analysis:

# Default tag for files not matching any tag-dir
default-tag = "default"

# Map directories to tags
[[tag-dirs-config]]
  path = "/server1"
  tag = "server1"

[[tag-dirs-config]]
  path = "/server2"
  tag = "server2"

Time-Based Filtering

Only analyze files modified within a specific time range. Supports:

  • ISO 8601 timestamps: 2024-01-15T10:30:00Z
  • Date format: 2024-01-15
  • Relative times: 7d (7 days), 30d (30 days), 1h (1 hour), 1w (1 week), 1m (1 month), 1y (1 year)
# Only analyze files modified in the last 7 days
modified-after = "7d"

# Only analyze files modified before yesterday
modified-before = "1d"

# Use specific dates
modified-after = "2024-01-15"
modified-before = "2024-12-31"

Target Loading

Load KAPE-style targets and modules directly from profiles:

# Load named targets or module paths
targets = ["KAPE_Triage", "browser/chrome"]

# Enable specific modules
enable-modules = ["browser/firefox"]

# Disable specific modules
disable-modules = ["windows/event-logs"]

Signatures

Custom SQL signatures query the analysis database to find complex patterns:

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

Profile Inheritance

Composite profiles use the includes directive to inherit from other profiles:

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

Testing Profiles

Each base profile has corresponding test files in the tests/ directory. These files contain patterns that should be detected by their respective profiles.

Running Tests

Test individual profiles:

# Test credentials profile
sus profiles/tests/credentials --profile profiles/base/credentials.toml --output-dir /tmp/sus-test-creds

# Test malware profile
sus profiles/tests/malware --profile profiles/base/malware.toml --output-dir /tmp/sus-test-malware

# Test web profile
sus profiles/tests/web --profile profiles/base/web.toml --output-dir /tmp/sus-test-web

# Test compliance profile
sus profiles/tests/compliance --profile profiles/base/compliance.toml --output-dir /tmp/sus-test-compliance

# Test crypto profile
sus profiles/tests/crypto --profile profiles/base/crypto.toml --output-dir /tmp/sus-test-crypto

# Test network profile
sus profiles/tests/network --profile profiles/base/network.toml --output-dir /tmp/sus-test-network

Test composite profiles:

# Test security audit profile
sus profiles/tests --profile profiles/composite/security-audit.toml --output-dir /tmp/sus-test-audit

# Test full scan profile
sus profiles/tests --profile profiles/composite/full-scan.toml --output-dir /tmp/sus-test-full

Viewing Test Results

After running a test, view the results in the web interface:

sus --server-only --output-dir /tmp/sus-test-creds

Or query the SQLite database directly:

sqlite3 /tmp/sus-test-creds/analysis.db "SELECT pattern_name, COUNT(*) as matches FROM pattern_matches GROUP BY pattern_name ORDER BY matches DESC"

Creating Custom Profiles

You can create your own custom profiles by combining existing profiles or defining new patterns.

Example: Custom Application Security Profile

# my-app-security.toml
includes = [
  "profiles/base/credentials.toml",
  "profiles/base/web.toml"
]

# Application-specific patterns
[[patterns]]
  name = "Internal API Key"
  pattern = "MYAPP-[A-Z0-9]{32}"
  type = "regex"

[[patterns]]
  name = "Legacy Authentication"
  pattern = "auth_v1_token"
  case-insensitive = true
  type = "string"

[[signatures]]
  name = "Application Security Issues"
  query = "SELECT sha256 FROM pattern_matches WHERE pattern_name LIKE '%API Key%' OR pattern_name = 'Legacy Authentication'"

Best Practices

  1. Start with base profiles for focused analysis on specific security domains
  2. Use composite profiles for comprehensive scans
  3. Create custom profiles for application-specific security requirements
  4. Test profiles against known test files before production use
  5. Combine multiple profiles on the command line for custom analysis: 
    sus /path --profile profiles/base/credentials.toml --profile profiles/base/malware.toml
  6. Review signatures to understand what complex patterns are being detected
  7. Adjust decode options based on your target files' encoding patterns

Performance Considerations

  • Base profiles: Fast, focused scanning
  • Composite profiles: Slower due to multiple pattern sets
  • Full scan profile: Most comprehensive but slowest
  • Max file size: Set appropriately for your use case (default: 100MB in full-scan)
  • Decode options: More decoders = slower analysis but better detection

Contributing

To add new profiles:

  1. Create base profiles in profiles/base/ for new security domains
  2. Add test files in profiles/tests/ with patterns your profile should detect
  3. Create composite profiles in profiles/composite/ for common use cases
  4. Update this README with profile documentation
  5. Test profiles against test files to verify detection accuracy

YARA Rules

sus supports YARA-X rules for advanced malware detection. YARA rules can be added to any profile:

yara-x-rules = ["path/to/yara/rules"]

For detailed information on integrating YARA rules, including:

  • Recommended YARA rule sources (Elastic, YARA-Rules, Signature-Base)
  • Creating custom YARA rules
  • Best practices and performance optimization
  • Example workflows

See the YARA Integration Guide for complete documentation.

Quick start with Elastic rules:

# Download Elastic endpoint protection YARA rules
git clone https://github.com/elastic/protections-artifacts.git yara-rules/elastic

# Use in a profile
yara-x-rules = ["yara-rules/elastic/yara/rules"]

Further Reading

License

These profiles are part of the sus project and are licensed under Apache-2.0.