Docker image vulnerability patching for Node.js and Python container images.

This tool provides:

• A CLI tool (docker-vuln-patcher) for local and CI/CD usage
• A public reusable GitHub Action (qasimnauman/patch-docker-image@v1)
• Verification gating that fails the run if targeted fixable CVEs still remain

Supported modes only:

• Public GitHub Action consumption via qasimnauman/patch-docker-image@v1
• CLI usage via docker-vuln-patcher (or patch_image.py)

Most patch automation flows stop at "build succeeded". This project enforces a stronger rule:

• Scan
• Patch
• Re-scan
• Fail unless targeted fixable vulnerabilities are actually reduced to zero for selected severities

This prevents false-success pipelines and gives safer production outcomes.

Supported runtime families:

• Node.js images
• Python images

Supported patch surfaces:

• OS packages when available (apt, apk, yum, dnf)
• npm
• pip

Current non-goals:

• Runtime families outside Node.js/Python
• Guaranteed remediation for every base image/CVE combination

1. Resolve inputs (image, Dockerfile path, credentials, options)
2. Build source image from Dockerfile or pull source image from registry
3. Run baseline Docker Scout scan
4. Select fixable CVEs by severity
5. Generate patch Dockerfile and patch plan artifacts
6. Build patched image
7. Run post-patch Docker Scout verification
8. Fail if targeted fixable CVEs remain
9. Optionally push verified patched image

Input precedence and source:

Image source behavior:

• If --dockerfile-path is set: build source image from local files.
• If --dockerfile-path is not set: pull --image from registry.

Action input sources:

• Image/build inputs come from with: values in workflow YAML.
• Credentials are typically wired from repository/org secrets.

Recommended secret mapping:

• dh-user: ${{ secrets.DOCKERHUB_USERNAME }}
• dh-password: ${{ secrets.DOCKERHUB_PASSWORD }}

Dockerfile behavior is identical to CLI:

• dockerfile-path set -> build first from workflow workspace.
• dockerfile-path empty -> pull image from registry.

name: Patch Docker Image

on:
  workflow_dispatch:

jobs:
  patch:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Patch and verify image
        id: patch
        uses: qasimnauman/patch-docker-image@v1
        with:
          image: myrepo/myapp:latest
          severities: CRITICAL,HIGH,MEDIUM,LOW
          push: "false"
          non-interactive: "true"
          dh-user: ${{ secrets.DOCKERHUB_USERNAME }}
          dh-password: ${{ secrets.DOCKERHUB_PASSWORD }}

      - name: Output patched tag
        run: echo "Patched image: ${{ steps.patch.outputs.patched_image }}"

Install:

python -m pip install --upgrade pip
pip install .

Patch an existing registry image:

docker-vuln-patcher \
  --image myrepo/myapp:latest \
  --non-interactive \
  --report-dir ./vuln_reports

Build from Dockerfile, then patch:

docker-vuln-patcher \
  --image myrepo/myapp:latest \
  --dockerfile-path ./Dockerfile \
  --context-path . \
  --build-arg APP_ENV=prod \
  --non-interactive \
  --report-dir ./vuln_reports

Patch, verify, and push:

docker-vuln-patcher \
  --image myrepo/myapp:latest \
  --non-interactive \
  --push

Public action:

• qasimnauman/patch-docker-image@v1

Primary action file:

• repository root action.yml

Supported usage policy:

• Use only qasimnauman/patch-docker-image@v1 in workflows.

• image (required, default: none): Target image reference.
• dockerfile-path (optional, default: empty): Optional Dockerfile path.
• context-path (optional, default: empty): Optional Docker build context.
• build-args (optional, default: empty): Newline-separated KEY=VALUE build args.
• severities (optional, default: CRITICAL,HIGH,MEDIUM,LOW): Severity selection.
• patched-suffix (optional, default: -patched): Patched image suffix.
• report-dir (optional, default: ./vuln_reports): Artifact output folder.
• dh-user (optional, default: empty): Docker Hub username.
• dh-password (optional, default: empty): Docker Hub password/token.
• push (optional, default: false): Push verified patched image.
• dry-run (optional, default: false): Generate only, skip build/verify/push.
• non-interactive (optional, default: true): Fail if credentials are missing.
• use-buildx (optional, default: false): Use buildx for patched build.
• python-version (optional, default: 3.12): Python runtime for action job.

Security behavior:

• Password/token is passed through stdin (docker login --password-stdin).
• Password value is not logged by the tool.
• Credential variables are configurable by key (--dh-user-env, --dh-password-env).

Best practices:

• Use short-lived tokens instead of account passwords when possible.
• Keep push permissions minimal and scoped.
• Do not commit raw vulnerability reports to public repos without review.
• Treat generated reports as potentially sensitive operational artifacts.

Default output root:

• ./vuln_reports

Generated artifacts:

• Baseline scan report: scout_<safe-image>.json
• Patch plan: patch_plan_<safe-image>.json
• Post-patch scan report: post_patch_scout_<safe-image>.json
• Generated Dockerfile: patches/Dockerfile.<safe-image>.patched

• 0: Success (or nothing fixable for selected severities).
• 1: Invalid configuration/input/auth/runtime error.
• 2: Safe failure (unsupported runtime, no patchable CVEs, or verification failed).

• Pin action usage to a stable major tag (@v1) or commit SHA.
• Configure repository/org secrets for Docker Hub credentials.
• Start with dry-run: "true" on new repos to validate behavior.
• Enable push only after successful verification behavior is confirmed.
• Keep base images and dependency lockfiles updated regularly.
• Monitor release notes and move tags intentionally.

• Ensure Docker is installed and daemon is running on the runner/host.

• Ensure Docker Scout plugin is installed and accessible (docker scout version).

• This is expected in some image/CVE combinations.
• The tool is intentionally strict and fails to avoid false success.
• Review generated reports and patch Dockerfile under report-dir.

• Provide dh-user and dh-password from secrets.
• Keep non-interactive enabled for deterministic CI behavior.

• EULA: EULA.md
• Privacy Policy: PRIVACY.md
• Support Policy: SUPPORT.md
• Security Policy: SECURITY.md

MIT