scan

package
v1.1.2 Latest Latest
Warning

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

 Go to latest Published: Nov 11, 2026 License: MIT Imports: 29 Imported by: 0

Documentation

Overview

Package scan provides the PingPlusPlusAdapter which integrates ping++ as the fingerprinting engine for the app-scanner pipeline.

Index

Constants

View Source 
const (
	TemplateKeyPrefix      = "scan:template:"
	TemplateListKey        = "scan:template:list"
	SystemTemplatesListKey = "scan:system-templates"
)

ValKey key constants for template storage

View Source 
const DEFAULT_WORKERS = 10

Default number of worker goroutines

View Source 
const DefaultFingerprintTimeout = 3 * time.Second

DefaultFingerprintTimeout is the default timeout for fingerprint probes.

Variables

View Source 
var DefaultFingerprintProbes = []string{"icmp", "tcp", "ssh", "http", "smb"}

DefaultFingerprintProbes are the default probe types for fingerprinting. This matches the ping++ CLI defaults which include SSH, HTTP, and SMB probes for accurate OS detection (especially Windows detection via SMB/SSH banners).

View Source 
var ErrScanContention = errors.New("current scan changed too often during update")
View Source 
var ErrScanMismatch = errors.New("current scan does not match requested scan")

Functions

This section is empty.

Types

type AgentScanConfig 

type AgentScanConfig struct {
	Enabled        bool     `json:"enabled"`
	Mode           string   `json:"mode"`                      // "comprehensive", "templates-only", "scripts-only"
	AgentIDs       []string `json:"agent_ids"`                 // empty = all connected agents
	Timeout        int      `json:"timeout"`                   // seconds, default 300
	Concurrency    int      `json:"concurrency"`               // parallel templates, default 5
	TemplateFilter []string `json:"template_filter,omitempty"` // specific templates, empty = all
}

AgentScanConfig defines agent-based scan settings within a template

type ControlMessage 

type ControlMessage struct {
	Action    string `json:"action"`    // Action to perform (e.g., "cancel")
	ScanID    string `json:"scan_id"`   // Required: exact scan to cancel
	Timestamp string `json:"timestamp"` // When the command was issued
	StateMode string `json:"state_mode,omitempty"`
	SubjectID string `json:"-"`
}

ControlMessage represents a control command for the scanner

type FingerprintOptions 

type FingerprintOptions struct {
	// ProbeTypes specifies which probes to use (icmp, tcp, arp, smb)
	ProbeTypes []string

	// Timeout is the per-probe timeout duration
	Timeout time.Duration

	// DisableICMP disables ICMP probing (for unprivileged mode)
	DisableICMP bool
}

FingerprintOptions contains configuration for fingerprint scanning.

func DefaultFingerprintOptions 

func DefaultFingerprintOptions() FingerprintOptions

DefaultFingerprintOptions returns sensible defaults for fingerprinting.

type FingerprintResult 

type FingerprintResult struct {
	IsAlive  bool              // Whether the host is alive/reachable
	OSFamily string            // Detected OS family (e.g., "windows", "linux", "unknown")
	TTL      int               // TTL value from ICMP response
	Details  map[string]string // Additional fingerprint details (confidence, hops, etc.)
}

FingerprintResult contains the results of a fingerprint scan. This struct is used by both the FingerprintStrategy interface and the ping++ adapter.

type FingerprintStrategy 

type FingerprintStrategy interface {
	Fingerprint(target string) (FingerprintResult, error)
	// FingerprintWithContext performs fingerprinting with cancellation support
	FingerprintWithContext(ctx context.Context, target string) (FingerprintResult, error)
}

FingerprintStrategy defines an interface for host fingerprinting operations. The default implementation uses ping++ for ICMP/TCP probing and TTL-based OS detection.

Implementations:

  • PingPlusPlusAdapter: Real fingerprinting using ping++ (see pingpp_adapter.go)

