Skip to content

SSF Tools CLI Structure

Project Overview

The ssf_tools CLI is a forensic analysis toolkit built with Click and Rich for cybersecurity professionals. The main CLI provides various sub-commands for different forensic workflows.

Folder Structure

src/
└── kp_ssf_tools/
    ├── __init__.py
    ├── cli/
    │   ├── __init__.py
    │   ├── main.py              # Root CLI entry point (`ssf_tools` command)
    │   └── commands/
    │       ├── __init__.py
    │       └── command_1.py     # Sub-command implementation
    ├── core/
    └── command_specific_packages/
        ├── __init__.py
        ├── services/           # Services required for implementation
        ├── models/             # Pydantic data models
        └── service.py          # Service interface and orchestration

Architecture Decision: Business Logic Separation

Recommendation: Separate business logic into dedicated modules

Rationale:

Based on the volatility workflow complexity, a separate business logic layer is recommended because:

  1. Complex Process Matching Logic: The platform-specific regex patterns, process name normalization, and partial extension handling are substantial
  2. File Management Complexity: Collision handling, timestamp naming, and multiple file type operations warrant dedicated modules
  3. Future Extensibility: Other forensic sub-commands will likely share common utilities
  4. Testing: Isolated business logic is easier to unit test
  5. Maintainability: Clear separation of CLI concerns from processing logic

Module Responsibilities:

cli/main.py

  • Root CLI definition (ssf_tools command)
  • Global options and configuration
  • Sub-command registration

cli/commands/volatility.py

  • Click command definition and parameter validation
  • User input/output handling
  • Rich console interactions
  • Calls to business logic modules

volatility/processor.py

  • Main workflow orchestration
  • Volatility command execution
  • High-level process coordination

volatility/parsers.py

  • Platform-specific regex handling
  • Process name normalization
  • PID extraction and matching logic
  • interesting_pids dictionary building

volatility/file_manager.py

  • File collision detection and resolution
  • Directory creation and management
  • JSON export with pretty formatting
  • Memory dump file renaming

core/utils.py

  • Common utilities shared across sub-commands
  • Path manipulation helpers
  • Validation functions

core/rich_helpers.py

  • Standardized Rich console styling
  • Error/warning message formatting
  • Progress indicators and status displays

CLI Command Structure

# Root command
ssf_tools --help

# Volatility sub-command
ssf_tools volatility [OPTIONS] IMAGE_FILE PLATFORM INTERESTING_PROCESSES

# Example usage
ssf_tools volatility \
    --results-dir ./analysis \
    --pid-list-file custom-pids.txt \
    memory.dd windows interesting-processes.txt

Benefits of This Structure

  1. Clear Separation: CLI concerns vs. business logic
  2. Reusability: Core utilities can be shared across sub-commands
  3. Testability: Each module can be independently tested
  4. Scalability: Easy to add new forensic sub-commands
  5. Maintainability: Changes to processing logic don't affect CLI interface
  6. Professional: Follows established Python project patterns

Future Sub-Commands

The structure accommodates future forensic tools: - ssf_tools testssl - SSL/TLS testing workflow - ssf_tools hash_comp - Hash comparison utilities - ssf_tools combine_csv - CSV combination tools

Each would follow the same pattern: CLI command in cli/commands/ with business logic in dedicated modules.