go-safe-cmd-runner

README

Go Safe Command Runner

A secure command execution framework in Go with comprehensive security controls designed for privilege delegation and automated batch processing.

Project page: https://github.com/isseis/go-safe-cmd-runner/

Table of Contents

• Background
• Key Security Features
• Core Features
• Architecture
• Quick Start
• Configuration
• Security Model
• Command-Line Tools
• Build and Installation
• Development
• Contributing
• License

Background

Go Safe Command Runner addresses the critical need for secure command execution in environments where:

• Regular users need to execute privileged operations safely
• Automated systems require secure batch processing capabilities
• File integrity verification is essential before command execution
• Strict control over environment variable exposure is necessary
• Audit trail and security boundaries are required for command execution

Common use cases include scheduled backups, system maintenance tasks, and delegating specific administrative operations to non-root users while maintaining security controls.

Key Security Features

Defense-in-Depth Architecture

• Pre-execution Verification: Hash validation of configuration and environment files before use prevents malicious configuration attacks
• Fixed Hash Directory: Production builds use only default hash directory, eliminating custom hash directory attack vectors
• Secure Fixed PATH: Uses hardcoded secure PATH (/sbin:/usr/sbin:/bin:/usr/bin), completely eliminating PATH manipulation attacks
• Risk-Based Command Control: Intelligent security assessment that automatically blocks high-risk operations
• Environment Variable Isolation: Strict allowlist-based filtering with zero-trust approach
• Hybrid Hash Encoding: Space-efficient file integrity verification with automatic fallback
• Sensitive Data Protection: Automatic detection and redaction of passwords, tokens, and API keys
• ELF Binary Static Analysis: Static analysis of ELF binaries to detect network capabilities, dangerous syscalls, and dynamic library dependencies before execution
• Shebang Interpreter Tracking: Script interpreters are automatically recorded and verified at runtime, preventing interpreter substitution attacks

Command Execution Security

• User/Group Execution Control: Secure user and group switching with comprehensive validation
• Privilege Management: Controlled privilege escalation with automatic privilege dropping
• Path Validation: Command path resolution with symlink attack prevention
• Output Capture Security: Secure file permissions (0600) for output files
• Timeout Control: Prevention of resource exhaustion attacks

Auditing and Monitoring

• ULID Execution Tracking: Time-ordered execution tracking with unique identifiers
• Multi-handler Logging: Console, file, and Slack integration with sensitive data redaction
• Interactive Terminal Support: Color-coded output with smart terminal detection
• Comprehensive Audit Trail: Complete logging of privileged operations and security events

Core Features

File Integrity and Verification

• SHA-256 Hash Validation: Verification of all executables and critical files before execution
• Pre-execution Verification: Validation of configuration and environment files before use
• Hybrid Hash Encoding: Space-efficient encoding with human-readable fallback
• Centralized Verification: Unified verification management with automatic privilege handling
• Group and Global Verification: Flexible file verification at multiple levels
• ELF Binary Static Analysis: Static analysis of ELF binaries detecting network capabilities (socket/connect symbols), dangerous syscall patterns (mprotect/pkey_mprotect with PROT_EXEC), and dynamic library dependencies
• Shebang Interpreter Tracking: The record command automatically detects and records the interpreter referenced in a script's shebang line (direct form #!/bin/sh and env form #!/usr/bin/env python3). At runtime, runner verifies the interpreter's hash and, for env-based scripts, confirms that the command resolves to the same path recorded at record time

Command Execution

• Command Templates: Reusable command definitions with parameter substitution for maintainability
  • Required parameters: ${param} - must be provided
  • Optional parameters: ${?param} - omitted if empty
  • Array parameters: ${@param} - expanded into multiple arguments
• Batch Processing: Command execution in organized groups with dependency management
• Automatic Temporary Directories: Auto-generation and cleanup of temporary directories per group
• Working Directory Control: Execute in fixed directories or auto-generated temporary directories
• __runner_workdir Variable: Reserved variable that references the runtime working directory
• Variable Expansion: %{var} format expansion in command names and arguments
• Automatic Environment Variables: Automatically generated variables for timestamps and process tracking
• Output Capture: Save command output to files with secure permissions
• Background Execution: Support for long-running processes with signal handling
• Extended Dry Run: Realistic simulation with comprehensive security analysis
  • Separate output streams: stdout for dry-run results, stderr for execution logs
  • --dry-run-format=json: JSON output for machine processing with debug information
  • --dry-run-detail=full: Display final environment variables with their origins and inheritance analysis
  • --show-sensitive: Show sensitive information in plain text (for debugging, use with caution)