Configuration options are available via ScanOptions:

  • FingerprintProbes: probe types (icmp, tcp, arp, smb)
  • FingerprintTimeout: per-probe timeout
  • DisableICMP: for unprivileged execution

type LoggingClient 

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

LoggingClient wraps the SDK LoggingClient for App Scanner convenience

func NewLoggingClient 

func NewLoggingClient() *LoggingClient

NewLoggingClient creates a new logging client using the SDK

func (*LoggingClient) Close 

func (lc *LoggingClient) Close() error

Close gracefully shuts down the logging client

func (*LoggingClient) LogEvent 

func (lc *LoggingClient) LogEvent(service, subcomponent, eventType, severity, title, description string, entityType, entityID string, metadata map[string]interface{})

LogEvent logs a structured event with all event fields (new convenience method)

func (*LoggingClient) LogHostDiscovered 

func (lc *LoggingClient) LogHostDiscovered(hostIP, scanID string, metadata map[string]interface{})

LogHostDiscovered logs when a new host is discovered (new convenience method)

func (*LoggingClient) LogHostDiscovery 

func (lc *LoggingClient) LogHostDiscovery(scanID, hostIP string, ports []int, toolUsed string)

LogHostDiscovery logs when a new host is discovered

func (*LoggingClient) LogScanCompleted 

func (lc *LoggingClient) LogScanCompleted(scanID string, stats map[string]interface{})

LogScanCompleted logs when a scan completes successfully (new convenience method)

func (*LoggingClient) LogScanCompletion 

func (lc *LoggingClient) LogScanCompletion(scanID, target string, metadata map[string]interface{})

LogScanCompletion logs the overall completion of a scan

func (*LoggingClient) LogScanError 

func (lc *LoggingClient) LogScanError(scanID, target, errorCode, message string, err error)

LogScanError logs an error related to a scan

func (*LoggingClient) LogScanEvent 

func (lc *LoggingClient) LogScanEvent(scanID, eventType, message string, metadata map[string]interface{})

LogScanEvent logs a general event related to a scan

func (*LoggingClient) LogScanStarted 

func (lc *LoggingClient) LogScanStarted(scanID string, targets []string, options map[string]interface{})

LogScanStarted logs when a scan starts (new convenience method)

func (*LoggingClient) LogToolExecution 

func (lc *LoggingClient) LogToolExecution(scanID, target, tool string, duration time.Duration, success bool, metadata map[string]interface{})

LogToolExecution logs the execution of an external scanning tool

func (*LoggingClient) LogVulnerabilityFound 

func (lc *LoggingClient) LogVulnerabilityFound(vulnID, hostIP, severity string, metadata map[string]interface{})

LogVulnerabilityFound logs when vulnerabilities are found (new convenience method)

func (*LoggingClient) LogVulnerabilityScan 

func (lc *LoggingClient) LogVulnerabilityScan(scanID, hostIP string, vulnerabilities []map[string]interface{}, toolUsed string)

LogVulnerabilityScan logs the results of a vulnerability scan

type NaabuStrategy 

type NaabuStrategy struct {
	Ports   string
	Retries int
}

NaabuStrategy implements port enumeration using Naabu

func (*NaabuStrategy) Execute 

func (n *NaabuStrategy) Execute(target string) (sirius.Host, error)

Execute performs port enumeration using Naabu. This is a convenience method that uses context.Background().

func (*NaabuStrategy) ExecuteWithContext 

func (n *NaabuStrategy) ExecuteWithContext(ctx context.Context, target string) (sirius.Host, error)

ExecuteWithContext performs port enumeration with cancellation support.

type NmapStrategy 

type NmapStrategy struct {
	Protocols  []string // Deprecated: use ScriptList
	ScriptList []string // Explicit list of scripts to run
	PortRange  string   // Port range to scan (from template)
}

NmapStrategy implements vulnerability scanning using Nmap.

func (*NmapStrategy) Execute 

func (n *NmapStrategy) Execute(target string) (sirius.Host, error)

