configsentry 0.0.9

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marius Morgenstern
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,126 @@
+# ConfigSentry (MVP)
+
+Developer-first guardrails for **docker-compose.yml** (security + ops footguns).
+
+## What it does
+ConfigSentry reads a Compose file and flags common **high-impact** mistakes:
+- privileged containers (`privileged: true`)
+- Docker socket mounts (`/var/run/docker.sock`)
+- 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 (after npm publish)
+
+```bash
+npx configsentry ./docker-compose.yml
+```
+
+### Run from source
+
+```bash
+npm install
+npm run build
+node dist/cli.js ./docker-compose.yml
+```
+
+### JSON output (CI / tooling)
+
+```bash
+node dist/cli.js ./docker-compose.yml --json
+```
+
+### SARIF output (GitHub Code Scanning)
+
+```bash
+node dist/cli.js ./docker-compose.yml --sarif > configsentry.sarif.json
+```
+
+## Baselines (incremental adoption)
+
+Generate a baseline (captures current findings):
+
+```bash
+node dist/cli.js ./docker-compose.yml --write-baseline .configsentry-baseline.json
+```
+
+Then suppress baseline findings in CI:
+
+```bash
+node dist/cli.js ./docker-compose.yml --baseline .configsentry-baseline.json
+```
+
+## Use in GitHub Actions (copy/paste)
+
+More examples: [`docs/action-usage.md`](docs/action-usage.md)
+
+### Option A: run from source
+
+```yml
+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 ./docker-compose.yml
+```
+
+### Option B: use the ConfigSentry composite action
+
+```yml
+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/configsentry@v0.0.9
+        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
+```
+
+> Tip: pin to a tag (like `v0.0.8`) for reproducible builds.
+
+## Exit codes
+- `0` no findings
+- `2` findings present
+- `1` error
+
+## Example
+
+```bash
+node dist/cli.js ./example.docker-compose.yml
+```
+
+## Next steps
+- publish as `configsentry` on npm
+- GitHub Action wrapper
+- SARIF output
+- autofix mode (`--fix`) for safe transforms

package/dist/baseline.js

@@ -0,0 +1,50 @@
+import fs from 'node:fs/promises';
+import crypto from 'node:crypto';
+export function fingerprintFinding(f) {
+    const h = crypto.createHash('sha256');
+    // Keep stable + minimal; avoid messages that could change wording.
+    h.update(String(f.id));
+    h.update('\n');
+    h.update(String(f.service ?? ''));
+    h.update('\n');
+    h.update(String(f.path ?? ''));
+    return h.digest('hex');
+}
+export async function writeBaseline(path, findings) {
+    const entries = findings.map((f) => ({
+        fingerprint: fingerprintFinding(f),
+        id: f.id,
+        service: f.service,
+        path: f.path,
+    }));
+    const file = {
+        version: 1,
+        generatedAt: new Date().toISOString(),
+        tool: 'ConfigSentry',
+        entries,
+    };
+    await fs.writeFile(path, JSON.stringify(file, null, 2) + '\n', 'utf8');
+}
+export async function loadBaseline(path) {
+    const raw = await fs.readFile(path, 'utf8');
+    const json = JSON.parse(raw);
+    const entries = Array.isArray(json?.entries) ? json.entries : [];
+    const set = new Set();
+    for (const e of entries) {
+        if (typeof e?.fingerprint === 'string')
+            set.add(e.fingerprint);
+    }
+    return set;
+}
+export function applyBaseline(findings, baselineFingerprints) {
+    const kept = [];
+    const suppressed = [];
+    for (const f of findings) {
+        const fp = fingerprintFinding(f);
+        if (baselineFingerprints.has(fp))
+            suppressed.push(f);
+        else
+            kept.push(f);
+    }
+    return { kept, suppressed };
+}

package/dist/baseline.test.js

@@ -0,0 +1,12 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { fingerprintFinding, applyBaseline } from './baseline.js';
+test('baseline suppression works', () => {
+    const f1 = { id: 'r1', title: 't', severity: 'low', message: 'm', service: 'svc', path: '/tmp/x#p' };
+    const f2 = { id: 'r2', title: 't', severity: 'low', message: 'm', service: 'svc', path: '/tmp/x#p2' };
+    const set = new Set([fingerprintFinding(f1)]);
+    const { kept, suppressed } = applyBaseline([f1, f2], set);
+    assert.equal(kept.length, 1);
+    assert.equal(suppressed.length, 1);
+    assert.equal(kept[0].id, 'r2');
+});

package/dist/cli.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import process from 'node:process';
+import fs from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { loadCompose } from './compose.js';
+import { runRules } from './rules.js';
+import { findingsToSarif } from './sarif.js';
+import { resolveTargets } from './scan.js';
+import { applyBaseline, loadBaseline, writeBaseline } from './baseline.js';
+function usage() {
+    console.log(`ConfigSentry (MVP)\n\nUsage:\n  configsentry <file-or-dir> [--json|--sarif] [--baseline <file>] [--write-baseline <file>]\n\nOutput:\n  --json           machine-readable findings\n  --sarif          SARIF 2.1.0 (for GitHub code scanning)\n\nBaselines:\n  --baseline <file>        suppress findings present in a baseline file\n  --write-baseline <file>  write baseline file for current findings and exit 0\n\nExit codes:\n  0 = no findings (after baseline suppression)
+  2 = findings present
+  1 = error
+`);
+}
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.includes('-v') || args.includes('--version')) {
+        try {
+            const here = path.dirname(fileURLToPath(import.meta.url));
+            const pkgPath = path.resolve(here, '../package.json');
+            const raw = await fs.readFile(pkgPath, 'utf8');
+            const pkg = JSON.parse(raw);
+            console.log(pkg.version || 'unknown');
+        }
+        catch {
+            console.log('unknown');
+        }
+        process.exit(0);
+    }
+    if (args.length === 0 || args.includes('-h') || args.includes('--help')) {
+        usage();
+        process.exit(0);
+    }
+    const json = args.includes('--json');
+    const sarif = args.includes('--sarif');
+    if (json && sarif) {
+        console.error('Error: choose only one output mode: --json or --sarif');
+        process.exit(1);
+    }
+    const baselineIdx = args.indexOf('--baseline');
+    const baselinePath = baselineIdx >= 0 ? args[baselineIdx + 1] : undefined;
+    const writeBaselineIdx = args.indexOf('--write-baseline');
+    const writeBaselinePath = writeBaselineIdx >= 0 ? args[writeBaselineIdx + 1] : undefined;
+    const target = args.find((a) => !a.startsWith('-'));
+    if (!target) {
+        usage();
+        process.exit(1);
+    }
+    const targetPaths = await resolveTargets(target);
+    if (targetPaths.length === 0) {
+        console.error(`No compose files found in: ${target}`);
+        process.exit(1);
+    }
+    let allFindings = [];
+    for (const targetPath of targetPaths) {
+        const { compose } = await loadCompose(targetPath);
+        allFindings = allFindings.concat(runRules(compose, targetPath));
+    }
+    // Baseline suppression
+    let suppressed = [];
+    let findings = allFindings;
+    if (baselinePath) {
+        const set = await loadBaseline(path.resolve(baselinePath));
+        const res = applyBaseline(allFindings, set);
+        findings = res.kept;
+        suppressed = res.suppressed;
+    }
+    // Baseline generation mode
+    if (writeBaselinePath) {
+        await writeBaseline(path.resolve(writeBaselinePath), allFindings);
+        console.log(`Wrote baseline: ${path.resolve(writeBaselinePath)} (${allFindings.length} finding(s))`);
+        process.exit(0);
+    }
+    if (json) {
+        console.log(JSON.stringify({ targetPaths, findings, suppressedCount: suppressed.length }, null, 2));
+    }
+    else if (sarif) {
+        console.log(JSON.stringify(findingsToSarif(findings), null, 2));
+    }
+    else {
+        const scope = targetPaths.length === 1 ? targetPaths[0] : `${targetPaths.length} file(s)`;
+        if (findings.length === 0) {
+            console.log(`✅ No findings for ${scope}`);
+            if (suppressed.length > 0) {
+                console.log(`(suppressed by baseline: ${suppressed.length})`);
+            }
+        }
+        else {
+            console.log(`❌ ${findings.length} finding(s) for ${scope}`);
+            if (suppressed.length > 0) {
+                console.log(`(suppressed by baseline: ${suppressed.length})`);
+            }
+            console.log('');
+            for (const f of findings) {
+                console.log(`[${f.severity.toUpperCase()}] ${f.title}`);
+                console.log(`- service: ${f.service ?? '-'}
+- rule: ${f.id}
+- where: ${f.path ?? '-'}
+- msg: ${f.message}`);
+                if (f.suggestion)
+                    console.log(`- fix: ${f.suggestion}`);
+                console.log('');
+            }
+        }
+    }
+    process.exit(findings.length === 0 ? 0 : 2);
+}
+main().catch((err) => {
+    console.error('Error:', err);
+    process.exit(1);
+});

package/dist/compose.js

@@ -0,0 +1,12 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import YAML from 'yaml';
+export async function loadCompose(filePath) {
+    const abs = path.resolve(filePath);
+    const text = await fs.readFile(abs, 'utf8');
+    // Support multi-document YAML (---). If multiple docs exist, Compose content is typically the first.
+    const docs = YAML.parseAllDocuments(text);
+    const first = docs[0];
+    const doc = first ? first.toJSON() : YAML.parse(text);
+    return { compose: doc, raw: doc };
+}

package/dist/rules.js

