compose

package
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Oct 1, 2026 License: Apache-2.0 Imports: 19 Imported by: 0

Documentation

Overview

Package compose loads Docker Compose files and normalizes them into the model analyzed by StackSentry's Compose rules.

Index

Constants

View Source
const (
	MountBind   = "bind"
	MountVolume = "volume"
	MountTmpfs  = "tmpfs"
	MountNpipe  = "npipe"
)

Mount types as used by the Compose specification.

View Source
const ExtensionKey = "x-stacksentry"

ExtensionKey is the service-level extension used for documented exceptions, e.g.

x-stacksentry:
  ignore:
    - rule: SST-SEC-001
      reason: Traefik reads container labels through a socket proxy.

Variables

View Source
var DefaultFileNames = []string{"compose.yaml", "compose.yml", "docker-compose.yaml", "docker-compose.yml"}

DefaultFileNames are the file names Docker Compose looks for, in order of preference, when no file is given explicitly.

Functions

This section is empty.

Types

type Dependency

type Dependency struct {
	Service   string
	Condition string
}

Dependency is one depends_on entry.

type EnvVar

type EnvVar struct {
	Name     string
	Value    string
	HasValue bool
}

EnvVar is one entry of a service's environment section. HasValue is false for entries such as "- DEBUG" that pass a variable through from the environment Compose runs in.

type ErrorKind

type ErrorKind string

ErrorKind classifies why loading a Compose project failed.

const (
	ErrNotFound       ErrorKind = "not_found"
	ErrPermission     ErrorKind = "permission_denied"
	ErrRead           ErrorKind = "read_error"
	ErrInvalidYAML    ErrorKind = "invalid_yaml"
	ErrUnsupported    ErrorKind = "unsupported_structure"
	ErrInvalidCompose ErrorKind = "invalid_compose"
	ErrNoServices     ErrorKind = "no_services"
)

Load error kinds.

type Exposure

type Exposure int

Exposure classifies on which host interfaces a port is published.

const (
	ExposureAllInterfaces Exposure = iota
	ExposureSpecificInterface
	ExposureLoopback
)

Exposure levels.

func (Exposure) String

func (e Exposure) String() string

String describes the exposure for evidence output.

type Healthcheck

type Healthcheck struct {
	Disabled bool
}

Healthcheck is the Compose healthcheck configuration of a service.

type LoadError

type LoadError struct {
	Kind ErrorKind
	Path string
	// Detail is a human readable explanation.
	Detail string
	Err    error
}

LoadError describes a failure to load a Compose project. All load errors are user input problems and map to exit code 2.

func (*LoadError) Error

func (e *LoadError) Error() string

Error implements error.

func (*LoadError) Unwrap

func (e *LoadError) Unwrap() error

Unwrap returns the underlying error.

type Logging

type Logging struct {
	Driver  string
	Options map[string]string
}

Logging is the logging configuration of a service. An empty Driver means the Docker daemon's default driver is used.

type Mount

type Mount struct {
	Type     string
	Source   string
	Target   string
	ReadOnly bool
}

Mount is a volume, bind mount, tmpfs or named pipe attached to a service.

func (Mount) IsHostPath

func (m Mount) IsHostPath() bool

IsHostPath reports whether the mount exposes a path from the host.

func (Mount) String

func (m Mount) String() string

String renders the mount in Compose short syntax.

type Port

type Port struct {
	HostIP    string
	Published string
	Target    uint32
	Protocol  string
}

Port is a published port mapping.

func (Port) Exposure

func (p Port) Exposure() Exposure

Exposure classifies the host binding of the port.

func (Port) String

func (p Port) String() string

String renders the mapping in Compose short syntax, e.g. "127.0.0.1:5432:5432/tcp". A missing host port is shown as an empty segment, which Docker interprets as a random host port.

type Project

type Project struct {
	// Name is the Compose project name.
	Name string
	// Files are the Compose files as given by the user, in merge order.
	Files []string
	// WorkingDir is the absolute project directory.
	WorkingDir string
	// Services are sorted by name and include services gated by profiles.
	Services []Service
	// Variables are interpolation references without a default value.
	Variables []VariableRef
	// Warnings are parser messages worth surfacing to the user.
	Warnings []string
	// Limitations describe parts of the configuration that were not analyzed.
	Limitations []string
}

Project is the normalized view of one Compose project.

func Load

func Load(ctx context.Context, paths []string) (*Project, error)

Load reads one or more Compose files (merged in order, like repeated "docker compose -f" flags) and returns the normalized project. A single directory argument is resolved like Docker Compose does: the first default file name found is used, together with its override file if present.

Interpolation is deterministic: StackSentry does not read the shell environment or .env files. Variables resolve to the defaults written in the file; variables without a default resolve to an empty string and are reported by rule SST-CFG-001.

func (*Project) Service

func (p *Project) Service(name string) (*Service, bool)

Service returns the service with the given name.

func (*Project) ServiceNames

func (p *Project) ServiceNames() []string

ServiceNames returns the sorted service names.

type Service

type Service struct {
	Name string
	// File and Line locate the service definition; Line is 0 when unknown.
	File string
	Line int

	Image    string
	HasBuild bool

	Privileged   bool
	NetworkMode  string
	Networks     []string
	CapAdd       []string
	CapDrop      []string
	User         string
	ReadOnly     bool
	UseAPISocket bool

	Mounts []Mount
	Ports  []Port

	Healthcheck *Healthcheck

	Restart                string
	DeployRestartCondition string
	ContainerName          string
	StopGracePeriod        *time.Duration

	Environment []EnvVar
	EnvFiles    []string
	Command     []string
	Entrypoint  []string

	MemoryLimit int64
	CPULimit    float64
	Logging     Logging

	DependsOn []Dependency

	// Ignore maps rule IDs to the reason given in x-stacksentry.ignore.
	Ignore map[string]string
}

Service is the normalized configuration of one Compose service.

func (*Service) Env

func (s *Service) Env(name string) (EnvVar, bool)

Env returns the environment variable with the given name.

type VariableRef

type VariableRef struct {
	Name string
	// Expression is the expression as written, e.g. "${NAME}" or "$NAME".
	Expression string
	File       string
	Line       int
	// Path is the YAML path of the value, e.g. services.app.environment.URL.
	Path string
	// Service is the service the reference belongs to, if any.
	Service string
}

VariableRef is an interpolation expression such as ${NAME} that has no default value.

Jump to

Keyboard shortcuts

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