Documentation
¶
Overview ¶
Package analyzer orchestrates the individual security analysis modules (rbac, podsec, network, admission, secrets, serviceaccount, privesc), runs them in parallel against a snapshot, filters by severity threshold, and returns a sorted finding list.
Package analyzer — module factory registry.
DefaultModules is the canonical, ordered list of constructors for every built-in analyzer module the engine knows about. The engine ranges over this slice (rather than hard-coding the module slice in NewWithConfig) so:
- new modules land by appending one factory entry here, not by editing the engine's construction site.
- the slice index defines the deterministic registration order, so we don't depend on Go's init() ordering for golden-test stability.
- parallel Wave 1 worktrees can add a stub module without conflicting on engine.go (the file each new analyzer owns is its own package, plus a one-line append to this slice).
Each factory receives the engine Config so per-module tuning (e.g. the privesc MaxDepth knob) stays inside the factory closure.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var DefaultModules = []func(cfg Config) Module{ func(_ Config) Module { return rbac.New() }, func(_ Config) Module { return podsec.New() }, func(_ Config) Module { return network.New() }, func(_ Config) Module { return admission.New() }, func(_ Config) Module { return secrets.New() }, func(_ Config) Module { return serviceaccount.New() }, func(cfg Config) Module { m := privesc.New() if cfg.MaxPrivescDepth > 0 { m.MaxDepth = cfg.MaxPrivescDepth } return m }, func(_ Config) Module { return leastprivilege.New(nil) }, func(_ Config) Module { return containersec.New() }, func(cfg Config) Module { return celmod.New(cfg.CustomRulesDir) }, }
DefaultModules lists every built-in module factory in the order the engine registers them. Adding a new analyzer requires (a) creating the package, (b) appending its factory here, (c) registering preset / glossary / e2e wiring in the relevant extension points (internal/exclusions/config.go, internal/report/glossary.go, testdata/e2e/expectations/<name>.expect).
The leastprivilege module is constructed with nil UsageIndex here; the engine rebinds it per-call from Options.UsageIndex in selectModules so the same engine instance can serve runs with and without audit data. See engine.go.
Functions ¶
This section is empty.
Types ¶
type AdmissionMode ¶
type AdmissionMode string
AdmissionMode controls how the engine reacts when a finding's underlying workload would be rejected by Pod Security Admission in its namespace. The default is suppress, which drops the finding from the output and counts it on the AdmissionSummary so the report header can surface "N findings suppressed by admission controls."
const ( // AdmissionModeOff disables admission-aware reweighting; findings are emitted // exactly as the analyzer modules produced them. AdmissionModeOff AdmissionMode = "off" // AdmissionModeAttenuate downweights findings (Score *= scoring.AdmissionMitigationFactor, // Severity drops one bucket via scoring.SeverityForScore) and tags them with // admission:mitigated-psa-<level>. Use when every residual risk must remain visible. AdmissionModeAttenuate AdmissionMode = "attenuate" // AdmissionModeSuppress drops findings that admission would block from the output. // The default. Counts are still surfaced via AdmissionSummary so the noise // reduction is auditable. AdmissionModeSuppress AdmissionMode = "suppress" )
func ParseAdmissionMode ¶
func ParseAdmissionMode(value string) (AdmissionMode, bool)
ParseAdmissionMode normalizes user input. Empty input maps to the default (suppress).
type AnalyzeResult ¶
type AnalyzeResult struct {
Findings []models.Finding
Admission models.AdmissionSummary
}
AnalyzeResult is the engine output. Findings is the post-correlate, post-dedupe, post-threshold-filter, sorted slice the report layer renders. Admission carries the metadata produced by applyAdmissionMitigations so the report can surface "X findings suppressed by admission controls."
type Config ¶
type Config struct {
MaxPrivescDepth int
// CustomRulesDir is the directory the CEL-based "custom-rules" module loads
// *.cel.yaml files from. Empty means "skip loading"; the module remains
// registered but evaluates to zero findings, keeping the JSON / HTML output
// byte-identical to a build that never received the flag.
CustomRulesDir string
}
Config tunes engine construction parameters like the privesc graph search depth.
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine holds the set of registered analysis modules to run.
func NewWithConfig ¶
NewWithConfig constructs an Engine with the default module set, applying cfg to tunable modules. The leastprivilege module is registered with a nil UsageIndex here; Analyze rebinds it from opts.UsageIndex on each invocation so the same engine can serve runs with and without audit data.
The module set comes from DefaultModules in modules.go — adding a new analyzer requires appending one factory entry there, not editing this constructor.
func (*Engine) Analyze ¶
func (e *Engine) Analyze(ctx context.Context, snapshot models.Snapshot, opts Options) (AnalyzeResult, error)
Analyze runs the selected modules in parallel, applies admission-aware reweighting, correlates and dedupes the results, filters at or above the severity threshold, and returns them sorted by severity then score along with an AdmissionSummary describing what the reweight stage did.
The pipeline is broken into four named stages below so a first-time reader can follow the data flow: snapshot → selected modules → raw findings → reweighted/correlated/ deduped findings → sorted slice ready for the report writer.
type Module ¶
type Module interface {
Name() string
Analyze(ctx context.Context, snapshot models.Snapshot) ([]models.Finding, error)
}
Module is the contract each analysis module implements.
type Options ¶
type Options struct {
OnlyModules []string
SkipModules []string
Threshold models.Severity
MaxPrivescDepth int
// AdmissionMode controls the admission-aware reweight stage. Empty defaults to suppress.
AdmissionMode AdmissionMode
// UsageIndex carries the audit-log observations consumed by the leastprivilege
// module. nil disables the module (it emits nothing); the CLI pre-flight in
// scan.go errors out before we get here when --least-privilege-only is set
// without --audit-log.
UsageIndex *usage.UsageIndex
}
Options selects which modules run, sets a severity floor, tunes privesc path depth, chooses how the engine reacts to namespace-level admission controls, and threads the audit-log-derived usage index into the leastprivilege module.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package admission analyzes Validating/MutatingWebhookConfigurations for common weaknesses like fail-open security webhooks, bypassable selectors, and exemptions that skip sensitive namespaces.
|
Package admission analyzes Validating/MutatingWebhookConfigurations for common weaknesses like fail-open security webhooks, bypassable selectors, and exemptions that skip sensitive namespaces. |
|
mitigation
Package mitigation maps kubesplaining pod-security findings to the cluster admission controls that would block their workload at admission time.
|
Package mitigation maps kubesplaining pod-security findings to the cluster admission controls that would block their workload at admission time. |
|
Package cel wires the user-supplied CEL rules loader/evaluator (in internal/rules/cel) into the analyzer engine's module set.
|
Package cel wires the user-supplied CEL rules loader/evaluator (in internal/rules/cel) into the analyzer engine's module set. |
|
Content for container-security findings.
|
Content for container-security findings. |
|
Package leastprivilege flags RBAC grants that look broader than the subject's actual usage.
|
Package leastprivilege flags RBAC grants that look broader than the subject's actual usage. |
|
Package network analyzes NetworkPolicy coverage and permissiveness so that unprotected namespaces, uncovered workloads, and overly-broad policies surface as findings.
|
Package network analyzes NetworkPolicy coverage and permissiveness so that unprotected namespaces, uncovered workloads, and overly-broad policies surface as findings. |
|
Package podsec analyzes pod specs (and their controlling workloads) for container-runtime security issues like privileged containers, host namespace sharing, sensitive hostPath mounts, and insecure image tags.
|
Package podsec analyzes pod specs (and their controlling workloads) for container-runtime security issues like privileged containers, host namespace sharing, sensitive hostPath mounts, and insecure image tags. |
|
Package privesc builds a privilege-escalation graph from the snapshot and searches for paths that reach sensitive sinks like cluster-admin, kube-system secrets, or node escape, turning each viable path into a Finding.
|
Package privesc builds a privilege-escalation graph from the snapshot and searches for paths that reach sensitive sinks like cluster-admin, kube-system secrets, or node escape, turning each viable path into a Finding. |
|
Package rbac analyzes Role/ClusterRole bindings and flags subjects whose effective permissions enable privilege escalation or data exfiltration.
|
Package rbac analyzes Role/ClusterRole bindings and flags subjects whose effective permissions enable privilege escalation or data exfiltration. |
|
Package secrets analyzes Secret metadata and ConfigMap contents for hygiene issues such as legacy service-account tokens, sensitive kube-system data, credential-like keys leaked into ConfigMaps, and risky CoreDNS rules.
|
Package secrets analyzes Secret metadata and ConfigMap contents for hygiene issues such as legacy service-account tokens, sensitive kube-system data, credential-like keys leaked into ConfigMaps, and risky CoreDNS rules. |
|
Package serviceaccount joins RBAC permissions with workload usage to flag ServiceAccounts that are actively mounted by pods and carry dangerous rights.
|
Package serviceaccount joins RBAC permissions with workload usage to flag ServiceAccounts that are actively mounted by pods and carry dangerous rights. |