Skip to main content

Docker sidecar

Bower.Agent.Docker is a small container you add to an existing Docker or Compose stack. It reads the logs of containers you opt in, picks out security events, and forwards them to a Bower collector. The collector then redacts, validates and applies policy exactly as it does for SDK events.

labelled containers ──json-file logs──▶ bower-sidecar ──HTTPS/token──▶ bower-collector ──▶ Sentinel
(read-only) select + map redact + policy

What it forwards​

The sidecar is deliberately selective; Bower is not a log shipper.

Line in a container logResult
A Bower event envelope printed as one JSON line (schemaVersion, eventId, eventType, …)Forwarded as-is, with docker.* labels added
SSH Failed password / Failed publickey / Invalid userauthentication_failure with username and source IP
SSH maximum authentication attempts exceededaccount_lockout
PAM pam_unix(...:auth): authentication failureauthentication_failure
nginx basic auth password mismatch / was not foundauthentication_failure
Anything elseDropped at the sidecar and counted

Mapped events never contain the raw line; they carry a SHA-256 of it plus the container id, name and image. Event ids derive from container id, log file and byte offset, so replays after a restart are deduplicated by the collector.

For anything not in the table, have the application print Bower events as JSON on stdout (see ASP.NET Core integration for the event shape) — they pass straight through.

Install into an existing stack​

  1. Use the published image ghcr.io/jusso-dev/bower-sidecar (see container images), or build your own from the Bower repository root:

    docker build -f deploy/docker/Dockerfile.sidecar -t bower-sidecar:local .
    export BOWER_SIDECAR_IMAGE=bower-sidecar:local
  2. Label each container whose logs Bower should read:

    services:
    ssh-gateway:
    image: example/ssh-gateway
    labels:
    bower.collect: "true"
    bower.application: ssh-gateway # optional; defaults to the container name
    bower.environment: production # optional
  3. Merge the sidecar into your stack, pointing it at your collector:

    export BOWER_INGEST_TOKEN=<the collector's ingest token>
    export BOWER_COLLECTOR_URL=http://bower-collector:4319 # or https://collector.example.org
    docker compose -f compose.yaml -f /path/to/bower/deploy/docker/compose.sidecar.yaml up -d
  4. Check it: docker compose logs bower-sidecar prints one summary line per pass with forwarded, rejected and dropped counts. docker ps shows the health check.

Try it all locally first with the demo stack (collector, sidecar, a labelled "legacy" container and an unlabelled one that is ignored):

export BOWER_INGEST_TOKEN="$(dotnet run --project src/Bower.Cli -- token generate)"
docker compose -f deploy/docker/compose.sidecar-demo.yaml up --build

Configuration​

VariableDefaultPurpose
BOWER_COLLECTOR_URLhttp://bower-collector:4319Collector base URL. With a token, plain HTTP is allowed only for loopback or a single-label Compose service name.
BOWER_INGEST_TOKEN / BOWER_INGEST_TOKEN_FILE—Collector ingest token.
BOWER_DOCKER_LABELbower.collectOpt-in label (value must be true).
BOWER_DOCKER_READ_EXISTINGfalsetrue replays existing log history the first time a container is seen.
BOWER_POLL_SECONDS5Poll interval (1–600). Backs off up to 2 minutes under backpressure.
BOWER_SIDECAR_IDhost nameIdentifies the sidecar on forwarded events.
BOWER_ENVIRONMENTproductionDefault application.environment when the container has no label.
BOWER_DOCKER_ROOT/var/lib/docker/containersMounted Docker container directory.
BOWER_SIDECAR_STATE/var/lib/bower-sidecar/cursors.dbDurable cursors (keep on a volume).

Delivery guarantees​

  • At least once. The cursor for each container advances only past lines the collector accepted (200/202), definitively refused (400/413/422), or the sidecar intentionally dropped. On 429, 503, 5xx, 401/403 or a network error it stops, keeps its position and backs off.
  • Restarts. Cursors live in SQLite on the bower-sidecar-state volume, so a restarted sidecar resumes where it stopped.
  • Rotation. Files are identified by their first bytes, so Docker's max-size/max-file rotation is detected; the rotated file is drained before the new one. If a log rotates more than once between passes, the gap is logged.
  • Bounds. Lines over 64 KiB are counted and skipped; each pass reads at most 1,000 lines or 4 MiB per container. Docker's 16 KiB partial chunks are reassembled. A line that is over 64 KiB, or whose chunks fill a whole pass's byte budget without ending, is never buffered: its chunks are consumed and committed as they are read, across passes and restarts, and the line is counted as oversized once when its final chunk arrives. Later lines are then read normally.

Cursor format​

Each container's cursor is JSON in the state database: {"schemaVersion":1,"fingerprint":"<sha256 of first 64 bytes>","offset":<bytes>}. While an oversized line is being skipped the cursor also carries "discarding":true, meaning offset is the next physical chunk of that line. The field is additive and omitted when false, so cursors written before it existed read unchanged and normal cursors serialise byte-for-byte as before. It holds no line content. Truncation or a missed rotation clears it; a rotation the sidecar drains carries it into the new file, so the rest of a line split by rotation is still skipped. Downgrading is not recommended while a line is being skipped: an older sidecar ignores the field and reads the rest of that line as if it were a new line.

Security model​

  • No Docker socket. The sidecar reads /var/lib/docker/containers mounted read-only. It cannot list, start, stop or exec containers.
  • Non-root. The process runs as uid 1654 on a chiseled image (no shell, no setuid binaries) with a read-only root filesystem and every capability dropped except DAC_READ_SEARCH, which only bypasses read and directory-traverse checks. Docker's container directory is root-only (0710, metadata 0600), so that one capability is required to list containers and read their labels.
  • Why no-new-privileges is off. Docker never grants added capabilities to a non-root user directly; the sidecar binary carries cap_dac_read_search as a file capability instead, and no-new-privileges blocks file capabilities. With nothing else in the image able to gain privileges, the effective result is one read-only capability. Without cap_add: DAC_READ_SEARCH the binary refuses to start (operation not permitted).
  • Opt-in only. Containers without bower.collect=true are never read.
  • Token handling. The ingest token is sent only as a bearer header and is never logged.

Limitations​

  • Requires the json-file logging driver (Docker's default). Containers using local, journald, syslog or other drivers are skipped and counted.
  • Docker Desktop and OrbStack keep container logs inside their Linux VM; the bind mount works when the daemon resolves /var/lib/docker/containers inside that VM (verified on Docker 29 with the demo stack).
  • Rootless Docker and user-namespace remapping store logs elsewhere; set BOWER_DOCKER_ROOT accordingly.
  • Kubernetes Pod Security "restricted" disallows DAC_READ_SEARCH; the sidecar targets Docker and Compose hosts.