config

Documentation

Overview

Package config loads and applies .sqlguard.yml configuration.

It is the only package that depends on a YAML library. Importing sqlguard/analyzer or sqlguard/middleware does NOT pull YAML in; only code that opts into file-based configuration through this package does. The analyzer stays parser- and config-agnostic: config translates a Config into an analyzer.Profile, which the analyzer applies once at construction.

Index

• Variables
• func Middleware(path, startDir string) ([]middleware.Option, error)
• type Config
  • func Default() *Config
  • func Discover(startDir string) (cfg *Config, path string, err error)
  • func Load(path string) (*Config, error)
  • func (c *Config) Analyzer() (*analyzer.Analyzer, error)
  • func (c *Config) DedupWindow() (d time.Duration, ok bool, err error)
  • func (c *Config) ExcludeMatcher() (func(path string) bool, error)
  • func (c *Config) MiddlewareOptions() ([]middleware.Option, error)
  • func (c *Config) Profile() (analyzer.Profile, error)
  • func (c *Config) SlowQueryThreshold() (d time.Duration, ok bool, err error)
  • func (c *Config) Warnings() []string
• type DedupConfig
• type RulesConfig
• type ScanConfig
• type SlowQueryConfig

Variables

var ConfigFileNames = []string{".sqlguard.yml", ".sqlguard.yaml"}

ConfigFileNames are the file names Discover looks for, in order.

Functions

func Middleware

func Middleware(path, startDir string) ([]middleware.Option, error)

Middleware loads configuration and returns ready-to-use middleware options. If path is non-empty it is loaded directly; otherwise config is discovered by walking up from startDir (use "." for the working directory). A missing config is not an error — it yields options equivalent to the built-in defaults.

Types

type Config

type Config struct {
	Version   int             `yaml:"version"`
	Strict    bool            `yaml:"strict"`
	Rules     RulesConfig     `yaml:"rules"`
	SlowQuery SlowQueryConfig `yaml:"slow-query"`
	Dedup     DedupConfig     `yaml:"dedup"`
	Scan      ScanConfig      `yaml:"scan"`
	// Redact controls Result.Query literal redaction. Pointer so an unset
	// key means "use the safe default" (redact). Set `redact: false` only
	// when the query text is trusted (local debugging).
	Redact *bool `yaml:"redact"`
	// contains filtered or unexported fields
}

Config mirrors the .sqlguard.yml schema. The Version field is reserved for forward compatibility: older binaries reading a newer config degrade with warnings rather than failing, unless Strict is set.

func Default

func Default() *Config

Default returns an empty configuration: every rule enabled at its default severity and settings. Used when no .sqlguard.yml is found.

func Discover

func Discover(startDir string) (cfg *Config, path string, err error)

Discover walks startDir and its parents looking for a config file. It stops at a directory containing a .git entry (project root) after checking that directory, or at the filesystem root. It returns Default() and an empty path when no config file is found.

func Load

func Load(path string) (*Config, error)

Load reads and parses the config at path. Parsing is lenient by default so a config written for a newer sqlguard still loads on an older binary; unknown top-level keys become warnings. If the file sets `strict: true`, unknown keys are a hard error instead.

func (*Config) Analyzer

func (c *Config) Analyzer() (*analyzer.Analyzer, error)

Analyzer is a convenience that builds an analyzer from the config's Profile using the fallback parser. Callers wanting a real dialect parser should take the Profile and combine with analyzer.DefaultWithProfile + WithParser themselves.

func (*Config) DedupWindow

func (c *Config) DedupWindow() (d time.Duration, ok bool, err error)

DedupWindow returns the configured static-finding dedup window. ok is false when unset, in which case the middleware keeps its own default. A configured "0" returns ok=true with d=0, which disables dedup (report every occurrence).

func (*Config) ExcludeMatcher

func (c *Config) ExcludeMatcher() (func(path string) bool, error)

ExcludeMatcher compiles Scan.ExcludePaths into a single predicate. It returns a nil func (never excludes) when no patterns are configured.

func (*Config) MiddlewareOptions

func (c *Config) MiddlewareOptions() ([]middleware.Option, error)

MiddlewareOptions translates this config into middleware options: an analyzer built from the rule Profile, and the slow-query threshold when configured. Combine with other middleware options as needed, e.g.:

opts, _ := cfg.MiddlewareOptions()
opts = append(opts, middleware.WithParser(pgparser.New()))
sqlguard.Register("sqlguard-pg", "pgx", opts...)

Keeping this in the config package (not middleware) keeps YAML out of the middleware import graph for users who do not use file configuration.

func (*Config) Profile

func (c *Config) Profile() (analyzer.Profile, error)

Profile resolves the config into an analyzer.Profile. Unknown rule names and unparseable severities are warnings (or errors if Strict). A severity of "off" disables the rule. The returned Profile is ready to pass to analyzer.DefaultWithProfile.

func (*Config) SlowQueryThreshold

func (c *Config) SlowQueryThreshold() (d time.Duration, ok bool, err error)

SlowQueryThreshold returns the configured slow-query threshold. ok is false when unset, in which case the caller keeps its own default.

func (*Config) Warnings

func (c *Config) Warnings() []string

Warnings returns non-fatal issues collected while loading or resolving the config (unknown keys in lenient mode, unknown rule names, bad severities). Callers should surface these to the user.

type DedupConfig

type DedupConfig struct {
	// Window is a Go duration string, e.g. "1m". The same finding (rule +
	// query fingerprint) is reported at most once per window. "0" disables
	// dedup (report every occurrence). Unset keeps the middleware default.
	Window string `yaml:"window"`
}

DedupConfig configures runtime suppression of repeated static findings.

type RulesConfig

type RulesConfig struct {
	// Disable turns off the named rules.
	Disable []string `yaml:"disable"`
	// Only, when non-empty, is a whitelist: only these rules run.
	Only []string `yaml:"only"`
	// Severity overrides per rule: info | warning | critical | off
	// ("off" is equivalent to disabling the rule).
	Severity map[string]string `yaml:"severity"`
	// Settings holds per-rule tunables, e.g. leading-wildcard.min-length.
	Settings map[string]map[string]any `yaml:"settings"`
}

RulesConfig configures which rules run, their severity, and per-rule settings.

type ScanConfig

type ScanConfig struct {
	// ExcludePaths is a list of regular expressions matched against scanned
	// file paths; matching files are skipped.
	ExcludePaths []string `yaml:"exclude-paths"`
}

ScanConfig holds settings that apply only to the static scanner.

type SlowQueryConfig

type SlowQueryConfig struct {
	// Threshold is a Go duration string, e.g. "200ms".
	Threshold string `yaml:"threshold"`
}

SlowQueryConfig configures the middleware slow-query threshold.