Configuration Management Guide¶

This guide provides comprehensive instructions for managing SSF Tools configuration files using the ssf-tools config command suite.

Overview¶

All core features of the toolkit are meant to be configured from the command line. Use --help to see available options.

For advanced use cases or to control back-end options such as the cache location, SSF Tools can also be configured using YAML configuration files:

Multi-source configuration: Combines user, local, and default settings
Hierarchical structure: Global settings with component-specific overrides
Real-time validation: Immediate feedback on configuration errors
Flexible management: Complete CLI toolkit for configuration tasks

Prerequisites¶

SSF Tools installed and accessible via command line
Basic familiarity with YAML syntax
Understanding of your analysis requirements

Configuration File Structure¶

SSF Tools uses a unified YAML configuration file with the following structure:

# Global settings that apply to all components
global:
  cache_dir: "~/.cache/ssf_tools"     # Unix: ~/.cache/ssf_tools, Windows: %LOCALAPPDATA%\ssf_tools
  output:
    format: json
    verbose: false
  network:
    timeout_seconds: 30
    retry_count: 3

# Component-specific settings
entropy:
  analysis:
    chunk_size: 8192
    memory_limit_mb: 1024
  detection:
    credentials: true

# Future components...
volatility:
  # Memory analysis settings

Configuration Commands¶

1. Creating Configuration Files (`init`)¶

The init command creates new configuration files with sensible defaults.

Basic Usage¶

# Create ssf-tools-config.yaml configuration in current directory
ssf-tools config init

# Create in specific location
ssf-tools config init --output /path/to/my-config.yaml

# Create in user config directory (~/.config/kirkpatrickprice/ssf_tools/)
ssf-tools config init --user

Advanced Options¶

# Overwrite existing configuration file
ssf-tools config init --overwrite

# Create user configuration with overwrite
ssf-tools config init --user --overwrite

# Specify output location with overwrite protection
ssf-tools config init --output ./custom-config.yaml

Command Options¶

Option	Short	Description	Default
`--output`	`-o`	Specify output file path	`./ssf-tools-config.yaml`
`--user`		Create in user config directory	Current directory
`--overwrite`		Overwrite existing files	Protect existing files
`--config-format`		Configuration format	`yaml`

Example Output¶

# Create a default configuration file in the local directory
$ ssf-tools config init
✓ Created unified configuration: global + entropy -> ./ssf-tools-config.yaml

# Create a default configuration in the user's platform-specific "config" directory (Unix/macOS)
$ ssf-tools config init --user
✓ Created unified configuration: global + entropy -> ~/.config/kirkpatrickprice/ssf_tools/ssf-tools-config.yaml

# Create a default configuration in the user's platform-specific "config" directory (Windows)
PS> ssf-tools config init --user
✓ Created unified configuration: global + entropy -> C:\Users\Username\AppData\Roaming\kirkpatrickprice\ssf-tools\ssf-tools-config.yaml

2. Validating Configuration (`validate`)¶

The validate command checks configuration files for errors and provides detailed feedback.

Basic Usage¶

# Unix/macOS - Validate specific configuration file
$ ssf-tools config validate ./ssf-tools-config.yaml

# Unix/macOS - Validate file in different location
$ ssf-tools config validate /path/to/config.yaml

# Windows PowerShell - Validate specific configuration file
PS> ssf-tools config validate .\ssf-tools-config.yaml

# Windows PowerShell - Validate file in different location
PS> ssf-tools config validate C:\path\to\config.yaml

Validation Results¶

The validator provides color-coded feedback:

✓ Green: Section is valid
⚠ Yellow: Valid with warnings (unknown sections, etc.)
✗ Red: Validation errors that must be fixed

Example: Valid Configuration¶

$ ssf-tools config validate ./ssf-tools-config.yaml
✓ Section 'global' is valid
✓ Section 'entropy' is valid
✓ Configuration file is valid: ./ssf-tools-config.yaml

Example: Configuration with Warnings¶