• Timeout Control: Configurable timeouts for command execution
• User/Group Context: Execute commands as specific users with validation

Logging and Monitoring

• Multi-handler Logging: Route logs to multiple destinations (console, file, Slack)
• Interactive Terminal Support: Color-coded output with enhanced visibility
• Smart Terminal Detection: Automatic detection of terminal capabilities
• Color Control: Support for CLICOLOR, NO_COLOR, CLICOLOR_FORCE environment variables
• Slack Integration: Real-time notifications for security events, with slack_allowed_host webhook URL host validation
• Sensitive Data Redaction: Automatic filtering of sensitive information
• ULID Execution Tracking: Time-ordered execution tracking

File Operations

• Safe File I/O: Symlink-aware file operations with security checks
• Hash Recording: Record SHA-256 hashes for integrity verification
• Verification Tools: Standalone utilities for file verification

Architecture

The system follows a modular architecture with clear separation of concerns:

cmd/                    # Command-line entry points
├── runner/            # Main command runner application
├── record/            # Hash recording utility
└── verify/            # File verification utility

internal/              # Core implementation
├── ansicolor/         # Terminal color support (ANSI escape codes)
├── arm64util/         # Shared ARM64 instruction decoding utilities
├── cmdcommon/         # Shared command utilities
├── common/            # Common utilities and filesystem abstraction
├── dynlib/            # Dynamic library dependency analysis
│   ├── elfdynlib/     # ELF binary dynamic library dependency analysis
│   └── machodylib/    # Mach-O binary dynamic library dependency analysis
├── fileanalysis/      # Unified file analysis records (hash, syscall, symbol, shebang)
├── filevalidator/     # File integrity validation
│   └── pathencoding/  # Hybrid hash filename encoding
├── groupmembership/   # User/group membership validation
├── libccache/         # libc syscall wrapper symbol caching and matching
├── logging/           # Advanced logging with Slack integration
├── redaction/         # Automatic sensitive data filtering
├── runner/            # Command execution engine
│   ├── base/          # Generic packages (no dependency on flat packages)
│   │   ├── audit/     # Security audit logging
│   │   ├── environment/ # Environment variable processing
│   │   ├── executor/  # Command execution logic
│   │   ├── output/    # Output capture management
│   │   ├── privilege/ # Privilege management
│   │   ├── risk/      # Risk-based command assessment
│   │   ├── runnertypes/ # Type definitions and interfaces
│   │   ├── security/  # Security validation framework
│   │   └── variable/  # Automatic variable generation and definitions
│   ├── bootstrap/     # System initialization
│   ├── cli/           # Command-line interface
│   ├── config/        # Configuration management
│   ├── debuginfo/     # Debug functionality and utilities
│   ├── resource/      # Resource management (normal/dry-run)
│   └── runerrors/     # Centralized error handling
├── safefileio/        # Secure file operations with symlink protection
├── security/          # Binary security analysis framework
│   ├── binaryanalyzer/ # Common interfaces and types for binary analysis
│   ├── elfanalyzer/   # ELF binary network capability detection
│   └── machoanalyzer/ # Mach-O binary network capability detection
├── shebang/           # Shebang line parsing and interpreter path resolution
├── terminal/          # Terminal capability detection
└── verification/      # Centralized verification management

Quick Start

Basic Usage

# Execute commands from configuration file
./runner -config config.toml

# Dry run mode (preview without execution)
./runner -config config.toml -dry-run

# Validate configuration file
./runner -config config.toml -validate

For detailed usage instructions, see the runner command guide.

Simple Configuration Example

version = "1.0"

[global]
timeout = 3600
log_level = "info"
env_allowlist = ["PATH", "HOME", "USER"]

[[groups]]
name = "backup"
description = "System backup operations"

[[groups.commands]]
name = "database_backup"
description = "Backup database"
cmd = "/usr/bin/mysqldump"
args = ["--all-databases"]
output = "backup.sql"  # Save output to file
run_as_user = "mysql"
risk_level = "medium"

Configuration

TOML-format configuration files define how commands are executed. Configuration files have the following hierarchical structure:

