scout

package module
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Oct 22, 2026 License: MIT Imports: 29 Imported by: 0

README

Scout

Point it at your app. See every way in.

CI Go Reference Go Report Card

Scout is a self-hosted, open-source vulnerability scanner and attack-surface mapper for developers. You give it a target — a running app, a website, a repo — and it probes for weaknesses, deduplicates them into a single findings model, scores the result into a letter grade, and tells you the exact fix for each issue, ranked by how much safety each fix buys per hour of work.

It is the third tool in a family with Sentinel (runtime defense) and Pulse (observability), and shares their ergonomics: one Mount(), an embedded dashboard, and zero external services.

⚠️ Project status: pre-release (v0.x)

The engine, scoring, dashboard, CLI, scheduling, alerts, reports, integrations and optional AI are complete and tested. The security checks (collectors) that actually probe a target are not yet bundled, so a scan currently runs safely but reports no findings.

In other words: the whole product around the checks is ready, and the check interface is stable — but Scout cannot find vulnerabilities yet. This is why it is tagged v0.x, not v1.0. Do not rely on it for real security coverage until collectors ship. See CHANGELOG.md and phases.md for exactly what is and isn't present.


Install

go install github.com/MUKE-coder/scout/cmd/scout@latest

No CGo, no Node needed — the dashboard is embedded in the binary. Builds on Linux, macOS and Windows.

Quick start

Scan a website
scout scan --target https://example.com --mode safe

Safe mode is read-only. Active and intrusive modes against a remote host require ownership verification and are capped by the environment (dev > staging > prod).

Add the dashboard to a Gin app
import scout "github.com/MUKE-coder/scout"

scout.Mount(router, scout.Config{AppName: "My API"})

That one line adds, under /scout:

  • the embedded dashboard at /scout/ui/,
  • the REST API at /scout/api/,
  • the live WebSocket at /scout/ws/live,

and exposes the Gin route table to the scanner so it can flag unprotected routes before sending any traffic. See examples/gin-mount.

Run the server standalone
scout serve   # http://localhost:9090/scout/ui/  (dev login: admin / scout)
Fail CI on new findings
scout ci --repo . --fail-on high --new-only --sarif out.sarif

Exit codes: 0 passed, 1 gate failed, 2 error. See examples/ci.

How it works

  • One findings model. Every collector emits the same Finding, with a stable fingerprint so Scout tracks new / fixed / regressed across scans.
  • Trustworthy scoring. A 0–100 score and A–F grade with per-category subscores, modeled on SSL Labs: one serious flaw caps the grade. Fixes are ranked by points regained per hour of effort.
  • Safe by construction. Every check declares a mode; every environment caps the mode it will run. Scope allowlist, rate limiting, scan windows, a kill switch, a signed self-test header and ownership verification are all enforced before any active traffic.
  • Self-hosted. No hosted SaaS, no telemetry. Pure-Go SQLite for storage.

Configuration

Scout reads scout.yaml (or --config), overlaid by SCOUT_* environment variables, overlaid by flags. Every option is documented in scout.example.yaml: targets, scope, per-asset criticality, rate limits, scan windows, schedules, alerts (Slack, Discord, email, signed webhooks), the Pulse/Sentinel integrations, and optional AI.

Optional AI

With ai.enabled and an AI_GATEWAY_API_KEY, Scout can explain a finding or write a stakeholder summary through the Vercel AI Gateway (any provider/model). Findings are redacted before anything leaves the process — evidence bodies are never sent, and hosts, IPs, emails and tokens are masked — and the dashboard shows exactly what was sent. Off by default.

Documentation

Building the dashboard

ui/dist/ is committed, so consumers never need Node. To rebuild it:

cd ui/dashboard && npm ci && npm run build

License

MIT

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

View Source
const (
	DefaultRateLimit    = 10
	DefaultConcurrency  = 4
	DefaultCheckTimeout = 60 * time.Second
	DefaultRetention    = 90 * 24 * time.Hour
	DefaultUsername     = "admin"
	DefaultPassword     = "scout"
)

Defaults for a fresh Config.

View Source
const (
	BasePath = "/scout"
	APIPath  = BasePath + "/api"
	UIPath   = BasePath + "/ui"
	WSPath   = BasePath + "/ws/live"
)

