Skip to content

SSF Tools - Configuration Service Architecture

Overview

The Configuration Service provides a unified, protocol-based approach to configuration management across all SSF Tools commands. This architecture enables consistent configuration handling while maintaining loose coupling through dependency injection patterns and supporting multiple configuration sources with proper precedence handling.

Architectural Principles

1. Protocol-Based Design

All configuration services implement well-defined protocols, enabling: - Dependency injection: Services receive configuration interfaces, not concrete implementations - Testability: Easy mocking and stubbing for unit tests - Flexibility: Swappable implementations (file-based, remote, in-memory) - Type safety: MyPy-compliant interfaces with generic type parameters

2. Registry Pattern

The configuration manager uses a registry pattern to avoid circular dependencies: - Core never imports commands: Commands register themselves with the core - Runtime registration: Services register when modules load - Unified interface: Single config CLI for all commands - Extensibility: New commands integrate seamlessly

3. Multi-Source Configuration

Configuration values are merged from multiple sources with clear precedence: - CLI arguments (highest priority) - Project configuration (./ssf-tools-config.yaml) - User configuration (platform-specific user directory) - Default values (Pydantic model defaults, lowest priority)

Architecture Overview

graph TD %% Core Configuration Components CM[Configuration Manager<br/>Registry Pattern] CMP[ConfigurationManagerProtocol] CSP["ConfigurationServiceProtocol&lt;T&gt;"] BC[BaseConfiguration<br/>Shared Base Class] %% Core Configuration Models Group subgraph CORE ["🏛️ Core Configuration Models"] OC[OutputConfig<br/>Cross-cutting Output Settings] NC[NetworkConfig<br/>Cross-cutting Network Settings] end %% Command-Specific Services ES["Configuration Service<br/>ConfigT: GlobalConfiguration"] VS["Configuration Service<br/>ConfigT: EntropyConfiguration"] %% Command-Specific Models GC[GlobalConfiguration<br/>Global settings] EC[EntropyConfiguration<br/>Entropy-specific settings] %% CLI Interface CLI["CLI Config Commands<br/>config init|validate|show|paths|list"] %% Relationships CLI --> CM CMP -.-> CM CM --> ES CM --> VS CSP -.-> ES CSP -.-> VS ES --> GC VS --> EC %% Core models are inherited by command-specific models GC -.-> BC EC -.-> BC %% Core models provide cross-cutting concerns OC --> BC NC --> BC %% Styling classDef coreService fill:#e1f5fe,stroke:#0277bd,stroke-width:2px classDef protocol fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px classDef commandService fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px classDef configModel fill:#fff3e0,stroke:#ef6c00,stroke-width:2px classDef baseModel fill:#fce4ec,stroke:#c2185b,stroke-width:2px classDef cli fill:#e3f2fd,stroke:#1565c0,stroke-width:2px classDef coreGroup fill:#f8f9fa,stroke:#6c757d,stroke-width:3px,stroke-dasharray: 5 5 class CM,CMP coreService class CSP protocol class ES,VS commandService class EC,GC,OC,NC configModel class BC baseModel class CLI cli class CORE coreGroup

Configuration Precedence

Configuration values follow a clear hierarchy, with higher priority sources overriding lower ones:

