devices

package
v0.6.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 29, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package devices provides hashcat-native device enumeration via `hashcat -I`. It parses the text output to produce structured device information including backend type, vendor, and device classification.

Index

Constants

View Source 
const (
	CapProcessors    = "processors"
	CapClock         = "clock"
	CapMemoryTotal   = "memory_total"
	CapMemoryFree    = "memory_free"
	CapVersion       = "version"
	CapDriverVersion = "driver_version"
	CapOpenCLVersion = "opencl_version"
)

Capability key constants for Device.Capabilities map entries.

Variables

View Source 
var (
	// ErrNoDevicesFound is returned when hashcat -I produces no parseable device blocks.
	ErrNoDevicesFound = errors.New("no devices found in hashcat output")
	// ErrInvalidDeviceID is returned by ValidateDeviceIDs when an ID is not in the enumerated set.
	ErrInvalidDeviceID = errors.New("invalid device ID")
	// ErrUnavailableDeviceID is returned when a device ID exists but the device is unavailable.
	ErrUnavailableDeviceID = errors.New("unavailable device ID")
)

Functions

func ValidateDeviceIDString deprecated 

func ValidateDeviceIDString(dm *DeviceManager, raw string) ([]int, error)

ValidateDeviceIDString parses a comma-separated string of device IDs and validates each against the enumerated device set. Returns the parsed IDs and nil on success, (nil, nil) when raw is empty, or a wrapped ErrInvalidDeviceID when any ID is not in the enumerated set. Non-numeric tokens produce a parse error.

Deprecated: Use DeviceConfig.Validate() for production code. This function is retained for standalone validation in tests.

Types

type CmdFactory 

type CmdFactory func(ctx context.Context, path string, args ...string) *exec.Cmd

CmdFactory creates an exec.Cmd for running hashcat with the given arguments. It exists to allow tests to inject a helper process binary.

type Device 

type Device struct {
	ID           int
	Name         string
	Type         string // "CPU" or "GPU"
	Backend      string // "OpenCL", "CUDA", "Metal", or "HIP"
	Vendor       string
	IsAvailable  bool
	Capabilities map[string]string // Optional capability fields parsed from hashcat -I output.
}

Device represents a single compute device enumerated by hashcat.

type DeviceConfig 

type DeviceConfig struct {
	// contains filtered or unexported fields
}

DeviceConfig encapsulates device selection state for hashcat sessions. It holds the server-provided or CLI-provided raw strings and an optional DeviceManager for validation. Constructed via NewDeviceConfig.

DeviceConfig is a value type — safe to copy across goroutines. The contained DeviceManager pointer is read-only after creation.

func NewDeviceConfig 

func NewDeviceConfig(rawBackend, rawOpenCL string, dm *DeviceManager) DeviceConfig

NewDeviceConfig creates a DeviceConfig from server/CLI strings and an optional DeviceManager. When dm is non-nil, the raw backend device string is parsed and validated against the enumerated devices. When dm is nil, the raw strings are preserved for best-effort forwarding to hashcat.

func (DeviceConfig) DeviceManager 

func (dc DeviceConfig) DeviceManager() *DeviceManager

DeviceManager returns the underlying DeviceManager, or nil if enumeration was not performed. Callers should use this for device name lookups and capability queries — not for validation (use Validate instead).

func (DeviceConfig) RawBackendDevices 

func (dc DeviceConfig) RawBackendDevices() string

RawBackendDevices returns the original server-sent or CLI-provided backend device string. Used for logging and diagnostics.

func (DeviceConfig) RawOpenCLDevices 

func (dc DeviceConfig) RawOpenCLDevices() string

RawOpenCLDevices returns the original server-sent or CLI-provided OpenCL device type string. Used for logging and diagnostics.

func (DeviceConfig) ResolvedBackendDevices 

func (dc DeviceConfig) ResolvedBackendDevices() string

ResolvedBackendDevices returns the --backend-devices flag value.

When no DeviceManager is available (enumeration failed), the raw server string is forwarded only if it matches a comma-separated integer pattern; non-numeric strings are rejected (returns "").

When a DeviceManager is available:

  • No IDs configured → "" (hashcat uses all devices)
  • All IDs invalid/unavailable → "" (hashcat auto-detects)
  • Some IDs valid → comma-separated valid IDs

func (DeviceConfig) ResolvedOpenCLDevices 

func (dc DeviceConfig) ResolvedOpenCLDevices() string

ResolvedOpenCLDevices returns the --opencl-device-types flag value. Only forwards the raw string if it matches a valid comma-separated integer pattern (e.g., "1,2,3" for CPU/GPU/accelerator types).

