From c76496c396d1f599c390406dfc922dd5ff2ab26f Mon Sep 17 00:00:00 2001
From: David Larsen <Dc2larsen@gmail.com>
Date: Wed, 4 Feb 2026 09:15:30 -0800
Subject: [PATCH] docs: add Dockerfile auto-discovery workflow pattern

Add documentation for automatically discovering Dockerfiles in repos
with multiple Dockerfile locations. Uses a two-job workflow pattern
where the first job finds Dockerfiles matching common patterns
(Dockerfile, Dockerfile.*, *.dockerfile) while excluding test fixtures
and build artifacts, then passes discovered paths to the scan job.

This approach was chosen over building discovery into Socket Basics
itself for better portability and per-repo customization.
---
 docs/github-action.md | 83 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 83 insertions(+)

diff --git a/docs/github-action.md b/docs/github-action.md
index 2aabf0b..2799d49 100644
--- a/docs/github-action.md
+++ b/docs/github-action.md
@@ -8,6 +8,7 @@ Complete guide to integrating Socket Basics into your GitHub Actions workflows f
 - [Basic Configuration](#basic-configuration)
 - [Enterprise Features](#enterprise-features)
 - [Advanced Workflows](#advanced-workflows)
+  - [Dockerfile Auto-Discovery](#dockerfile-auto-discovery)
 - [Configuration Reference](#configuration-reference)
 - [Troubleshooting](#troubleshooting)
 
@@ -385,6 +386,88 @@ jobs:
           trivy_vuln_enabled: 'true'
 ```
 
+### Dockerfile Auto-Discovery
+
+For repositories with multiple Dockerfiles across different directories, you can automatically discover them instead of manually listing each path.
+
+```yaml
+name: Security Scan with Dockerfile Auto-Discovery
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+  push:
+    branches: [main]
+
+jobs:
+  discover-dockerfiles:
+    runs-on: ubuntu-latest
+    outputs:
+      dockerfiles: ${{ steps.discover.outputs.dockerfiles }}
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Discover Dockerfiles
+        id: discover
+        run: |
+          DOCKERFILES=$(find . -type d \( \
+            -name node_modules -o -name vendor -o -name .git -o \
+            -name test -o -name tests -o -name testing -o -name __tests__ -o \
+            -name fixture -o -name fixtures -o -name testdata -o \
+            -name example -o -name examples -o -name sample -o -name samples -o \
+            -name dist -o -name build -o -name out -o -name target -o \
+            -name venv -o -name .venv -o -name .cache \
+            \) -prune -o \
+            -type f \( -name 'Dockerfile' -o -name 'Dockerfile.*' -o -name '*.dockerfile' \) \
+            -print | sed 's|^./||' | paste -sd ',' -)
+
+          echo "Discovered Dockerfiles: $DOCKERFILES"
+          echo "dockerfiles=$DOCKERFILES" >> $GITHUB_OUTPUT
+
+  security-scan:
+    needs: discover-dockerfiles
+    if: needs.discover-dockerfiles.outputs.dockerfiles != ''
+    permissions:
+      issues: write
+      contents: read
+      pull-requests: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Run Socket Basics
+        uses: SocketDev/socket-basics@1.0.26
+        env:
+          GITHUB_PR_NUMBER: ${{ github.event.pull_request.number || github.event.issue.number }}
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          dockerfiles: ${{ needs.discover-dockerfiles.outputs.dockerfiles }}
+          trivy_vuln_enabled: 'true'
+```
+
+**How it works:**
+
+1. **Discovery job** uses `find` to locate Dockerfiles matching common patterns:
+   - `Dockerfile` (exact match)
+   - `Dockerfile.*` (e.g., `Dockerfile.prod`, `Dockerfile.dev`)
+   - `*.dockerfile` (e.g., `backend.dockerfile`)
+
+2. **Excluded directories** prevent scanning test fixtures and build artifacts:
+   - Package managers: `node_modules`, `vendor`, `venv`
+   - Test directories: `test`, `tests`, `__tests__`, `fixtures`
+   - Build outputs: `dist`, `build`, `out`, `target`
+
+3. **Scan job** receives discovered paths via job output and skips if none found
+
+**Customizing discovery patterns:**
+
+```yaml
+# Only scan production Dockerfiles
+-type f -name 'Dockerfile.prod' -print
+
+# Add custom exclusions
+-name custom_test_dir -o -name legacy -o \
+```
+
 ### Custom Rule Configuration
 
 ```yaml