configsentry 0.0.18 → 0.0.20

package/README.md

@@ -4,6 +4,37 @@
 
 Developer-first guardrails for **docker-compose.yml** (security + ops footguns).
 
+## 60-second quickstart
+
+### Local (npx)
+
+```bash
+npx configsentry ./docker-compose.yml
+```
+
+### GitHub Action (minimal)
+
+```yml
+- uses: alfredMorgenstern/configsentry@v0.0.18
+  with:
+    target: .
+```
+
+### GitHub Code Scanning (SARIF upload)
+
+```yml
+permissions:
+  contents: read
+  security-events: write
+
+- uses: alfredMorgenstern/configsentry@v0.0.18
+  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`)
@@ -11,6 +42,7 @@ ConfigSentry reads a Compose file and flags common **high-impact** mistakes:
 - 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:`
@@ -31,19 +63,19 @@ npx configsentry ./docker-compose.yml
 ```bash
 npm install
 npm run build
-node dist/cli.js ./docker-compose.yml
+node dist/cli.js --target ./docker-compose.yml
 ```
 
 ### JSON output (CI / tooling)
 
 ```bash
-node dist/cli.js ./docker-compose.yml --json
+node dist/cli.js --target ./docker-compose.yml --json
 ```
 
 ### SARIF output (GitHub Code Scanning)
 
 ```bash
-node dist/cli.js ./docker-compose.yml --sarif > configsentry.sarif.json
+node dist/cli.js --target ./docker-compose.yml --sarif > configsentry.sarif.json
 ```
 
 ## Baselines (incremental adoption)
@@ -51,15 +83,23 @@ node dist/cli.js ./docker-compose.yml --sarif > configsentry.sarif.json
 Generate a baseline (captures current findings):
 
 ```bash
-node dist/cli.js ./docker-compose.yml --write-baseline .configsentry-baseline.json
+node dist/cli.js --target ./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
+node dist/cli.js --target ./docker-compose.yml --baseline .configsentry-baseline.json
 ```
 
+## Docs
+
+- GitHub Action usage examples: [`docs/action-usage.md`](docs/action-usage.md)
+- Baselines (incremental adoption): [`docs/baselines.md`](docs/baselines.md)
+- Compatibility & scope: [`docs/compatibility.md`](docs/compatibility.md)
+- Troubleshooting / FAQ: [`docs/troubleshooting.md`](docs/troubleshooting.md)
+- Launch pack (links + demo assets): [`docs/launch-pack.md`](docs/launch-pack.md)
+
 ## Use in GitHub Actions (copy/paste)
 
 More examples: [`docs/action-usage.md`](docs/action-usage.md)
@@ -81,7 +121,7 @@ jobs:
 
       - run: npm ci
       - run: npm run build
-      - run: node dist/cli.js ./docker-compose.yml
+      - run: node dist/cli.js --target ./docker-compose.yml
 ```
 
 ### Option B: use the ConfigSentry composite action
@@ -111,7 +151,9 @@ jobs:
       #   security-events: write
 ```
 
-> Tip: pin to a tag (like `v0.0.13`) for reproducible builds.
+**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.18`) for reproducible builds.
 
 ## Exit codes
 - `0` no findings
@@ -121,7 +163,7 @@ jobs:
 ## Example
 
 ```bash
-node dist/cli.js ./example.docker-compose.yml
+node dist/cli.js --target ./example.docker-compose.yml
 ```
 
 ## Next steps

package/dist/cli.js

@@ -8,15 +8,49 @@ import { runRules } from './rules.js';
 import { findingsToSarif } from './sarif.js';
 import { resolveTargets } from './scan.js';
 import { applyBaseline, loadBaseline, writeBaseline } from './baseline.js';
+function parseArgs(argv) {
+    const args = argv.slice(2);
+    const help = args.includes('-h') || args.includes('--help');
+    const version = args.includes('-v') || args.includes('--version');
+    const json = args.includes('--json');
+    const sarif = args.includes('--sarif');
+    const output = json ? 'json' : sarif ? 'sarif' : 'pretty';
+    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;
+    // Prefer explicit flag (matches the GitHub Action input)
+    const targetIdx = args.indexOf('--target');
+    const targetFromFlag = targetIdx >= 0 ? args[targetIdx + 1] : undefined;
+    // Back-compat: first positional arg
+    const targetFromPositional = args.find((a) => !a.startsWith('-'));
+    const target = targetFromFlag ?? targetFromPositional;
+    return { args, help, version, output, baselinePath, writeBaselinePath, target };
+}
 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)