URL namespace shared with Sentinel and Pulse.

View Source
const DefaultConfigFile = "scout.yaml"

DefaultConfigFile is looked for in the working directory when no --config path is given.

View Source
const DefaultPruneInterval = time.Hour

DefaultPruneInterval is how often the background pruner runs.

Variables

View Source
var ErrShutdownTimeout = errors.New("scout: shutdown timed out waiting for goroutines")

ErrShutdownTimeout is returned when goroutines outlive the shutdown deadline.

View Source
var Version = "0.0.0-dev"

Version is the Scout version. Release builds override it with -ldflags "-X github.com/MUKE-coder/scout.Version=v1.2.3".

Functions

func FindConfig

func FindConfig(explicit string) string

FindConfig returns explicit if set, else DefaultConfigFile when it exists in the working directory, else "".

func NewLogger

func NewLogger(w io.Writer, level, format string) (*slog.Logger, error)

NewLogger returns a structured logger. level is debug|info|warn|error and format is text|json.

func Prune

func Prune(ctx context.Context, store storage.Store, retention time.Duration, now time.Time) (int, error)

Prune deletes scans that finished more than retention ago and returns how many were removed.

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.

func (*AIConfig) Validate

func (a *AIConfig) Validate() error

Validate checks the AI settings.

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

func LoadConfig(path string, getenv func(string) string) (Config, error)

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 NewConfig

func NewConfig(opts ...Option) (Config, error)

NewConfig builds a config from defaults plus options, then validates it.

func (Config) EffectiveMode

func (c Config) EffectiveMode() core.Mode

EffectiveMode is the requested mode capped by the environment.

func (Config) UsesDefaultCredentials

func (c Config) UsesDefaultCredentials() bool

UsesDefaultCredentials reports whether the dashboard login is unchanged.

func (Config) Validate

func (c Config) Validate() error

Validate rejects unsafe or inconsistent configuration.

func (Config) ValidateDashboard

func (c Config) ValidateDashboard() error

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

func NewLifecycle(parent context.Context) *Lifecycle

NewLifecycle returns a lifecycle derived from parent.

func (*Lifecycle) Context

func (l *Lifecycle) Context() context.Context

Context is cancelled when shutdown begins.

func (*Lifecycle) Go

func (l *Lifecycle) Go(fn func(ctx context.Context))

Go runs fn in a tracked goroutine.

func (*Lifecycle) Shutdown

func (l *Lifecycle) Shutdown(timeout time.Duration) error

Shutdown cancels the context and waits up to timeout for goroutines to return. It is safe to call more than once.

type Option

type Option func(*Config)

Option mutates a Config.

func WithConfig

func WithConfig(c Config) Option

WithConfig replaces the whole config; later options still apply on top.

func WithDB

func WithDB(path string) Option

WithDB sets the SQLite file path.

func WithEnvironment

func WithEnvironment(e core.Environment) Option

WithEnvironment sets the environment, which caps the mode.

func WithMode

func WithMode(m core.Mode) Option

WithMode sets the requested scan mode.

func WithScope

func WithScope(s Scope) Option

WithScope sets the scope allowlist.

func WithTarget

func WithTarget(url string) Option

WithTarget adds a target URL in the current environment.

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

type ScheduleInfo struct {
	Schedule
	Next time.Time `json:"next"`
}

ScheduleInfo is a schedule with its next run, for the dashboard.

type Scope

type Scope = core.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

func Mount(r gin.IRouter, cfg Config, opts ...Option) *Scout

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.

func New

func New(cfg Config, opts ...Option) (*Scout, error)

New builds a Scout instance without mounting it.

func (*Scout) Close

func (s *Scout) Close(timeout time.Duration) error

Close stops background work and closes storage.

func (*Scout) Config

func (s *Scout) Config() Config

Config returns the effective configuration.

func (*Scout) Register

func (s *Scout) Register(r gin.IRouter)

Register adds the /scout route group to r.

func (*Scout) Store

func (s *Scout) Store() storage.Store

Store returns the backing store.

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.

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).
internal/httpx
Package httpx is the shared HTTP helper for collectors.
Package httpx is the shared HTTP helper for collectors.
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 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.

Jump to

Keyboard shortcuts

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