scan

Documentation

Overview

Package scan implements the local detectors that ship with the CLI.

Right now: a port of workers/src/security/secrets.ts. Two-pass — provider regex (high confidence) + keyword-proximity + Shannon entropy fallback — kept independent from the server-side TS so `npx getdebug analyze . --ci` works offline with no account.

Behavioral parity with the TS implementation is enforced by secrets_test.go. When updating either, update both.

Index

• Constants
• type Finding
• type Result
  • func ScanSecrets(opts ScanOptions) (*Result, error)
• type ScanOptions

Constants

const (
	SeverityCritical = "critical"
	SeverityHigh     = "high"
	SeverityMedium   = "medium"
	SeverityLow      = "low"
	SeverityInfo     = "info"
)

Severity levels. Mirrors api/src/db/schema.ts severityEnum.

Types

type Finding

type Finding struct {
	FilePath    string `json:"filePath"`
	LineStart   int    `json:"lineStart"`
	LineEnd     int    `json:"lineEnd"`
	Category    string `json:"category"`
	Severity    string `json:"severity"`
	Title       string `json:"title"`
	Explanation string `json:"explanation"`
	ContentHash string `json:"contentHash"`
	Pattern     string `json:"pattern,omitempty"`
	Detection   string `json:"detection,omitempty"` // "regex" | "entropy"
	Snippet     string `json:"snippet,omitempty"`
	CWE         string `json:"cwe,omitempty"`
	OWASP       string `json:"owasp,omitempty"`
}

Finding is the CLI-local shape of a security finding. Maps onto the SecurityFinding type in workers/src/security/types.ts.

type Result

type Result struct {
	Findings     []Finding
	ScannedFiles int
	ScannedBytes int64
	Truncated    bool // hit MAX_TOTAL_BYTES before finishing the walk
}

Result is what ScanSecrets returns.

func ScanSecrets

func ScanSecrets(opts ScanOptions) (*Result, error)

ScanSecrets runs the two-pass secret detector across Workdir. Manually recurses with os.ReadDir per directory (rather than filepath.WalkDir) because we need the full directory listing in hand to check the database-data-dir sentinels (PG_VERSION etc.) before descending — WalkDir delivers entries individually.

type ScanOptions

type ScanOptions struct {
	// Workdir is the root to walk. Required.
	Workdir string
	// Ignore is a set of relative paths to skip (forward-slash form).
	Ignore map[string]struct{}
}

ScanOptions controls the secrets walk.