diff --git a/.github/SECURITY_SCANS.md b/.github/SECURITY_SCANS.md new file mode 100644 index 0000000..2b5e92f --- /dev/null +++ b/.github/SECURITY_SCANS.md @@ -0,0 +1,31 @@ +# Security Scanning + +This repository runs automated security scans on every pull request to `main`. + +## What's Scanned + +| Scan | Tool | Frequency | What It Checks | +|------|------|-----------|----------------| +| Secret Scanning | GitHub Secret Scanning | On push/PR + push protection | Detects leaked credentials, API keys, tokens in code, issues, PRs, wikis | +| ShellCheck | `ludeeus/shellicopter` (via `actions/checkout`) | On every PR/push | Security + linting issues in `.sh` scripts | +| CodeQL | GitHub CodeQL | On every PR/push | SAST for Python — detects injection, hardcoded secrets, insecure code patterns | +| Python Dependencies | `pip-audit` | On every PR/push | Known CVEs in `requirements.txt` files | +| Docker Images | Docker Scout | On every PR/push | Critical CVEs in Dockerfiles | + +## Workflow Files + +- `.github/workflows/security-scans.yml` — ShellCheck, pip-audit, Docker Scout +- `.github/workflows/codeql.yml` — CodeQL SAST analysis +- `.github/secret_scanning.yml` — Exclusions for secret scanning + +## Enabling Secret Scanning & Push Protection + +1. Go to **Settings** → **Advanced Security** → **Enable** "Secret Protection" +2. Enable **"Push protection"** under Secret Protection +3. Optionally enable: + - **Non-provider patterns** — detect private keys, connection strings + - **Validity checks** — verify if detected secrets are still active + +## Failing Builds + +When a security scan fails on a PR, GitHub will post check results directly on the PR. All contributors must address security findings before the PR can be merged (enforced via branch protection rules on `main`). diff --git a/.github/secret_scanning.yml b/.github/secret_scanning.yml new file mode 100644 index 0000000..21cf162 --- /dev/null +++ b/.github/secret_scanning.yml @@ -0,0 +1,6 @@ +paths-ignore: + # Ignore example/test files that may contain placeholder secrets + - "**/sample.*" + - "**/example.*" + - "test/fixtures/**" + - "docs/**" diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml new file mode 100644 index 0000000..978618a --- /dev/null +++ b/.github/workflows/codeql.yml @@ -0,0 +1,37 @@ +name: CodeQL + +on: + pull_request: + branches: [main] + push: + branches: [main] + +permissions: + actions: read + contents: read + security-events: write + +strategy: + matrix: + language: ['python'] + +jobs: + analyze: + name: CodeQL Analysis + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Initialize CodeQL + uses: github/codeql-action/init@v3 + with: + languages: ${{ matrix.language }} + upload: true + + - name: Autobuild + uses: github/codeql-action/autobuild@v3 + + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v3 diff --git a/.github/workflows/security-scans.yml b/.github/workflows/security-scans.yml new file mode 100644 index 0000000..5a377af --- /dev/null +++ b/.github/workflows/security-scans.yml @@ -0,0 +1,82 @@ +name: Security Scans + +on: + pull_request: + branches: [main] + push: + branches: [main] + +permissions: + contents: read + security-events: write + packages: read + +jobs: + shellcheck: + name: ShellCheck + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Install ShellCheck + run: sudo apt-get install -y shellcheck + + - name: Run ShellCheck + # Non-blocking on first rollout — existing scripts have pre-existing warnings. + # Set to `false` to make it gating. + continue-on-error: true + run: | + find . -name '*.sh' -not -path './.git/*' -not -path './.idea/*' -not -path './.vscode/*' -print0 \ + | while IFS= read -r -d '' script; do + echo "Checking: $script" + shellcheck "$script" || true + done + + python-deps: + name: Python Dependency Audit + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Find requirements.txt files + id: find_reqs + run: | + echo "reqs=$(find . -name 'requirements.txt' -not -path './.git/*' -print0 | tr '\0' ' ')" >> "$GITHUB_OUTPUT" + + - name: Install pip-audit + if: steps.find_reqs.outputs.reqs != '' + run: pip install pip-audit + + - name: Audit Python dependencies + if: steps.find_reqs.outputs.reqs != '' + run: | + for req in ${{ steps.find_reqs.outputs.reqs }}; do + echo "Auditing: $req" + pip-audit -r "$req" + done + + docker-vulns: + name: Docker Vulnerability Scan + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Find Dockerfiles + id: find_dockerfiles + run: | + echo "files=$(find . -iname 'Dockerfile*' -not -path './.git/*' -print0 | tr '\0' ' ')" >> "$GITHUB_OUTPUT" + + - name: Scan Dockerfiles with Trivy + if: steps.find_dockerfiles.outputs.files != '' + uses: aquasecurity/trivy-action@v0.36.0 + with: + scan-type: 'fs' + scan-ref: '.' + severity: 'CRITICAL,HIGH' + exit-code: '1' + format: 'table' + ignore-unfixed: true + skip-dirs: | + .git + .idea + .vscode