CIVWATCH/scorecard-workflow.yml at main · POWDER-RANGER/CIVWATCH · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
name: OpenSSF Scorecard

# This workflow runs the OpenSSF Scorecard analysis to assess the security
# posture of this repository against industry best practices.
#
# Scorecard evaluates 18 security checks including:
# - Branch protection enforcement
# - Dependency vulnerability scanning
# - Dangerous workflow detection
# - Code review requirements
# - Signed releases
# - And more...
#
# Results are uploaded to GitHub Security tab and published to the public
# Scorecard API for transparency.

on:
  # Run weekly to catch new security issues or changes in best practices
  schedule:
    - cron: '0 3 * * 1'  # Every Monday at 3 AM UTC

  # Run on every push to main to validate security posture stays healthy
  push:
    branches: [main]

  # Run when branch protection rules change
  branch_protection_rule:

  # Allow manual triggering for immediate security checks
  workflow_dispatch:

# Declare permissions explicitly for security
# This workflow needs minimal permissions - only read access to code
# and write access to security events for uploading SARIF results
permissions:
  contents: read        # Read repository code
  actions: read         # Read workflow run data
  security-events: write  # Upload SARIF results to Security tab

jobs:
  analysis:
    name: Scorecard security analysis
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          # Disable credential persistence to avoid exposing tokens
          persist-credentials: false

      - name: Run OpenSSF Scorecard
        uses: ossf/[email protected]
        with:
          # Output file for SARIF results
          results_file: results.sarif

          # Publish results to the OpenSSF Scorecard public API
          # This makes your score visible at:
          # https://securityscorecards.dev/viewer/?uri=github.com/POWDER-RANGER/OBLISK
          #
          # Set to false if you prefer to keep results private
          publish_results: true

          # Optional: Specify which checks to run
          # By default, all checks are enabled
          # Uncomment to customize:
          # checks: 'Branch-Protection,Signed-Releases,Vulnerabilities'

      - name: Upload SARIF results to GitHub Security tab
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif
        # Always upload results even if Scorecard finds issues
        # This ensures visibility of problems in the Security tab
        if: always()

      - name: Upload Scorecard results as workflow artifact
        uses: actions/upload-artifact@v4
        with:
          name: scorecard-results
          path: results.sarif
          retention-days: 30
        # Keep results available for 30 days for historical analysis
        if: always()

# --- UNDERSTANDING SCORECARD CHECKS ---
#
# The most impactful checks for individual projects:
#
# 1. Branch-Protection (Weight: High)
#    - Requires pull request reviews before merging
#    - Prevents direct pushes to main branch
#    - Setup: Repository Settings → Branches → Add protection rule
#
# 2. Signed-Releases (Weight: High)
#    - Verifies releases are cryptographically signed
#    - Prevents tampering with release artifacts
#    - Setup: Sign releases with GPG (see SECURITY.md)
#
# 3. Vulnerabilities (Weight: High)
#    - Scans for known CVEs in dependencies
#    - Automatically passes if Dependabot is enabled
#    - Setup: Settings → Security & analysis → Enable Dependabot
#
# 4. Dangerous-Workflow (Weight: High)
#    - Detects insecure GitHub Actions configurations
#    - Looks for secret leaks and unsafe pull_request_target usage
#    - Setup: Review workflow files for anti-patterns
#
# 5. Dependency-Update-Tool (Weight: Medium)
#    - Checks for automated dependency updates
#    - Passes if Dependabot or Renovate is configured
#    - Setup: Enable Dependabot in repository settings
#
# 6. Code-Review (Weight: Medium)
#    - Verifies changes go through pull request review
#    - Checks git history for review evidence
#    - Setup: Use pull requests for all changes
#
# Checks that are harder for individual projects:
#
# - Fuzzing: Requires OSS-Fuzz or similar infrastructure
# - SAST: Needs CodeQL or commercial static analysis tools
# - Token-Permissions: Advanced workflow security hardening
#
# Target Score: 7.0+ is achievable with basic security hygiene
#              8.5+ requires advanced practices
#              10.0 is rare even for large projects

# --- TROUBLESHOOTING COMMON ISSUES ---
#
# Issue: Scorecard workflow fails with "Resource not accessible by integration"
# Fix: Ensure the workflow has security-events: write permission (already set above)
#
# Issue: Branch-Protection check fails
# Fix: Enable branch protection on main with required PR reviews
#      Settings → Branches → Add rule for 'main' → Require pull request reviews
#
# Issue: Signed-Releases check fails
# Fix: Add GPG signatures to releases (see docs in SECURITY.md)
#      Or tag releases through GitHub UI which auto-signs them
#
# Issue: Dangerous-Workflow check warns about pull_request_target
# Fix: Avoid pull_request_target unless necessary, use pull_request instead
#      If using pull_request_target, ensure secrets are not exposed
#
# Issue: Publishing results fails
# Fix: Ensure the repository is public or disable publish_results
#      Private repos can't publish to the public Scorecard API

# --- CUSTOMIZATION CHECKLIST ---
#
# 1. Replace POWDER-RANGER/OBLISK in comments with your repository path
# 2. Decide whether to publish results publicly (publish_results: true/false)
# 3. Set up branch protection before first run to avoid Branch-Protection failure
# 4. Enable Dependabot to automatically pass Vulnerabilities check
# 5. Review other workflows for dangerous patterns before enabling this
# 6. Consider running manually first (workflow_dispatch) to see current score
# 7. Add Scorecard badge to README:
#    [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/YOUR-USERNAME/YOUR-REPO/badge)](https://securityscorecards.dev/viewer/?uri=github.com/YOUR-USERNAME/YOUR-REPO)