scan

package
v0.21.1 Latest Latest
Warning

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

Go to latest
Published: Nov 10, 2026 License: Apache-2.0 Imports: 15 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Finalize added in v0.7.0

func Finalize(report *Report)

Finalize dedupes the report's findings and recomputes its summary and status. Call it after merging in findings from an external scanner so the publish block-on-status logic sees the combined result.

func MergeExternal added in v0.7.0

func MergeExternal(ctx context.Context, ext *ExternalScanner, dir string, report *Report)

MergeExternal runs the (optional) external scanner over dir and merges its findings into report, recomputing status. It is best-effort: if the scanner is unset it is a no-op, and if it fails it logs a warning and leaves the native report untouched — an optional external tool must never block a publish because it is missing or misconfigured.

func Relativize added in v0.10.0

func Relativize(report *Report, root string)

Relativize rewrites every finding's File to a path relative to root, so a server-side scan does not leak the host's filesystem layout.

Types

type Class added in v0.10.0

type Class string

Class groups a finding by whether an empirical measurement could overturn it.

const (
	// Unappealable: no evaluation overrides credential theft.
	ClassExfiltration Class = "exfiltration"
	ClassSecret       Class = "secret"

	// Appealable: shape-based guesses a sandbox can verify.
	ClassExecution Class = "execution"
	ClassInjection Class = "injection"
	ClassHeuristic Class = "heuristic"
)

func ClassOf added in v0.10.0

func ClassOf(category string) (Class, bool)

ClassOf maps a rule category onto a Class. False for an unmapped category; Decide treats unmapped as Block.

type ExternalScanner added in v0.7.0

type ExternalScanner struct {
	// Name namespaces the rule IDs in merged findings.
	Name string
	// Command is the argv to execute; the token "{dir}" is replaced with the
	// skill directory. The command must emit SARIF JSON on stdout.
	Command []string
	// Timeout bounds a single scan; defaults to 60s when zero.
	Timeout time.Duration
}

ExternalScanner is an opt-in, operator-configured external security scanner (Phase 2, SDD external.go). skael shells out to a free/OSS tool — e.g. gitleaks, Cisco skill-scanner, or Semgrep with operator-authored rules — runs it over the already-unpacked skill directory, and merges its SARIF output into the native report. Nothing is bundled: the operator installs the tool, so skael's licensing stays clean (subprocess only, no linking).

Findings are namespaced (e.g. "gitleaks:generic-api-key") and merged via Finalize so the same critical/warn → block-on-publish logic applies. If the tool is missing or errors, the caller logs and continues on the native scanner alone — an optional external must never hard-block a publish.

func NewExternalScanner added in v0.7.0

func NewExternalScanner(cmdline string, timeout time.Duration) *ExternalScanner

NewExternalScanner builds a scanner from a whitespace-separated command line, or returns nil when cmdline is empty (feature disabled). The first token is used as the scanner Name when it has no explicit name.

func (*ExternalScanner) Run added in v0.7.0

func (e *ExternalScanner) Run(ctx context.Context, dir string) ([]Finding, error)

Run executes the external scanner over dir and returns the parsed findings.

type Finding

type Finding struct {
	Rule       string `json:"rule"`
	Severity   string `json:"severity"`   // critical, high, medium, info
	Confidence string `json:"confidence"` // high, medium, low
	File       string `json:"file"`
	Line       int    `json:"line"`
	Match      string `json:"match"`
	Message    string `json:"message"`

	// Persisted wire name in scan_result JSONB; do not rename.
	Class string `json:"class,omitempty"`
}

Finding describes a single matched security rule.

type Report

type Report struct {
	Status   string    `json:"status"` // clean, info, warn, critical
	Findings []Finding `json:"findings"`
	Summary  Summary   `json:"summary"`
}

Report is the result of scanning a skill archive or content for security issues.

func ScanContent

func ScanContent(filename, content string) *Report

ScanContent scans a single file's content and returns a completed report.

func ScanDir

func ScanDir(dir string) (*Report, error)

ScanDir walks a directory tree, scans each file, and returns an aggregated report. Binary files and files larger than maxScanBytes are not fully scanned but are surfaced as informational findings rather than skipped silently.

type Rule

type Rule struct {
	Name       string
	Category   string
	Severity   string
	Confidence string
	Pattern    *regexp.Regexp
	Message    string
	// Reject suppresses a match when the text also matches this. RE2 has no
	// lookahead, so this is how a rule excludes placeholders.
	Reject *regexp.Regexp
	// Class overrides the class derived from Category. Every override must
	// carry a comment saying why, because nothing else verifies correctness.
	Class Class
}

Rule defines a single security detection rule with its pattern and metadata.

func AllRules added in v0.10.0

func AllRules() []Rule

AllRules returns every native detection rule.

func (Rule) ResolvedClass added in v0.10.0

func (r Rule) ResolvedClass() (Class, bool)

ResolvedClass returns the rule's explicit Class override, or its category's.

type Summary

type Summary struct {
	Critical int `json:"critical"`
	High     int `json:"high"`
	Medium   int `json:"medium"`
	Info     int `json:"info"`
}

Summary aggregates finding counts by severity.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL