Documentation
¶
Overview ¶
Package engine is the core of docker-security: it defines the analysis Target, the Finding/Report model, the Module plugin interface, and the Engine that runs registered modules against a Target. Frontends (CLI, HTTP, connectors) and capability modules both depend only on this package.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine runs registered modules against a target and aggregates the results.
func (*Engine) Run ¶
Run executes matching modules against the target. If names is non-empty, only those modules are considered (still filtered by Supports); otherwise every registered module that supports the target type runs. A module returning an error is recorded in the report but does not abort the run.
type Finding ¶
type Finding struct {
RuleID string `json:"rule_id"`
Module string `json:"module"`
Severity Severity `json:"severity"`
Title string `json:"title"`
Description string `json:"description,omitempty"`
Resource string `json:"resource,omitempty"`
Location *Location `json:"location,omitempty"`
Remediation string `json:"remediation,omitempty"`
References []string `json:"references,omitempty"`
Metadata map[string]string `json:"metadata,omitempty"`
}
Finding is a single security issue reported by a module.
type Location ¶
type Location struct {
Path string `json:"path,omitempty"`
StartLine int `json:"start_line,omitempty"`
EndLine int `json:"end_line,omitempty"`
}
Location points at where in a resource a finding was detected.
type Module ¶
type Module interface {
// Name is the stable identifier used to select the module.
Name() string
// Description is a one-line human summary.
Description() string
// Domains lists the CAPABILITY_SPEC domain numbers this module addresses.
Domains() []string
// Supports reports whether the module can analyze the given target type.
Supports(TargetType) bool
// Analyze inspects the target and returns findings.
Analyze(ctx context.Context, t *Target) ([]Finding, error)
}
Module is a self-contained capability (a scanner, linter, analyzer). Modules depend only on the engine package and know nothing about CLI or HTTP.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry holds the set of available modules in registration order.
type Report ¶
type Report struct {
Tool string `json:"tool"`
TargetType TargetType `json:"target_type"`
Target string `json:"target"`
GeneratedAt time.Time `json:"generated_at"`
Findings []Finding `json:"findings"`
ModuleRuns []ModuleRun `json:"module_runs"`
}
Report is the format-agnostic result of an analysis run. Formatters render it; frontends return it. It is safe to JSON-marshal directly.
type Severity ¶
type Severity int
Severity is an ordered risk level. Higher values are more severe, so findings sort and gate naturally by numeric comparison.
func ParseSeverity ¶
ParseSeverity parses a case-insensitive severity name. Unrecognized input (including the empty string) yields SeverityUnknown.
func (Severity) MarshalJSON ¶
MarshalJSON renders severities as their string names in JSON output.
func (*Severity) UnmarshalJSON ¶
UnmarshalJSON parses a severity from its string name, so an engine.Report serialized to JSON round-trips back into the model (used by the result store and the policy engine). An unrecognized or non-string value becomes SeverityUnknown rather than erroring, keeping ingestion resilient.
type Target ¶
type Target struct {
Type TargetType `json:"type"`
// Location is a filesystem path, image reference, or container id,
// depending on Type.
Location string `json:"location"`
// Content holds inlined bytes (e.g. Dockerfile contents) when the caller
// has already loaded them. Modules should prefer Content when present.
Content []byte `json:"-"`
Metadata map[string]string `json:"metadata,omitempty"`
// contains filtered or unexported fields
}
Target is the subject of an analysis run.
func NewDockerfileTarget ¶
NewDockerfileTarget loads a Dockerfile from disk.
func (*Target) Image ¶
Image lazily loads and caches the target's *oci.Image, decompressing Location at most once regardless of how many callers invoke Image() during a scan. Every caller observes the same loaded image (and the same error, if loading failed); callers must treat the returned *oci.Image as read-only since it is shared. It is the caller's responsibility to only call Image() for an image-bearing Target (e.g. Type == TargetImage).
type TargetType ¶
type TargetType string
TargetType identifies what kind of artifact is being analyzed.
const ( TargetDockerfile TargetType = "dockerfile" TargetImage TargetType = "image" TargetFilesystem TargetType = "filesystem" TargetContainer TargetType = "container" TargetRegistry TargetType = "registry" )
func DetectType ¶
func DetectType(ref string) TargetType
DetectType makes a best-effort guess of the target type from a reference string: a Dockerfile path, an image archive/layout, some other filesystem path, or an image ref.
Source Files