diff --git a/.github/SECURITY_SCANS.md b/.github/SECURITY_SCANS.md index 2b5e92f..8e562eb 100644 --- a/.github/SECURITY_SCANS.md +++ b/.github/SECURITY_SCANS.md @@ -4,21 +4,31 @@ 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 | +| Scan | Tool | Frequency | What It Checks | Blocking | +|------|------|-----------|----------------|----------| +| Secret Scanning | Trufflehog | On push/PR + weekly | Detects leaked credentials, API keys, tokens in all repository files | ✅ Yes | +| ShellCheck | ShellCheck | On every PR/push | Security + linting issues in `.sh` scripts | ✅ Yes | +| ShellCheck (Legacy) | ludeeus/shellicopter | On every PR/push | Additional shell script checks | ❌ No | +| CodeQL | GitHub CodeQL | On every PR/push | SAST for Python — detects injection, hardcoded secrets, insecure code patterns | ✅ Yes | +| Python Dependencies | `pip-audit` | On every PR/push | Known CVEs in `requirements.txt` files | ❌ No | +| Docker Images | Docker Scout (Trivy) | On every PR/push | Critical/HIGH CVEs in Dockerfiles | ❌ No | ## Workflow Files -- `.github/workflows/security-scans.yml` — ShellCheck, pip-audit, Docker Scout +- `.github/workflows/shellcheck.yml` — ShellCheck linting (blocking) on all `.sh` files +- `.github/workflows/secret-scanning.yml` — Trufflehog secret scanning (blocking) on all files, runs weekly +- `.github/workflows/security-scans.yml` — ShellCheck (legacy), pip-audit, Docker Scout - `.github/workflows/codeql.yml` — CodeQL SAST analysis -- `.github/secret_scanning.yml` — Exclusions for secret scanning +- `.github/secret_scanning.yml` — GitHub-native secret scanning exclusion patterns -## Enabling Secret Scanning & Push Protection +## Required Checks on `main` + +Branch protection requires the following checks to pass before merging: +- `ShellCheck` — shellcheck.yml workflow +- `CodeQL` — codeql.yml workflow +- `Trufflehog Secret Scanning` — secret-scanning.yml workflow + +## Enabling Push Protection (GitHub-native) 1. Go to **Settings** → **Advanced Security** → **Enable** "Secret Protection" 2. Enable **"Push protection"** under Secret Protection @@ -29,3 +39,9 @@ This repository runs automated security scans on every pull request to `main`. ## 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`). + +### Secret scanning failures + +If Trufflehog detects a potential secret, the CI will fail and the `results.sarif` file will be uploaded to the **Security** tab. Review findings and either: +- Rotate the exposed secret immediately +- Add the path to `.github/secret_scanning.yml` exclusions if it's a false positive (e.g., an example file with placeholder values) diff --git a/.github/secret_scanning.yml b/.github/secret_scanning.yml index 21cf162..b54e3e7 100644 --- a/.github/secret_scanning.yml +++ b/.github/secret_scanning.yml @@ -3,4 +3,9 @@ paths-ignore: - "**/sample.*" - "**/example.*" - "test/fixtures/**" + # Ignore documentation/wiki content (not code) - "docs/**" + - ".github/wiki/**" + # Ignore env files with placeholder values only (actual secrets should never be committed) + - "**/gluetun.env.example" + - "**/docker-compose.*.env.example" diff --git a/.github/workflows/secret-scanning.yml b/.github/workflows/secret-scanning.yml new file mode 100644 index 0000000..5db62b7 --- /dev/null +++ b/.github/workflows/secret-scanning.yml @@ -0,0 +1,46 @@ +name: Secret Scanning + +on: + push: + branches: [main] + pull_request: + branches: [main] + # Run weekly on schedule for ongoing monitoring + schedule: + - cron: ['0 6 * * 1'] # Mondays at 06:00 UTC + +permissions: + contents: read + security-events: write + +jobs: + trufflehog: + name: Trufflehog Secret Scanning + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + # Fetch full history for thorough scanning + fetch-depth: 0 + + - name: Run Trufflehog + uses: trufflesecurity/trufflehog@main + with: + # Scan the full repository path + path: ./ + # Output results in SARIF format for GitHub code scanning + format: sarif + output: results.sarif + # Fail the workflow if secrets are found + fail: true + # Use entropy-based detection in addition to regex patterns + only-failed: false + + - name: Upload Trufflehog results to GitHub Security tab + if: always() + uses: github/codeql-action/upload-security-sarif@v3 + with: + sarif_file: results.sarif + # Don't fail the build on upload issues (scanning might have passed) + checkout_path: ./ diff --git a/.github/workflows/shellcheck.yml b/.github/workflows/shellcheck.yml new file mode 100644 index 0000000..b5a0014 --- /dev/null +++ b/.github/workflows/shellcheck.yml @@ -0,0 +1,31 @@ +name: ShellCheck + +on: + push: + branches: [main] + pull_request: + branches: [main] + +permissions: + contents: read + +jobs: + shellcheck: + name: ShellCheck Linting + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Run ShellCheck on all shell scripts + uses: ludeeus/action-shellcheck@2.1.0 + with: + # Check all .sh files, excluding .git and vendor directories + files: | + *.sh + **/*.sh + # Exclude directories we don't want to lint + exclude: | + .git + .idea + .vscode