@@ -0,0 +1,142 @@
+const SENSITIVE_PORTS = new Set([5432, 3306, 6379, 27017, 9200]);
+function normalizePorts(ports) {
+    if (!Array.isArray(ports))
+        return [];
+    const res = [];
+    for (const p of ports) {
+        if (typeof p === 'number') {
+            res.push({ containerPort: p, raw: String(p) });
+            continue;
+        }
+        if (typeof p !== 'string')
+            continue;
+        // patterns:
+        // "8080:80"
+        // "127.0.0.1:8080:80"
+        // "5432:5432"
+        const parts = p.split(':');
+        if (parts.length === 2) {
+            const hostPort = Number(parts[0]);
+            const containerPort = Number(parts[1]);
+            res.push({ hostPort: Number.isFinite(hostPort) ? hostPort : undefined, containerPort: Number.isFinite(containerPort) ? containerPort : undefined, raw: p });
+        }
+        else if (parts.length === 3) {
+            const hostIp = parts[0];
+            const hostPort = Number(parts[1]);
+            const containerPort = Number(parts[2]);
+            res.push({ hostIp, hostPort: Number.isFinite(hostPort) ? hostPort : undefined, containerPort: Number.isFinite(containerPort) ? containerPort : undefined, raw: p });
+        }
+        else {
+            res.push({ raw: p });
+        }
+    }
+    return res;
+}
+export function runRules(compose, targetPath) {
+    const findings = [];
+    const services = compose?.services ?? {};
+    for (const [serviceName, svc] of Object.entries(services)) {
+        // Rule: privileged
+        if (svc?.privileged === true) {
+            findings.push({
+                id: 'compose.privileged',
+                title: 'Privileged container',
+                severity: 'high',
+                message: `Service '${serviceName}' runs with privileged: true.`,
+                service: serviceName,
+                path: `${targetPath}#services.${serviceName}.privileged`,
+                suggestion: 'Remove privileged: true unless absolutely required; prefer adding only the needed capabilities.'
+            });
+        }
+        // Rule: docker socket mount
+        const volumes = Array.isArray(svc?.volumes) ? svc.volumes : [];
+        for (const v of volumes) {
+            if (typeof v !== 'string')
+                continue;
+            if (v.includes('/var/run/docker.sock')) {
+                findings.push({
+                    id: 'compose.docker-socket',
+                    title: 'Docker socket mounted',
+                    severity: 'high',
+                    message: `Service '${serviceName}' mounts /var/run/docker.sock which effectively grants root-on-host.`,
+                    service: serviceName,
+                    path: `${targetPath}#services.${serviceName}.volumes`,
+                    suggestion: 'Avoid mounting the docker socket. If you need it, isolate the runner and treat it as privileged infrastructure.'
+                });
+            }
+            if (v.startsWith('/:') || v.startsWith('/:/')) {
+                findings.push({
+                    id: 'compose.host-root-mount',
+                    title: 'Host root mounted',
+                    severity: 'high',
+                    message: `Service '${serviceName}' appears to mount the host root filesystem ('${v}').`,
+                    service: serviceName,
+                    path: `${targetPath}#services.${serviceName}.volumes`,
+                    suggestion: 'Avoid mounting /. Mount only specific directories required by the app.'
+                });
+            }
+        }
+        // Rule: restart policy
+        if (svc?.restart == null) {
+            findings.push({
+                id: 'compose.missing-restart',
+                title: 'Missing restart policy',
+                severity: 'medium',
+                message: `Service '${serviceName}' has no restart policy.`,
+                service: serviceName,
+                path: `${targetPath}#services.${serviceName}.restart`,
+                suggestion: "Set restart: unless-stopped (or on-failure) to improve resilience."
+            });
+        }
+        // Rule: healthcheck
+        if (svc?.healthcheck == null) {
+            findings.push({
+                id: 'compose.missing-healthcheck',
+                title: 'Missing healthcheck',
+                severity: 'medium',
+                message: `Service '${serviceName}' has no healthcheck.`,
+                service: serviceName,
+                path: `${targetPath}#services.${serviceName}.healthcheck`,
+                suggestion: 'Add a healthcheck so orchestrators can detect broken containers (and dependent services can wait on healthy state).'
+            });
+        }
+        // Rule: runs as root
+        const user = svc?.user;
+        if (user == null || user === '0' || user === 0 || user === 'root') {
+            findings.push({
+                id: 'compose.runs-as-root',
+                title: 'Container likely runs as root',
+                severity: 'high',
+                message: `Service '${serviceName}' does not specify a non-root user (user:).`,
+                service: serviceName,
+                path: `${targetPath}#services.${serviceName}.user`,
+                suggestion: 'Set user: "1000:1000" (or a dedicated UID/GID) and ensure the image supports running unprivileged.'
+            });
+        }
+        // Rule: exposed sensitive ports
+        const ports = normalizePorts(svc?.ports);
+        for (const p of ports) {
+            const hostIp = p.hostIp;
+            const hostPort = p.hostPort;
+            const containerPort = p.containerPort;
+            const checkPort = containerPort ?? hostPort;
+            if (checkPort == null)
+                continue;
+            if (!SENSITIVE_PORTS.has(checkPort))
+                continue;
+            const bindsAll = hostIp == null || hostIp === '0.0.0.0' || hostIp === '';
+            if (bindsAll) {
+                findings.push({
+                    id: 'compose.exposed-sensitive-port',
+                    title: 'Sensitive port exposed publicly',
+                    severity: 'high',
+                    message: `Service '${serviceName}' exposes a commonly sensitive port (${checkPort}) on all interfaces (ports: '${p.raw}').`,
+                    service: serviceName,
+                    path: `${targetPath}#services.${serviceName}.ports`,
+                    suggestion: `Bind to 127.0.0.1 (e.g. '127.0.0.1:${hostPort ?? checkPort}:${containerPort ?? checkPort}') or remove the port and use an internal network.`
+                });
+            }
+        }
+    }
+    return findings;
+}

