Stamusctl

Important: This repository contains the CLI tool only. Configuration templates are maintained in the separate stamusctl-templates repository. Template-related issues should be reported there.

Table of Contents

• Description
• Installation
• Quick Start
• Usage
• Architecture
• Template System
• Commands Reference
• NixOS Support
• Daemon Mode (stamusd)
• Contributing
• License
• Support
• Acknowledgments

Description

stamusctl is a comprehensive Command-Line Interface application written in Go by Stamus Networks that provides powerful functionalities to manage and deploy the Stamus security stack. It serves as the primary management tool for Stamus Network Detection and Response (NDR) deployments.

Key features include:

• Configuration Management: Manage Stamus stack configuration files with template-based approach
• Stack Deployment: Deploy and manage containerized Stamus stack using Docker Compose
• Template System: Built-in template system for configuration management with support for external templates
• Registry Integration: Support for public and private container registries
• PCAP Analysis: Built-in PCAP file reading capabilities for network traffic analysis
• Daemon Mode: REST API server (stamusd) for remote management

stamusd is the companion daemon that provides a REST API with functionalities similar to stamusctl, enabling remote management and automation. You can find its API documentation here.

For comprehensive documentation, visit https://docs.clearndr.io/.

Installation

stamusctl can be installed through multiple methods:

Quick Installation

Direct Download:

# Download the latest release
wget https://github.com/StamusNetworks/stamusctl/releases/latest/download/stamusctl-linux-amd64
chmod +x stamusctl-linux-amd64
sudo mv stamusctl-linux-amd64 /usr/local/bin/stamusctl

From Stamus Networks:

# Download from Stamus Networks
wget https://dl.clearndr.io/stamusctl-linux-amd64
chmod +x stamusctl-linux-amd64
sudo mv stamusctl-linux-amd64 /usr/local/bin/stamusctl

Build from Source

# Clone the repository
git clone https://github.com/StamusNetworks/stamusctl.git
cd stamusctl

# Build stamusctl CLI
STAMUS_APP_NAME=stamusctl go build -o ./stamusctl ./cmd

# Build stamusd daemon
go build -o ./stamusd ./cmd

Using Make:

# Build both CLI and daemon
make all

# Build only CLI
make cli

# Build only daemon
make daemon

Windows Build:

make all CLI_NAME=stamusctl.exe DAEMON_NAME=./stamusd.exe CURRENT_DIR=. HOST_OS=windows HOST_ARCH=amd64 VERSION=$(cat VERSION) GIT_COMMIT=$(git rev-parse HEAD)

Nix/NixOS

For NixOS users, a Nix flake is available for integration into your system configuration:

# In your flake.nix inputs
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    stamusctl.url = "github:StamusNetworks/stamusctl";
    # ... other inputs
  };

  outputs = { self, nixpkgs, stamusctl, ... }: {
    nixosConfigurations.your-hostname = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        # ... your other modules
        {
          environment.systemPackages = with pkgs; [
            stamusctl.packages.x86_64-linux.default
            # ... other packages
          ];
        }
      ];
    };
  };
}

Or install directly for testing:

# Install using nix profile
nix profile install github:StamusNetworks/stamusctl

# Or run directly
nix run github:StamusNetworks/stamusctl

Quick Start

Basic Usage

# Initialize a new configuration with default settings
stamusctl compose init

# Initialize with custom network interface
stamusctl compose init suricata.interfaces=eth0

# Get current configuration
stamusctl config get

# Update configuration parameters
stamusctl config set suricata.interfaces=eth1

# Start the stack in detached mode
stamusctl compose up -d

# Process a PCAP file
stamusctl compose readpcap /path/to/capture.pcap

# Stop the stack
stamusctl compose down

Advanced Configuration

# Initialize with custom values file
stamusctl compose init --values values.yaml

# Use custom configuration directory
stamusctl compose init --config /path/to/config

# Login to private registry
stamusctl login --registry registry.example.com --user username --pass password

# Update stack to specific version
stamusctl compose update --version v2.1.0

# Get template configuration keys
stamusctl template keys --template /path/to/template

Architecture

stamusctl leverages a template-based architecture to manage complex security stack configurations:

• Template Consumer: stamusctl consumes templates from the stamusctl-templates repository
• Separation of Concerns: Templates are maintained separately from the CLI tool for independent development
• Registry Support: Templates can be pulled from public/private container registries
• Go Templates: Uses Go's powerful template engine with Sprig functions for dynamic configuration

Template Repository Structure

Templates are organized in the stamusctl-templates repository:

• Template definitions and configurations
• Version-specific templates
• Documentation for template usage
• Issue tracking for template-related problems

Template System

stamusctl is a template consumer that uses configuration templates from the separate stamusctl-templates repository. This separation allows for:

• Independent Template Development: Templates are maintained separately from the CLI tool
• Template Versioning: Templates can be updated independently of stamusctl releases
• Template Issues: All template-related issues, bugs, and feature requests should be reported to the stamusctl-templates repository, not this repository

How Templates Work

stamusctl consumes templates to generate configuration files:

• External Templates: Primary templates are fetched from the stamusctl-templates repository
• Default Template: The default template used is "clearndr", hosted at https://github.com/StamusNetworks/stamusctl-templates/tree/main/data/clearndr
• Registry Integration: Templates can be pulled from container registries
• Version Management: Support for different template versions via --version flag

Usage

If you have the binary in your path, you can:

stamusctl [commands] [flags] [args]

If not, you can:

./stamusctl [commands] [flags] [args]

Commands Reference

Core Commands

stamusctl compose

Manages containerized Stamus stack deployments using Docker Compose.

Subcommands:

• init - Initialize configuration files

  • --config / -c - Configuration directory path (default: "config")
  • --values / -v - Use values.yaml file for configuration
  • --fromFile / -F - Use file content as parameter values
  • --default / -d - Use default settings (deprecated - now default behavior)
  • --expert / -E - Enable expert mode for advanced configuration
  • --template / -t - Specify template folder path (hidden)
  • --version - Target template version (default: "latest")
  • --registry - Registry to pull templates from
  • --bind / -b - Bind local files to config folder (/local:/config)
  • [key]=[value] - Set configuration values (e.g., suricata.interfaces=eth0)
  • clearndr - Initialize ClearNDR container compose file (subcommand)

• update - Update configuration to newer version

  • --config / -c - Configuration directory path
  • --version - Target version (default: "latest")
  • --template / -t - Template folder path (hidden)

• readpcap - Process PCAP files

  • --config / -c - Configuration directory path
  • <pcap_file> - Path to PCAP file (required argument)

Docker Compose Commands:

• up - Start the stack

  • --config / -c - Configuration directory path
  • --detach - Run in detached mode
  • --build - Build images before starting

• down - Stop the stack

  • --config / -c - Configuration directory path
  • --volumes - Remove named volumes
  • --remove-orphans - Remove undefined containers

• restart - Restart services

  • --config / -c - Configuration directory path

• ps - List running containers

  • --config / -c - Configuration directory path
  • --services - Display services
  • --quiet - Only display container IDs
  • --format - Format output

• logs - View service logs

  • --config / -c - Configuration directory path
  • --timestamps - Show timestamps
  • --tail - Number of lines to show from end
  • --since - Show logs since timestamp
  • --until - Show logs until timestamp
  • --follow - Follow log output
  • --details - Show extra details

• exec - Execute command in running container

  • --config / -c - Configuration directory path
  • --detach - Run in detached mode
  • --privileged - Give extended privileges
  • --user - Username or UID
  • --workdir - Working directory
  • --env - Set environment variables
  • --no-TTY - Disable pseudo-TTY allocation
  • --dry-run - Execute command in dry run mode
  • --index - Index of container if multiple instances

• pull - Pull service images

  • --config / -c - Configuration directory path
  • --ignore-buildable - Ignore buildable images
  • --ignore-pull-failures - Ignore pull failures
  • --include-deps - Include dependencies
  • --quiet - Pull without printing progress

• images - List images

  • --config / -c - Configuration directory path
  • --format - Format output
  • --quiet - Only display image IDs

stamusctl config

Manages configuration files and parameters.

Subcommands:

• get - Display configuration values (also default when no subcommand specified)

  • --config / -c - Configuration directory path
  • [key]... - Get specific configuration values
  • content - Get configuration file architecture
  • keys - Get configuration parameter keys
    • --markdown - Output in Markdown format

• set - Modify configuration

  • --config / -c - Configuration directory path
  • --values / -v - Values file to use
  • --reload - Reload configuration, don't keep arbitrary parameters
  • --apply - Apply configuration changes
  • --fromFile / -F - Use file content as parameter values
  • [key]=[value]... - Set configuration values
  • content - Set configuration files
    • [host_folder]:[config_folder] - Bind specific configuration files

• list - List available configurations

• clear - Clear configuration values

  • --config / -c - Configuration directory path

• version - Get configuration version

  • --config / -c - Configuration directory path

stamusctl template

Manages configuration templates.

Subcommands:

• keys - List available template keys
  • --template / -t - Template folder path (required)
  • --markdown - Output in Markdown format

stamusctl login

Manages authentication with container registries.

Options:

• --registry - Registry URL (required)
• --user - Username (required)
• --pass - Password (required)
• --verif - Verify registry connectivity (default: true)

stamusctl version

Display version information including build commit and architecture.

stamusctl nix

Manages NixOS-based Stamus appliance deployments. Generates NixOS configuration from templates and applies it via nixos-rebuild.

Subcommands:

• init - Initialize NixOS configuration from templates

  • --config / -c - Configuration output directory (default: "config")
  • --values / -v - Path to a values.yaml file
  • --fromFile / -F - Use file content as parameter values
  • --expert / -E - Expert mode for advanced configuration
  • --version - Template version (default: "latest")
  • --registry - Registry to pull templates from
  • --bind / -b - Bind local files to config (/local:/config)
  • [template] - Template to fetch from the registry (default: "clearndr")
  • [key]=[value] - Set configuration parameters
  • clearndr - Init ClearNDR NixOS configuration (subcommand)

• switch - Apply NixOS configuration via nixos-rebuild switch

  • --config / -c - Configuration directory path

• test - Run .sh and .nix test scripts from <config>/tests/

  • --config / -c - Configuration directory path
  • --filter / -f - Glob pattern to filter test files

• diff - Preview package changes between current system and pending configuration

  • --config / -c - Configuration directory path

• update - Update NixOS configuration templates to a newer version

  • --config / -c - Configuration directory path
  • --version - Target template version (default: "latest")
  • --interactive - Interactive parameter review

• build-vm - Build a throwaway QEMU VM from the NixOS configuration

  • --config / -c - Configuration directory path
  • --run - Launch the VM after building

• `statu