• Root Level: Version information
• Global Level: Default settings applied to all groups
• Group Level: Grouping of related commands
• Command Level: Individual command configuration

Basic Configuration Example

version = "1.0"

[global]
timeout = 3600
log_level = "info"
env_allowlist = ["PATH", "HOME", "USER", "LANG"]

[[groups]]
name = "backup"
description = "Backup operations"
# workdir not specified - automatic temporary directory will be created

[[groups.commands]]
name = "database_backup"
cmd = "/usr/bin/mysqldump"
args = ["--all-databases", "--result-file=%{__runner_workdir}/db.sql"]
risk_level = "medium"

[[groups]]
name = "maintenance"
description = "System maintenance tasks"
workdir = "/tmp/maintenance"  # Specify fixed working directory

[[groups.commands]]
name = "system_check"
cmd = "/usr/bin/systemctl"
args = ["status"]
risk_level = "high"  # systemctl is always high regardless of subcommand (including status)

Automatic Variables

The system automatically provides the following internal variables:

• __runner_datetime: Runner execution start timestamp (UTC) in YYYYMMDDHHmmSS.msec format
• __runner_pid: Process ID of runner
• __runner_workdir: Working directory of the group (available at command level)

These variables can be referenced using %{variable_name} format in command paths, arguments, and environment variable values:

[[groups.commands]]
name = "backup_with_timestamp"
cmd = "/usr/bin/tar"
args = ["czf", "/tmp/backup/data-%{__runner_datetime}.tar.gz", "/data"]

[[groups.commands]]
name = "log_execution"
cmd = "/bin/sh"
args = ["-c", "echo 'PID: %{__runner_pid}, Time: %{__runner_datetime}' >> /var/log/executions.log"]

Note: The prefix __runner_ is reserved and cannot be used for user-defined variables.

User-Defined Variables

The system supports user-defined variables at different configuration levels with strict naming conventions that enforce variable scope:

Global Variables

Global variables are defined in the [global.vars] section and are available to all groups and commands. Global variable names must start with an uppercase letter (A-Z):

[global.vars]
BackupDir = "/data/backups"
MaxRetries = "3"
Environment = "production"

Local Variables

Local variables are defined in the [groups.vars] or [groups.commands.vars] sections and are only available within their scope. Local variable names must start with a lowercase letter (a-z) or underscore (_):

[[groups]]
name = "backup"

[groups.vars]
backup_date = "20250101"
_temp_file = "/tmp/backup.tmp"

[[groups.commands]]
name = "database_backup"
cmd = "/usr/bin/mysqldump"
args = ["--all-databases", "--result-file=%{BackupDir}/db-%{backup_date}.sql"]

[groups.commands.vars]
connection_timeout = "30"
retry_count = "%{MaxRetries}"

Variable Naming Rules

All variable names (global and local) must follow these rules:

• First Character: Global variables must start with uppercase letter (A-Z), local variables must start with lowercase letter (a-z) or underscore (_)
• Subsequent Characters: Alphanumeric (A-Z, a-z, 0-9) or underscore (_)
• Reserved Prefix: Variable names starting with __ (double underscore) are reserved for system use

Variable Scope Validation

The system enforces strict scope rules:

• Within Templates: Only global variables can be referenced (uppercase variables)
• Within params: Both global and local variables can be referenced
• Validation: The system validates variable names at configuration load time and reports scope violations as errors

Error case examples:

# Error: Global variables must start with uppercase letter
[global.vars]
backupDir = "/data/backups"  # ❌ Rejected

# Error: Local variables must start with lowercase letter or _
[groups.vars]
BackupDate = "20250101"  # ❌ Rejected

# Error: Reserved prefix cannot be used
[global.vars]
__custom_var = "value"  # ❌ Rejected

For detailed variable expansion documentation, refer to the Variable Expansion Guide.

Command Templates

Command templates allow you to define reusable command patterns with parameters, reducing configuration duplication:

# Define a template
[command_templates.restic_backup]
cmd = "restic"
args = ["${@flags}", "backup", "${path}"]
env = ["RESTIC_REPOSITORY=${repo}"]

# Use the template with different parameters
[[groups]]
name = "backup"

[[groups.commands]]
name = "backup_volumes"
template = "restic_backup"

