scan

package
v0.10.0 Latest Latest
Warning

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

Go to latest
Published: Aug 6, 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.

A server-side scan runs against a throwaway unpack directory, so the raw paths are meaningless to the publisher and disclose the server's filesystem layout to anyone who can publish. Findings are also persisted in scan_result and rendered by the CLI and the review UI, so the rewrite has to happen once, at the scan site, before anything reads them.

A path that is not under root is left alone: it is not the scanner's job to invent a relationship that isn't there.

Types

type Class added in v0.10.0

type Class string

Class groups a scan finding by what kind of claim it makes. Severity says how confident the scanner is; class says whether an empirical measurement could ever overturn it.

const (
	// ClassExfiltration and ClassSecret are unappealable. No evaluation
	// overrides credential theft: a sandbox observing sixty well-behaved
	// runs does not prove the sixty-first will not post a token somewhere.
	ClassExfiltration Class = "exfiltration"
	ClassSecret       Class = "secret"

	// The rest are guesses the scanner makes from shape alone, which is
	// exactly what running the skill in a network-off sandbox measures
	// directly.
	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 scan rule category onto a Class. The bool is false for an unmapped category; callers must not substitute a default, because every plausible default is wrong in one direction or the other. Decide treats an unmapped class as Block, and TestEveryRuleHasAClass keeps that unreachable from the native rule set.

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"`

	// Class groups the finding by whether an empirical measurement could
	// overturn it. Derived from the matched rule's Category via
	// gate.ClassOf. Empty on findings deserialized from a scan_result
	// written before this field existed.
	//
	// "class" is a persisted wire name, not just a response field: it is
	// stored in the scan_result JSONB column. Renaming it would make
	// Reconsider read an empty class off every existing row, hit Decide's
	// fail-closed default, and hold those versions permanently.
	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, when set, suppresses a match if the matched text also matches this
	// pattern. Go's regexp (RE2) has no lookahead, so this is how a rule excludes
	// placeholders/references (e.g. `password = "your-password-here"`) that would
	// otherwise be false positives.
	Reject *regexp.Regexp
	// Class overrides the class derived from Category. Set it only where a rule
	// does not share its category's appealability — an RCE cradle sits in
	// exfiltration.go but is a guess a sandbox run can overturn, while a
	// reverse shell in the same file is the exfiltration channel itself.
	//
	// Every override carries a comment saying why that rule's appealability
	// differs from its category's. An override without a stated reason is a
	// review defect: nothing in the code verifies that an override is
	// correct, only that it names a class the gate recognises, so the
	// justification in the comment is the only check there is.
	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 the concatenation of every native detection rule slice. scanner.go's init iterates this (rather than assembling its own copy) so the two cannot drift, and internal/gate's TestEveryRuleHasAClass uses it to guard that every rule's Category maps to a Class.

func (Rule) ResolvedClass added in v0.10.0

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

ResolvedClass is the class a finding from this rule carries: the explicit override when the rule sets one, otherwise the class its category implies. The bool is false only when neither is available, which TestEveryRuleHasAClass keeps unreachable.

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