package/dist/rules.test.js

@@ -0,0 +1,18 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { runRules } from './rules.js';
+test('detects privileged container', () => {
+    const compose = { services: { app: { privileged: true } } };
+    const findings = runRules(compose, 'docker-compose.yml');
+    assert.ok(findings.some((f) => f.id === 'compose.privileged' && f.service === 'app'));
+});
+test('detects sensitive port exposed', () => {
+    const compose = { services: { db: { ports: ['5432:5432'] } } };
+    const findings = runRules(compose, 'docker-compose.yml');
+    assert.ok(findings.some((f) => f.id === 'compose.exposed-sensitive-port' && f.service === 'db'));
+});
+test('detects docker socket mount', () => {
+    const compose = { services: { runner: { volumes: ['/var/run/docker.sock:/var/run/docker.sock'] } } };
+    const findings = runRules(compose, 'docker-compose.yml');
+    assert.ok(findings.some((f) => f.id === 'compose.docker-socket' && f.service === 'runner'));
+});

package/dist/sarif.js

@@ -0,0 +1,67 @@
+// Minimal SARIF 2.1.0 generator for GitHub code scanning.
+// Docs: https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html
+function level(sev) {
+    const s = String(sev || '').toLowerCase();
+    if (s === 'high' || s === 'critical' || s === 'error')
+        return 'error';
+    if (s === 'medium' || s === 'warn' || s === 'warning')
+        return 'warning';
+    return 'note';
+}
+export function findingsToSarif(findings, opts = {}) {
+    const toolName = opts.toolName || 'ConfigSentry';
+    const rulesById = new Map();
+    for (const f of findings) {
+        if (!rulesById.has(f.id)) {
+            rulesById.set(f.id, {
+                id: f.id,
+                name: f.id,
+                shortDescription: { text: f.title },
+                fullDescription: { text: f.message },
+                help: { text: f.suggestion ? `${f.message}\n\nFix: ${f.suggestion}` : f.message },
+                defaultConfiguration: { level: level(f.severity) },
+            });
+        }
+    }
+    const results = findings.map((f) => {
+        const res = {
+            ruleId: f.id,
+            level: level(f.severity),
+            message: { text: f.suggestion ? `${f.message} Fix: ${f.suggestion}` : f.message },
+            properties: {
+                severity: f.severity,
+                service: f.service ?? undefined,
+            },
+        };
+        // Best-effort location: we store a pseudo "where" path today.
+        // If it contains "file#pointer", split it; else treat it as a file uri.
+        if (f.path) {
+            const [file, fragment] = String(f.path).split('#');
+            res.locations = [
+                {
+                    physicalLocation: {
+                        artifactLocation: { uri: file },
+                        region: fragment ? { snippet: { text: fragment } } : undefined,
+                    },
+                },
+            ];
+        }
+        return res;
+    });
+    return {
+        version: '2.1.0',
+        $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+        runs: [
+            {
+                tool: {
+                    driver: {
+                        name: toolName,
+                        informationUri: 'https://github.com/alfredMorgenstern/configsentry',
+                        rules: Array.from(rulesById.values()),
+                    },
+                },
+                results,
+            },
+        ],
+    };
+}

package/dist/scan.js