Execute performs the vulnerability scan using Nmap and expands vulnerability details. This is a convenience method that uses context.Background().

func (*NmapStrategy) ExecuteWithContext 

func (n *NmapStrategy) ExecuteWithContext(ctx context.Context, target string) (sirius.Host, error)

ExecuteWithContext performs the vulnerability scan with cancellation support.

type PingPlusPlusAdapter 

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

PingPlusPlusAdapter wraps the ping++ PingPlusPlusStrategy to implement the app-scanner FingerprintStrategy interface.

This adapter: - Converts between ping++ and app-scanner result types - Provides configuration options for probe types and timeouts - Handles the interface bridging without circular imports

func NewPingPlusPlusAdapter 

func NewPingPlusPlusAdapter() *PingPlusPlusAdapter

NewPingPlusPlusAdapter creates a new adapter with default options.

func NewPingPlusPlusAdapterWithOptions 

func NewPingPlusPlusAdapterWithOptions(opts FingerprintOptions) *PingPlusPlusAdapter

NewPingPlusPlusAdapterWithOptions creates a new adapter with custom options.

func (*PingPlusPlusAdapter) Fingerprint 

func (a *PingPlusPlusAdapter) Fingerprint(target string) (FingerprintResult, error)

Fingerprint performs host fingerprinting using ping++. This method implements the FingerprintStrategy interface. This is a convenience method that uses context.Background().

func (*PingPlusPlusAdapter) FingerprintWithContext 

func (a *PingPlusPlusAdapter) FingerprintWithContext(ctx context.Context, target string) (FingerprintResult, error)

FingerprintWithContext performs host fingerprinting with cancellation support. This method implements the FingerprintStrategy interface.

func (*PingPlusPlusAdapter) Options 

func (a *PingPlusPlusAdapter) Options() FingerprintOptions

Options returns the current fingerprint options.

type ScanManager 

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

ScanManager manages scan operations.

func NewScanManager 

func NewScanManager(kvStore store.KVStore, toolFactory *ScanToolFactory, updater *ScanUpdater) *ScanManager

NewScanManager creates a new ScanManager.

func (*ScanManager) CancelCurrentScan 

func (sm *ScanManager) CancelCurrentScan(scanID string)

CancelCurrentScan cancels only the explicitly identified scan. Untargeted commands are rejected because delayed queue delivery could hit a later scan.

func (*ScanManager) ForceStopCurrentScan 

func (sm *ScanManager) ForceStopCurrentScan(scanID string)

func (*ScanManager) GetActiveScanContext 

func (sm *ScanManager) GetActiveScanContext() context.Context

GetActiveScanContext returns the context for the currently running scan. Returns nil if no scan is active.

func (*ScanManager) IsCancelling 

func (sm *ScanManager) IsCancelling() bool

IsCancelling returns whether a cancellation is in progress

func (*ScanManager) ListenForCancelCommands 

func (sm *ScanManager) ListenForCancelCommands()

ListenForCancelCommands starts listening for scan control commands on the scan_control queue. This allows external systems (like the API) to cancel running scans. Uses ListenWithRetry for resilient connection handling.

func (*ScanManager) ListenForScans 

func (sm *ScanManager) ListenForScans()

ListenForScans attaches the ScanManager to the "scan" queue. Uses ListenWithRetry for resilient connection handling — if RabbitMQ is unavailable at startup or drops the connection later, the listener will automatically reconnect with exponential backoff instead of crashing.

func (*ScanManager) SetScanOptions 

func (m *ScanManager) SetScanOptions(options *ScanOptions)

SetScanOptions configures the scan options.

func (*ScanManager) Shutdown 

func (sm *ScanManager) Shutdown()

Add a cleanup method to properly shut down the worker pool

type ScanMessage 