$ ssf-tools config validate ./ssf-tools-config.yaml
✓ Section 'global' is valid
✓ Section 'entropy' is valid
⚠ Unknown section 'custom_section' (not registered)
⚠ Configuration file is valid (with warnings): ./ssf-tools-config.yaml

Example: Configuration with Errors¶

$ ssf-tools config validate ./bad-config.yaml
✗ Section 'entropy' has validation errors:
  - analysis -> chunk_size: Input should be greater than 0
  - analysis -> invalid_field: Extra inputs are not permitted
✗ Configuration file has validation errors

3. Viewing Configuration (`show`)¶

The show command displays effective configuration with proper merging from multiple sources.

Basic Usage¶

# Unix/macOS - Show effective merged configuration from all sources
$ ssf-tools config show

# Unix/macOS - Show specific configuration file
$ ssf-tools config show --config ./my-config.yaml

# Unix/macOS - Show configuration from different location
$ ssf-tools config show --config /path/to/config.yaml

# Windows PowerShell - Show effective merged configuration from all sources
PS> ssf-tools config show

# Windows PowerShell - Show specific configuration file
PS> ssf-tools config show --config .\my-config.yaml

# Windows PowerShell - Show configuration from different location
PS> ssf-tools config show --config C:\path\to\config.yaml

Multi-Source Merging¶

When no specific file is provided, SSF Tools automatically merges configuration from:

User configuration:
Unix/macOS: ~/.config/kirkpatrickprice/ssf_tools/ssf-tools-config.yaml
Windows: %APPDATA%\kirkpatrickprice\ssf-tools\ssf-tools-config.yaml
Local configuration: ./ssf-tools-config.yaml (current directory)
Default configuration: Built-in sensible defaults

graph TD DEFAULTS["Pydantic Defaults Built into models LOWEST PRIORITY"] USER["User Config ~/.config/ssf_tools/entropy-config.yaml Personal preferences"] PROJECT["Project Config ./entropy-config.yaml Project-specific settings"] CLI["CLI Arguments --verbose --output-format json HIGHEST PRIORITY"] FINAL["Final Configuration Merged Result"] DEFAULTS --> USER USER --> PROJECT PROJECT --> CLI CLI --> FINAL DEFAULTS -.->|Merged with| USER USER -.->|Overridden by| PROJECT PROJECT -.->|Overridden by| CLI classDef lowest fill:#d0ebff,stroke:#339af0,stroke-width:1px classDef medium fill:#74c0fc,stroke:#339af0,stroke-width:2px classDef high fill:#ffd93d,stroke:#fab005,stroke-width:2px classDef highest fill:#ff6b6b,stroke:#c92a2a,stroke-width:3px,color:#fff classDef final fill:#51cf66,stroke:#37b24d,stroke-width:3px,color:#fff class DEFAULTS lowest class USER medium class PROJECT high class CLI highest class FINAL final

Example: Merged Configuration¶

$ ssf-tools config show
ℹ Effective configuration (merged from all available sources)
global:
  cache_dir: /Users/username/.cache/ssf_tools
  output:
    format: json
    verbose: false
  network:
    timeout_seconds: 30
    retry_count: 3
entropy:
  analysis:
    chunk_size: 8192
    memory_limit_mb: 1024
  detection:
    credentials: true
    crypto_structures: true
    statistical_analysis: true

Example: Specific File¶

$ ssf-tools config show --config ./custom-config.yaml
ℹ Configuration from single source: ./custom-config.yaml
global:
  output:
    verbose: true
entropy:
  analysis:
    chunk_size: 4096

4. Finding Configuration Files (`paths`)¶

The paths command shows where SSF Tools looks for configuration files.

Basic Usage¶

ssf-tools config paths

Example Output¶

# Unix/macOS example
$ ssf-tools config paths
ℹ Unified configuration file search paths:
  1. /current/working/directory/ssf-tools-config.yaml (✗ not found)
  2. ~/.config/kirkpatrickprice/ssf_tools/ssf-tools-config.yaml (✓ exists)