@@ -0,0 +1,46 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+const COMPOSE_FILENAMES = new Set([
+    'docker-compose.yml',
+    'docker-compose.yaml',
+    'compose.yml',
+    'compose.yaml',
+]);
+async function isFile(p) {
+    try {
+        return (await fs.stat(p)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+async function isDir(p) {
+    try {
+        return (await fs.stat(p)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export async function resolveTargets(input) {
+    const abs = path.resolve(input);
+    if (await isFile(abs))
+        return [abs];
+    if (await isDir(abs)) {
+        const entries = await fs.readdir(abs);
+        const hits = [];
+        for (const e of entries) {
+            if (COMPOSE_FILENAMES.has(e))
+                hits.push(path.join(abs, e));
+            // Common pattern: docker-compose.prod.yml etc.
+            if (/^docker-compose\..+\.ya?ml$/i.test(e))
+                hits.push(path.join(abs, e));
+            if (/^compose\..+\.ya?ml$/i.test(e))
+                hits.push(path.join(abs, e));
+        }
+        // de-dupe
+        return Array.from(new Set(hits)).sort();
+    }
+    // Not a file/dir: treat as a path anyway (will fail later with a nice error)
+    return [abs];
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "configsentry",
+  "version": "0.0.9",
+  "description": "Developer-first guardrails for docker-compose.yml (security + ops footguns).",
+  "type": "module",
+  "license": "MIT",
+  "author": "Marius Morgenstern",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alfredMorgenstern/configsentry.git"
+  },
+  "homepage": "https://configsentry.morgenstern.work",
+  "bugs": {
+    "url": "https://github.com/alfredMorgenstern/configsentry/issues"
+  },
+  "bin": {
+    "configsentry": "dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test dist/**/*.test.js",
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "start": "node dist/cli.js",
+    "dev": "node --loader ts-node/esm src/cli.ts",
+    "lint:example": "node dist/cli.js ./example.docker-compose.yml"
+  },
+  "keywords": [
+    "docker",
+    "docker-compose",
+    "compose",
+    "security",
+    "devops",
+    "lint",
+    "yaml"
+  ],
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "yaml": "^2.8.2",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
+  }
+}

package/src/baseline.test.ts

@@ -0,0 +1,15 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { fingerprintFinding, applyBaseline } from './baseline.js';
+
+test('baseline suppression works', () => {
+  const f1 = { id: 'r1', title: 't', severity: 'low', message: 'm', service: 'svc', path: '/tmp/x#p' };
+  const f2 = { id: 'r2', title: 't', severity: 'low', message: 'm', service: 'svc', path: '/tmp/x#p2' };
+
+  const set = new Set([fingerprintFinding(f1 as any)]);
+  const { kept, suppressed } = applyBaseline([f1 as any, f2 as any], set);
+
+  assert.equal(kept.length, 1);
+  assert.equal(suppressed.length, 1);
+  assert.equal(kept[0].id, 'r2');
+});

package/src/baseline.ts

@@ -0,0 +1,68 @@
+import fs from 'node:fs/promises';
+import crypto from 'node:crypto';
+import type { Finding } from './types.js';
+
+export type BaselineEntry = {
+  fingerprint: string;
+  id: string;
+  service?: string;
+  path?: string;
+};
+
+export type BaselineFile = {
+  version: 1;
+  generatedAt: string;
+  tool: string;
+  entries: BaselineEntry[];
+};
+
+export function fingerprintFinding(f: Finding): string {
+  const h = crypto.createHash('sha256');
+  // Keep stable + minimal; avoid messages that could change wording.
+  h.update(String(f.id));
+  h.update('\n');
+  h.update(String(f.service ?? ''));
+  h.update('\n');
+  h.update(String(f.path ?? ''));
+  return h.digest('hex');
+}
+
+export async function writeBaseline(path: string, findings: Finding[]) {
+  const entries: BaselineEntry[] = findings.map((f) => ({
+    fingerprint: fingerprintFinding(f),
+    id: f.id,
+    service: f.service,
+    path: f.path,
+  }));
+
+  const file: BaselineFile = {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    tool: 'ConfigSentry',
+    entries,
+  };
+
+  await fs.writeFile(path, JSON.stringify(file, null, 2) + '\n', 'utf8');
+}
+
+export async function loadBaseline(path: string): Promise<Set<string>> {
+  const raw = await fs.readFile(path, 'utf8');
+  const json = JSON.parse(raw);
+  const entries: any[] = Array.isArray(json?.entries) ? json.entries : [];
+  const set = new Set<string>();
+  for (const e of entries) {
+    if (typeof e?.fingerprint === 'string') set.add(e.fingerprint);
+  }
+  return set;
+}
+
+export function applyBaseline(findings: Finding[], baselineFingerprints: Set<string>) {
+  const kept: Finding[] = [];
+  const suppressed: Finding[] = [];
+  for (const f of findings) {
+    const fp = fingerprintFinding(f);
+    if (baselineFingerprints.has(fp)) suppressed.push(f);
+    else kept.push(f);
+  }
+  return { kept, suppressed };
+}

package/src/cli.ts

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import process from 'node:process';
+import fs from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { loadCompose } from './compose.js';
+import { runRules } from './rules.js';
+import { findingsToSarif } from './sarif.js';
+import { resolveTargets } from './scan.js';
+import { applyBaseline, loadBaseline, writeBaseline } from './baseline.js';
+
+function usage() {
+  console.log(`ConfigSentry (MVP)\n\nUsage:\n  configsentry <file-or-dir> [--json|--sarif] [--baseline <file>] [--write-baseline <file>]\n\nOutput:\n  --json           machine-readable findings\n  --sarif          SARIF 2.1.0 (for GitHub code scanning)\n\nBaselines:\n  --baseline <file>        suppress findings present in a baseline file\n  --write-baseline <file>  write baseline file for current findings and exit 0\n\nExit codes:\n  0 = no findings (after baseline suppression)
+  2 = findings present
+  1 = error
+`);
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.includes('-v') || args.includes('--version')) {
+    try {
+      const here = path.dirname(fileURLToPath(import.meta.url));
+      const pkgPath = path.resolve(here, '../package.json');
+      const raw = await fs.readFile(pkgPath, 'utf8');
+      const pkg = JSON.parse(raw);
+      console.log(pkg.version || 'unknown');
+    } catch {
+      console.log('unknown');
+    }
+    process.exit(0);
+  }
+
+  if (args.length === 0 || args.includes('-h') || args.includes('--help')) {
+    usage();
+    process.exit(0);
+  }
+
+  const json = args.includes('--json');
+  const sarif = args.includes('--sarif');
+  if (json && sarif) {
+    console.error('Error: choose only one output mode: --json or --sarif');
+    process.exit(1);
+  }
+
+  const baselineIdx = args.indexOf('--baseline');
+  const baselinePath = baselineIdx >= 0 ? args[baselineIdx + 1] : undefined;
+  const writeBaselineIdx = args.indexOf('--write-baseline');
+  const writeBaselinePath = writeBaselineIdx >= 0 ? args[writeBaselineIdx + 1] : undefined;
+
+  const target = args.find((a) => !a.startsWith('-'));
+  if (!target) {
+    usage();
+    process.exit(1);
+  }
+
+  const targetPaths = await resolveTargets(target);
+  if (targetPaths.length === 0) {
+    console.error(`No compose files found in: ${target}`);
+    process.exit(1);
+  }
+
+  let allFindings = [] as any[];
+  for (const targetPath of targetPaths) {
+    const { compose } = await loadCompose(targetPath);
+    allFindings = allFindings.concat(runRules(compose, targetPath));
+  }
+
+  // Baseline suppression
+  let suppressed: any[] = [];
+  let findings = allFindings;
+  if (baselinePath) {
+    const set = await loadBaseline(path.resolve(baselinePath));
+    const res = applyBaseline(allFindings, set);
+    findings = res.kept;
+    suppressed = res.suppressed;
+  }
+
+  // Baseline generation mode
+  if (writeBaselinePath) {
+    await writeBaseline(path.resolve(writeBaselinePath), allFindings);
+    console.log(`Wrote baseline: ${path.resolve(writeBaselinePath)} (${allFindings.length} finding(s))`);
+    process.exit(0);
+  }
+
+  if (json) {
+    console.log(JSON.stringify({ targetPaths, findings, suppressedCount: suppressed.length }, null, 2));
+  } else if (sarif) {
+    console.log(JSON.stringify(findingsToSarif(findings), null, 2));
+  } else {
+    const scope = targetPaths.length === 1 ? targetPaths[0] : `${targetPaths.length} file(s)`;
+
+    if (findings.length === 0) {
+      console.log(`✅ No findings for ${scope}`);
+      if (suppressed.length > 0) {
+        console.log(`(suppressed by baseline: ${suppressed.length})`);
+      }
+    } else {
+      console.log(`❌ ${findings.length} finding(s) for ${scope}`);
+      if (suppressed.length > 0) {
+        console.log(`(suppressed by baseline: ${suppressed.length})`);
+      }
+      console.log('');
+      for (const f of findings) {
+        console.log(`[${f.severity.toUpperCase()}] ${f.title}`);
+        console.log(`- service: ${f.service ?? '-'}
+- rule: ${f.id}
+- where: ${f.path ?? '-'}
+- msg: ${f.message}`);
+        if (f.suggestion) console.log(`- fix: ${f.suggestion}`);
+        console.log('');
+      }
+    }
+  }
+
+  process.exit(findings.length === 0 ? 0 : 2);
+}
+
+main().catch((err) => {
+  console.error('Error:', err);
+  process.exit(1);
+});

package/src/compose.ts

@@ -0,0 +1,19 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import YAML from 'yaml';
+
+export type ComposeFile = {
+  services?: Record<string, any>;
+};
+
+export async function loadCompose(filePath: string): Promise<{ compose: ComposeFile; raw: any }> {
+  const abs = path.resolve(filePath);
+  const text = await fs.readFile(abs, 'utf8');
+
+  // Support multi-document YAML (---). If multiple docs exist, Compose content is typically the first.
+  const docs = YAML.parseAllDocuments(text);
+  const first = docs[0];
+  const doc = first ? first.toJSON() : YAML.parse(text);
+
+  return { compose: doc as ComposeFile, raw: doc };
+}

package/src/rules.test.ts

@@ -0,0 +1,21 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { runRules } from './rules.js';
+
+test('detects privileged container', () => {
+  const compose = { services: { app: { privileged: true } } };
+  const findings = runRules(compose, 'docker-compose.yml');
+  assert.ok(findings.some((f) => f.id === 'compose.privileged' && f.service === 'app'));
+});
+
+test('detects sensitive port exposed', () => {
+  const compose = { services: { db: { ports: ['5432:5432'] } } };
+  const findings = runRules(compose, 'docker-compose.yml');
+  assert.ok(findings.some((f) => f.id === 'compose.exposed-sensitive-port' && f.service === 'db'));
+});
+
+test('detects docker socket mount', () => {
+  const compose = { services: { runner: { volumes: ['/var/run/docker.sock:/var/run/docker.sock'] } } };
+  const findings = runRules(compose, 'docker-compose.yml');
+  assert.ok(findings.some((f) => f.id === 'compose.docker-socket' && f.service === 'runner'));
+});

package/src/rules.ts

@@ -0,0 +1,148 @@
+import type { Finding } from './types.js';
+
+const SENSITIVE_PORTS = new Set([5432, 3306, 6379, 27017, 9200]);
+
+function normalizePorts(ports: any): Array<{ hostIp?: string; hostPort?: number; containerPort?: number; raw: string }> {
+  if (!Array.isArray(ports)) return [];
+  const res: Array<{ hostIp?: string; hostPort?: number; containerPort?: number; raw: string }> = [];
+  for (const p of ports) {
+    if (typeof p === 'number') {
+      res.push({ containerPort: p, raw: String(p) });
+      continue;
+    }
+    if (typeof p !== 'string') continue;
+    // patterns:
+    // "8080:80"
+    // "127.0.0.1:8080:80"
+    // "5432:5432"
+    const parts = p.split(':');
+    if (parts.length === 2) {
+      const hostPort = Number(parts[0]);
+      const containerPort = Number(parts[1]);
+      res.push({ hostPort: Number.isFinite(hostPort) ? hostPort : undefined, containerPort: Number.isFinite(containerPort) ? containerPort : undefined, raw: p });
+    } else if (parts.length === 3) {
+      const hostIp = parts[0];
+      const hostPort = Number(parts[1]);
+      const containerPort = Number(parts[2]);
+      res.push({ hostIp, hostPort: Number.isFinite(hostPort) ? hostPort : undefined, containerPort: Number.isFinite(containerPort) ? containerPort : undefined, raw: p });
+    } else {
+      res.push({ raw: p });
+    }
+  }
+  return res;
+}
+
+export function runRules(compose: any, targetPath: string): Finding[] {
+  const findings: Finding[] = [];
+  const services: Record<string, any> = compose?.services ?? {};
+
+  for (const [serviceName, svc] of Object.entries(services)) {
+    // Rule: privileged
+    if (svc?.privileged === true) {
+      findings.push({
+        id: 'compose.privileged',
+        title: 'Privileged container',
+        severity: 'high',
+        message: `Service '${serviceName}' runs with privileged: true.`,
+        service: serviceName,
+        path: `${targetPath}#services.${serviceName}.privileged`,
+        suggestion: 'Remove privileged: true unless absolutely required; prefer adding only the needed capabilities.'
+      });
+    }
+
+    // Rule: docker socket mount
+    const volumes: any[] = Array.isArray(svc?.volumes) ? svc.volumes : [];
+    for (const v of volumes) {
+      if (typeof v !== 'string') continue;
+      if (v.includes('/var/run/docker.sock')) {
+        findings.push({
+          id: 'compose.docker-socket',
+          title: 'Docker socket mounted',
+          severity: 'high',
+          message: `Service '${serviceName}' mounts /var/run/docker.sock which effectively grants root-on-host.`,
+          service: serviceName,
+          path: `${targetPath}#services.${serviceName}.volumes`,
+          suggestion: 'Avoid mounting the docker socket. If you need it, isolate the runner and treat it as privileged infrastructure.'
+        });
+      }
+      if (v.startsWith('/:') || v.startsWith('/:/')) {
+        findings.push({
+          id: 'compose.host-root-mount',
+          title: 'Host root mounted',
+          severity: 'high',
+          message: `Service '${serviceName}' appears to mount the host root filesystem ('${v}').`,
+          service: serviceName,
+          path: `${targetPath}#services.${serviceName}.volumes`,
+          suggestion: 'Avoid mounting /. Mount only specific directories required by the app.'
+        });
+      }
+    }
+
+    // Rule: restart policy
+    if (svc?.restart == null) {
+      findings.push({
+        id: 'compose.missing-restart',
+        title: 'Missing restart policy',
+        severity: 'medium',
+        message: `Service '${serviceName}' has no restart policy.`,
+        service: serviceName,
+        path: `${targetPath}#services.${serviceName}.restart`,
+        suggestion: "Set restart: unless-stopped (or on-failure) to improve resilience."
+      });
+    }
+
+    // Rule: healthcheck
+    if (svc?.healthcheck == null) {
+      findings.push({
+        id: 'compose.missing-healthcheck',
+        title: 'Missing healthcheck',
+        severity: 'medium',
+        message: `Service '${serviceName}' has no healthcheck.`,
+        service: serviceName,
+        path: `${targetPath}#services.${serviceName}.healthcheck`,
+        suggestion: 'Add a healthcheck so orchestrators can detect broken containers (and dependent services can wait on healthy state).'
+      });
+    }
+
+    // Rule: runs as root
+    const user = svc?.user;
+    if (user == null || user === '0' || user === 0 || user === 'root') {
+      findings.push({
+        id: 'compose.runs-as-root',
+        title: 'Container likely runs as root',
+        severity: 'high',
+        message: `Service '${serviceName}' does not specify a non-root user (user:).`,
+        service: serviceName,
+        path: `${targetPath}#services.${serviceName}.user`,
+        suggestion: 'Set user: "1000:1000" (or a dedicated UID/GID) and ensure the image supports running unprivileged.'
+      });
+    }
+
+    // Rule: exposed sensitive ports
+    const ports = normalizePorts(svc?.ports);
+    for (const p of ports) {
+      const hostIp = p.hostIp;
+      const hostPort = p.hostPort;
+      const containerPort = p.containerPort;
+
+      const checkPort = containerPort ?? hostPort;
+      if (checkPort == null) continue;
+      if (!SENSITIVE_PORTS.has(checkPort)) continue;
+
+      const bindsAll = hostIp == null || hostIp === '0.0.0.0' || hostIp === '';
+      if (bindsAll) {
+        findings.push({
+          id: 'compose.exposed-sensitive-port',
+          title: 'Sensitive port exposed publicly',
+          severity: 'high',
+          message: `Service '${serviceName}' exposes a commonly sensitive port (${checkPort}) on all interfaces (ports: '${p.raw}').`,
+          service: serviceName,
+          path: `${targetPath}#services.${serviceName}.ports`,
+          suggestion: `Bind to 127.0.0.1 (e.g. '127.0.0.1:${hostPort ?? checkPort}:${containerPort ?? checkPort}') or remove the port and use an internal network.`
+        });
+      }
+    }
+  }
+
+  return findings;
+}

package/src/sarif.ts

@@ -0,0 +1,74 @@
+import type { Finding } from './types.js';
+
+// Minimal SARIF 2.1.0 generator for GitHub code scanning.
+// Docs: https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html
+
+function level(sev: string): 'error' | 'warning' | 'note' {
+  const s = String(sev || '').toLowerCase();
+  if (s === 'high' || s === 'critical' || s === 'error') return 'error';
+  if (s === 'medium' || s === 'warn' || s === 'warning') return 'warning';
+  return 'note';
+}
+
+export function findingsToSarif(findings: Finding[], opts: { toolName?: string; repoRoot?: string } = {}) {
+  const toolName = opts.toolName || 'ConfigSentry';
+
+  const rulesById = new Map<string, any>();
+  for (const f of findings) {
+    if (!rulesById.has(f.id)) {
+      rulesById.set(f.id, {
+        id: f.id,
+        name: f.id,
+        shortDescription: { text: f.title },
+        fullDescription: { text: f.message },
+        help: { text: f.suggestion ? `${f.message}\n\nFix: ${f.suggestion}` : f.message },
+        defaultConfiguration: { level: level(f.severity) },
+      });
+    }
+  }
+
+  const results = findings.map((f) => {
+    const res: any = {
+      ruleId: f.id,
+      level: level(f.severity),
+      message: { text: f.suggestion ? `${f.message} Fix: ${f.suggestion}` : f.message },
+      properties: {
+        severity: f.severity,
+        service: f.service ?? undefined,
+      },
+    };
+
+    // Best-effort location: we store a pseudo "where" path today.
+    // If it contains "file#pointer", split it; else treat it as a file uri.
+    if (f.path) {
+      const [file, fragment] = String(f.path).split('#');
+      res.locations = [
+        {
+          physicalLocation: {
+            artifactLocation: { uri: file },
+            region: fragment ? { snippet: { text: fragment } } : undefined,
+          },
+        },
+      ];
+    }
+
+    return res;
+  });
+
+  return {
+    version: '2.1.0',
+    $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: toolName,
+            informationUri: 'https://github.com/alfredMorgenstern/configsentry',
+            rules: Array.from(rulesById.values()),
+          },
+        },
+        results,
+      },
+    ],
+  };
+}