type ScanMessage struct {
	ID            string      `json:"id"`                   // Unique identifier for this scan
	Targets       []Target    `json:"targets"`              // List of targets to scan
	Options       ScanOptions `json:"options"`              // Scan configuration options
	Priority      int         `json:"priority"`             // Scan priority (1-5)
	CallbackURL   string      `json:"callback_url"`         // Optional webhook for scan completion
	StateMode     string      `json:"state_mode,omitempty"` // "keyed" uses scan:<id>; empty retains legacy state
	ResourceScope struct {
		OwnerSubjectID string `json:"owner_subject_id,omitempty"`
	} `json:"resource_scope,omitempty"`
}

ScanMessage represents the incoming scan request message

type ScanOptions 

type ScanOptions struct {
	TemplateID   string   `json:"template_id"`   // Template ID to use for scan
	PortRange    string   `json:"port_range"`    // Port range to scan
	Aggressive   bool     `json:"aggressive"`    // Whether to use aggressive scanning
	ExcludePorts []string `json:"exclude_ports"` // Ports to exclude
	ScanTypes    []string `json:"scan_types"`    // Types of scans to perform
	MaxRetries   int      `json:"max_retries"`   // Maximum number of retries
	Parallel     bool     `json:"parallel"`      // Whether to scan targets in parallel

	// Fingerprint options (ping++ integration)
	FingerprintProbes  []string `json:"fingerprint_probes,omitempty"`  // Probe types: icmp, tcp, arp, smb
	FingerprintTimeout string   `json:"fingerprint_timeout,omitempty"` // Per-probe timeout (e.g., "3s")
	DisableICMP        bool     `json:"disable_icmp,omitempty"`        // Disable ICMP for unprivileged mode
}

ScanOptions struct for scan configuration

type ScanStrategy 

type ScanStrategy interface {
	Execute(target string) (sirius.Host, error)
	// ExecuteWithContext performs the scan with cancellation support
	ExecuteWithContext(ctx context.Context, target string) (sirius.Host, error)
}

ScanStrategy defines an interface for executing a scan on a target. The Execute method accepts a context for cancellation support.

type ScanTask 

type ScanTask struct {
	IP      string
	Options ScanOptions
	// contains filtered or unexported fields
}

ScanTask represents a single scanning task

type ScanToolFactory 

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

ScanToolFactory creates scan strategies based on the scan type.

func NewScanToolFactory 

func NewScanToolFactory() *ScanToolFactory

func (*ScanToolFactory) CreateFingerprintTool 

func (f *ScanToolFactory) CreateFingerprintTool() FingerprintStrategy

CreateFingerprintTool returns a FingerprintStrategy for host fingerprinting. This is separate from CreateTool because FingerprintStrategy has a different interface. Uses ping++ for real ICMP/TCP probing and TTL-based OS detection.

func (*ScanToolFactory) CreateTool 

func (f *ScanToolFactory) CreateTool(toolType string) ScanStrategy

CreateTool returns a ScanStrategy based on the provided scan type.

func (*ScanToolFactory) SetOptions 

func (f *ScanToolFactory) SetOptions(opts ScanOptions)

type ScanUpdater 

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

ScanUpdater serializes updates made by this scanner. Cross-process writers also need a store-level compare-and-set contract; this mutex alone is not one.

func NewScanUpdater 

func NewScanUpdater(kv store.KVStore) *ScanUpdater

func (*ScanUpdater) Update 

func (su *ScanUpdater) Update(ctx context.Context, modifier func(*store.ScanResult) error) error

Update is retained for callers without a scan identity. Scanner lifecycle operations must use UpdateForScan so late work cannot update another scan.

func (*ScanUpdater) UpdateForScan added in v1.1.0 

func (su *ScanUpdater) UpdateForScan(ctx context.Context, scanID string, modifier func(*store.ScanResult) error) error

type SourcedHostRequest 

type SourcedHostRequest struct {
	Host   sirius.Host       `json:"host"`
	Source models.ScanSource `json:"source"`
}

SourcedHostRequest represents the request structure for source-aware API submissions

type Target 

