docker

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: 18 Imported by: 0

Documentation

Overview

Package docker inspects a local Docker daemon through the official Docker Engine API client. It only uses read-only API endpoints and never changes containers, images, networks, volumes or daemon configuration.

Index

Constants

View Source
const PingTimeout = 10 * time.Second

PingTimeout bounds how long Connect waits for the daemon to answer.

View Source
const UnencryptedAPIPort = 2375

UnencryptedAPIPort is the conventional port of the unencrypted Docker API.

Variables

This section is empty.

Functions

func ListenerExposure

func ListenerExposure(address string) (loopbackOnly bool)

ListenerExposure classifies a listener address: true when it is reachable only from the local machine.

func Verify

func Verify(ctx context.Context, conn *Connection) error

Verify pings the daemon and converts failures into an UnavailableError.

Types

type API

API is the read-only subset of the Docker Engine API used by StackSentry. *client.Client satisfies it; tests provide fakes.

type Connection

type Connection struct {
	API API
	// Endpoint is the daemon address, e.g. unix:///var/run/docker.sock.
	Endpoint string
	// TLS reports whether the client was configured with TLS certificates.
	TLS bool
}

Connection is an established, verified connection to a Docker daemon.

func Connect

func Connect(ctx context.Context) (*Connection, error)

Connect creates a client from the standard Docker environment variables (DOCKER_HOST, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_TLS_VERIFY) and verifies that the daemon answers. Docker CLI contexts are not consulted.

type Container

type Container struct {
	ID      string
	Name    string
	Image   string
	State   string
	Running bool
	// Inspected is true when detailed configuration was read.
	Inspected     bool
	Privileged    bool
	NetworkMode   string
	RestartPolicy string
	AutoRemove    bool
	Mounts        []Mount
}

Container describes one container.

type Daemon

type Daemon struct {
	Version         string
	APIVersion      string
	OperatingSystem string
	OSType          string
	Architecture    string
	KernelVersion   string
	Name            string
	RootDir         string
	Rootless        bool
	Warnings        []string
}

Daemon describes the Docker daemon.

type DiskUsage

type DiskUsage struct {
	Images     UsageItem
	Containers UsageItem
	Volumes    UsageItem
	BuildCache UsageItem
}

DiskUsage summarizes Docker's disk usage by object type.

func (DiskUsage) Reclaimable

func (d DiskUsage) Reclaimable() int64

Reclaimable returns the combined reclaimable size of all object types.

func (DiskUsage) Total

func (d DiskUsage) Total() int64

Total returns the combined size of all object types.

type Image

type Image struct {
	ID   string
	Size int64
}

Image is an image summary.

type Inspector

type Inspector struct {
	Conn *Connection
	// HostFS is the host root filesystem used to read daemon configuration
	// and /proc. It may be nil, in which case those checks are skipped.
	HostFS fs.FS
	// GOOS is the operating system StackSentry runs on.
	GOOS string
}

Inspector collects a Snapshot from a Docker daemon.

func (*Inspector) Inspect

func (in *Inspector) Inspect(ctx context.Context) *Snapshot

Inspect gathers the snapshot. It is best-effort: failures of individual API calls are recorded as limitations instead of aborting the scan.

type ListenerObservation

type ListenerObservation struct {
	// Source names where the observation came from.
	Source string
	// Address is the listening address, e.g. tcp://0.0.0.0:2375.
	Address string
	// Detail adds context such as missing TLS verification.
	Detail     string
	Confidence findings.Confidence
}

ListenerObservation is evidence that the Docker API listens on TCP.

type Mount

type Mount struct {
	Type        string
	Source      string
	Destination string
	RW          bool
}

Mount is a mount point of a container.

type Snapshot

type Snapshot struct {
	Endpoint string
	Daemon   Daemon
	// Containers lists all containers, running and stopped, sorted by name.
	Containers []Container
	// ImagesTotal is the number of images reported by the daemon.
	ImagesTotal int
	// DanglingImages are untagged images not referenced by any tag.
	DanglingImages []Image
	// DiskUsage is nil when the daemon did not provide usage data.
	DiskUsage *DiskUsage
	// Listeners are observations of TCP API listeners.
	Listeners []ListenerObservation
	// Limitations describe information that could not be collected.
	Limitations []string
}

Snapshot is a read-only view of a Docker host collected for host rules.

type UnavailableError

type UnavailableError struct {
	Endpoint string
	Reason   string
	Hint     string
	Err      error
}

UnavailableError explains why the Docker daemon could not be used. It is a user-environment problem and maps to exit code 2.

func Classify

func Classify(endpoint string, err error) *UnavailableError

Classify turns a connection error into an actionable UnavailableError.

func (*UnavailableError) Error

func (e *UnavailableError) Error() string

Error implements error.

func (*UnavailableError) Unwrap

func (e *UnavailableError) Unwrap() error

Unwrap returns the underlying error.

type UsageItem

type UsageItem struct {
	Count       int64
	Size        int64
	Reclaimable int64
}

UsageItem is the usage of one object type.

Directories

Path Synopsis
Package dockertest provides an in-memory fake of the read-only Docker API used by StackSentry, for tests that must not depend on a Docker daemon.
Package dockertest provides an in-memory fake of the read-only Docker API used by StackSentry, for tests that must not depend on a Docker daemon.

Jump to

Keyboard shortcuts

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