+    console.log(`ConfigSentry (MVP)
+
+Usage:
+  configsentry <file-or-dir> [--json|--sarif] [--baseline <file>] [--write-baseline <file>]
+  configsentry --target <file-or-dir> [--json|--sarif] [--baseline <file>] [--write-baseline <file>]
+
+Output:
+  --json           machine-readable findings
+  --sarif          SARIF 2.1.0 (for GitHub code scanning)
+
+Baselines:
+  --baseline <file>        suppress findings present in a baseline file
+  --write-baseline <file>  write baseline file for current findings and exit 0
+
+Exit codes:
+  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')) {
+    const { args, help, version, output, baselinePath, writeBaselinePath, target } = parseArgs(process.argv);
+    if (version) {
         try {
             const here = path.dirname(fileURLToPath(import.meta.url));
             const pkgPath = path.resolve(here, '../package.json');
@@ -29,21 +63,19 @@ async function main() {
         }
         process.exit(0);
     }
-    if (args.length === 0 || args.includes('-h') || args.includes('--help')) {
+    if (args.length === 0 || help) {
         usage();
         process.exit(0);
     }
-    const json = args.includes('--json');
-    const sarif = args.includes('--sarif');
-    if (json && sarif) {
+    if (output === 'json' && args.includes('--sarif')) {
+        // should be impossible due to parseArgs, but keep a clear message
+        console.error('Error: choose only one output mode: --json or --sarif');
+        process.exit(1);
+    }
+    if (output === 'sarif' && args.includes('--json')) {
         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);
@@ -73,10 +105,10 @@ async function main() {
         console.log(`Wrote baseline: ${path.resolve(writeBaselinePath)} (${allFindings.length} finding(s))`);
         process.exit(0);
     }
-    if (json) {
+    if (output === 'json') {
         console.log(JSON.stringify({ targetPaths, findings, suppressedCount: suppressed.length }, null, 2));
     }
-    else if (sarif) {
+    else if (output === 'sarif') {
         console.log(JSON.stringify(findingsToSarif(findings), null, 2));
     }
     else {

package/dist/rules.js

@@ -113,9 +113,66 @@ export function runRules(compose, targetPath) {
         // Rule: docker socket mount
         const volumes = Array.isArray(svc?.volumes) ? svc.volumes : [];
         for (const v of volumes) {
-            if (typeof v !== 'string')
+            // Support both short syntax (string) and long syntax (object).
+            // Long syntax example:
+            //   - type: bind
+            //     source: /etc
+            //     target: /host-etc
+            let raw = '';
+            let hostPath;
+            if (typeof v === 'string') {
+                raw = v;
+                hostPath = v.split(':')[0];
+            }
+            else if (v && typeof v === 'object') {
+                raw = JSON.stringify(v);
+                const type = String(v.type ?? '').toLowerCase();
+                if (type === '' || type === 'bind') {
+                    hostPath = v.source ?? v.src;
+                }
+            }
+            else {
                 continue;
-            if (v.includes('/var/run/docker.sock')) {
+            }
+            // Rule: sensitive host path mounts
+            // Only consider bind mounts where the host path is absolute.
+            if (typeof hostPath === 'string' && hostPath.startsWith('/')) {
+                const hp = hostPath.replace(/\/$/, '');
+                if (hp === '/etc' || hp.startsWith('/etc/')) {
+                    findings.push({
+                        id: 'compose.host-etc-mount',
+                        title: 'Sensitive host path mounted (/etc)',
+                        severity: 'high',
+                        message: `Service '${serviceName}' mounts host /etc into the container ('${raw}').`,
+                        service: serviceName,
+                        path: `${targetPath}#services.${serviceName}.volumes`,
+                        suggestion: 'Avoid mounting /etc. If you only need a single config file, mount that file explicitly read-only.'
+                    });
+                }
+                if (hp === '/proc' || hp.startsWith('/proc/')) {
+                    findings.push({
+                        id: 'compose.host-proc-mount',
+                        title: 'Sensitive host path mounted (/proc)',
+                        severity: 'high',
+                        message: `Service '${serviceName}' mounts host /proc into the container ('${raw}').`,
+                        service: serviceName,
+                        path: `${targetPath}#services.${serviceName}.volumes`,
+                        suggestion: 'Avoid mounting /proc. If you need host metrics, prefer safer exporters or explicit APIs.'
+                    });
+                }
+                if (hp === '/sys' || hp.startsWith('/sys/')) {
+                    findings.push({
+                        id: 'compose.host-sys-mount',
+                        title: 'Sensitive host path mounted (/sys)',
+                        severity: 'high',
+                        message: `Service '${serviceName}' mounts host /sys into the container ('${raw}').`,
+                        service: serviceName,
+                        path: `${targetPath}#services.${serviceName}.volumes`,
+                        suggestion: 'Avoid mounting /sys. If hardware/host introspection is required, isolate the container and mount only specific needed subpaths read-only.'
+                    });
+                }
+            }
+            if (raw.includes('/var/run/docker.sock')) {
                 findings.push({
                     id: 'compose.docker-socket',
                     title: 'Docker socket mounted',
@@ -126,23 +183,23 @@ export function runRules(compose, targetPath) {
                     suggestion: 'Avoid mounting the docker socket. If you need it, isolate the runner and treat it as privileged infrastructure.'
                 });
             }
-            if (v.startsWith('/:') || v.startsWith('/:/')) {
+            if (raw.startsWith('/:') || raw.startsWith('/:/') || hostPath === '/') {
                 findings.push({
                     id: 'compose.host-root-mount',
                     title: 'Host root mounted',
                     severity: 'high',
-                    message: `Service '${serviceName}' appears to mount the host root filesystem ('${v}').`,
+                    message: `Service '${serviceName}' appears to mount the host root filesystem ('${raw}').`,
                     service: serviceName,
                     path: `${targetPath}#services.${serviceName}.volumes`,
                     suggestion: 'Avoid mounting /. Mount only specific directories required by the app.'
                 });
             }
-            if (v.startsWith('/dev:/dev') || v.startsWith('/dev/:/dev')) {
+            if (raw.startsWith('/dev:/dev') || raw.startsWith('/dev/:/dev') || hostPath === '/dev') {
                 findings.push({
                     id: 'compose.host-dev-mount',
                     title: 'Host /dev mounted into container',
                     severity: 'high',
-                    message: `Service '${serviceName}' mounts host /dev into the container ('${v}'), which can enable device access and privilege escalation.`,
+                    message: `Service '${serviceName}' mounts host /dev into the container ('${raw}'), which can enable device access and privilege escalation.`,
                     service: serviceName,
                     path: `${targetPath}#services.${serviceName}.volumes`,
                     suggestion: 'Avoid mounting /dev. If hardware access is required, map only the specific device(s) needed via devices:.'
@@ -204,6 +261,19 @@ export function runRules(compose, targetPath) {
                 suggestion: 'Set user: "1000:1000" (or a dedicated UID/GID) and ensure the image supports running unprivileged.'
             });
         }
+        // Rule: filesystem not read-only (hardening)
+        // Low severity because many images expect write access unless explicitly designed for read-only.
+        if (svc?.read_only !== true) {
+            findings.push({
+                id: 'compose.missing-read-only',
+                title: 'Filesystem not set to read-only',
+                severity: 'low',
+                message: `Service '${serviceName}' does not set read_only: true (container filesystem is writable by default).`,
+                service: serviceName,
+                path: `${targetPath}#services.${serviceName}.read_only`,
+                suggestion: 'Consider setting read_only: true + add explicit writable mounts (e.g. tmpfs:/tmp or a data volume) if the app supports it.'
+            });
+        }
         // Rule: exposed sensitive ports
         const ports = normalizePorts(svc?.ports);
         for (const p of ports) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "configsentry",
-  "version": "0.0.18",
+  "version": "0.0.20",
   "description": "Developer-first guardrails for docker-compose.yml (security + ops footguns).",
   "type": "module",
   "license": "MIT",