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 AiAppRegexResult
  • func ScanAiAppRegex(workdir string, logf func(format string, args ...any)) (*AiAppRegexResult, error)
• type Finding
• type Result
  • func ScanSecrets(opts ScanOptions) (*Result, error)
• type SastLocalOptions
• type SastLocalResult
  • func ScanSastLocal(ctx context.Context, opts SastLocalOptions) (*SastLocalResult, 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 AiAppRegexResult

type AiAppRegexResult struct {
	Findings        []Finding
	FilesConsidered int
	FilesScanned    int
	FilesSkipped    int
	Errors          int
}

AiAppRegexResult mirrors the existing scan-pass return shapes so the CLI's analyze command can emit honest coverage numbers (files considered, scanned, errors, etc.) the same way as secrets + sastlocal.

func ScanAiAppRegex

func ScanAiAppRegex(workdir string, logf func(format string, args ...any)) (*AiAppRegexResult, error)

ScanAiAppRegex walks workdir for JS/TS/JSX/TSX files and applies both regex prefilters. Mirrors the file-walk shape secrets.go uses, with the same vendor + lockfile skips, so a clean analyze run never double-walks. Best-effort: read errors are logged via logf and the walk continues.

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 SastLocalOptions

type SastLocalOptions struct {
	Workdir string
	Client  *localllm.Client
	Model   string
	// MaxFiles caps the per-scan call count. Local 7B models on CPU run
	// 30s–5min per file; without this, a 500-file repo could pin the
	// laptop for hours. Default 50.
	MaxFiles int
	// MaxFileBytes skips oversize files (generated, vendored, lockfiles).
	// Default 96 KiB — large enough for almost every hand-written source
	// file, small enough that the model's context window isn't a problem.
	MaxFileBytes int
	// Logf is an optional progress logger (printed to stderr by the CLI).
	Logf func(format string, args ...any)
}

SastLocalOptions configures one local-SAST pass.

type SastLocalResult

type SastLocalResult struct {
	Findings        []Finding
	FilesConsidered int
	FilesScanned    int
	FilesSkipped    int // oversize / unreadable
	Malformed       int // model responses we couldn't parse
	Errors          int // transport / model errors
}

SastLocalResult summarises what the pass covered + emitted.

func ScanSastLocal

func ScanSastLocal(ctx context.Context, opts SastLocalOptions) (*SastLocalResult, error)

ScanSastLocal runs the local SAST pass over Workdir. Returns the findings alongside the coverage counters so the CLI can render an honest "scanned N of M, dropped K malformed" footer (mirroring how the hosted dashboard surfaces SAST coverage).

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.