func (DeviceConfig) Validate 

func (dc DeviceConfig) Validate(logWarnFn func(msg any, keyvals ...any)) ValidatedDevices

Validate runs device ID validation against the DeviceManager and returns the filtered result. Logs warnings for unknown/unavailable IDs via logWarnFn. Returns an empty ValidatedDevices when dm is nil or no IDs are configured.

func (DeviceConfig) WarnInvalidDevices 

func (dc DeviceConfig) WarnInvalidDevices(logWarnFn func(msg any, keyvals ...any))

WarnInvalidDevices logs warnings for any configured device IDs that are not present or available in the enumerated device set. This is a fire-and-forget method intended for startup diagnostics — use Validate() when you need the filtered result.

type DeviceManager 

type DeviceManager struct {
	// contains filtered or unexported fields
}

DeviceManager holds the enumerated devices and provides query methods.

func NewDeviceManagerForTest 

func NewDeviceManagerForTest(devs []Device) *DeviceManager

NewDeviceManagerForTest creates a DeviceManager pre-populated with the given devices. Intended for use by other packages' tests that need a non-nil DeviceManager without running hashcat.

func (*DeviceManager) EnumerateDevices 

func (dm *DeviceManager) EnumerateDevices(ctx context.Context, hashcatPath string) error

EnumerateDevices runs hashcat -I and parses the output to populate the device list. When hashcatPath is empty, it falls back to cracker.FindHashcatBinary() to resolve the binary path using the same discovery strategy as the rest of the agent.

func (*DeviceManager) GetAllDevices 

func (dm *DeviceManager) GetAllDevices() []Device

GetAllDevices returns a deep copy of all enumerated devices. Each returned Device has its own Capabilities map (not shared with internal state).

func (*DeviceManager) GetAvailableDeviceIDs 

func (dm *DeviceManager) GetAvailableDeviceIDs() []int

GetAvailableDeviceIDs returns the IDs of all devices that are available.

func (*DeviceManager) GetDevice 

func (dm *DeviceManager) GetDevice(id int) (*Device, bool)

GetDevice returns a copy of the device with the given ID and whether it was found. The returned Device has its own Capabilities map (not shared with internal state).

func (*DeviceManager) GetDevicesByType 

func (dm *DeviceManager) GetDevicesByType(deviceType string) []Device

GetDevicesByType returns all devices matching the given type (case-insensitive).

func (*DeviceManager) HasDevices 

func (dm *DeviceManager) HasDevices() bool

HasDevices reports whether the manager has any enumerated devices.

func (*DeviceManager) ValidateDeviceIDs 

func (dm *DeviceManager) ValidateDeviceIDs(ids []int) error

ValidateDeviceIDs checks that all provided IDs exist in the enumerated device set.

func (*DeviceManager) ValidateDeviceIDsDetailed 

func (dm *DeviceManager) ValidateDeviceIDsDetailed(ids []int) DeviceValidationResult

ValidateDeviceIDsDetailed checks each provided ID against the enumerated device set, classifying IDs as valid, unknown (not in set), or unavailable (in set but IsAvailable is false).

type DeviceValidationResult 

type DeviceValidationResult struct {
	ValidIDs       []int
	UnknownIDs     []int
	UnavailableIDs []int
}

DeviceValidationResult holds the outcome of validating device IDs against the enumerated device set, separating valid, unknown, and unavailable IDs.

type ValidatedDevices 

type ValidatedDevices struct {
	BackendDeviceIDs  []int
	OpenCLDeviceTypes string
}

ValidatedDevices holds the validated device selection for a hashcat session. BackendDeviceIDs contains only IDs that exist and are available. OpenCLDeviceTypes is the raw OpenCL device type string (not ID-validated).

func ValidateAndFilterDevices deprecated 

func ValidateAndFilterDevices(
	dm *DeviceManager,
	rawBackendDevices string,
	rawOpenCLDevices string,
	logWarnFn func(msg any, keyvals ...any),
) ValidatedDevices

ValidateAndFilterDevices parses the raw device config strings, validates backend device IDs against the DeviceManager, and returns only the IDs that are known and available. Logs warnings for unknown and unavailable IDs via the provided log function. Returns an empty ValidatedDevices (use all devices) when dm is nil or rawBackendDevices is empty.

Deprecated: Use DeviceConfig.Validate() for production code. This function is retained for standalone validation in tests.

func (ValidatedDevices) BackendDevicesFlag 

func (vd ValidatedDevices) BackendDevicesFlag() string

BackendDevicesFlag returns the comma-separated string for --backend-devices, or empty string if no specific devices are selected.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.