ConfigSentry (MVP)

Developer-first guardrails for docker-compose.yml (security + ops footguns).

60-second quickstart

Local (npx)

npx configsentry ./docker-compose.yml

GitHub Action (minimal)

- uses: alfredMorgenstern/[email protected]
  with:
    target: .

GitHub Code Scanning (SARIF upload)

permissions:
  contents: read
  security-events: write

- uses: alfredMorgenstern/[email protected]
  with:
    target: .
    sarif: true
    upload-sarif: true
    fail-on-findings: false

What it does

ConfigSentry reads a Compose file and flags common high-impact mistakes:

• privileged containers (privileged: true)
• dangerous capabilities (cap_add: [ALL])
• host namespaces (network_mode: host, pid: host, ipc: host)
• unconfined security profiles (security_opt: ["seccomp=unconfined"] / apparmor:unconfined)
• Docker socket mounts (/var/run/docker.sock)
• sensitive host mounts (/etc, /proc, /sys)
• sensitive ports exposed publicly (e.g. 5432:5432 instead of 127.0.0.1:5432:5432)
• missing restart: policy
• missing healthcheck:
• likely running as root (missing user:)

Designed to be CI-friendly (non-zero exit code when findings exist).

Quickstart

Run via npx

npx configsentry ./docker-compose.yml

Run from source

npm install
npm run build
node dist/cli.js --target ./docker-compose.yml

JSON output (CI / tooling)

node dist/cli.js --target ./docker-compose.yml --format json

Write JSON to a file (no shell redirection needed):

node dist/cli.js --target ./docker-compose.yml --format json --output configsentry.json

SARIF output (GitHub Code Scanning)

node dist/cli.js --target ./docker-compose.yml --format sarif --output configsentry.sarif.json

Baselines (incremental adoption)

Generate a baseline (captures current findings):

node dist/cli.js --target ./docker-compose.yml --write-baseline .configsentry-baseline.json

Then suppress baseline findings in CI:

node dist/cli.js --target ./docker-compose.yml --baseline .configsentry-baseline.json

Tip: for machine output use --format json / --format sarif.

Docs

• Proof in the wild (public repo tests): repo-tests/
• GitHub Action usage examples: docs/action-usage.md
• Baselines (incremental adoption): docs/baselines.md
• Compatibility & scope: docs/compatibility.md
• Troubleshooting / FAQ: docs/troubleshooting.md
• Launch pack (links + demo assets): docs/launch-pack.md

Footguns (short explainers)

• Docker socket mount: docs/footguns/docker-socket.md
• Exposed DB ports: docs/footguns/exposed-db-ports.md
• Risky host mounts: docs/footguns/host-mounts.md

Use in GitHub Actions (copy/paste)

More examples: docs/action-usage.md

Option A: run from source

name: Compose lint
on: [push, pull_request]

jobs:
  configsentry:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - run: npm ci
      - run: npm run build
      - run: node dist/cli.js --target ./docker-compose.yml

Option B: use the ConfigSentry composite action

name: Compose lint
on: [push, pull_request]

permissions:
  contents: read
  security-events: write   # required if upload-sarif=true (Code Scanning)

jobs:
  configsentry:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: alfredMorgenstern/[email protected]
        with:
          target: .
          # optional: baseline: .configsentry-baseline.json
          sarif: true
          upload-sarif: false

      # If you set upload-sarif: true, also ensure the workflow has:
      # permissions:
      #   security-events: write

Note (consumer repos): your repo does not need a package-lock.json. The action installs/builds ConfigSentry from the action package itself.

Tip: pin to a tag (like v0.0.25) for reproducible builds.

Exit codes

• 0 no findings
• 2 findings present
• 1 error

CI: fail only on high severity (optional)

If you want ConfigSentry to block builds only on high severity findings:

npx configsentry ./docker-compose.yml --severity-threshold high

This also works in GitHub Actions via args: (see docs/action-usage.md).

Example

node dist/cli.js --target ./example.docker-compose.yml

Feedback / ideas

• Open an issue with a sanitized minimal Compose snippet: https://github.com/alfredMorgenstern/configsentry/issues

Next steps

• GitHub Marketplace listing (Action)
• more rules (policy packs for common stacks)
• PR annotations/comments (optional)
• autofix mode (--fix) for safe transforms