graph TD DEFAULTS["Pydantic Defaults<br/>Built into models<br/>LOWEST PRIORITY"] USER["User Config<br/>~/.config/ssf-tools/entropy-config.yaml<br/>Personal preferences"] PROJECT["Project Config<br/>./entropy-config.yaml<br/>Project-specific settings"] CLI["CLI Arguments<br/>--verbose --output-format json<br/>HIGHEST PRIORITY"] FINAL["Final Configuration<br/>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

Platform-Specific User Configuration

The configuration system uses platformdirs for cross-platform user configuration directories:

  • Windows: %APPDATA%\kirkpatrickprice\ssf-tools\ssf-tools-config.yaml
  • macOS: ~/Library/Application Support/ssf-tools/ssf-tools-config.yaml
  • Linux: ~/.config/ssf-tools/ssf-tools-config.yaml

Configuration Service Protocols

The configuration architecture is built around two main protocols that define the contracts for configuration management.

ConfigurationServiceProtocol

This protocol defines the interface for managing configuration of a specific command type:

kp_ssf_tools.core.services.config.interfaces.ConfigurationServiceProtocol

Bases: Protocol[ConfigT]

Protocol for configuration management - dependency injection compatible.

Source code in src\kp_ssf_tools\core\services\config\interfaces.py 
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
class ConfigurationServiceProtocol(Protocol[ConfigT]):
    """Protocol for configuration management - dependency injection compatible."""

    def load_config(
        self,
        config_path: Path | None = None,
        command_overrides: ConfigOverrides = None,
    ) -> ConfigT:
        """Load configuration from file with CLI overrides."""
        ...

    def save_config(self, config: ConfigT, config_path: Path) -> None:
        """Save configuration to file."""
        ...

    def validate_config(self, config: ConfigT | ConfigDict) -> ValidationResult:
        """Validate configuration and return detailed results."""
        ...

    def create_default_config(self, command: str) -> ConfigT:
        """Create default configuration for specific command."""
        ...

    def merge_configurations(self, base: ConfigT, overrides: ConfigDict) -> ConfigT:
        """Merge configuration with runtime overrides."""
        ...

    def get_config_paths(self) -> list[Path]:
        """Get standard configuration file paths."""
        ...

    def discover_config_files(
        self,
        search_paths: list[Path],
    ) -> list[ConfigurationSource]:
        """Discover configuration files in search paths."""
        ...

Functions

create_default_config(command)

Create default configuration for specific command.

Source code in src\kp_ssf_tools\core\services\config\interfaces.py 
37
38
39
def create_default_config(self, command: str) -> ConfigT:
    """Create default configuration for specific command."""
    ...

discover_config_files(search_paths)

Discover configuration files in search paths.

Source code in src\kp_ssf_tools\core\services\config\interfaces.py 
49
50
51
52
53
54
def discover_config_files(
    self,
    search_paths: list[Path],
) -> list[ConfigurationSource]:
    """Discover configuration files in search paths."""
    ...

get_config_paths()

Get standard configuration file paths.

Source code in src\kp_ssf_tools\core\services\config\interfaces.py 
45
46
47
def get_config_paths(self) -> list[Path]:
    """Get standard configuration file paths."""
    ...

load_config(config_path=None, command_overrides=None)

Load configuration from file with CLI overrides.

Source code in src\kp_ssf_tools\core\services\config\interfaces.py 
21
22
23
24
25
26
27
def load_config(
    self,
    config_path: Path | None = None,
    command_overrides: ConfigOverrides = None,
) -> ConfigT:
    """Load configuration from file with CLI overrides."""
    ...

merge_configurations(base, overrides)

Merge configuration with runtime overrides.

Source code in src\kp_ssf_tools\core\services\config\interfaces.py 
41
42
43
def merge_configurations(self, base: ConfigT, overrides: ConfigDict) -> ConfigT:
    """Merge configuration with runtime overrides."""
    ...

save_config(config, config_path)

Save configuration to file.

Source code in src\kp_ssf_tools\core\services\config\interfaces.py 
29
30
31
def save_config(self, config: ConfigT, config_path: Path) -> None:
    """Save configuration to file."""
    ...

validate_config(config)

Validate configuration and return detailed results.

Source code in src\kp_ssf_tools\core\services\config\interfaces.py 
33
34
35
def validate_config(self, config: ConfigT | ConfigDict) -> ValidationResult:
    """Validate configuration and return detailed results."""
    ...

ConfigurationManagerProtocol

This protocol defines the interface for the registry that manages multiple configuration services:

kp_ssf_tools.core.services.config.interfaces.ConfigurationManagerProtocol

Bases: Protocol

Protocol for managing multiple configuration types.

Source code in src\kp_ssf_tools\core\services\config\interfaces.py 
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
class ConfigurationManagerProtocol(Protocol):
    """Protocol for managing multiple configuration types."""

    def get_service(
        self,
        command: str,
    ) -> ConfigurationServiceProtocol[SSFToolsBaseModel]:
        """Get configuration service for any supported command."""
        ...

    def list_available_commands(self) -> list[str]:
        """List commands with configuration support."""
        ...

    def register_command(
        self,
        command: str,
        service: ConfigurationServiceProtocol[SSFToolsBaseModel],
    ) -> None:
        """Register a configuration service for a command."""
        ...

    def is_command_supported(self, command: str) -> bool:
        """Check if a command has configuration support."""
        ...

    def validate_command_config(
        self,
        command: str,
        config_data: ConfigDict,
    ) -> ValidationResult:
        """Validate configuration for a specific command without importing models."""
        ...

    def get_effective_config(
        self,
        command: str,
        user_config_path: Path | None = None,
        project_config_path: Path | None = None,
        cli_overrides: ConfigOverrides = None,
    ) -> ConfigDict:
        """Get effective configuration merged from all sources as dict."""
        ...

    def extract_cli_overrides(
        self,
        param_mapping: dict[str, tuple[str, str]],
    ) -> ConfigDict:
        """
        Extract CLI parameter overrides using a mapping table.

        Args:
            param_mapping: Dict mapping CLI param names to (config_section, config_key) tuples

        Returns:
            ConfigDict suitable for passing to get_effective_config as cli_overrides

        """
        ...

Functions

extract_cli_overrides(param_mapping)

Extract CLI parameter overrides using a mapping table.

Parameters:

Name Type Description Default
param_mapping dict[str, tuple[str, str]]

Dict mapping CLI param names to (config_section, config_key) tuples

 required

Returns:

Type Description
ConfigDict

ConfigDict suitable for passing to get_effective_config as cli_overrides
Source code in src\kp_ssf_tools\core\services\config\interfaces.py 
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
def extract_cli_overrides(
    self,
    param_mapping: dict[str, tuple[str, str]],
) -> ConfigDict:
    """
    Extract CLI parameter overrides using a mapping table.

    Args:
        param_mapping: Dict mapping CLI param names to (config_section, config_key) tuples

    Returns:
        ConfigDict suitable for passing to get_effective_config as cli_overrides

    """
    ...

get_effective_config(command, user_config_path=None, project_config_path=None, cli_overrides=None)

Get effective configuration merged from all sources as dict.

Source code in src\kp_ssf_tools\core\services\config\interfaces.py 
91
92
93
94
95
96
97
98
99
def get_effective_config(
    self,
    command: str,
    user_config_path: Path | None = None,
    project_config_path: Path | None = None,
    cli_overrides: ConfigOverrides = None,
) -> ConfigDict:
    """Get effective configuration merged from all sources as dict."""
    ...

get_service(command)

Get configuration service for any supported command.

Source code in src\kp_ssf_tools\core\services\config\interfaces.py 
60
61
62
63
64
65
def get_service(
    self,
    command: str,
) -> ConfigurationServiceProtocol[SSFToolsBaseModel]:
    """Get configuration service for any supported command."""
    ...

is_command_supported(command)

Check if a command has configuration support.

Source code in src\kp_ssf_tools\core\services\config\interfaces.py 
79
80
81
def is_command_supported(self, command: str) -> bool:
    """Check if a command has configuration support."""
    ...

list_available_commands()

List commands with configuration support.

Source code in src\kp_ssf_tools\core\services\config\interfaces.py 
67
68
69
def list_available_commands(self) -> list[str]:
    """List commands with configuration support."""
    ...

register_command(command, service)

Register a configuration service for a command.

Source code in src\kp_ssf_tools\core\services\config\interfaces.py 
71
72
73
74
75
76
77
def register_command(
    self,
    command: str,
    service: ConfigurationServiceProtocol[SSFToolsBaseModel],
) -> None:
    """Register a configuration service for a command."""
    ...

validate_command_config(command, config_data)

Validate configuration for a specific command without importing models.

Source code in src\kp_ssf_tools\core\services\config\interfaces.py 
83
84
85
86
87
88
89
def validate_command_config(
    self,
    command: str,
    config_data: ConfigDict,
) -> ValidationResult:
    """Validate configuration for a specific command without importing models."""
    ...

Configuration Models

The system uses Pydantic models for type-safe configuration with validation and serialization:

Base Configuration Model

kp_ssf_tools.core.services.config.models.BaseConfiguration

Bases: SSFToolsBaseModel

Base configuration model with common fields.

Source code in src\kp_ssf_tools\core\services\config\models.py 
104
105
106
107
108
109
110
111
112
113
114
115
class BaseConfiguration(SSFToolsBaseModel):
    """Base configuration model with common fields."""

    version: str = Field(default="1.0", description="Configuration version")
    created_at: str | None = Field(
        default=None,
        description="Configuration creation timestamp",
    )
    description: str | None = Field(
        default=None,
        description="Configuration description",
    )

Global Configuration Model

kp_ssf_tools.core.services.config.models.GlobalConfiguration

Bases: BaseConfiguration

Global SSF Tools configuration.

Source code in src\kp_ssf_tools\core\services\config\models.py 
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
class GlobalConfiguration(BaseConfiguration):
    """Global SSF Tools configuration."""

    # These fields are used by all commands
    output: OutputConfig = Field(
        default_factory=OutputConfig,
        description="Output settings for all commands",
    )
    network: NetworkConfig = Field(
        default_factory=NetworkConfig,
        description="Network settings for all commands",
    )

    # Default paths (platform-independent using platformdirs)
    @staticmethod
    def _get_user_config_dir() -> Path:
        from platformdirs import user_config_dir

        return Path(user_config_dir("ssf_tools", "kirkpatrickprice"))

    @staticmethod
    def _get_cache_dir() -> Path:
        from platformdirs import user_cache_dir

        return Path(user_cache_dir("ssf_tools", "kirkpatrickprice"))

    @staticmethod
    def _get_default_log_dir() -> Path:
        from platformdirs import user_log_dir

        return Path(user_log_dir("ssf_tools", "kirkpatrickprice"))

    user_config_dir: Path = Field(
        default_factory=_get_user_config_dir,
        description="Default configuration directory",
    )
    cache_dir: Path = Field(
        default_factory=_get_cache_dir,
        description="Default cache directory",
    )

Configuration Support Models

kp_ssf_tools.core.services.config.models.ValidationResult

Bases: SSFToolsBaseModel

Configuration validation results.

Source code in src\kp_ssf_tools\core\services\config\models.py 
49
50
51
52
53
54
55
56
57
58
class ValidationResult(SSFToolsBaseModel):
    """Configuration validation results."""

    is_valid: bool = Field(description="Whether the configuration is valid")
    errors: list[str] = Field(default_factory=list, description="Validation errors")
    warnings: list[str] = Field(default_factory=list, description="Validation warnings")
    deprecated_fields: list[str] = Field(
        default_factory=list,
        description="Deprecated field names",
    )

kp_ssf_tools.core.services.config.models.ConfigurationSource

Bases: SSFToolsBaseModel

Configuration source metadata.

Source code in src\kp_ssf_tools\core\services\config\models.py 
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
class ConfigurationSource(SSFToolsBaseModel):
    """Configuration source metadata."""

    path: Path | None = Field(default=None, description="Path to configuration file")
    scope: ConfigurationScope = Field(description="Configuration scope level")
    format: ConfigurationFormat = Field(description="Configuration file format")
    priority: int = Field(description="Priority level (higher overrides lower)")
    last_modified: float | None = Field(
        default=None,
        description="Last modification timestamp",
    )
    is_default: bool = Field(
        default=False,
        description="Whether this is a default configuration",
    )

Per-Command Configuration Models

kp_ssf_tools.<command>.models.configuration.py

Entropy Configuration Model

kp_ssf_tools.analyze.models.configuration

Entropy-specific configuration models.

Classes

AnalysisConfig

Bases: SSFToolsBaseModel

Analysis-specific configuration.

Source code in src\kp_ssf_tools\analyze\models\configuration.py 
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
class AnalysisConfig(SSFToolsBaseModel):
    """Analysis-specific configuration."""

    file_chunk_size: int = Field(
        default=8192,
        gt=0,
        description="File I/O chunk size in bytes - controls how much data is read from disk at once",
    )
    analysis_block_size: int = Field(
        default=64,
        gt=0,
        description="Analysis block size in bytes - controls the size of entropy analysis windows",
    )
    step_size: int = Field(
        default=16,
        gt=0,
        description="Step size for sliding window analysis",
    )

ContentAwareConfig

Bases: SSFToolsBaseModel

Content-aware analysis configuration for PCI SSF 2.3 compliance.

Source code in src\kp_ssf_tools\analyze\models\configuration.py 
33
34
35
36
37
38
39
40
41
42
43
44
45
46
class ContentAwareConfig(SSFToolsBaseModel):
    """Content-aware analysis configuration for PCI SSF 2.3 compliance."""

    enabled: bool = True
    thresholds: ContentAwareThresholds = Field(
        default_factory=lambda: ContentAwareThresholds.for_file_type(
            FileType.DOCUMENTATION,
        ),
        description="File type-specific thresholds",
    )
    language_detection: bool = Field(
        default=True,
        description="Enable programming language detection",
    )

DetectionConfig

Bases: SSFToolsBaseModel

Detection feature configuration.

Source code in src\kp_ssf_tools\analyze\models\configuration.py 
49
50
51
52
53
54
55
class DetectionConfig(SSFToolsBaseModel):
    """Detection feature configuration."""

    crypto_structures: bool = True
    credentials: bool = True
    credential_detection: bool = True
    statistical_analysis: bool = True

CredentialConfig

Bases: SSFToolsBaseModel

Credential detection configuration.

Source code in src\kp_ssf_tools\analyze\models\configuration.py 
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
class CredentialConfig(SSFToolsBaseModel):
    """Credential detection configuration."""

    enabled: bool = True
    cache_duration_hours: int = Field(
        default=24,
        description="Hours to cache downloaded wordlists",
    )
    auto_download: bool = Field(
        default=True,
        description="Automatically download wordlists from SecLists",
    )
    wordlist_sources: dict[str, str] = Field(
        default_factory=lambda: {
            "usernames": "https://raw.githubusercontent.com/danielmiessler/SecLists/master/Usernames/Names/names.txt",
            "xato_passwords": "https://github.com/danielmiessler/SecLists/raw/refs/heads/master/Passwords/Common-Credentials/xato-net-10-million-passwords-100000.txt",
            "ncsc_passwords": "https://github.com/danielmiessler/SecLists/raw/refs/heads/master/Passwords/Common-Credentials/100k-most-used-passwords-NCSC.txt",
        },
        description="Wordlist source URLs from SecLists repository",
    )

StatisticalConfig

Bases: SSFToolsBaseModel

Statistical analysis configuration.

Source code in src\kp_ssf_tools\analyze\models\configuration.py 
80
81
82
83
84
85
86
87
class StatisticalConfig(SSFToolsBaseModel):
    """Statistical analysis configuration."""

    normality_tests: list[str] = Field(
        default_factory=lambda: ["shapiro", "anderson", "kstest"],
    )
    outlier_detection: bool = True
    confidence_level: float = 0.95

ComplianceConfig

Bases: SSFToolsBaseModel

Compliance-specific configuration.

Source code in src\kp_ssf_tools\analyze\models\configuration.py 
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
class ComplianceConfig(SSFToolsBaseModel):
    """Compliance-specific configuration."""

    required_checks: list[str] = Field(
        default_factory=lambda: [
            "crypto_structures",
            "credentials",
            "entropy_analysis",
        ],
        description="Required compliance checks for PCI SSF 2.3",
    )
    generate_evidence: bool = Field(
        default=True,
        description="Generate audit trail evidence",
    )
    executive_summary: bool = Field(
        default=False,
        description="Generate executive summary",
    )

ReportingConfig

Bases: SSFToolsBaseModel

Reporting configuration for compliance.

Source code in src\kp_ssf_tools\analyze\models\configuration.py 
111
112
113
114
115
116
117
118
119
120
121
122
123
124
class ReportingConfig(SSFToolsBaseModel):
    """Reporting configuration for compliance."""

    risk_assessment: bool = True
    detailed_findings: bool = True
    include_samples: bool = Field(
        default=False,
        description="Include data samples in reports (sanitized)",
    )
    max_sample_length: int = Field(
        default=64,
        gt=0,
        description="Maximum length of data samples",
    )

AnalysisConfiguration

Bases: BaseConfiguration

Complete security analysis configuration.

Inherits common output and network settings from BaseConfiguration. Contains analysis-specific configuration options for entropy analysis, wordlist detection, and cryptographic structure detection.

Source code in src\kp_ssf_tools\analyze\models\configuration.py 
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
class AnalysisConfiguration(BaseConfiguration):
    """
    Complete security analysis configuration.

    Inherits common output and network settings from BaseConfiguration.
    Contains analysis-specific configuration options for entropy analysis,
    wordlist detection, and cryptographic structure detection.
    """

    # Entropy-specific settings
    analysis: AnalysisConfig = Field(
        default_factory=AnalysisConfig,
        description="Analysis-specific settings",
    )

    # Content-aware thresholds
    content_aware: ContentAwareConfig = Field(
        default_factory=ContentAwareConfig,
        description="Content-aware analysis settings",
    )

    # Detection settings
    detection: DetectionConfig = Field(
        default_factory=DetectionConfig,
        description="Detection feature toggles",
    )

    # Credential detection
    credentials: CredentialConfig = Field(
        default_factory=CredentialConfig,
        description="Credential detection settings",
    )

    # Statistical analysis
    statistical: StatisticalConfig = Field(
        default_factory=StatisticalConfig,
        description="Statistical analysis settings",
    )

    # Compliance settings
    compliance: ComplianceConfig = Field(
        default_factory=ComplianceConfig,
        description="PCI SSF compliance settings",
    )

    # Reporting settings
    reporting: ReportingConfig = Field(
        default_factory=ReportingConfig,
        description="Report generation settings",
    )

CLI Integration

The unified config command provides consistent configuration management across all SSF Tools commands. These are documented in the Configuration Management User Guide:

Key Architecture Benefits

🔄 No Circular Dependencies

  • Core configuration services never import command-specific models
  • Commands register themselves with the configuration manager at runtime
  • Clean separation between core infrastructure and command implementations

📋 Registry Pattern

  • Central registry manages all configuration services
  • Commands can be added without modifying core code
  • Unified CLI interface automatically supports new commands

🔍 Type Safety

  • Protocol-based design enables full MyPy compliance
  • Generic type parameters ensure configuration type safety
  • Pydantic validation provides runtime type checking

⚙️ Multi-Source Merging

  • Intelligent merging from user, project, and CLI sources
  • Clear precedence rules prevent configuration conflicts
  • Field-level merging allows granular overrides

🔌 Extensibility

  • New commands integrate with zero changes to core systems
  • Configuration services are pluggable and swappable
  • Support for future configuration sources (remote, database, etc.)

Implementation Guide

Adding Configuration to a New Command

  1. Define the configuration model: 

    # src/kp_ssf_tools/mycommand/models/configuration.py
from kp_ssf_tools.core.services.config.models import BaseConfiguration

class MyCommandConfiguration(BaseConfiguration):
    my_setting: str = "default_value"
    my_number: int = 42

  2. Register with the container: 

    # In your container configuration
mycommand_config_service = providers.Singleton(
    ConfigurationService[MyCommandConfiguration],
    config_model=MyCommandConfiguration,
    rich_output=...,
    timestamp_service=...,
    default_config_name="mycommand"
)

  3. Register with the manager:

In the kp_ssf_tools.containers.application container initiationalize, add the new command's service with the Configuration Manager.

kp_ssf_tools.containers.application._configure_config_manager(manager, global_service, entropy_service)

Configure the configuration manager with all available services.

Source code in src\kp_ssf_tools\containers\application.py 
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
def _configure_config_manager(
    manager: ConfigurationManager,
    global_service: ConfigurationService[GlobalConfiguration],
    entropy_service: ConfigurationService[AnalysisConfiguration],
) -> ConfigurationManager:
    """Configure the configuration manager with all available services."""
    # Register all command configuration services for unified config approach
    # Must use cast() to avoid mypy type safety warnings
    manager.register_command(
        "global",
        cast("ConfigurationServiceProtocol[SSFToolsBaseModel]", global_service),
    )
    manager.register_command(
        "entropy",
        cast("ConfigurationServiceProtocol[SSFToolsBaseModel]", entropy_service),
    )

    # Future commands will be registered here:
    # manager.register_command("volatility", volatility_service)
    # manager.register_command("forensics", forensics_service)

    return manager

The CLI automatically supports the new command: 

ssf-tools config init mycommand --user
ssf-tools config validate mycommand-config.yaml
ssf-tools config show mycommand

Using Configuration in Commands

Commands receive configuration through dependency injection:

@click.command()
@inject
def my_command(
    config_service: ConfigurationServiceProtocol[MyCommandConfiguration] = Provide[...],
):
    # Load effective configuration (user + project + CLI overrides)
    config = config_service.load_config(
        command_overrides={"my_setting": "cli_override"}
    )

    # Use type-safe configuration
    print(f"Setting: {config.my_setting}")
    print(f"Number: {config.my_number}")

This architecture ensures consistent, type-safe, and extensible configuration management across all SSF Tools commands while maintaining clean separation of concerns and excellent testability.

Configuration File Examples

The system supports unified configuration files that contain settings for multiple commands:

# ssf-tools-config.yaml
global:
  output:
    format: json
    verbose: true
  network:
    timeout_seconds: 30

entropy:
  analysis:
    chunk_size: 8192
    memory_limit_mb: 1024
  detection:
    credentials: true
    crypto_structures: true

# Future commands automatically supported
volatility:
  memory_analysis:
    profile: WinXPSP2x86

This unified approach reduces configuration file proliferation while maintaining command-specific settings organization.