ℹ Use 'ssf_tools config init' to create a configuration file

# Windows PowerShell example
PS> ssf-tools config paths
ℹ Unified configuration file search paths:
  1. C:\current\working\directory\ssf-tools-config.yaml (✗ not found)
  2. C:\Users\Username\AppData\Roaming\kirkpatrickprice\ssf-tools\ssf-tools-config.yaml (✓ exists)

ℹ Use 'ssf_tools config init' to create a configuration file

This helps you understand:

Where SSF Tools looks for configuration files
Which files currently exist
The search order priority

PowerShell Configuration Search¶

You can also search for configuration files manually using PowerShell:

# Search for configuration files in common locations
PS> Get-ChildItem -Path @(
    ".\ssf-tools-config.yaml",
    "$env:APPDATA\kirkpatrickprice\ssf-tools\ssf-tools-config.yaml",
    "$env:USERPROFILE\.config\kirkpatrickprice\ssf-tools\ssf-tools-config.yaml"
) -ErrorAction SilentlyContinue | Select-Object FullName, LastWriteTime

# Check if user config directory exists
PS> Test-Path "$env:APPDATA\kirkpatrickprice\ssf_tools"

# Create user config directory if it doesn't exist
PS> if (!(Test-Path "$env:APPDATA\kirkpatrickprice\ssf_tools")) {
    New-Item -ItemType Directory -Path "$env:APPDATA\kirkpatrickprice\ssf_tools" -Force
}

5. Listing Available Components (`list`)¶

The list command shows which components support configuration.

Basic Usage¶

ssf-tools config list

Example Output¶

$ ssf-tools config list
ℹ Commands with configuration support:
  • entropy
  • global
  • volatility

ℹ Total: 3 command(s)
ℹ Use 'ssf_tools config init' to create a unified configuration file

Common Use Cases¶

Setting Up a New Project¶

Create project directory:

# Unix/macOS
$ mkdir my-ssf-analysis
$ cd my-ssf-analysis

# Windows PowerShell
PS> New-Item -ItemType Directory -Name "my-ssf-analysis"
PS> Set-Location .\my-ssf-analysis

Initialize configuration:
```
# Unix/macOS
$ ssf-tools config init
```

# Windows PowerShell
PS> ssf-tools config init

Validate configuration:

# Unix/macOS
$ ssf-tools config validate ./ssf-tools-config.yaml

# Windows PowerShell
PS> ssf-tools config validate .\ssf-tools-config.yaml

Review settings:
```
# Unix/macOS
$ ssf-tools config show
```

# Windows PowerShell
PS> ssf-tools config show

Customizing Analysis Settings¶

Create configuration file:

# Unix/macOS
$ ssf-tools config init --output ./analysis-config.yaml

# Windows PowerShell
PS> ssf-tools config init --output .\analysis-config.yaml

Edit configuration (example):

global:
  output:
    verbose: true
    format: json

entropy:
  analysis:
    chunk_size: 16384      # Larger chunks for faster processing
    memory_limit_mb: 2048   # More memory for large files
  detection:
    credentials: true
    crypto_structures: false  # Skip crypto detection

Validate changes:

# Unix/macOS
$ ssf-tools config validate ./analysis-config.yaml

# Windows PowerShell
PS> ssf-tools config validate .\analysis-config.yaml

Use with analysis:

# Unix/macOS
$ ssf-tools --config ./analysis-config.yaml entropy analyze /path/to/data

# Windows PowerShell
PS> ssf-tools --config .\analysis-config.yaml entropy analyze C:\path\to\data

Managing Multiple Environments¶

Development Environment¶

# Unix/macOS - Create development configuration
$ ssf-tools config init --output ./config-dev.yaml

# Windows PowerShell - Create development configuration
PS> ssf-tools config init --output .\config-dev.yaml

# Edit for development (more verbose, smaller chunks for testing)
# config-dev.yaml:
global:
  output:
    verbose: true
