Project Structure#

This document explains the organization and architecture of the CipherSwarm Agent codebase.

Overview#

The CipherSwarm Agent is built with Go 1.26+ and follows a modular architecture for maintainability and testability. The project structure separates concerns into logical modules and provides clear interfaces between components.

Directory Layout#

CipherSwarmAgent/
├── cmd/ # CLI entrypoint and command registration
├── internal/ # Internal-only packages (not importable by external modules)
│ └── util/ # Small generic helpers (e.g., UnwrapOr) shared across the agent
├── lib/ # Core agent logic and utilities
│ ├── agent/ # Agent lifecycle (startup, heartbeat, shutdown), client, and config mapping
│ ├── api/ # API client layer (generated + hand-written)
│ ├── apierrors/ # Generic API error handler
│ ├── arch/ # OS-specific abstractions
│ ├── benchmark/ # Benchmark execution, caching, and submission
│ ├── config/ # Configuration defaults as exported constants
│ ├── cracker/ # Hashcat binary discovery and extraction
│ ├── cserrors/ # Centralized error reporting
│ ├── display/ # User-facing output (status, progress)
│ ├── downloader/ # File download with checksum verification
│ ├── hashcat/ # Hashcat session management and parsing
│ ├── monitor/ # Background system performance monitoring
│ ├── progress/ # Progress calculation utilities
│ ├── task/ # Task lifecycle management
│ ├── testdata/ # Test fixtures and data files
│ ├── testhelpers/ # Shared test helpers and mocks
│ └── zap/ # Zap file monitoring for cracked hashes
├── agentstate/ # Global agent state, loggers, synchronized fields
├── docs/ # Documentation (this directory)
│ └── solutions/ # Solution references for bugs and fixes
│ └── logic-errors/ # Logic error investigations and resolutions
├── .github/ # GitHub workflows and templates
├── .chglog/ # Changelog configuration
├── Dockerfile # Container build for agent
├── Dockerfile.releaser # Container for releases
├── go.mod # Go module definition
├── go.sum # Go module checksums
├── justfile # Command runner configuration
├── main.go # Application entrypoint
├── mise.toml # Dev toolchain management
├── mkdocs.yml # Documentation configuration
└── README.md # Project overview

Core Modules#

1. Main Entrypoint (main.go)#

The application's entry point that delegates to the Cobra CLI framework.

package main

import "github.com/unclesp1d3r/cipherswarmagent/cmd"

func main() {
    cmd.Execute()
}

2. Command Interface (cmd/)#

cmd/root.go#

• Purpose: Cobra CLI command definition and configuration
• Key Functions:
  • Command-line flag parsing and Viper binding
  • Configuration initialization (initConfig)
  • Agent lifecycle startup (startAgent)
  • Signal handling for graceful shutdown

3. Agent State (agentstate/)#

agentstate/agentstate.go#

• Purpose: Global application state and configuration
• Key Types:
  • State: Runtime state with synchronized fields (atomic.Bool, sync.RWMutex)
  • CurrentActivity: Current agent activity enum
• Globals:
  • State: Shared agent state (access via getter/setter methods only)
  • Logger: Application logger (charmbracelet/log)

4. Core Library (lib/)#

The main business logic of the agent, organized by functional area:

lib/agent/#

The agent lifecycle, server communication, and configuration mapping. This package consolidated several files from the former root lib/ package:

• client.go: Server communication and configuration mapping
  • AuthenticateAgent(): Server authentication
  • GetAgentConfiguration(): Fetch and map server configuration
  • UpdateAgentMetadata(): Send agent info to server
  • SendHeartBeat(): Periodic health check
  • mapConfiguration(): Map API response to internal config
  • getConfiguration(): Thread-safe access to current agent configuration (via atomic.Value, unexported)
  • SetConfiguration(): Atomically replace agent configuration
  • SetMetadataProvider(): Wire enumerated device manager for metadata updates
• datatypes.go: Core data structures and type definitions (agentConfiguration, type conversion utilities)
• errors.go: Error handling helpers for API responses
• cracker_utils.go: Hashcat binary path management (setNativeHashcatPath())
• agent.go: Agent main loop and lifecycle management
  • StartAgent(): Main agent loop (heartbeat, task polling, benchmark gating). After creating the lock file, calls hashcat.CleanupOrphanedSessionFiles() to remove stale session files from previous ungraceful shutdowns before entering the main loop.

5. Internal Utilities (internal/util/)#

internal/util/util.go#

• Purpose: Small generic helpers shared across the agent
• Key Functions:
  • UnwrapOr[T](): Returns the dereferenced pointer value, or a default if the pointer is nil (used for optional API response fields)

