core

package
v0.4.7 Latest Latest
Warning

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

Go to latest
Published: Oct 24, 2026 License: MIT Imports: 13 Imported by: 0

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

View Source
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

View Source
var DefaultRegistry = NewRegistry()

DefaultRegistry is where built-in collectors register their checks.

View Source
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

func Fingerprint(checkID string, asset Asset, location string) string

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

func HTTPClient(ctx context.Context) *http.Client

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

func Memo[T any](ctx context.Context, key string, fn func() (T, error)) (T, error)

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

func WithHTTPClient(ctx context.Context, c *http.Client) context.Context

WithHTTPClient attaches the scan's guarded client to ctx. The engine calls this; checks never construct their own clients.

func WithScanCache

func WithScanCache(ctx context.Context) context.Context

WithScanCache attaches a fresh cache to ctx. The engine does this per scan.

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.

func (Asset) Key

func (a Asset) Key() string

Key is a stable identity for the asset, independent of display metadata.

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.

const (
	CategoryApp Category = iota
	CategoryAPI
	CategoryAuth
	CategoryTLS
	CategoryHeaders
	CategoryExposure
	CategoryNetwork
	CategoryDNS
	CategoryHost
	CategoryCode
	CategoryConfig
)

func Categories

func Categories() []Category

Categories returns every category in declaration order.

func ParseCategory

func ParseCategory(v string) (Category, error)

func (Category) MarshalText

func (c Category) MarshalText() ([]byte, error)

func (Category) String

func (c Category) String() string

func (*Category) UnmarshalText

func (c *Category) UnmarshalText(b []byte) error

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

type CheckError struct {
	CheckID string `json:"check_id"`
	Error   string `json:"error"`
}

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) Category

func (c CheckFunc) Category() Category

func (CheckFunc) Description

func (c CheckFunc) Description() string

func (CheckFunc) ID

func (c CheckFunc) ID() string

func (CheckFunc) Mode

func (c CheckFunc) Mode() Mode

func (CheckFunc) Run

func (c CheckFunc) Run(ctx context.Context, t Target) ([]Finding, error)

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 Effort

type Effort string

Effort is the rough cost of a fix: small, medium or large.

const (
	EffortS Effort = "S"
	EffortM Effort = "M"
	EffortL Effort = "L"
)

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 Exposure

type Exposure string

Exposure is who can reach an asset.

const (
	ExposureInternet      Exposure = "internet"
	ExposureAuthenticated Exposure = "authenticated"
	ExposureInternal      Exposure = "internal"
)

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

func (f Finding) AcceptanceExpired(now time.Time) bool

AcceptanceExpired reports whether an accepted risk's expiry has passed.

func (Finding) HasTag

func (f Finding) HasTag(tag string) bool

HasTag reports whether the finding carries tag.

func (Finding) IsOpenAt

func (f Finding) IsOpenAt(now time.Time) bool

IsOpenAt reports whether the finding needs attention at time now: it is open, or it was an accepted risk whose acceptance has expired.

func (*Finding) Normalize

func (f *Finding) Normalize()

Normalize fills derived fields: the fingerprint and a default status.

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 ParseMode

func ParseMode(v string) (Mode, error)

func (Mode) MarshalText

func (m Mode) MarshalText() ([]byte, error)

func (Mode) String

func (m Mode) String() string

func (*Mode) UnmarshalText

func (m *Mode) UnmarshalText(b []byte) error

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 NewRegistry

func NewRegistry() *Registry

NewRegistry returns an empty registry.

func (*Registry) All

func (r *Registry) All() []Check

All returns every check sorted by ID, so scans and plans are deterministic.

func (*Registry) Filter

func (r *Registry) Filter(keep func(Check) bool) []Check

Filter returns the checks for which keep returns true, sorted by ID. A nil keep returns all checks.

func (*Registry) Get

func (r *Registry) Get(id string) (Check, bool)

Get returns a check by ID.

func (*Registry) Len

func (r *Registry) Len() int

Len returns the number of registered checks.

func (*Registry) MustRegister

func (r *Registry) MustRegister(c Check)

MustRegister is Register for init-time registration; it panics on error.

func (*Registry) Register

func (r *Registry) Register(c Check) error

Register adds a check. IDs must be unique and non-empty.

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

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) Allows

func (s Scope) Allows(u *url.URL) bool

Allows reports whether a URL is in scope (host and path).

func (Scope) AllowsHost

func (s Scope) AllowsHost(host string) bool

AllowsHost reports whether host (without port) is in scope.

func (Scope) AllowsPath

func (s Scope) AllowsPath(path string) bool

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.

const (
	SeverityInfo Severity = iota
	SeverityLow
	SeverityMedium
	SeverityHigh
	SeverityCritical
)

func ParseSeverity

func ParseSeverity(v string) (Severity, error)

func (Severity) MarshalText

func (s Severity) MarshalText() ([]byte, error)

func (Severity) String

func (s Severity) String() string

func (*Severity) UnmarshalText

func (s *Severity) UnmarshalText(b []byte) error

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 Status

type Status string

Status is where a finding sits in its lifecycle.

const (
	StatusOpen          Status = "open"
	StatusFixed         Status = "fixed"
	StatusAcceptedRisk  Status = "accepted-risk"
	StatusFalsePositive Status = "false-positive"
)

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.

func (Target) Host

func (t Target) Host() string

Host returns the hostname of the target URL, or "" if there is none.

func (Target) IsLocal

func (t Target) IsLocal() bool

IsLocal reports whether the target is loopback or a private address, where ownership verification is not required.

func (Target) Validate

func (t Target) Validate() error

Validate checks that the target names something scannable.

Jump to

Keyboard shortcuts

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