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
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
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.
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 ¶
ScanContent scans a single file's content and returns a completed report.
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
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.