[groups.commands.params]
flags = ["-v", "--exclude-caches"]
path = "/data/volumes"
repo = "/backup/repo"

[[groups.commands]]
name = "backup_database"
template = "restic_backup"

[groups.commands.params]
flags = ["-q"]
path = "/data/database"
repo = "/backup/repo"

Template parameters support three types:

• ${param}: Required parameter (error if missing)
• ${?param}: Optional parameter (omitted if empty)
• ${@param}: Array parameter (expanded into multiple arguments)

For more details, see Command Templates Guide.

Group-Level Command Allowlist

For each group, you can allow additional commands beyond the hardcoded global patterns (^/bin/.*, ^/usr/bin/.*, ^/usr/sbin/.*, ^/usr/local/bin/.*):

[global]
env_import = ["Home=HOME"]

[[groups]]
name = "custom_build"
# Additional commands allowed only in this group
cmd_allowed = [
    "%{Home}/bin/custom_tool",
    "/opt/myapp/bin/processor"
]

[[groups.commands]]
name = "run_custom"
cmd = "%{Home}/bin/custom_tool"
args = ["--verbose"]

Key features:

• Commands can be executed if they match EITHER hardcoded global patterns OR group-level cmd_allowed list
• Variable expansion (%{variable}) is supported in cmd_allowed paths
• Only absolute paths are allowed (relative paths are rejected for security)
• Other security checks (permissions, risk assessment, etc.) continue to be executed

See sample/group_cmd_allowed.toml for complete examples.

Detailed Configuration Guide

For detailed configuration file documentation, refer to the following documents:

• TOML Configuration File User Guide - Comprehensive configuration guide
  • Configuration File Hierarchy
  • Global Level Settings
  • Group Level Settings
  • Command Level Settings
  • Command Templates
  • Variable Expansion
  • Practical Configuration Examples

Security Model

File Integrity Verification

1. Pre-execution Verification

   • Validate configuration files before loading
   • Verify environment files before use
   • Prevent malicious configuration attacks

2. Hash Directory Security

   • Fixed default: /usr/local/etc/go-safe-cmd-runner/hashes
   • No custom directories in production builds
   • Test APIs separated by build tags

3. Hybrid Hash Encoding

   • Space-efficient encoding (1.00x expansion)
   • Human-readable for debugging
   • Automatic SHA256 fallback

4. Verification Management

   • Centralized verification
   • Automatic privilege handling
   • Group and global verification lists

Risk-Based Security Controls

• Automatic Risk Assessment: Command classification combining inherent command characteristics (Axis-1) with the path trust category of operands (Axis-2)
• Configurable Thresholds: Risk level limits per command
• Automatic Blocking: Automatic blocking of high-risk commands
• Risk Audit Logging: Records the allow/deny rationale with reason codes and operand zone information
• Risk Categories:
  • Low: Basic operations (ls, cat, grep), or operations involving writes to safe-zone locations (/tmp, auto-generated working directories)
  • Medium: File modifications (cp, mv) to ordinary paths, system modifications (mount, crontab), read-only subcommands such as systemctl status/show
  • High: Package management (apt, yum, dpkg, etc.), write operations targeting trust-critical paths (/etc, /usr, /lib, /boot, /var, /sbin, device nodes, etc.), destructive operations
  • Critical: Privilege escalation (sudo, su) - always blocked

Environment Isolation

• Secure Fixed PATH: Hardcoded /sbin:/usr/sbin:/bin:/usr/bin
• No PATH Inheritance: Eliminates PATH manipulation attacks
• Allowlist Filtering: Strict zero-trust environment control
• Variable Expansion: Secure %{var} expansion with allowlist
• Command.Env Priority: Configuration overrides OS environment

Privilege Management

• Automatic Dropping: Privilege dropping after initialization
• Controlled Escalation: Risk-aware privilege management
• User/Group Switching: Secure context switching with validation
• Audit Trail: Complete logging of privilege changes

Output Capture Security

• Secure Permissions: Output files created with 0600 permissions
• Privilege Separation: Output files use real UID (not run_as_user)
• Directory Security: Automatic directory creation with secure permissions
• Path Validation: Prevention of path traversal attacks

Log Security

• Sensitive Data Redaction: Automatic detection of secrets, tokens, API keys
• Multi-channel Notifications: Encrypted Slack communication
• Audit Trail Protection: Tamper-resistant structured logs
• Real-time Alerts: Immediate notification of security violations