entropy:
  analysis:
    chunk_size: 1024

Production Environment¶

# Unix/macOS - Create production configuration
$ ssf-tools config init --output ./config-prod.yaml

# Windows PowerShell - Create production configuration
PS> ssf-tools config init --output .\config-prod.yaml

# Edit for production (optimized performance)
# config-prod.yaml:
global:
  output:
    verbose: false
entropy:
  analysis:
    chunk_size: 65536
    memory_limit_mb: 4096

Usage¶

# Unix/macOS - Development analysis
$ ssf-tools --config ./config-dev.yaml entropy analyze ./test-data

# Unix/macOS - Production analysis
$ ssf-tools --config ./config-prod.yaml entropy analyze ./production-data

# Windows PowerShell - Development analysis
PS> ssf-tools --config .\config-dev.yaml entropy analyze .\test-data

# Windows PowerShell - Production analysis
PS> ssf-tools --config .\config-prod.yaml entropy analyze .\production-data

User-Wide Default Configuration¶

Create user configuration:

# Both Unix/macOS and Windows
$ ssf-tools config init --user
PS> ssf-tools config init --user

Edit user defaults:
Unix/macOS: ~/.config/kirkpatrickprice/ssf_tools/ssf-tools-config.yaml
Windows: %APPDATA%\kirkpatrickprice\ssf-tools\ssf-tools-config.yaml

global:
  output:
    verbose: true        # Always show detailed output
    format: json
  network:
    timeout_seconds: 60  # Longer timeouts for slow networks

entropy:
  analysis:
    chunk_size: 8192     # Standard chunk size

Override per project (./ssf-tools-config.yaml):

entropy:
  analysis:
    chunk_size: 32768    # Larger chunks for this project

Verify merged configuration:

# Both platforms
$ ssf-tools config show

PS> ssf-tools config show
# Shows user defaults + project overrides

PowerShell - Check user config location:

PS> echo $env:APPDATA\kirkpatrickprice\ssf-tools\ssf-tools-config.yaml
PS> Get-Content "$env:APPDATA\kirkpatrickprice\ssf-tools\ssf-tools-config.yaml"

Troubleshooting¶

Common Issues¶

1. Configuration File Not Found¶

Problem: No valid configurations found

Solutions:

# Check search paths
$ ssf-tools config paths

# Create configuration file
$ ssf-tools config init

# Verify file exists - Unix/macOS
$ ls -la ssf-tools-config.yaml

# Check search paths
PS> ssf-tools config paths

# Create configuration file
PS> ssf-tools config init

# Verify file exists - Windows PowerShell
PS> Get-ChildItem .\ssf-tools-config.yaml
PS> Test-Path .\ssf-tools-config.yaml

2. Validation Errors¶

Problem: Section has validation errors

Solutions:

# Check detailed validation output
$ ssf-tools config validate ./ssf-tools-config.yaml

# Common fixes:
# - Remove invalid fields
# - Fix data types (strings vs numbers)
# - Ensure required fields are present
# - Check value ranges (e.g., chunk_size > 0)

PS> ssf-tools config validate .\ssf-tools-config.yaml

# Common fixes:
# - Remove invalid fields
# - Fix data types (strings vs numbers)
# - Ensure required fields are present
# - Check value ranges (e.g., chunk_size > 0)

Example Fix:

# ❌ Invalid
entropy:
  analysis:
    chunk_size: 0          # Must be > 0
    invalid_field: value   # Unknown field

# ✅ Valid
entropy:
  analysis:
    chunk_size: 8192

3. Permission Issues¶

Problem: Failed to save configuration

Solutions:

# Check permissions - Unix/macOS
$ ls -la ./

# Use different location - Unix/macOS
$ ssf-tools config init --output ~/my-config.yaml

# Use user directory (~/.config/...)
$ ssf-tools config init --user

# Check user directories
$ ls -la /path/to/ssf-tools-config.yaml

# Check permissions - Windows PowerShell
PS> Get-ChildItem . | Select-Object Name, Mode, LastWriteTime

