Documentation
¶
Overview ¶
Package core defines the shared types every part of Scout speaks: the unified Finding model, checks, modes, categories, targets and scan results.
Index ¶
- Constants
- Variables
- func Fingerprint(checkID string, asset Asset, location string) string
- func HTTPClient(ctx context.Context) *http.Client
- func Memo[T any](ctx context.Context, key string, fn func() (T, error)) (T, error)
- func Register(c Check)
- func WithHTTPClient(ctx context.Context, c *http.Client) context.Context
- func WithScanCache(ctx context.Context) context.Context
- type Asset
- type AssetKind
- type Category
- type Check
- type CheckError
- type CheckFunc
- type Confidence
- type Describer
- type Effort
- type Environment
- type Evidence
- type Exposure
- type Finding
- type Fix
- type Identity
- type Mode
- type Registry
- type Remediation
- type Route
- type ScanCache
- type ScanResult
- type Scope
- type Severity
- type SkippedCheck
- type StackComponent
- type StandardsMapper
- type Status
- type Target
Constants ¶
const ( // TagExpiredCert marks an expired TLS certificate (caps the grade at D). TagExpiredCert = "expired-cert" // TagExposedSecret marks a leaked credential or key (caps the grade at D // when the asset is internet-facing). TagExposedSecret = "exposed-secret" )
Finding tags with scoring meaning.
Variables ¶
var DefaultRegistry = NewRegistry()
DefaultRegistry is where built-in collectors register their checks.
var ErrNoGuardedClient = errors.New("scout: no guarded HTTP client in context; requests must go through the engine")
ErrNoGuardedClient is returned for requests made outside a scan, where no guarded client is attached to the context.
Functions ¶
func Fingerprint ¶
Fingerprint returns the stable identity of a finding: checkID + asset + location. It deliberately ignores evidence, severity and timestamps so the same issue keeps the same fingerprint across scans.
func HTTPClient ¶
HTTPClient returns the guarded client for this scan. Checks must use it for every outbound request: it enforces scope, rate limits, scan windows and the kill switch, and signs requests as Scout self-tests.
Outside a scan it returns a client that refuses every request, so a check can never send unguarded traffic by accident.
func Memo ¶
Memo returns the cached value for key, computing it with fn exactly once per scan even when called concurrently. Without a cache in ctx, fn runs every time.
func Register ¶
func Register(c Check)
Register adds a check to DefaultRegistry, panicking on a duplicate ID. Collectors call it from init().
func WithHTTPClient ¶
WithHTTPClient attaches the scan's guarded client to ctx. The engine calls this; checks never construct their own clients.
Types ¶
type Asset ¶
type Asset struct {
Kind AssetKind `json:"kind"`
Value string `json:"value"` // canonical display form: "example.com", "10.0.0.1:6379", "GET /api/users/:id", "main.go:42"
Host string `json:"host,omitempty"`
Port int `json:"port,omitempty"`
Method string `json:"method,omitempty"`
Path string `json:"path,omitempty"`
File string `json:"file,omitempty"`
Line int `json:"line,omitempty"`
Exposure Exposure `json:"exposure,omitempty"`
// Criticality scales risk for this asset (payments API 1.5, marketing
// site 0.7). Zero means the default of 1.0.
Criticality float64 `json:"criticality,omitempty"`
}
Asset is the thing a finding is about.
type AssetKind ¶
type AssetKind string
AssetKind says what kind of thing an Asset is.
const ( AssetDomain AssetKind = "domain" AssetHost AssetKind = "host" // host:port AssetURL AssetKind = "url" // a page or endpoint AssetRoute AssetKind = "route" // METHOD /path from a route table AssetFile AssetKind = "file" // file:line in a repo AssetContainer AssetKind = "container" // container or image )
type Category ¶
type Category int
Category groups checks and drives per-category subscores.
func Categories ¶
func Categories() []Category
Categories returns every category in declaration order.
func ParseCategory ¶
func (Category) MarshalText ¶
func (*Category) UnmarshalText ¶
type Check ¶
type Check interface {
// ID is stable and namespaced: "tls.weak-protocols", "app.sqli".
ID() string
Category() Category
// Mode is the most aggressive mode this check uses.
Mode() Mode
Run(ctx context.Context, t Target) ([]Finding, error)
}
Check is one pluggable security test. Collectors implement it and register into a Registry; the engine selects checks whose Mode fits the environment.
type CheckError ¶
CheckError records a check that failed or panicked.
type CheckFunc ¶
type CheckFunc struct {
CheckID string
CheckCategory Category
CheckMode Mode
Desc string
Fn func(ctx context.Context, t Target) ([]Finding, error)
}
CheckFunc adapts a plain function into a Check. Handy for small native checks and tests.
func (CheckFunc) Description ¶
type Confidence ¶
type Confidence int
Confidence is how sure Scout is that a finding is real.
const ( ConfidencePossible Confidence = iota ConfidenceLikely ConfidenceConfirmed )
func ParseConfidence ¶
func ParseConfidence(v string) (Confidence, error)
func (Confidence) MarshalText ¶
func (c Confidence) MarshalText() ([]byte, error)
func (Confidence) String ¶
func (c Confidence) String() string
func (*Confidence) UnmarshalText ¶
func (c *Confidence) UnmarshalText(b []byte) error
type Describer ¶
type Describer interface {
Description() string
}
Describer is optionally implemented by checks to explain themselves in plan (dry-run) output and the dashboard.
type Environment ¶
type Environment string
Environment is where a target runs. It caps the scan mode.
const ( EnvDev Environment = "dev" EnvStaging Environment = "staging" EnvProd Environment = "prod" )
func ParseEnvironment ¶
func ParseEnvironment(v string) (Environment, error)
ParseEnvironment validates an environment name.
func (Environment) Cap ¶
func (e Environment) Cap(optIn bool) Mode
Cap is the most aggressive mode an environment permits. optIn is the explicit per-target opt-in (Target.AllowActive):
dev Intrusive staging Active (Intrusive with opt-in) prod Safe (Active with opt-in; never Intrusive)
func (Environment) MaxMode ¶
func (e Environment) MaxMode() Mode
MaxMode is the most aggressive mode an environment permits without any per-target opt-in.
type Evidence ¶
type Evidence struct {
Request string `json:"request,omitempty"` // raw HTTP request
Response string `json:"response,omitempty"` // raw HTTP response (possibly truncated)
Matched string `json:"matched,omitempty"` // the payload or pattern that matched
ConfigLine string `json:"config_line,omitempty"` // offending config or source line
Notes string `json:"notes,omitempty"`
Redacted bool `json:"redacted,omitempty"`
}
Evidence is what Scout saw that made it raise a finding.
type Finding ¶
type Finding struct {
Fingerprint string `json:"fingerprint"`
CheckID string `json:"check_id"`
Title string `json:"title"`
Category Category `json:"category"`
Severity Severity `json:"severity"`
CVSS float64 `json:"cvss,omitempty"`
Confidence Confidence `json:"confidence"`
Asset Asset `json:"asset"`
// Location distinguishes several findings from one check on one asset,
// such as a cookie name or a form parameter.
Location string `json:"location,omitempty"`
Evidence Evidence `json:"evidence"`
CWE []string `json:"cwe,omitempty"`
OWASP []string `json:"owasp,omitempty"`
Remediation Remediation `json:"remediation"`
// Tags mark findings that scoring treats specially, such as TagExpiredCert.
Tags []string `json:"tags,omitempty"`
Status Status `json:"status"`
// StatusReason explains an accepted-risk or false-positive decision, or
// notes that an acceptance expired.
StatusReason string `json:"status_reason,omitempty"`
// StatusUntil is when an accepted risk expires and the finding counts
// again. Nil means no expiry.
StatusUntil *time.Time `json:"status_until,omitempty"`
// StatusBy is who made the decision.
StatusBy string `json:"status_by,omitempty"`
FirstSeen time.Time `json:"first_seen"`
LastSeen time.Time `json:"last_seen"`
}
Finding is the single shape every collector emits. It is what makes dedupe, diffs, scoring and the dashboard possible.
func (Finding) AcceptanceExpired ¶
AcceptanceExpired reports whether an accepted risk's expiry has passed.
type Fix ¶
type Fix struct {
Stack string `json:"stack"` // "gin", "nginx", "caddy", "nextjs", "dockerfile", "sentinel", "generic"
Language string `json:"language"` // syntax hint for the code viewer: "go", "nginx", "yaml"...
Code string `json:"code"`
Note string `json:"note,omitempty"`
}
Fix is one stack-specific way to remediate a finding.
type Identity ¶ added in v0.3.1
type Identity struct {
Name string `json:"name" yaml:"name"`
Headers map[string]string `json:"headers,omitempty" yaml:"headers"`
Owns []string `json:"owns,omitempty" yaml:"owns"`
}
Identity is a disposable test account the access-control checks use to probe authorization boundaries. It is never a real user. Headers carry whatever authenticates it (e.g. "Authorization: Bearer ...", "Cookie: session=..."), which the checks attach to requests they make as this identity. Owns lists private resources (absolute URLs, or paths resolved against the target URL) that this identity legitimately owns; the IDOR check asks whether a *different* identity can read them. Every probe using these is read-only.
type Mode ¶
type Mode int
Mode is how aggressive a check is. Every check declares the most aggressive mode it uses; every environment caps the mode it will run.
const ( // ModePassive reads headers, TLS, DNS, config and route tables. No attack traffic. ModePassive Mode = iota // ModeSafe sends harmless probes: canaries, GET-only fuzzing, version checks. ModeSafe // ModeActive sends real injection payloads and auth-bypass attempts. ModeActive // ModeIntrusive brute forces, load tests and sends state-changing requests. ModeIntrusive )
func (Mode) MarshalText ¶
func (*Mode) UnmarshalText ¶
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry holds the checks available to a scan. It is safe for concurrent use.
func (*Registry) Filter ¶
Filter returns the checks for which keep returns true, sorted by ID. A nil keep returns all checks.
func (*Registry) MustRegister ¶
MustRegister is Register for init-time registration; it panics on error.
type Remediation ¶
type Remediation struct {
What string `json:"what"` // plain-language description
Why string `json:"why"` // realistic attack scenario
How []Fix `json:"how,omitempty"` // stack-specific fixes
Effort Effort `json:"effort"` // S | M | L
References []string `json:"references,omitempty"`
}
Remediation is the deterministic fix guidance attached to a finding.
type Route ¶
type Route struct {
Method string `json:"method"`
Path string `json:"path"`
Handler string `json:"handler,omitempty"`
Middleware []string `json:"middleware,omitempty"`
// Public marks a route that is unauthenticated by design (sign-in, health,
// webhook receivers, OAuth callbacks). The missing-auth check skips it rather
// than reporting the absence of the auth it was told not to expect.
Public bool `json:"public,omitempty"`
}
Route is one entry of an app's route table, as exported by scout.Mount.
type ScanCache ¶
type ScanCache struct {
// contains filtered or unexported fields
}
ScanCache memoizes expensive lookups (page fetches, TLS handshakes, DNS) within one scan so checks that need the same data share a single request.
type ScanResult ¶
type ScanResult struct {
ID string `json:"id"`
Target Target `json:"target"`
Mode Mode `json:"mode"`
StartedAt time.Time `json:"started_at"`
FinishedAt time.Time `json:"finished_at"`
Findings []Finding `json:"findings"`
Skipped []SkippedCheck `json:"skipped,omitempty"`
Errors []CheckError `json:"errors,omitempty"`
Score float64 `json:"score"`
Grade string `json:"grade"`
// Assessed lists the categories of the checks that ran; the score only
// covers these.
Assessed []Category `json:"assessed,omitempty"`
}
ScanResult is the outcome of one scan.
type Scope ¶
type Scope struct {
// Hosts are exact hostnames ("api.example.com") or wildcard subdomains
// ("*.example.com", which does not match the apex "example.com").
Hosts []string `json:"hosts,omitempty" yaml:"hosts"`
// IncludePaths are path prefixes; empty means every path on allowed hosts.
IncludePaths []string `json:"include_paths,omitempty" yaml:"include_paths"`
// ExcludePaths are path prefixes that are never touched. They win over includes.
ExcludePaths []string `json:"exclude_paths,omitempty" yaml:"exclude_paths"`
}
Scope is the allowlist of what a scan may touch. Scout never widens it implicitly: the engine fills an empty Hosts list with the target's own host.
func (Scope) AllowsHost ¶
AllowsHost reports whether host (without port) is in scope.
func (Scope) AllowsPath ¶
AllowsPath reports whether a URL path is in scope.
type Severity ¶
type Severity int
Severity is how bad a finding is. Ordered so that a larger value is worse.
func ParseSeverity ¶
func (Severity) MarshalText ¶
func (*Severity) UnmarshalText ¶
type SkippedCheck ¶
type SkippedCheck struct {
CheckID string `json:"check_id"`
Mode Mode `json:"mode"`
Reason string `json:"reason"`
}
SkippedCheck records a check the engine chose not to run, and why.
type StackComponent ¶ added in v0.4.0
type StackComponent struct {
Kind string `json:"kind"` // language | framework | runtime | server | package-manager
Name string `json:"name"` // e.g. "Next.js", "Django", "Go"
Version string `json:"version,omitempty"` // when known
Source string `json:"source,omitempty"` // how it was detected (e.g. "package.json", "Server header")
}
StackComponent is one detected part of a target's technology stack.
type StandardsMapper ¶
type StandardsMapper interface {
// OWASP returns OWASP Top 10 2021 IDs, e.g. "A05:2021".
OWASP() []string
// ASVS returns ASVS 4.0.3 requirement or chapter IDs, e.g. "V14.4.1".
ASVS() []string
}
StandardsMapper is optionally implemented by checks to declare which standards requirements they test, for the compliance coverage view.
type Target ¶
type Target struct {
Name string `json:"name" yaml:"name"`
// URL is the base URL for black-box scanning ("https://example.com").
URL string `json:"url,omitempty" yaml:"url"`
// Repo is a local path for code and supply-chain collectors.
Repo string `json:"repo,omitempty" yaml:"repo"`
Environment Environment `json:"environment" yaml:"environment"`
// AllowActive is the explicit per-target opt-in required for Active
// mode in prod and Intrusive mode in staging.
AllowActive bool `json:"allow_active,omitempty" yaml:"allow_active"`
// Criticality is the default asset criticality for findings on this target.
Criticality float64 `json:"criticality,omitempty" yaml:"criticality"`
// Routes is the real route table when the app uses scout.Mount.
Routes []Route `json:"routes,omitempty" yaml:"-"`
// Identities are disposable test accounts for access-control checks
// (e.g. IDOR). Never real users. Set via scout.WithTestIdentities or the
// config file; empty disables the identity-dependent checks for this
// target. Not serialized in scan results (may carry credentials).
Identities []Identity `json:"-" yaml:"identities"`
// Stack is the languages, frameworks and runtimes detected on this target
// during a scan (filled by the engine). It drives stack-aware checks and
// the dashboard's "Stack" view.
Stack []StackComponent `json:"stack,omitempty" yaml:"-"`
}
Target is something Scout scans: a URL, a host, a repo, or all three.