6. API Client Layer (lib/api/)#

lib/api/client.gen.go#

• Purpose: Auto-generated API client from OpenAPI spec (oapi-codegen)
• Note: Never modify manually — regenerate with just generate

lib/api/client.go#

• Purpose: Hand-written API client wrapper
• Key Types:
  • AgentClient: Wraps ClientWithResponses, implements APIClient interface
  • Sub-clients: Tasks(), Attacks(), Agents(), Auth()

lib/api/interfaces.go#

• Purpose: APIClient aggregate interface for all sub-client operations

lib/api/errors.go#

• Purpose: API error types (APIError wrapper for generated ErrorObject)

lib/api/mock.go#

• Purpose: Mock implementations for testing

7. API Error Handler (lib/apierrors/)#

lib/apierrors/handler.go#

• Purpose: Generic API error handler (Handler) for log-or-send error handling

8. Benchmark System (lib/benchmark/)#

lib/benchmark/manager.go#

• Purpose: Benchmark execution and incremental submission
• Key Types:
  • Manager: Orchestrates benchmark sessions with constructor injection
• Key Functions:
  • UpdateBenchmarks(): Run full benchmark session
  • cacheAndSubmitBenchmarks(): Combined cache + submit with early-return

lib/benchmark/runner.go#

• Purpose: Benchmark runner logic (split from manager.go for maintainability)

lib/benchmark/result.go#

• Purpose: Benchmark result data structure and logging
• Key Types:
  • Result: Represents the outcome of a benchmark session (device, hash type, runtime, speed, submission status)

lib/benchmark/cache.go#

• Purpose: Persistent benchmark cache at {data_path}/benchmark_cache.json
• Key Functions:
  • saveBenchmarkCache(): Atomic cache persistence using os.CreateTemp + os.Rename pattern for race-free writes
  • loadBenchmarkCache(): Cache persistence
  • TrySubmitCachedBenchmarks(): Submit cached results on startup

lib/benchmark/parse.go#

• Purpose: Benchmark output parsing from hashcat stdout

9. Configuration (lib/config/)#

lib/config/config.go#

• Purpose: Configuration defaults as exported constants
• Key Constants:
  • AgentVersion: Current version of the agent software
• Key Functions:
  • SetDefaultConfigValues(): Register viper defaults
  • SetupSharedState(): Wire config into agentstate.State

10. Hashcat Integration (lib/hashcat/)#

lib/hashcat/session.go#

• Purpose: Hashcat process lifecycle management
• Key Types:
  • Session: Represents a running Hashcat instance with context-aware I/O goroutines. Includes sessionName field for tracking hashcat session name and sync.WaitGroup for tracking I/O goroutines during shutdown.
  • Session.StderrMessages: Channel type is chan ErrorInfo (changed from chan string). Consumers receive structured error information with classification and context instead of raw strings. Stdout lines are classified before being sent to this channel for error/warning lines.
• Key Functions:
  • NewHashcatSession(ctx context.Context, id string, params Params): Create configured session with parent context for proper cancellation propagation
  • Start(): Launch Hashcat process with stdout/stderr/tailer goroutines (all tracked in WaitGroup)
  • Kill(): Terminate process gracefully
  • Cleanup(): Kills the process, waits for all I/O goroutines to exit via WaitGroup, then performs resource cleanup including temporary files (output files, charset files, hash files, restore files, zaps directory) and hashcat-created session files (.log and .pid files)

lib/hashcat/params.go#

• Purpose: Hashcat parameter configuration and validation
• Key Types:
  • Params: Attack configuration structure
• Key Functions:
  • Validate(): Parameter validation per attack mode
  • toCmdArgs(): Command-line argument generation

lib/hashcat/types.go#

• Purpose: Hashcat data structures (Status, Result, StatusDevice)

lib/hashcat/exitcode.go#

• Purpose: Hashcat exit code interpretation
• Key Types:
  • ExitCodeInfo: Adds Context map[string]any field for structured metadata
• Exit Codes:
  • Corrected mappings (codes -3 through -7 match hashcat 7.x types.h):
    • -3 (ExitCodeRuntimeSkip): All backend devices skipped at runtime
    • -4 (ExitCodeMemoryHit): Insufficient device memory
    • -5 (ExitCodeKernelBuild): Kernel compilation failed
    • -6 (ExitCodeKernelCreate): Kernel creation failed
    • -7 (ExitCodeKernelAccel): Autotune failed on all devices
  • New codes:
    • 5 (ExitCodeAbortFinish): Aborted after finish flag set (RC_FINAL_ABORT_FINISH)
    • -8 (ExitCodeExtraSize): Extra size backend issue (shell: 248)
    • -9 (ExitCodeMixedWarnings): Multiple backend issues (shell: 247)
    • -11 (ExitCodeSelftestFail): Kernel self-test failed (shell: 245)

