Command Execution in Profiles

• Overview
• Basic Usage
• Group-Level Options
  • Required Fields
  • Optional Fields
• Command Entry Options
• Platform Filtering
  • Operating System
  • CPU Architecture
  • Combined Filtering
• Error Handling
  • Default Behavior
  • Ignoring Errors
• Environment Variables
• Working Directory
• Execution Targets
  • Local Execution (Default)
  • Agent Execution
  • Controller Execution
• Command Matrix
  • Basic Matrix
  • Matrix with OS and Arch
  • Matrix Options
• Disabled Groups
• Complete Examples
  • System Diagnostics Profile
  • Security Collection Profile
• Best Practices
• Security Considerations
• See Also

This document provides a detailed guide on using command execution features in sus profiles.

Overview

Sus profiles support executing commands during analysis. Commands are organized into groups with inline command entries. Group-level settings are inherited by all commands in the group, with optional per-command overrides.

This feature enables:

• Running system diagnostics
• Collecting additional context
• Automating pre/post-analysis tasks
• Platform-specific operations
• Distributed execution across agents and controllers

Basic Usage

Commands are defined in profile TOML files using [[commands]] groups with nested [[commands.commands]] entries:

[[commands]]
  name = "System Check"
  ignore-errors = true
    [[commands.commands]]
      command = "echo 'Hello from sus'"
    [[commands.commands]]
      command = "uname -a"

Group-Level Options

Required Fields

Optional Fields

Command Entry Options

Platform Filtering

Operating System

Groups can be restricted to specific operating systems:

# Linux only
[[commands]]
  name = "Linux Uptime"
  os = ["linux"]
    [[commands.commands]]
      command = "uptime"

# Windows only
[[commands]]
  name = "Windows Version"
  os = ["windows"]
    [[commands.commands]]
      command = "ver"

# Multiple OSes
[[commands]]
  name = "Unix Date"
  os = ["linux", "macos", "freebsd"]
    [[commands.commands]]
      command = "date"

Valid OS values: linux, windows, macos, freebsd, netbsd, openbsd, solaris, android, ios

CPU Architecture

Groups can be restricted to specific architectures:

# x86_64 only
[[commands]]
  name = "x64 Specific"
  arch = ["x86-64"]
    [[commands.commands]]
      command = "echo 'Running on x86_64'"

# Multiple architectures
[[commands]]
  name = "64-bit Systems"
  arch = ["x86-64", "aarch64"]
    [[commands.commands]]
      command = "echo '64-bit system'"

Valid architecture values: x86-64 (alias: x86_64), x86, aarch64, arm, mips64, mips, powerpc64, powerpc, riscv64, s390x

Combined Filtering

OS and architecture filters can be combined:

[[commands]]
  name = "Linux ARM64"
  os = ["linux"]
  arch = ["aarch64"]
    [[commands.commands]]
      command = "echo 'Linux on ARM64'"

Error Handling

Default Behavior

By default, commands that fail (non-zero exit code) will cause the analysis to stop:

[[commands]]
  name = "Critical Check"
    [[commands.commands]]
      command = "test -f /important/file"

Ignoring Errors

Set ignore-errors = true at the group level, or override per-command:

[[commands]]
  name = "Optional Checks"
  ignore-errors = true
    [[commands.commands]]
      command = "test -f /optional/file"
    [[commands.commands]]
      command = "critical-check"
      ignore-errors = false

Environment Variables

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

[[commands]]
  name = "Custom Environment"
  env = [["SHARED_VAR", "shared"]]
    [[commands.commands]]
      command = "echo $SHARED_VAR $CMD_VAR"
      env = [["CMD_VAR", "per-command"]]

Working Directory

Specify a working directory at the group or command level:

[[commands]]
  name = "List Temp Files"
  os = ["linux", "macos"]
  working-dir = "/tmp"
  ignore-errors = true
    [[commands.commands]]
      command = "ls -la"
    [[commands.commands]]
      command = "pwd"
      working-dir = "/var/log"

Execution Targets

Local Execution (Default)

[[commands]]
  name = "Local Command"
  target = "local"
    [[commands.commands]]
      command = "hostname"

Agent Execution

[[commands]]
  name = "Agent Commands"
  target = "agent"
    [[commands.commands]]
      command = "collect-system-info.sh"

Controller Execution

[[commands]]
  name = "Controller Commands"
  target = "controller"
    [[commands.commands]]
      command = "aggregate-results.sh"

Command Matrix

A matrix defined within a group runs all commands for each combination of matrix values. The os and arch keys filter by platform.

Basic Matrix

[[commands]]
  name = "Multi-OS Check"
    [commands.matrix]
      os = ["linux", "macos"]
    [[commands.commands]]
      command = "uname -a"

Matrix with OS and Arch

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

Matrix Options

Disabled Groups

Groups can be disabled without removing them:

[[commands]]
  name = "Disabled Group"
  enabled = false
    [[commands.commands]]
      command = "echo 'This will not run'"

Complete Examples

System Diagnostics Profile

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

# Linux diagnostics
[[commands]]
  name = "Linux System"
  os = ["linux"]
  ignore-errors = true
    [[commands.commands]]
      command = "uname -r"
    [[commands.commands]]
      command = "lscpu"
    [[commands.commands]]
      command = "free -h"

# macOS diagnostics
[[commands]]
  name = "macOS System"
  os = ["macos"]
  ignore-errors = true
    [[commands.commands]]
      command = "sw_vers"
    [[commands.commands]]
      command = "sysctl -n machdep.cpu.brand_string"

# Windows diagnostics
[[commands]]
  name = "Windows System"
  os = ["windows"]
  ignore-errors = true
    [[commands.commands]]
      command = "ver"
    [[commands.commands]]
      command = "systeminfo"

Security Collection Profile

# User information
[[commands]]
  name = "User Info"
  os = ["linux", "macos"]
  ignore-errors = true
    [[commands.commands]]
      command = "whoami"
    [[commands.commands]]
      command = "groups"
    [[commands.commands]]
      command = "who"

# Network information
[[commands]]
  name = "Network Info"
  os = ["linux"]
  ignore-errors = true
    [[commands.commands]]
      command = "ip addr show"
    [[commands.commands]]
      command = "ss -tulpn"
    [[commands.commands]]
      command = "ss -tunp state established"

# Distributed collection via agents
[[commands]]
  name = "Agent Collection"
  os = ["linux"]
  target = "agent"
  ignore-errors = true
    [[commands.commands]]
      command = "ps aux"
    [[commands.commands]]
      command = "hostname"

Best Practices

1. Always set ignore-errors = true for optional commands to prevent analysis interruption
2. Use OS and architecture filters to ensure commands run only where they make sense
3. Group related commands together for better organization and shared settings
4. Use matrix definitions to run commands across multiple platform combinations
5. Test commands on target platforms before deploying profiles
6. Use descriptive group names to make logs and output more readable
7. Be cautious with agent/controller targets in distributed setups

Security Considerations

• Commands run with the same privileges as the sus process
• Validate command inputs if they come from untrusted sources
• Be cautious with shell metacharacters and injection risks
• Review commands from external profiles before use
• Use target = "agent" carefully in distributed setups

See Also

• Profile Options - Complete profile reference
• CLI Options - Command-line reference
• Examples - Example command profile