Command-Line Tools

go-safe-cmd-runner provides three command-line tools:

runner - Main Execution Command

# Basic execution
./runner -config config.toml

# Dry run (verify execution content)
./runner -config config.toml -dry-run

# Validate configuration
./runner -config config.toml -validate

For details, see the runner command guide.

Group Filtering

Run only the groups you need by passing the --groups flag with a comma-separated list.

# Single group
./runner -config config.toml --groups=build

# Multiple groups
./runner -config config.toml --groups=build,test

# Default (all groups)
./runner -config config.toml

Group names follow the same naming rules as environment variables and must be [A-Za-z_][A-Za-z0-9_]* (first character is letter or underscore, subsequent characters are alphanumeric or underscore).

record - Hash Recording Command

# Record file hash
./record -file /path/to/executable

# Force overwrite existing hash
./record -file /path/to/file -force

For details, see the record command guide.

verify - File Verification Command

# Verify file integrity
./verify -file /path/to/file

For details, see the verify command guide.

Comprehensive User Guide

For detailed usage instructions, configuration examples, and troubleshooting, refer to the User Guide.

Build and Installation

Prerequisites

• Go 1.26.2 or later
• golangci-lint (for development)
• gofumpt (for code formatting)

Build Commands

# Build all binaries
make build

# Build specific binaries
make build/runner
make build/record
make build/verify

# Run tests
make test

# Run linter
make lint

# Format code
make fmt

# Clean build artifacts
make clean

# Run benchmarks
make benchmark

# Generate coverage report
make coverage

Installation

# Install from source
git clone https://github.com/isseis/go-safe-cmd-runner.git
cd go-safe-cmd-runner
make build

# Install binaries to system location
sudo install -o root -g root -m 4755 build/runner /usr/local/bin/go-safe-cmd-runner
sudo install -o root -g root -m 0755 build/record /usr/local/bin/go-safe-cmd-record
sudo install -o root -g root -m 0755 build/verify /usr/local/bin/go-safe-cmd-verify

# Create default hash directory
sudo mkdir -p /usr/local/etc/go-safe-cmd-runner/hashes
sudo chown root:root /usr/local/etc/go-safe-cmd-runner/hashes
sudo chmod 755 /usr/local/etc/go-safe-cmd-runner/hashes

Development

Dependencies

• github.com/pelletier/go-toml/v2 - TOML configuration parsing
• github.com/oklog/ulid/v2 - ULID generation for execution tracking
• github.com/stretchr/testify - Testing framework
• golang.org/x/term - Terminal capability detection

Testing

# Run all tests
go test -v ./...

# Run tests for specific package
go test -v ./internal/runner

# Run integration tests
make integration-test

# Run Slack notification tests (requires GSCR_SLACK_WEBHOOK_URL_SUCCESS and GSCR_SLACK_WEBHOOK_URL_ERROR)
make slack-notify-test
make slack-group-notification-test

Project Structure

The codebase follows Go best practices:

• Interface-driven design for testability
• Comprehensive error handling with custom error types
• Security-first approach with extensive validation
• Modular architecture with clear boundaries
• Build tag separation for production/test code

Execution Identification with ULID

The system uses ULID (Universally Unique Lexicographically Sortable Identifier):

• Time-ordered sortable: Naturally ordered by creation time
• URL-safe: No special characters, suitable for filenames
• Compact: Fixed 26-character length
• Collision-resistant: Monotonic entropy ensures uniqueness
• Example: 01K2YK812JA735M4TWZ6BK0JH9

Out of Scope

This project explicitly does not provide:

• Container orchestration or Docker integration
• Network security features (firewalls, VPNs, etc.)
• User authentication or authorization systems
• Web interfaces or REST APIs
• Database management capabilities
• Real-time monitoring or alerting systems
• Cross-platform GUI applications
• Package management or software installation

It focuses on secure command execution with comprehensive security controls in Unix-like environments.

Contributing

This project emphasizes security and reliability. When contributing:

• Follow security-first design principles
• Add comprehensive tests for new features
• Update documentation for configuration changes
• Ensure all security validations are tested
• Use static analysis tools (golangci-lint)
• Follow Go coding standards and best practices

For questions or contributions, refer to the project's issue tracker.

License

This project is released under the MIT License. For details, see the LICENSE file.