[FEATURE] Add GitHub Actions workflow template for automated Docker security scanning in CI

[advaitpatel]

Feature Request

Add a ready-to-use GitHub Actions workflow in the `examples/` directory so teams can drop DockSec into their CI pipeline in minutes. This is one of the highest-leverage contributions for an OWASP project — it shows security teams exactly how to automate scanning without needing to figure out the YAML from scratch.

What to Create

File: `examples/github-actions.yml`

name: DockSec Container Security Scan

on:
  push:
    branches: [main, master]
    paths:
      - 'Dockerfile*'
      - '.github/workflows/docksec.yml'
  pull_request:
    branches: [main, master]
    paths:
      - 'Dockerfile*'

jobs:
  docksec-scan:
    name: Docker Security Analysis
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write   # Required for SARIF upload

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Install DockSec
        run: pip install docksec

      - name: Install scanning tools
        run: python -c "from setup_external_tools import setup_tools; setup_tools()"

      - name: Build Docker image
        run: docker build -t myapp:${{ github.sha }} .

      - name: Run DockSec scan
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          docksec Dockerfile \
            -i myapp:${{ github.sha }} \
            --threshold 70 \
            -o results/docksec-report

      - name: Upload scan results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: docksec-security-report
          path: results/

      # Optional: Upload SARIF to GitHub Security tab (once --format sarif is available)
      # - name: Upload SARIF
      #   uses: github/codeql-action/upload-sarif@v3
      #   with:
      #     sarif_file: results/docksec-report.sarif

File: `examples/gitlab-ci.yml`

docksec-scan:
  image: python:3.12-slim
  stage: security
  before_script:
    - pip install docksec
    - python -c "from setup_external_tools import setup_tools; setup_tools()"
  script:
    - docker build -t myapp:$CI_COMMIT_SHA .
    - docksec Dockerfile -i myapp:$CI_COMMIT_SHA --threshold 70 -o gl-security-report
  artifacts:
    reports:
      # security: gl-security-report.json   # GitLab Security Dashboard format (future)
      paths:
        - gl-security-report.*
  only:
    changes:
      - Dockerfile

File: `examples/jenkins/Jenkinsfile`

pipeline {
    agent any
    environment {
        OPENAI_API_KEY = credentials('openai-api-key')
    }
    stages {
        stage('DockSec Security Scan') {
            steps {
                sh 'pip install docksec'
                sh 'docksec Dockerfile -i myapp:${BUILD_NUMBER} --threshold 70'
            }
            post {
                always {
                    archiveArtifacts artifacts: 'results/**', allowEmptyArchive: true
                }
            }
        }
    }
}

Documentation to Update

Add a "CI/CD Integration" section to `README.md` pointing to these examples.

Acceptance Criteria

• `examples/github-actions.yml` created and syntactically valid (check with `actionlint`)
• `examples/gitlab-ci.yml` created
• `examples/jenkins/Jenkinsfile` created
• README updated with a CI/CD Integration section
• Instructions cover: how to store API keys as secrets, what the threshold flag does, where reports are saved

Skill Level

Intermediate. DevOps/CI familiarity helpful. No Python coding required.