lib/hashcat/errorparser.go#

• Purpose: Hashcat error message parsing and classification
• Key Types:
  • ErrorInfo: Adds Context map[string]any field containing extracted structured metadata. Fields include error_type, hashfile, line_number, hash_preview, affected_count, total_count, device_id, backend_api, api_error, terminal, and others.
  • contextExtractor: Function type for extracting structured context from matched lines
  • errorPattern: Pattern matcher with optional extract field for context extraction
• Key Functions:
  • ClassifyStderr(): Classifies error/warning lines from hashcat. Despite the name, processes both stdout and stderr lines, as hashcat emits hash parsing errors via stdout.

lib/hashcat/session_dir.go#

• Purpose: Hashcat session directory resolution and orphaned file cleanup
• Constants:
  • sessionPrefix ("attack-"): Shared constant for agent-created session names, used across session.go, params.go, and cleanup functions
• Key Functions:
  • hashcatSessionDir(binaryPath): Resolves platform-specific session directory (~/.hashcat/sessions/ on Linux/macOS, binary directory on Windows)
  • CleanupOrphanedSessionFiles(binaryPath): Removes stale attack-*.log and attack-*.pid files from hashcat's session directory at agent startup. Skipped on Windows where the session directory equals the binary directory. Errors are logged but never propagate — cleanup failure cannot prevent agent startup.
  • cleanupOrphanedInDir(dir): Internal function that scans a directory for orphaned session files matching the attack-* pattern and removes only regular files (symlinks, directories, and .restore files are preserved)

11. Task Management (lib/task/)#

lib/task/manager.go#

• Purpose: Task acceptance and lifecycle
• Key Functions:
  • AcceptTask(), AbandonTask(), MarkTaskExhausted()

lib/task/runner.go#

• Purpose: Task execution with hashcat
• Key Functions:
  • RunTask(): Main task runner

lib/task/status.go#

• Purpose: Status update submission during task execution

lib/task/download.go#

• Purpose: Task resource downloads (hash lists, wordlists, rules)

lib/task/cleanup.go#

• Purpose: Post-task cleanup

lib/task/errors.go#

• Purpose: Task-specific error handling

12. Centralized Error Reporting (lib/cserrors/)#

lib/cserrors/errors.go#

• Purpose: Error reporting to server
• Key Functions:
  • SendAgentError(): Report errors with severity and metadata
  • LogAndSendError(): Combined logging and server reporting
  • WithContext(ctx map[string]any): Adds structured context fields to error metadata. Fields are merged into the metadata map alongside classification and platform info.

Example usage with context:

cserrors.SendAgentError(ctx, client, api.SeverityCritical, errorMsg,
    cserrors.WithClassification("backend", false),
    cserrors.WithContext(map[string]any{"device_id": 1, "error_type": "memory_hit"}))

13. OS Abstractions (lib/arch/)#

Platform-specific functionality for cross-platform support:

• linux.go: Linux device detection
• darwin.go: macOS (Intel + Apple Silicon) support
• windows.go: Windows device detection
• validate.go: Defense-in-depth path validation before exec.CommandContext calls

Common Functions: GetHashcatVersion(), Extract7z(), GetDefaultHashcatBinaryName(), GetAdditionalHashcatArgs()

lib/arch/validate.go#

• Purpose: Cross-platform path validation for executable and archive paths
• Key Functions:
  • ValidateExecutablePath(path): Verifies binary path is absolute, exists, and is not a directory
  • ValidateArchivePaths(srcFile, destDir): Validates source archive file and destination directory exist with correct types
• Key Errors:
  • ErrRelativePath: Path is not absolute
  • ErrPathNotFound: Path does not exist on disk
  • ErrPathIsDirectory: Path points to a directory when a file was expected
  • ErrPathNotDirectory: Path is not a directory when one was expected

14. Supporting Packages#

lib/cracker/ — Hashcat binary discovery and archive extraction#

lib/display/ — User-facing output formatting#

Note: The BenchmarkResult type has been moved to benchmark.Result in the lib/benchmark package.

lib/downloader/ — File download with checksum verification and retries#

lib/monitor/ — Background system performance monitoring#

Samples host resource usage (CPU, memory, swap, system load, disk/network I/O) on a configurable interval and reports through structured logging.