type Target struct {
	Value   string     `json:"value"`
	Type    TargetType `json:"type"`
	Timeout int        `json:"timeout,omitempty"` // Optional timeout in seconds
}

Target represents a single scan target with its configuration

type TargetType 

type TargetType string

TargetType represents the type of scan target 

const (
	SingleIP    TargetType = "single_ip"
	IPRange     TargetType = "ip_range"
	CIDR        TargetType = "cidr"
	DNSName     TargetType = "dns_name"
	DNSWildcard TargetType = "dns_wildcard"
)

type Template 

type Template struct {
	ID             string          `json:"id"`
	Name           string          `json:"name"`
	Description    string          `json:"description"`
	Type           TemplateType    `json:"type"`
	EnabledScripts []string        `json:"enabled_scripts"`
	ScanOptions    TemplateOptions `json:"scan_options"`
	CreatedAt      time.Time       `json:"created_at"`
	UpdatedAt      time.Time       `json:"updated_at"`
}

Template represents a scan configuration template

type TemplateList 

type TemplateList struct {
	Templates []string `json:"templates"`
}

TemplateList represents a list of template IDs

type TemplateManager 

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

TemplateManager manages scan templates in ValKey

func NewTemplateManager 

func NewTemplateManager(kvStore store.KVStore) *TemplateManager

NewTemplateManager creates a new TemplateManager instance

func (*TemplateManager) CreateTemplate 

func (tm *TemplateManager) CreateTemplate(ctx context.Context, template *Template) error

CreateTemplate creates a new template

func (*TemplateManager) DeleteTemplate 

func (tm *TemplateManager) DeleteTemplate(ctx context.Context, id string) error

DeleteTemplate deletes a template (only custom templates can be deleted)

func (*TemplateManager) GetTemplate 

func (tm *TemplateManager) GetTemplate(ctx context.Context, id string) (*Template, error)

GetTemplate retrieves a template by ID

func (*TemplateManager) InitializeSystemTemplates 

func (tm *TemplateManager) InitializeSystemTemplates(ctx context.Context) error

InitializeSystemTemplates creates the default system templates if they don't exist

func (*TemplateManager) ListTemplates 

func (tm *TemplateManager) ListTemplates(ctx context.Context) ([]Template, error)

ListTemplates retrieves all templates

func (*TemplateManager) ResolveScripts 

func (tm *TemplateManager) ResolveScripts(ctx context.Context, templateID string) ([]string, error)

ResolveScripts returns the list of enabled scripts for a template

func (*TemplateManager) UpdateTemplate 

func (tm *TemplateManager) UpdateTemplate(ctx context.Context, template *Template) error

UpdateTemplate updates an existing template

type TemplateOptions 

type TemplateOptions struct {
	ScanTypes    []string         `json:"scan_types"`
	PortRange    string           `json:"port_range"`
	Aggressive   bool             `json:"aggressive"`
	MaxRetries   int              `json:"max_retries"`
	Parallel     bool             `json:"parallel"`
	ExcludePorts []string         `json:"exclude_ports,omitempty"`
	AgentScan    *AgentScanConfig `json:"agent_scan,omitempty"`
}

TemplateOptions defines the scan configuration for a template

type TemplateType 

type TemplateType string

TemplateType represents whether a template is system-defined or user-created 

const (
	SystemTemplate TemplateType = "system"
	CustomTemplate TemplateType = "custom"
)

type WorkerPool 

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

WorkerPool manages a pool of scanner workers

func NewWorkerPool 

func NewWorkerPool(numWorkers int, manager *ScanManager) *WorkerPool

NewWorkerPool creates a new worker pool

func (*WorkerPool) AddTask 

func (wp *WorkerPool) AddTask(task ScanTask)

AddTask accepts only tasks already bound to a scan run.

func (*WorkerPool) Start 

func (wp *WorkerPool) Start(ctx context.Context)

Start initializes and starts the worker pool

func (*WorkerPool) Stop 

func (wp *WorkerPool) Stop()

Stop gracefully shuts down the worker pool

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.