auditspec

Documentation

Overview

Package auditspec is the policy model and evaluation engine for gowdk audit.

A Policy is a named, composable set of Rules applied to targets (routes, endpoints, contracts, or the frontend surface) selected by Selectors. The built-in Baseline encodes the production-readiness gates from docs/engineering/security.md; declared *.audit.gwdk policies extend or override it. Evaluate matches the policies against a securitymanifest posture and returns registry-coded Findings; it never decides severity — that comes only from internal/diagnostics.

Index

• func SortFindings(findings []Finding)
• func Status(summary Summary) string
• type Finding
  • func Evaluate(manifest securitymanifest.SecurityManifest, policies []Policy) []Finding
• type Policy
  • func Baseline() []Policy
  • func ComposeBaseline(declared []Policy) []Policy
  • func PoliciesFromIR(specs []gwdkir.AuditSpec) []Policy
• type Rule
• type RuleKind
• type Selector
  • func ParseSelector(raw string) Selector
• type SelectorKind
• type Summary
  • func Summarize(findings []Finding) Summary

Functions

func SortFindings

func SortFindings(findings []Finding)

SortFindings orders findings deterministically by severity, code, then target.

func Status

func Status(summary Summary) string

Status reports "fail" when any error finding exists, "warning" when only warnings exist, and "ok" otherwise.

Types

type Finding

type Finding struct {
	Code        string               `json:"code"`
	Severity    diagnostics.Severity `json:"severity"`
	Target      string               `json:"target,omitempty"`
	Policy      string               `json:"policy,omitempty"`
	Rule        string               `json:"rule,omitempty"`
	Message     string               `json:"message"`
	Source      string               `json:"source,omitempty"`
	Remediation string               `json:"remediation,omitempty"`
}

Finding is one policy violation or policy-resolution error.

func Evaluate

func Evaluate(manifest securitymanifest.SecurityManifest, policies []Policy) []Finding

Evaluate matches policies against the posture manifest and returns findings. It first reports policy-resolution problems (cycles, unknown extends), then the per-target rule violations. Findings are returned in a stable order.

type Policy

type Policy struct {
	Name      string
	Extends   []string
	Selectors []Selector
	Rules     []Rule
	Source    string
	Builtin   bool
}

Policy is a named, composable set of rules applied to selected targets.

func Baseline

func Baseline() []Policy

Baseline returns the built-in policy set that gowdk audit applies with zero configuration. It encodes the production-readiness gates from docs/engineering/security.md and docs/engineering/security-threat-model.md so security is enforced by default, not by opt-in. Declared *.audit.gwdk policies extend or override these via matching selectors and rules.

Severity is never set here; each rule references a registry code and the engine resolves severity from internal/diagnostics.

func ComposeBaseline

func ComposeBaseline(declared []Policy) []Policy

ComposeBaseline returns the built-in baseline with declared policies appended. A declared policy with the same name as a built-in baseline policy replaces that built-in policy so projects can intentionally override a baseline slice.

func PoliciesFromIR

func PoliciesFromIR(specs []gwdkir.AuditSpec) []Policy

PoliciesFromIR converts parsed *.audit.gwdk specs into engine policies.

type Rule

type Rule struct {
	Kind  RuleKind
	Value string
	Code  string
}

Rule is one policy constraint. Code is the diagnostic code emitted when the rule is violated; Value carries the rule argument (a guard ID, header name, byte size, or allowlist entry) when the rule kind needs one.

type RuleKind

type RuleKind string

RuleKind classifies one policy rule.

const (
	// RuleRequireCSRF requires a matched endpoint to enforce CSRF.
	RuleRequireCSRF RuleKind = "require_csrf"
	// RuleRequireAnyGuard requires a matched target to state access (any guard,
	// including guard public) rather than be denied by omission.
	RuleRequireAnyGuard RuleKind = "require_any_guard"
	// RuleRequireGuard requires a specific guard ID (for example role:admin).
	RuleRequireGuard RuleKind = "require_guard"
	// RuleDenyPublic forbids guard public on a matched target.
	RuleDenyPublic RuleKind = "deny_public"
	// RuleMaxBody caps a matched endpoint's request body limit.
	RuleMaxBody RuleKind = "max_body"
	// RuleRequireHeader requires the app to be configured to emit a response
	// header.
	RuleRequireHeader RuleKind = "require_header"
	// RuleRequireClientRouteGuards reports client-visible routes that rely on
	// default-deny because the source declared no guard.
	RuleRequireClientRouteGuards RuleKind = "require_client_route_guards"
	// RuleNoSecretsInBundle forbids secret-shaped values in embedded output.
	RuleNoSecretsInBundle RuleKind = "no_secrets_in_bundle"
	// RuleDenyRawHTMLSinks reports every raw-HTML sink not allowlisted by a
	// RuleAllowRawHTML rule in any resolved frontend policy.
	RuleDenyRawHTMLSinks RuleKind = "deny_raw_html_sinks"
	// RuleAllowRawHTML allowlists one raw-HTML sink (source:field); every sink
	// not allowlisted is reported.
	RuleAllowRawHTML RuleKind = "allow_raw_html"
	// RuleDenyRolelessContract reports a web-exposed command or query contract
	// that declares no roles, so the data-layer authorization gate has no role to
	// admit. The contract must declare at least one role (or RoleAny to be
	// intentionally public).
	RuleDenyRolelessContract RuleKind = "deny_roleless_contract"
)

type Selector

type Selector struct {
	Raw  string
	Kind SelectorKind
}

Selector targets a set of routes, endpoints, or the frontend surface.

func ParseSelector

func ParseSelector(raw string) Selector

ParseSelector classifies a raw selector string.

type SelectorKind

type SelectorKind string

SelectorKind classifies a policy target selector.

const (
	SelectorRoute    SelectorKind = "route"
	SelectorEndpoint SelectorKind = "endpoint"
	SelectorContract SelectorKind = "contract"
	SelectorFrontend SelectorKind = "frontend"
	SelectorUnknown  SelectorKind = "unknown"
)

type Summary

type Summary struct {
	Errors   int `json:"errors"`
	Warnings int `json:"warnings"`
	Info     int `json:"info"`
}

Summary counts findings by severity.

func Summarize

func Summarize(findings []Finding) Summary

Summarize counts findings by their registry severity.