• metrics.go: Domain types for Metrics, MemoryStats, SwapStats, LoadStats, DiskIOStats, NetIOStats, and ProcessStats
• source.go: Source interface abstracting gopsutil/v4 for testability, with production gopsutilSource implementation. Sampling is non-blocking (delta-based CPU counters, primed before the loop).
• monitor.go: Monitor implementation with Collect(ctx) for single samples and Run(ctx) for background sampling loop (exits on context cancellation)
• Key Features:
  • Graceful degradation: Unsupported system load averages (e.g., Windows) and transient per-process errors are soft failures; core-counter (CPU/memory/swap) failures return partial metrics alongside an error
  • Configurable sampling: Default 30-second interval (clamped to ≥5s), toggles for per-CPU and per-process collection
  • Local reporting: Metrics flow through the agent's structured logger; no server-side API exists in the v1 contract

Note: GPU temperature/utilization are intentionally not duplicated here — they already flow to the server per device via DeviceStatus task status updates.

lib/progress/ — Progress calculation utilities#

lib/zap/ — Zap file monitoring for cracked hashes (shared cracking)#

lib/testhelpers/ — Shared test fixtures, HTTP mocking, and state setup#

Architecture Patterns#

1. Modular Design#

Each major functional area is separated into its own sub-package under lib/:

• Separation of Concerns: Clear boundaries between functionality
• Testability: Modules can be tested independently with constructor injection
• Maintainability: Changes are localized to relevant packages

2. Interface-Based Design#

Key interfaces abstract dependencies for testing:

• APIClient: Aggregate interface for all API operations (lib/api/interfaces.go)
• OS Abstractions: Platform-specific code isolated in arch/
• Mock Support: lib/api/mock.go and lib/testhelpers/ for test isolation

3. Configuration Management#

Multi-layered configuration system:

• Command-line flags (highest priority)
• Environment variables
• Configuration files (cipherswarmagent.yaml)
• Default values (lowest priority, from lib/config/config.go)

4. Error Handling#

Centralized error management:

• Structured Errors: api.APIError wraps generated error types
• Error Reporting: cserrors.SendAgentError() reports to server with metadata
• Graceful Degradation: Non-fatal error recovery with exponential backoff

5. State Management#

Global state with synchronized access:

• agentstate.State: Runtime state with atomic.Bool and sync.RWMutex fields
• Getter/Setter Methods: Never access synchronized fields directly
• Configuration Management: Agent configuration is accessed through agent.getConfiguration() (unexported) and agent.SetConfiguration(), which use atomic.Value for race-free concurrent access from multiple goroutines (e.g., heartbeat and main agent loop)

Data Flow#

1. Startup Sequence#

2. Task Execution Flow#

3. Error Handling Flow#

Testing Structure#

Unit Tests#

• File Pattern: *_test.go within the same package
• Naming: TestFunctionName_Scenario
• Style: Table-driven tests for core logic
• Mocking: lib/api/mock.go for API, lib/testhelpers/ for shared fixtures
• Note: hashcat package cannot import testhelpers (circular dependency) — use local helpers

Test Helpers (lib/testhelpers/)#

• fixtures.go: Common test data setup
• http_mock.go: HTTP server mocking (SetupHTTPMock)
• state_helper.go: Agent state setup (SetupTestState, SetupMinimalTestState)
• error_helpers.go: Test error utilities
• mock_session.go: Hashcat session mocking
• assertions.go: Custom test assertions

Build and Release#

Development Build#

# Local development
go build -o cipherswarm-agent

# Using just
just install

Release Build#

• GoReleaser: Automated release builds via .goreleaser.yaml
• Cross-compilation: Linux, macOS, Windows (amd64, arm64)
• Packaging: Binaries, .deb, .rpm, .pkg.tar.xz, and Docker images
• Distribution: GitHub releases and ghcr.io container registry

Docker Build#

• Multi-stage: Separate build and runtime stages
• Variants: Standard (GPU) and POCL (CPU-only)
• Tags: latest, pocl, version-specific

Dependencies#

Core Dependencies#

• Cobra: CLI framework and command parsing
• Viper: Configuration management
• charmbracelet/log: Structured logging
• oapi-codegen: OpenAPI client generation

Build Dependencies#

• GoReleaser: Release automation
• Just: Command runner
• mise: Dev toolchain management
• MkDocs: Documentation generation (Material theme)

Optional Dependencies#

• Hashcat: Hash cracking engine (bundled in Docker)
• 7zip: Archive extraction

Next Steps#

• Review Configuration for setup options
• Check Usage for operational guidance
• See Contributing to help improve the project