Documentation
¶
Overview ¶
Package scout is a self-hosted vulnerability scanner and attack-surface mapper. Point it at your app. See every way in.
The simplest integration is one line in a Gin app:
scout.Mount(router, scout.Config{AppName: "My API"})
Index ¶
- Constants
- Variables
- func FindConfig(explicit string) string
- func NewLogger(w io.Writer, level, format string) (*slog.Logger, error)
- func Prune(ctx context.Context, store storage.Store, retention time.Duration, ...) (int, error)
- type AIConfig
- type AlertsConfig
- type Config
- type IntegrationsConfig
- type Lifecycle
- type Option
- func WithConfig(c Config) Option
- func WithDB(path string) Option
- func WithEnvironment(e core.Environment) Option
- func WithMode(m core.Mode) Option
- func WithRoutes(routes ...core.Route) Option
- func WithScope(s Scope) Option
- func WithTarget(url string) Option
- func WithTestIdentities(ids ...core.Identity) Option
- type ScanWindow
- type Schedule
- type ScheduleInfo
- type Scope
- type Scout
- type SiblingConfig
Constants ¶
const ( DefaultRateLimit = 10 DefaultConcurrency = 4 DefaultCheckTimeout = 60 * time.Second DefaultRetention = 90 * 24 * time.Hour DefaultUsername = "admin" DefaultPassword = "scout" )
Defaults for a fresh Config.
const ( BasePath = "/scout" APIPath = BasePath + "/api" UIPath = BasePath + "/ui" WSPath = BasePath + "/ws/live" )
URL namespace shared with Sentinel and Pulse.
const DefaultConfigFile = "scout.yaml"
DefaultConfigFile is looked for in the working directory when no --config path is given.
const DefaultPruneInterval = time.Hour
DefaultPruneInterval is how often the background pruner runs.
Variables ¶
var ErrShutdownTimeout = errors.New("scout: shutdown timed out waiting for goroutines")
ErrShutdownTimeout is returned when goroutines outlive the shutdown deadline.
var Version = resolveVersion()
Version is the Scout version, resolved once at startup. Resolution order:
- the release ldflags stamp (buildVersion), when present;
- the module version recorded in the binary by `go install module@vX`;
- a dev marker for a local checkout build.
Functions ¶
func FindConfig ¶
FindConfig returns explicit if set, else DefaultConfigFile when it exists in the working directory, else "".
Types ¶
type AIConfig ¶
type AIConfig struct {
Enabled bool `json:"enabled" yaml:"enabled"`
// Model is any AI Gateway model ID, e.g. "anthropic/claude-sonnet-5.5".
Model string `json:"model,omitempty" yaml:"model"`
// BaseURL overrides the Gateway endpoint (OpenAI-compatible).
BaseURL string `json:"base_url,omitempty" yaml:"base_url"`
}
AIConfig enables optional AI explanations through the Vercel AI Gateway. The API key is read only from the AI_GATEWAY_API_KEY environment variable so it never lands in scout.yaml.
type AlertsConfig ¶
type AlertsConfig struct {
// MinSeverity is the lowest severity that alerts (default high).
MinSeverity string `json:"min_severity,omitempty" yaml:"min_severity"`
// DashboardURL is linked from every alert.
DashboardURL string `json:"dashboard_url,omitempty" yaml:"dashboard_url"`
Slack *alerts.Slack `json:"-" yaml:"slack"`
Discord *alerts.Discord `json:"-" yaml:"discord"`
Email *alerts.Email `json:"-" yaml:"email"`
Webhooks []alerts.Webhook `json:"-" yaml:"webhooks"`
}
AlertsConfig configures notifications for new or regressed findings.
func (*AlertsConfig) Validate ¶
func (a *AlertsConfig) Validate() error
Validate checks every configured channel.
type Config ¶
type Config struct {
AppName string `json:"app_name" yaml:"app_name"`
Environment core.Environment `json:"environment" yaml:"environment"`
// Mode is the requested mode. It is always capped by the environment.
Mode core.Mode `json:"mode" yaml:"mode"`
Targets []core.Target `json:"targets,omitempty" yaml:"targets"`
// Routes is the app's route table, handed to the scanner by scout.Mount
// (via gin introspection or WithRoutes). It is attached to configured
// targets that have none, so the route-table checks (unprotected routes)
// run with no attack traffic. Set programmatically, not from YAML.
Routes []core.Route `json:"-" yaml:"-"`
// Identities are disposable test accounts for access-control checks such
// as IDOR. They are attached to configured targets that declare none.
// Never real users; carried into scans but never written to results.
Identities []core.Identity `json:"-" yaml:"identities"`
Scope Scope `json:"scope" yaml:"scope"`
// Criticality weights findings by asset (payments API 1.5, marketing
// site 0.7). First matching rule wins.
Criticality []scoring.CriticalityRule `json:"criticality,omitempty" yaml:"criticality"`
// RateLimit is the max outbound requests per second per target.
RateLimit int `json:"rate_limit" yaml:"rate_limit"`
// Concurrency is the number of checks run in parallel.
Concurrency int `json:"concurrency" yaml:"concurrency"`
// CheckTimeout bounds a single check run.
CheckTimeout time.Duration `json:"check_timeout" yaml:"check_timeout"`
// DBPath is the SQLite file. Empty uses in-memory storage only.
DBPath string `json:"db_path" yaml:"db"`
// Retention is how long scan history is kept.
Retention time.Duration `json:"retention" yaml:"retention"`
// Window restricts when scans may run; nil allows any time.
Window *ScanWindow `json:"window,omitempty" yaml:"window"`
// Schedules run scans automatically while Scout is serving.
Schedules []Schedule `json:"schedules,omitempty" yaml:"schedules"`
// Alerts notify about new or regressed findings after each saved scan.
Alerts *AlertsConfig `json:"alerts,omitempty" yaml:"alerts"`
// AI enables optional, redacted AI explanations (off by default).
AI *AIConfig `json:"ai,omitempty" yaml:"ai"`
// Integrations links optional Pulse and Sentinel instances.
Integrations *IntegrationsConfig `json:"integrations,omitempty" yaml:"integrations"`
// SigningKey signs the X-Scout-Scan self-test header. Generated if empty.
SigningKey string `json:"-" yaml:"signing_key"`
// Dashboard credentials. Defaults are refused outside dev.
Username string `json:"-" yaml:"username"`
Password string `json:"-" yaml:"password"`
JWTSecret string `json:"-" yaml:"jwt_secret"`
}
Config is the full Scout configuration. Build it directly or with options.
func DefaultConfig ¶
func DefaultConfig() Config
DefaultConfig returns a dev-safe config: dev environment, Safe mode.
func LoadConfig ¶
LoadConfig builds a Config from defaults, then the YAML file at path (if path is non-empty), then SCOUT_* environment variables read with getenv. Callers apply command-line flags last. The file is decoded strictly: an unknown key is an error, so a typo cannot silently disable a setting.
func (Config) EffectiveMode ¶
EffectiveMode is the requested mode capped by the environment.
func (Config) UsesDefaultCredentials ¶
UsesDefaultCredentials reports whether the dashboard login is unchanged.
func (Config) ValidateDashboard ¶
ValidateDashboard adds the checks needed before serving the dashboard: default credentials are refused outside dev.
type IntegrationsConfig ¶
type IntegrationsConfig struct {
Pulse *SiblingConfig `json:"pulse,omitempty" yaml:"pulse"`
Sentinel *SiblingConfig `json:"sentinel,omitempty" yaml:"sentinel"`
}
IntegrationsConfig configures the optional Pulse and Sentinel links.
func (*IntegrationsConfig) Validate ¶
func (c *IntegrationsConfig) Validate() error
Validate checks the integration URLs.
type Lifecycle ¶
type Lifecycle struct {
// contains filtered or unexported fields
}
Lifecycle owns Scout's background goroutines. Every goroutine is started through Go and receives a context that is cancelled on Shutdown, which then waits for all of them to return.
func NewLifecycle ¶
NewLifecycle returns a lifecycle derived from parent.
type Option ¶
type Option func(*Config)
Option mutates a Config.
func WithConfig ¶
WithConfig replaces the whole config; later options still apply on top.
func WithEnvironment ¶
func WithEnvironment(e core.Environment) Option
WithEnvironment sets the environment, which caps the mode.
func WithRoutes ¶ added in v0.3.1
WithRoutes hands Scout the app's route table. Prefer this when your framework knows each route's authorization middleware (roles, permissions): it is strictly richer than what gin introspection can recover, and the "route has no auth middleware" check depends on the Middleware field.
scout.Mount(r, cfg, scout.WithRoutes(myRouteTable...))
func WithTarget ¶
WithTarget adds a target URL in the current environment.
func WithTestIdentities ¶ added in v0.3.1
WithTestIdentities registers disposable test accounts for the access-control checks (IDOR and future identity-dependent probes). Each identity carries the headers that authenticate it and the private resources it owns; the checks are read-only and never use real user credentials.
scout.WithTestIdentities(
core.Identity{Name: "alice", Headers: map[string]string{"Cookie": "session=a"}, Owns: []string{"/api/users/1"}},
core.Identity{Name: "bob", Headers: map[string]string{"Cookie": "session=b"}, Owns: []string{"/api/users/2"}},
)
type ScanWindow ¶
type ScanWindow struct {
Start string `json:"start" yaml:"start"` // "HH:MM"
End string `json:"end" yaml:"end"` // "HH:MM"; before Start wraps past midnight
Days []string `json:"days,omitempty" yaml:"days"`
Timezone string `json:"timezone,omitempty" yaml:"timezone"` // IANA name; empty is local time
}
ScanWindow is the config-file form of a daily scan window.
func (*ScanWindow) EngineWindow ¶
func (w *ScanWindow) EngineWindow() (*engine.Window, error)
EngineWindow converts the window for the engine. A nil window is nil.
type Schedule ¶
type Schedule struct {
Name string `json:"name" yaml:"name"`
// Cron is a standard 5-field expression ("0 3 * * *") or a descriptor
// such as "@daily".
Cron string `json:"cron" yaml:"cron"`
// Timezone is an IANA name; empty means local time.
Timezone string `json:"timezone,omitempty" yaml:"timezone"`
// Targets are target names; empty means every configured target.
Targets []string `json:"targets,omitempty" yaml:"targets"`
// Mode caps this schedule (default safe). The environment caps it further.
Mode string `json:"mode,omitempty" yaml:"mode"`
}
Schedule runs scans on a cron schedule.
type ScheduleInfo ¶
ScheduleInfo is a schedule with its next run, for the dashboard.
type Scope ¶
Scope limits what a scan may touch. Empty Hosts means "only the target's own host"; Scout never widens scope implicitly.
type Scout ¶
type Scout struct {
// contains filtered or unexported fields
}
Scout is a mounted Scout instance.
func Mount ¶
Mount attaches Scout to a Gin router under /scout and returns the instance. It is the one-line integration:
scout.Mount(router, scout.Config{AppName: "My API"})
Mount panics on invalid configuration, matching Sentinel and Pulse; use New + Register when you want the error instead.
type SiblingConfig ¶
type SiblingConfig struct {
URL string `json:"url,omitempty" yaml:"url"`
Path string `json:"path,omitempty" yaml:"path"`
}
SiblingConfig points Scout at a Pulse or Sentinel instance. Tokens come from the environment (SCOUT_PULSE_TOKEN, SCOUT_SENTINEL_TOKEN), not the file.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package ai adds optional AI explanations through the Vercel AI Gateway's OpenAI-compatible API.
|
Package ai adds optional AI explanations through the Vercel AI Gateway's OpenAI-compatible API. |
|
Package alerts notifies Slack, Discord, email and webhooks when a scan finds new or regressed findings at or above a severity threshold.
|
Package alerts notifies Slack, Discord, email and webhooks when a scan finds new or regressed findings at or above a severity threshold. |
|
Package api serves the Scout REST API under /scout/api/ and the live WebSocket at /scout/ws/live.
|
Package api serves the Scout REST API under /scout/api/ and the live WebSocket at /scout/ws/live. |
|
Package cli implements the scout command-line interface.
|
Package cli implements the scout command-line interface. |
|
cmd
|
|
|
scout
command
Command scout is the Scout CLI.
|
Command scout is the Scout CLI. |
|
Package collectors holds Scout's check collectors (external, headers, exposure, ports, DNS, nuclei, DAST, host, code).
|
Package collectors holds Scout's check collectors (external, headers, exposure, ports, DNS, nuclei, DAST, host, code). |
|
all
Package all blank-imports every built-in collector so their init() functions register their checks into core.DefaultRegistry.
|
Package all blank-imports every built-in collector so their init() functions register their checks into core.DefaultRegistry. |
|
authz
Package authz holds the authentication and access-control checks.
|
Package authz holds the authentication and access-control checks. |
|
clientside
Package clientside flags client-side integrity problems in a page's HTML: cross-origin scripts and stylesheets loaded without Subresource Integrity, and mixed content (an HTTPS page pulling resources over plain HTTP).
|
Package clientside flags client-side integrity problems in a page's HTML: cross-origin scripts and stylesheets loaded without Subresource Integrity, and mixed content (an HTTPS page pulling resources over plain HTTP). |
|
codeaudit
Package codeaudit is a light static analyzer (SAST-lite) over a target's source tree (Target.Repo).
|
Package codeaudit is a light static analyzer (SAST-lite) over a target's source tree (Target.Repo). |
|
config
Package config checks configuration posture: framework debug mode left on, shipped default credentials, and misconfigured sibling tools (Sentinel, Pulse) such as monitor-only WAF or in-memory storage in production.
|
Package config checks configuration posture: framework debug mode left on, shipped default credentials, and misconfigured sibling tools (Sentinel, Pulse) such as monitor-only WAF or in-memory storage in production. |
|
crawl
Package crawl spiders a target from its base URL to discover pages, forms and API endpoints, and flags state-changing forms that carry no CSRF token.
|
Package crawl spiders a target from its base URL to discover pages, forms and API endpoints, and flags state-changing forms that carry no CSRF token. |
|
dast
Package dast holds the active application-testing checks (injection and related classes).
|
Package dast holds the active application-testing checks (injection and related classes). |
|
dns
Package dns checks a target domain's DNS posture: email anti-spoofing records (SPF, DKIM, DMARC), certificate-issuance control (CAA), and dangling / takeover-prone CNAMEs.
|
Package dns checks a target domain's DNS posture: email anti-spoofing records (SPF, DKIM, DMARC), certificate-issuance control (CAA), and dangling / takeover-prone CNAMEs. |
|
dockerfile
Package dockerfile lints Dockerfiles in a target's source tree for common security misconfigurations: running as root, unpinned base images, remote ADD, and secrets baked into ENV/ARG.
|
Package dockerfile lints Dockerfiles in a target's source tree for common security misconfigurations: running as root, unpinned base images, remote ADD, and secrets baked into ENV/ARG. |
|
exposure
Package exposure checks for sensitive files and endpoints that should never be reachable: dotfiles, VCS metadata, API docs, metrics, backups, directory listings and admin dashboards.
|
Package exposure checks for sensitive files and endpoints that should never be reachable: dotfiles, VCS metadata, API docs, metrics, backups, directory listings and admin dashboards. |
|
fingerprint
Package fingerprint flags information that helps an attacker fingerprint the stack: software/version banners in response headers, and directory listings (autoindex) that enumerate files.
|
Package fingerprint flags information that helps an attacker fingerprint the stack: software/version banners in response headers, and directory listings (autoindex) that enumerate files. |
|
headers
Package headers checks HTTP security-hardening headers.
|
Package headers checks HTTP security-hardening headers. |
|
infodisc
Package infodisc flags information disclosure: verbose error pages / stack traces that leak internals, and GraphQL schema introspection left enabled.
|
Package infodisc flags information disclosure: verbose error pages / stack traces that leak internals, and GraphQL schema introspection left enabled. |
|
internal/httpx
Package httpx is the shared HTTP helper for collectors.
|
Package httpx is the shared HTTP helper for collectors. |
|
internal/repo
Package repo is a shared helper for collectors that read a target's source tree (Target.Repo).
|
Package repo is a shared helper for collectors that read a target's source tree (Target.Repo). |
|
ports
Package ports detects risky back-end services that are reachable on the target's own host — exposed databases, caches, container APIs and remote shells that are usually meant to stay private.
|
Package ports detects risky back-end services that are reachable on the target's own host — exposed databases, caches, container APIs and remote shells that are usually meant to stay private. |
|
sca
Package sca performs Software Composition Analysis: it inventories a repo's dependencies across every major ecosystem (from lockfiles/manifests) and matches them against known vulnerabilities via the intel layer (OSV.dev, which aggregates NVD, GitHub Advisories, RustSec, PyPA, the Go vuln DB …).
|
Package sca performs Software Composition Analysis: it inventories a repo's dependencies across every major ecosystem (from lockfiles/manifests) and matches them against known vulnerabilities via the intel layer (OSV.dev, which aggregates NVD, GitHub Advisories, RustSec, PyPA, the Go vuln DB …). |
|
secrets
Package secrets scans a target's source tree (Target.Repo) for credentials that should never be committed: cloud keys, private keys, tokens and obvious password/secret assignments.
|
Package secrets scans a target's source tree (Target.Repo) for credentials that should never be committed: cloud keys, private keys, tokens and obvious password/secret assignments. |
|
tls
Package tls checks a target's TLS configuration: protocol versions, cipher strength, certificate validity and expiry, chain, and HSTS preload eligibility.
|
Package tls checks a target's TLS configuration: protocol versions, cipher strength, certificate validity and expiry, chain, and HSTS preload eligibility. |
|
vulncheck
Package vulncheck finds known, reachable vulnerabilities in a Go module's dependencies by running govulncheck over the target's repository (Target.Repo).
|
Package vulncheck finds known, reachable vulnerabilities in a Go module's dependencies by running govulncheck over the target's repository (Target.Repo). |
|
Package core defines the shared types every part of Scout speaks: the unified Finding model, checks, modes, categories, targets and scan results.
|
Package core defines the shared types every part of Scout speaks: the unified Finding model, checks, modes, categories, targets and scan results. |
|
Package engine runs scans: it selects checks permitted by the environment's mode cap, executes them against in-scope targets and streams findings.
|
Package engine runs scans: it selects checks permitted by the environment's mode cap, executes them against in-scope targets and streams findings. |
|
examples
|
|
|
gin-mount
command
Command gin-mount is a minimal Gin application that mounts Scout with one line.
|
Command gin-mount is a minimal Gin application that mounts Scout with one line. |
|
Package integrations connects Scout to its sibling tools, Pulse (observability) and Sentinel (runtime defense).
|
Package integrations connects Scout to its sibling tools, Pulse (observability) and Sentinel (runtime defense). |
|
Package intel provides vulnerability intelligence: it matches a software bill of materials (packages + versions) against known-vulnerability databases.
|
Package intel provides vulnerability intelligence: it matches a software bill of materials (packages + versions) against known-vulnerability databases. |
|
stack
Package stack detects a target's technology stack — languages, frameworks, runtimes — from a repo's manifests and from a running app's fingerprint findings.
|
Package stack detects a target's technology stack — languages, frameworks, runtimes — from a repo's manifests and from a running app's fingerprint findings. |
|
Package remediation renders deterministic, stack-specific fix guidance for findings.
|
Package remediation renders deterministic, stack-specific fix guidance for findings. |
|
Package report renders scan results: a terminal report, JSON, SARIF and diffs between scans.
|
Package report renders scan results: a terminal report, JSON, SARIF and diffs between scans. |
|
Package scoring turns findings into a 0-100 score, a letter grade, per-category subscores and the "fix next" ranking.
|
Package scoring turns findings into a 0-100 score, a letter grade, per-category subscores and the "fix next" ranking. |
|
Package selftest signs and verifies the X-Scout-Scan header that Scout puts on every outbound scan request.
|
Package selftest signs and verifies the X-Scout-Scan header that Scout puts on every outbound scan request. |
|
Package storage persists scans and findings.
|
Package storage persists scans and findings. |
|
Package ui embeds the built dashboard (ui/dist) so consumers never need Node.
|
Package ui embeds the built dashboard (ui/dist) so consumers never need Node. |