# Use different location - Windows PowerShell
PS> ssf-tools config init --output "$env:USERPROFILE\my-config.yaml"

# Use user directory ($env:APPDATA\...)
$ ssf-tools config init --user

# Windows - Check/set directory permissions
PS> icacls "$env:APPDATA\kirkpatrickprice\ssf-tools"
PS> New-Item -ItemType Directory -Path "$env:APPDATA\kirkpatrickprice\ssf-tools" -Force

4. YAML Syntax Errors¶

Problem: Failed to validate configuration: YAML error

Solutions: - Check YAML syntax with online validators - Ensure proper indentation (spaces, not tabs) - Quote strings with special characters - Verify bracket/brace matching

Example:

# ❌ Invalid YAML
global:
output:              # Missing indentation
  format: json
  list:
  - item1
   - item2            # Inconsistent indentation

# ✅ Valid YAML
global:
  output:             # Proper indentation
    format: json
  list:
    - item1
    - item2           # Consistent indentation

Getting Help¶

# Command help (--help on all commands)
$ ssf-tools config --help
$ ssf-tools config init --help
$ ssf-tools config validate --help

# Check configuration status
$ ssf-tools config paths
$ ssf-tools config list

# Validate before use - Unix/macOS
$ ssf-tools config validate ./your-config.yaml

# Command help (--help on all commands)
PS> ssf-tools config --help
PS> ssf-tools config init --help
PS> ssf-tools config validate --help

# Check configuration status
PS> ssf-tools config paths
PS> ssf-tools config list

# Validate before use - Windows PowerShell
PS> ssf-tools config validate .\your-config.yaml

Best Practices¶

1. Version Control¶

Include project-specific configurations in version control
Exclude user-specific settings (use .gitignore)
Document configuration requirements in README

2. Configuration Management¶

Only include override parameters in user and local config files
Always validate configurations after editing
Use meaningful file names for different environments
Keep configurations minimal (only override necessary defaults)

3. Security¶

Don't store sensitive information in configuration files
Set appropriate file permissions (600 for user configs)

4. Testing¶

Test configurations in development environment first
Validate before deploying to production
Keep backup configurations for rollback

5. Documentation¶

Document custom configuration choices
Include example configurations in project documentation
Maintain configuration change log

This guide provides comprehensive coverage of SSF Tools configuration management. For additional technical details, see the Configuration Service Implementation Summary.

Configuration Management Guide¶

Overview¶

Prerequisites¶

Configuration File Structure¶

Configuration Commands¶

1. Creating Configuration Files (init)¶

Basic Usage¶

Advanced Options¶

Command Options¶

Example Output¶

2. Validating Configuration (validate)¶

Basic Usage¶

Validation Results¶

Example: Valid Configuration¶

Example: Configuration with Warnings¶

Example: Configuration with Errors¶

3. Viewing Configuration (show)¶

Basic Usage¶

Multi-Source Merging¶

Example: Merged Configuration¶

Example: Specific File¶

4. Finding Configuration Files (paths)¶

Basic Usage¶

Example Output¶

PowerShell Configuration Search¶

5. Listing Available Components (list)¶

Basic Usage¶

Example Output¶

Common Use Cases¶

Setting Up a New Project¶

Customizing Analysis Settings¶

Managing Multiple Environments¶

Development Environment¶

Production Environment¶

Usage¶

User-Wide Default Configuration¶

Troubleshooting¶

Common Issues¶

1. Configuration File Not Found¶

2. Validation Errors¶

3. Permission Issues¶

4. YAML Syntax Errors¶

Getting Help¶

Best Practices¶

1. Version Control¶

2. Configuration Management¶

3. Security¶

4. Testing¶

5. Documentation¶

1. Creating Configuration Files (`init`)¶

2. Validating Configuration (`validate`)¶

3. Viewing Configuration (`show`)¶

4. Finding Configuration Files (`paths`)¶

5. Listing Available Components (`list`)¶