package/src/scan.ts

@@ -0,0 +1,47 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const COMPOSE_FILENAMES = new Set([
+  'docker-compose.yml',
+  'docker-compose.yaml',
+  'compose.yml',
+  'compose.yaml',
+]);
+
+async function isFile(p: string) {
+  try {
+    return (await fs.stat(p)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+async function isDir(p: string) {
+  try {
+    return (await fs.stat(p)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export async function resolveTargets(input: string): Promise<string[]> {
+  const abs = path.resolve(input);
+
+  if (await isFile(abs)) return [abs];
+
+  if (await isDir(abs)) {
+    const entries = await fs.readdir(abs);
+    const hits: string[] = [];
+    for (const e of entries) {
+      if (COMPOSE_FILENAMES.has(e)) hits.push(path.join(abs, e));
+      // Common pattern: docker-compose.prod.yml etc.
+      if (/^docker-compose\..+\.ya?ml$/i.test(e)) hits.push(path.join(abs, e));
+      if (/^compose\..+\.ya?ml$/i.test(e)) hits.push(path.join(abs, e));
+    }
+    // de-dupe
+    return Array.from(new Set(hits)).sort();
+  }
+
+  // Not a file/dir: treat as a path anyway (will fail later with a nice error)
+  return [abs];
+}

package/src/types.ts

@@ -0,0 +1,16 @@
+export type Severity = 'low' | 'medium' | 'high';
+
+export type Finding = {
+  id: string;
+  title: string;
+  severity: Severity;
+  message: string;
+  service?: string;
+  path?: string;
+  suggestion?: string;
+};
+
+export type Report = {
+  targetPath: string;
+  findings: Finding[];
+};