diff --git a/.github/workflows/README.md b/.github/workflows/README.md index 01b4e436..3de86f5e 100644 --- a/.github/workflows/README.md +++ b/.github/workflows/README.md @@ -10,176 +10,288 @@ keywords: - ci/cd - automation - validation -estimated_reading_time: 12 + - security +estimated_reading_time: 20 --- # GitHub Actions Workflows -This directory contains GitHub Actions workflow definitions for continuous integration, code quality validation, and automated checks in the HVE Core project. +This directory contains GitHub Actions workflow definitions for continuous integration, code quality validation, security scanning, and automated maintenance in the HVE Core project. ## Overview -All workflows run automatically on pull requests and pushes to protected branches. They enforce code quality standards, validate documentation, and ensure consistency across the codebase. +Workflows run automatically on pull requests, pushes to protected branches, and scheduled intervals. They enforce code quality standards, validate documentation, perform security scans, and ensure consistency across the codebase. -## Workflows +## Workflow Organization -### Code Quality +### Naming Conventions -#### `ps-script-analyzer.yml` +Workflows follow a consistent naming pattern to indicate their purpose and usage: -**Purpose**: Static analysis of PowerShell scripts using PSScriptAnalyzer +* **`*-scan.yml`**: Security scanning workflows (reusable or standalone) + * Example: `gitleaks-scan.yml`, `checkov-scan.yml`, `dependency-pinning-scan.yml` + * Purpose: Run security scanners and produce SARIF outputs for the Security tab + * Typically support `workflow_call` trigger for composition -**Triggers**: +* **`*-check.yml`**: Validation and compliance checking workflows + * Example: `sha-staleness-check.yml` + * Purpose: Validate code/configuration quality or security posture + * May run on schedule or be called by orchestrator workflows -* Pull requests modifying `*.ps1` or `*.psm1` files -* Manual workflow dispatch +* **`*-lint.yml`**: Code quality and formatting workflows + * Example: `markdown-lint.yml`, `spell-check.yml` + * Purpose: Enforce code style and formatting standards + * Typically run on pull requests -**Features**: +* **Orchestrator workflows**: Compose multiple reusable workflows + * Example: `weekly-security-maintenance.yml` + * Purpose: Run multiple related checks and generate consolidated reports + * Typically run on schedule or manual trigger -* Analyzes only changed PowerShell files -* Creates GitHub annotations for violations -* Exports JSON results and markdown summary -* Uploads artifacts with 30-day retention +### Workflow Types -**Configuration**: `scripts/linting/PSScriptAnalyzer.psd1` +**Reusable Workflows** (`workflow_call` trigger) -**Exit Behavior**: Fails on Error or Warning severity issues +* Designed to be called by other workflows +* Accept inputs via `workflow_call.inputs` +* Expose outputs via `workflow_call.outputs` +* Should be self-contained and focused on a single task +* Include appropriate permissions declarations -### Documentation Validation +**Standalone Workflows** (`schedule`, `workflow_dispatch`, `push`, `pull_request` triggers) -#### `markdown-lint.yml` +* Run independently based on event triggers +* May call reusable workflows for composition +* Should minimize duplication by using reusable workflows -**Purpose**: Enforces markdown formatting standards using markdownlint +## Current Workflows -**Triggers**: +### Security Workflows -* Pull requests modifying `*.md` files -* Manual workflow dispatch +| Workflow | Type | Purpose | Triggers | +|----------|------|---------|----------| +| `weekly-security-maintenance.yml` | Orchestrator | Weekly security posture check | `schedule`, `workflow_dispatch` | +| `dependency-pinning-scan.yml` | Reusable | Validate SHA pinning compliance | `workflow_call` | +| `sha-staleness-check.yml` | Reusable | Check for stale SHA pins | `workflow_call`, `workflow_dispatch` | +| `codeql-analysis.yml` | Reusable | CodeQL security analysis | `push`, `pull_request`, `schedule`, `workflow_call` | +| `dependency-review.yml` | Reusable | Dependency vulnerability review | `pull_request`, `workflow_call` | +| `security-scan.yml` | Standalone | Security scanning orchestrator | `push`, `pull_request` | -**Configuration**: `.markdownlint.json` +### Validation Workflows -**Features**: +| Workflow | Purpose | Triggers | Configuration | +|----------|---------|----------|---------------| +| `ps-script-analyzer.yml` | PowerShell static analysis | PR (*.ps1, *.psm1), dispatch | `scripts/linting/PSScriptAnalyzer.psd1` | +| `markdown-lint.yml` | Markdown formatting standards | PR (*.md), dispatch | `.markdownlint.json` | +| `frontmatter-validation.yml` | YAML frontmatter validation | PR (*.md), dispatch | Script hardcoded | +| `markdown-link-check.yml` | Link validation | PR (*.md), dispatch | `scripts/linting/markdown-link-check.config.json` | +| `link-lang-check.yml` | Detect language-specific URLs | PR (*.md), dispatch | Script regex | +| `spell-check.yml` | Spell checking | PR, dispatch | `.cspell.json` | +| `table-format.yml` | Markdown table formatting | PR (*.md), dispatch | N/A | -* Validates markdown syntax and style -* Checks heading hierarchy -* Enforces consistent list formatting +## Using Reusable Workflows -#### `frontmatter-validation.yml` +### Basic Usage -**Purpose**: Validates YAML frontmatter and footer format in markdown files +Call a reusable workflow from another workflow using the `uses` keyword: -**Triggers**: +```yaml +jobs: + security-scan: + name: CodeQL Security Analysis + uses: ./.github/workflows/codeql-analysis.yml + permissions: + contents: read + security-events: write + actions: read +``` -* Pull requests modifying `*.md` files -* Manual workflow dispatch +### Passing Inputs -**Features**: +Provide inputs to reusable workflows using the `with` keyword: -* Validates required frontmatter fields -* Checks footer format and copyright notice -* Creates GitHub annotations for violations -* Exports JSON results with statistics -* Uploads artifacts with 30-day retention +```yaml +jobs: + pinning-check: + uses: ./.github/workflows/dependency-pinning-scan.yml + with: + threshold: 95 + dependency-types: 'actions,containers' + soft-fail: true + upload-sarif: true + upload-artifact: true +``` -**Configuration**: Hardcoded in `scripts/linting/Validate-MarkdownFrontmatter.ps1` +### Accessing Outputs -**Required Frontmatter Fields**: +Access outputs from reusable workflows in downstream jobs: -* `title` -* `description` -* `author` -* `ms.date` -* `ms.topic` -* `keywords` -* `estimated_reading_time` +```yaml +jobs: + security-scan: + uses: ./.github/workflows/dependency-pinning-scan.yml + with: + soft-fail: true + + summary: + needs: security-scan + runs-on: ubuntu-latest + steps: + - name: Check compliance + run: | + echo "Compliance: ${{ needs.security-scan.outputs.compliance-score }}%" + echo "Unpinned: ${{ needs.security-scan.outputs.unpinned-count }}" +``` -**Exit Behavior**: Fails if validation errors found +## Workflow Details -#### `markdown-link-check.yml` +### Security Workflows -**Purpose**: Validates all links in markdown files using markdown-link-check +#### `weekly-security-maintenance.yml` -**Triggers**: +**Purpose**: Orchestrates weekly security posture checks -* Pull requests modifying `*.md` files -* Manual workflow dispatch +**Schedule**: Weekly on Sundays at 02:00 UTC -**Features**: +**Jobs**: -* Checks internal and external links -* Retries failed links -* Creates GitHub annotations for broken links -* Exports JSON results with link statistics -* Generates detailed step summary -* Uploads artifacts with 30-day retention +* `validate-pinning`: Checks SHA pinning compliance (100% threshold) +* `check-staleness`: Identifies stale SHA pins (>30 days) +* `codeql-scan`: Runs CodeQL security analysis +* `summary`: Generates consolidated report -**Configuration**: `scripts/linting/markdown-link-check.config.json` +**Outputs**: Consolidated job summaries, JSON reports -**Exit Behavior**: Soft-fail (continues workflow but sets failure status) +**Security Coverage**: -#### `link-lang-check.yml` +* **CodeQL Analysis**: JavaScript/TypeScript code security scanning with security-extended queries +* **GitHub Secret Scanning**: Automatic detection of 200+ secret patterns (enabled via Security tab) +* **Dependabot Alerts**: Automatic vulnerability detection for npm dependencies (enabled via Security tab) -**Purpose**: Detects URLs with language paths that should be removed +#### `dependency-pinning-scan.yml` -**Triggers**: +**Purpose**: Validates that all GitHub Actions use SHA-pinned versions -* Pull requests modifying `*.md` files -* Manual workflow dispatch +**Inputs**: + +* `threshold` (number, default: 95): Minimum compliance percentage +* `dependency-types` (string, default: 'actions,containers'): Types to validate +* `soft-fail` (boolean, default: false): Continue on failures +* `upload-sarif` (boolean, default: false): Upload to Security tab +* `upload-artifact` (boolean, default: true): Upload JSON results + +**Outputs**: + +* `compliance-score`: Percentage of dependencies properly pinned +* `unpinned-count`: Number of unpinned dependencies +* `is-compliant`: Boolean indicating threshold met + +#### `sha-staleness-check.yml` + +**Purpose**: Detects outdated GitHub Action SHA pins + +**Inputs**: + +* `max-age-days` (number, default: 30): Maximum age before stale + +**Outputs**: + +* `stale-count`: Number of stale SHA pins +* `has-stale`: Boolean indicating stale pins found + +**Severity Levels**: + +* Info: 0-30 days +* Low: 31-90 days +* Medium: 91-180 days +* High: 181-365 days +* Critical: >365 days + +#### `codeql-analysis.yml` + +**Purpose**: Performs comprehensive security analysis using GitHub CodeQL + +**Triggers**: `push`, `pull_request`, `schedule` (Sundays at 4 AM UTC), `workflow_call` **Features**: -* Scans for `/en-us/` and similar patterns -* Creates GitHub warning annotations -* Provides fix instructions in summary -* Uploads artifacts with 30-day retention +* **Languages**: JavaScript/TypeScript analysis +* **Queries**: security-extended and security-and-quality query suites +* **Coverage**: Detects SQL injection, XSS, command injection, path traversal, and 200+ other vulnerabilities +* **Integration**: Results appear in Security > Code Scanning tab +* **Autobuild**: Automatically detects and builds JavaScript/TypeScript projects -**Configuration**: Regex patterns in `scripts/linting/Link-Lang-Check.ps1` +**Outputs**: SARIF results uploaded to GitHub Security tab, job summary with analysis details -**Exit Behavior**: Warning only (does not fail workflow) +#### `dependency-review.yml` -### Content Quality +**Purpose**: Reviews dependency changes in pull requests for known vulnerabilities -#### `spell-check.yml` +**Triggers**: `pull_request`, `workflow_call` -**Purpose**: Spell checking across all file types using cspell +**Features**: + +* **Threshold**: Fails on moderate or higher severity vulnerabilities +* **PR Comments**: Automatically comments on PRs with vulnerability summary +* **Coverage**: Checks npm packages against GitHub Advisory Database +* **Integration**: Works with Dependabot alerts and security advisories -**Triggers**: +**Behavior**: Blocks PRs introducing vulnerable dependencies (moderate+ severity) -* Pull requests -* Manual workflow dispatch +### Validation Workflows + +#### `ps-script-analyzer.yml` -**Configuration**: `.cspell.json` +**Purpose**: Static analysis of PowerShell scripts using PSScriptAnalyzer **Features**: -* Supports multiple languages -* Custom dictionary support -* Ignores code blocks and technical terms +* Analyzes only changed PowerShell files +* Creates GitHub annotations for violations +* Exports JSON results and markdown summary +* Uploads artifacts with 30-day retention -**Exit Behavior**: Fails on spelling errors +**Exit Behavior**: Fails on Error or Warning severity issues -#### `table-format.yml` +#### `frontmatter-validation.yml` -**Purpose**: Ensures consistent markdown table formatting +**Purpose**: Validates YAML frontmatter in markdown files -**Triggers**: +**Required Fields**: -* Pull requests modifying `*.md` files -* Manual workflow dispatch +* `title`, `description`, `author`, `ms.date`, `ms.topic`, `keywords`, `estimated_reading_time` **Features**: -* Aligns table columns -* Validates table structure -* Checks for consistent pipe usage +* Validates frontmatter format +* Checks footer format and copyright notice +* Creates GitHub annotations +* Exports JSON statistics + +#### `markdown-link-check.yml` + +**Purpose**: Validates all links in markdown files -**Exit Behavior**: Fails on formatting issues +**Features**: + +* Checks internal and external links +* Retries failed links +* Creates GitHub annotations +* Generates detailed summaries + +**Exit Behavior**: Soft-fail (sets failure status but continues) + +#### `link-lang-check.yml` + +**Purpose**: Detects URLs with language paths (e.g., `/en-us/`) + +**Exit Behavior**: Warning only (does not fail workflow) ## Common Patterns ### Workflow Structure -All validation workflows follow a consistent pattern: +All workflows follow a consistent pattern: ```yaml name: Workflow Name @@ -189,18 +301,23 @@ on: - '**/*.ext' workflow_dispatch: +permissions: + contents: read + jobs: validate: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4.2.2 + - uses: actions/checkout@ # v4.2.2 + with: + persist-credentials: false - name: Setup environment # Install dependencies - name: Run validation # Execute validation script - name: Upload artifacts if: always() - uses: actions/upload-artifact@v4 + uses: actions/upload-artifact@ # v4 ``` ### Artifact Handling @@ -236,7 +353,20 @@ Workflows generate markdown summaries displayed in the workflow run: ## Local Testing -All validation scripts can be tested locally before pushing: +### Security Scripts + +```powershell +# Dependency pinning validation +.\scripts\security\Test-DependencyPinning.ps1 -Path .github/workflows -Verbose + +# SHA staleness check +.\scripts\security\Test-SHAStaleness.ps1 -MaxAge 30 -OutputFormat github + +# Update stale SHA pins +.\scripts\security\Update-ActionSHAPinning.ps1 -Path .github/workflows -UpdateStale +``` + +### Validation Scripts ```powershell # PowerShell analysis @@ -263,33 +393,106 @@ npm run spell-check npm run format:tables ``` -## Configuration Files +## Best Practices + +### When to Extract a Reusable Workflow + +Extract workflow logic to a reusable workflow when: + +* The logic is duplicated across multiple workflows (DRY principle) +* The workflow performs a focused, reusable task (single responsibility) +* The workflow needs to be tested or maintained independently +* The workflow could benefit other projects or teams + +**Do NOT extract** when: + +* The logic is highly specific to a single workflow +* The extraction would create more complexity than it solves +* The workflow is fewer than 20 lines and unlikely to be reused + +### Input and Output Design + +**Inputs:** + +* Use descriptive names with clear documentation +* Provide sensible defaults for optional inputs +* Use appropriate types (`string`, `number`, `boolean`) +* Consider `required: false` with defaults over `required: true` + +**Outputs:** + +* Export key metrics and results for downstream jobs +* Use consistent naming conventions across workflows +* Include both raw values and computed flags (e.g., `count` and `has-items`) + +Example: + +```yaml +workflow_call: + inputs: + max-age-days: + description: 'Maximum SHA age in days before considered stale' + required: false + type: number + default: 30 + outputs: + stale-count: + description: 'Number of stale SHA pins found' + value: ${{ jobs.check.outputs.stale-count }} + has-stale: + description: 'Whether any stale SHA pins were found' + value: ${{ jobs.check.outputs.has-stale }} +``` + +### Permissions -| File | Purpose | Used By | -|------------------------------------------------------|---------------------------------|-----------------------------| -| `scripts/linting/PSScriptAnalyzer.psd1` | PowerShell linting rules | ps-script-analyzer.yml | -| `.markdownlint.json` | Markdown formatting rules | markdown-lint.yml | -| `scripts/linting/markdown-link-check.config.json` | Link checking configuration | markdown-link-check.yml | -| `.cspell.json` | Spell checking configuration | spell-check.yml | -| `.github/instructions/markdown.instructions.md` | Markdown style guide | All markdown workflows | -| `.github/instructions/commit-message.instructions.md` | Commit message standards | All workflows (informative) | - -## Adding New Workflows - -To add a new validation workflow: - -1. **Create workflow file** in `.github/workflows/` using consistent naming -2. **Follow common patterns** from existing workflows -3. **Add appropriate triggers** (pull_request paths, workflow_dispatch) -4. **Implement artifact uploads** with 30-day retention -5. **Create GitHub annotations** for violations -6. **Generate step summary** with results -7. **Support local testing** with corresponding script -8. **Document** in this README -9. **Test thoroughly** before merging +* Declare minimal required permissions at workflow and job levels +* Use `permissions: {}` to disable all permissions when not needed +* Escalate permissions only where necessary (e.g., `security-events: write` for SARIF upload) + +Example: + +```yaml +permissions: + contents: read + security-events: write # Required for SARIF upload +``` + +### Security Considerations + +* All actions MUST be pinned to SHA commits (not tags or branches) +* Include SHA comment showing the tag/version (e.g., `# v4.2.2`) +* Use Harden Runner for audit logging +* Disable credential persistence when checking out code: `persist-credentials: false` ## Troubleshooting +### "Unable to find reusable workflow" error + +This lint error appears in VS Code but workflows run correctly on GitHub. The editor cannot resolve local workflow files at edit time. Ignore this error if: + +* The workflow file exists at the specified path +* The workflow has a `workflow_call` trigger +* The workflow runs successfully on GitHub + +### Outputs not available in downstream jobs + +Ensure outputs are defined at three levels: + +1. Step outputs: `echo "key=value" >> $GITHUB_OUTPUT` +2. Job outputs: `outputs.key: ${{ steps.step-id.outputs.key }}` +3. Workflow outputs: `outputs.key: ${{ jobs.job-id.outputs.key }}` + +### SARIF upload failures + +SARIF uploads require: + +* `security-events: write` permission +* SARIF file generated by the scanner +* Valid SARIF format (JSON schema validation) + +Use `continue-on-error: true` to prevent workflow failure on SARIF upload issues. + ### Workflow Fails But Local Test Passes * Check environment differences (Node.js version, PowerShell version) @@ -308,12 +511,61 @@ To add a new validation workflow: * Ensure file paths are relative to repository root * Check that workflow has write permissions +## Configuration Files + +| File | Purpose | Used By | +|------|---------|---------| +| `scripts/linting/PSScriptAnalyzer.psd1` | PowerShell linting rules | ps-script-analyzer.yml | +| `.markdownlint.json` | Markdown formatting rules | markdown-lint.yml | +| `scripts/linting/markdown-link-check.config.json` | Link checking configuration | markdown-link-check.yml | +| `.cspell.json` | Spell checking configuration | spell-check.yml | +| `.github/instructions/markdown.instructions.md` | Markdown style guide | All markdown workflows | +| `.github/instructions/commit-message.instructions.md` | Commit message standards | All workflows (informative) | + +## Maintenance + +### Updating SHA Pins + +Keep action SHA pins up-to-date using the provided script: + +```powershell +# Update all stale SHA pins +scripts/security/Update-ActionSHAPinning.ps1 -Path .github/workflows -UpdateStale + +# Dry-run to see what would be updated +scripts/security/Update-ActionSHAPinning.ps1 -Path .github/workflows -WhatIf +``` + +### Adding New Workflows + +When adding a new workflow: + +1. Follow the naming convention (`*-scan.yml`, `*-check.yml`, or `*-lint.yml`) +2. Pin all actions to SHA commits +3. Include Harden Runner as the first step (security workflows) +4. Document inputs, outputs, and purpose +5. Add appropriate triggers (pull_request paths, workflow_dispatch) +6. Implement artifact uploads with 30-day retention +7. Create GitHub annotations for violations +8. Generate step summary with results +9. Support local testing with corresponding script +10. Update this README with the new workflow entry +11. Test thoroughly before merging + ## Related Documentation * [Linting Scripts Documentation](../../scripts/linting/README.md) +* [Security Scripts Documentation](../../scripts/security/) * [Scripts Documentation](../../scripts/README.md) * [Contributing Guidelines](../../CONTRIBUTING.md) +## Resources + +* [GitHub Actions: Reusing workflows](https://docs.github.com/en/actions/using-workflows/reusing-workflows) +* [GitHub Actions: Workflow syntax](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) +* [GitHub Actions: Security hardening](https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions) +* [SARIF specification](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html) + --- diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml new file mode 100644 index 00000000..41e6ccce --- /dev/null +++ b/.github/workflows/codeql-analysis.yml @@ -0,0 +1,57 @@ +name: CodeQL Security Analysis + +on: + push: + branches: [ main, develop, feature/* ] + pull_request: + branches: [ main, develop ] + schedule: + - cron: '0 4 * * 0' # Sundays at 4 AM UTC + workflow_call: + +permissions: + contents: read + security-events: write + +jobs: + analyze: + name: CodeQL Analysis + runs-on: ubuntu-latest + permissions: + contents: read + security-events: write + actions: read + + strategy: + fail-fast: false + matrix: + language: [ 'javascript' ] + + steps: + - name: Checkout repository + uses: actions/checkout@71cf2267d89c5cb81562390fa70a37fa40b1305e # v4.2.2 + with: + persist-credentials: false + + - name: Initialize CodeQL + uses: github/codeql-action/init@95b1867cf797beb28ce725a6f25268e2d3304672 # v3.27.0 + with: + languages: ${{ matrix.language }} + queries: security-extended,security-and-quality + + - name: Autobuild + uses: github/codeql-action/autobuild@95b1867cf797beb28ce725a6f25268e2d3304672 # v3.27.0 + + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@95b1867cf797beb28ce725a6f25268e2d3304672 # v3.27.0 + with: + category: "/language:${{ matrix.language }}" + + - name: Add job summary + if: always() + run: | + echo "## CodeQL Security Analysis Complete" >> $GITHUB_STEP_SUMMARY + echo "**Language:** ${{ matrix.language }}" >> $GITHUB_STEP_SUMMARY + echo "**Queries:** security-extended, security-and-quality" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "📊 View results in the Security tab under Code Scanning" >> $GITHUB_STEP_SUMMARY diff --git a/.github/workflows/dependency-pinning-scan.yml b/.github/workflows/dependency-pinning-scan.yml new file mode 100644 index 00000000..7b3ad2e3 --- /dev/null +++ b/.github/workflows/dependency-pinning-scan.yml @@ -0,0 +1,172 @@ +name: Dependency Pinning Scan + +on: + workflow_call: + inputs: + threshold: + description: 'Compliance threshold percentage (0-100)' + required: false + type: number + default: 95 + dependency-types: + description: 'Comma-separated list of dependency types to check' + required: false + type: string + default: 'actions,containers' + soft-fail: + description: 'Whether to continue on compliance violations' + required: false + type: boolean + default: false + upload-sarif: + description: 'Whether to upload SARIF results to Security tab' + required: false + type: boolean + default: false + upload-artifact: + description: 'Whether to upload results as artifact' + required: false + type: boolean + default: true + outputs: + compliance-score: + description: 'Compliance score percentage' + value: ${{ jobs.scan.outputs.compliance-score }} + unpinned-count: + description: 'Number of unpinned dependencies found' + value: ${{ jobs.scan.outputs.unpinned-count }} + is-compliant: + description: 'Whether repository meets compliance threshold' + value: ${{ jobs.scan.outputs.is-compliant }} + +permissions: + contents: read + security-events: write + +jobs: + scan: + name: Validate SHA Pinning Compliance + runs-on: ubuntu-latest + permissions: + contents: read + security-events: write + outputs: + compliance-score: ${{ steps.pinning.outputs.compliance-score }} + unpinned-count: ${{ steps.pinning.outputs.unpinned-count }} + is-compliant: ${{ steps.pinning.outputs.is-compliant }} + steps: + - name: Harden Runner + uses: step-security/harden-runner@92c522aaa6f53af082553dedc1596c80b71aba33 # v2.10.2 + with: + egress-policy: audit + + - name: Checkout code + uses: actions/checkout@71cf2267d89c5cb81562390fa70a37fa40b1305e # v4.2.2 + with: + persist-credentials: false + + - name: Run SHA Pinning Validation + id: pinning + shell: pwsh + run: | + Write-Host "Validating dependency SHA pinning compliance..." + + # Build parameter list + $params = @{ + Path = '.' + Format = 'json' + OutputPath = 'logs/dependency-pinning-results.json' + } + + if ('${{ inputs.dependency-types }}') { + $params['DependencyTypes'] = '${{ inputs.dependency-types }}' + } + + if ('${{ inputs.threshold }}') { + $params['Threshold'] = [int]'${{ inputs.threshold }}' + } + + # Run validation script + & scripts/security/Test-DependencyPinning.ps1 @params + + # Extract metrics from report + $report = Get-Content logs/dependency-pinning-results.json | ConvertFrom-Json + $complianceScore = $report.ComplianceScore + $unpinnedCount = $report.UnpinnedDependencies + $threshold = [int]'${{ inputs.threshold }}' + $isCompliant = $complianceScore -ge $threshold + + "compliance-score=$complianceScore" >> $env:GITHUB_OUTPUT + "unpinned-count=$unpinnedCount" >> $env:GITHUB_OUTPUT + "is-compliant=$($isCompliant.ToString().ToLower())" >> $env:GITHUB_OUTPUT + + Write-Host "Compliance Score: $complianceScore%" + Write-Host "Unpinned Dependencies: $unpinnedCount" + Write-Host "Is Compliant (>=$threshold%): $isCompliant" + + # Fire GitHub Actions warnings for each violation + if ($unpinnedCount -gt 0) { + foreach ($violation in $report.Violations) { + Write-Output "::warning file=$($violation.File),line=$($violation.Line)::Unpinned $($violation.Type) dependency: $($violation.Name)@$($violation.Version) (Severity: $($violation.Severity))" + } + } + + - name: Upload SARIF to Security tab + if: inputs.upload-sarif && always() + uses: github/codeql-action/upload-sarif@95b1867cf797beb28ce725a6f25268e2d3304672 # v3.27.0 + with: + sarif_file: logs/dependency-pinning-results.sarif + category: dependency-pinning + continue-on-error: true + + - name: Upload validation report + if: inputs.upload-artifact && always() + uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v4.4.3 + with: + name: dependency-pinning-results + path: logs/dependency-pinning-results.json + retention-days: 90 + + - name: Add job summary + if: always() + shell: pwsh + run: | + $complianceScore = '${{ steps.pinning.outputs.compliance-score }}' + $unpinnedCount = '${{ steps.pinning.outputs.unpinned-count }}' + $isCompliant = '${{ steps.pinning.outputs.is-compliant }}' + + @" + ## Dependency Pinning Scan Results + + | Metric | Value | + |--------|-------| + | Compliance Score | $complianceScore% | + | Unpinned Dependencies | $unpinnedCount | + | Status | $(if ($isCompliant -eq 'true') { '✅ Compliant' } else { '⚠ī¸ Non-Compliant' }) | + + $(if ($unpinnedCount -ne '0') { + @" + + ### ⚠ī¸ Action Required + + **$unpinnedCount dependencies are not SHA-pinned.** + + Review the warnings in the workflow log and pin dependencies to specific SHA commits. + + "@ + } else { + @" + + ### ✅ All Dependencies Pinned + + All dependencies are properly SHA-pinned. + + "@ + }) + "@ | Out-File -FilePath $env:GITHUB_STEP_SUMMARY -Encoding UTF8 + + - name: Fail job if non-compliant + if: steps.pinning.outputs.is-compliant == 'false' && !inputs.soft-fail + run: | + echo "Dependency pinning scan failed - compliance threshold not met" + exit 1 diff --git a/.github/workflows/dependency-review.yml b/.github/workflows/dependency-review.yml new file mode 100644 index 00000000..65f1ddea --- /dev/null +++ b/.github/workflows/dependency-review.yml @@ -0,0 +1,30 @@ +name: Dependency Review + +on: + pull_request: + branches: [ main, develop ] + workflow_call: + +permissions: + contents: read + pull-requests: write + +jobs: + dependency-review: + name: Review Dependencies + runs-on: ubuntu-latest + permissions: + contents: read + pull-requests: write + + steps: + - name: Checkout code + uses: actions/checkout@71cf2267d89c5cb81562390fa70a37fa40b1305e # v4.2.2 + with: + persist-credentials: false + + - name: Dependency Review + uses: actions/dependency-review-action@9129d7d40b8c12c1ed0f60400d00c92d437adcce # v4.3.4 + with: + fail-on-severity: moderate + comment-summary-in-pr: always diff --git a/.github/workflows/security-scan.yml b/.github/workflows/security-scan.yml new file mode 100644 index 00000000..7bd46742 --- /dev/null +++ b/.github/workflows/security-scan.yml @@ -0,0 +1,29 @@ +name: Security Scan + +on: + push: + branches: [ main, develop ] + pull_request: + branches: [ main, develop ] + +permissions: + contents: read + security-events: write + pull-requests: write + +jobs: + codeql: + name: CodeQL Security Analysis + uses: ./.github/workflows/codeql-analysis.yml + permissions: + contents: read + security-events: write + actions: read + + dependency-review: + name: Dependency Review + if: github.event_name == 'pull_request' + uses: ./.github/workflows/dependency-review.yml + permissions: + contents: read + pull-requests: write diff --git a/.github/workflows/sha-staleness-check.yml b/.github/workflows/sha-staleness-check.yml new file mode 100644 index 00000000..ecc0e2d4 --- /dev/null +++ b/.github/workflows/sha-staleness-check.yml @@ -0,0 +1,102 @@ +name: SHA Staleness Check + +on: + workflow_dispatch: + inputs: + max-age-days: + description: 'Maximum SHA age in days before considered stale' + required: false + type: number + default: 30 + workflow_call: + inputs: + max-age-days: + description: 'Maximum SHA age in days before considered stale' + required: false + type: number + default: 30 + outputs: + stale-count: + description: 'Number of stale SHA pins found' + value: ${{ jobs.check-staleness.outputs.stale-count }} + has-stale: + description: 'Whether any stale SHA pins were found' + value: ${{ jobs.check-staleness.outputs.has-stale }} + +permissions: + contents: read + +jobs: + check-staleness: + name: Check Action SHA Staleness + runs-on: ubuntu-latest + permissions: + contents: read + outputs: + stale-count: ${{ steps.staleness.outputs.stale-count }} + has-stale: ${{ steps.staleness.outputs.has-stale }} + steps: + - name: Harden Runner + uses: step-security/harden-runner@92c522aaa6f53af082553dedc1596c80b71aba33 # v2.10.2 + with: + egress-policy: audit + + - name: Checkout code + uses: actions/checkout@71cf2267d89c5cb81562390fa70a37fa40b1305e # v4.2.2 + with: + persist-credentials: false + + - name: Run SHA Staleness Check + id: staleness + shell: pwsh + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + $thresholdDays = if ('${{ inputs.max-age-days }}') { + [int]'${{ inputs.max-age-days }}' + } else { + 30 + } + + Write-Host "Running SHA staleness check with $thresholdDays day threshold..." + + # Run staleness check and capture output + & scripts/security/Test-SHAStaleness.ps1 ` + -MaxAge $thresholdDays ` + -OutputFormat github ` + -OutputPath logs/sha-staleness-results.json + + # Extract stale count from JSON report + if (Test-Path logs/sha-staleness-results.json) { + $report = Get-Content logs/sha-staleness-results.json | ConvertFrom-Json + $staleCount = ($report.Dependencies | Where-Object { $_.DaysOld -gt $thresholdDays } | Measure-Object).Count + "stale-count=$staleCount" >> $env:GITHUB_OUTPUT + "has-stale=$(if ($staleCount -gt 0) { 'true' } else { 'false' })" >> $env:GITHUB_OUTPUT + + Write-Host "Stale Dependencies Found: $staleCount" + + # Fire warnings for each stale dependency + foreach ($staleDep in $report.Dependencies) { + if ($staleDep.DaysOld -gt $thresholdDays) { + Write-Output "::warning file=$($staleDep.File)::Stale SHA detected: $($staleDep.Action)@$($staleDep.CurrentVersion) is $($staleDep.DaysOld) days old (latest: $($staleDep.LatestVersion))" + } + } + } else { + "stale-count=0" >> $env:GITHUB_OUTPUT + "has-stale=false" >> $env:GITHUB_OUTPUT + } + + if ($LASTEXITCODE -ne 0) { + Write-Warning "Some GitHub Actions have stale SHA pins. Review the warnings above." + Write-Host "::warning::GitHub Actions with stale SHA pins detected. This is informational only - no action required immediately." + } else { + Write-Host "All GitHub Actions SHA pins are up to date." + } + + - name: Upload staleness report + if: always() + uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v4.4.3 + with: + name: sha-staleness-results + path: logs/sha-staleness-results.json + retention-days: 90 diff --git a/.github/workflows/weekly-security-maintenance.yml b/.github/workflows/weekly-security-maintenance.yml new file mode 100644 index 00000000..2dba099e --- /dev/null +++ b/.github/workflows/weekly-security-maintenance.yml @@ -0,0 +1,195 @@ +name: Weekly Security Maintenance + +on: + schedule: + - cron: '0 2 * * 0' # Sundays at 2 AM UTC + workflow_dispatch: + inputs: + max-age-days: + description: 'Maximum SHA age in days before considered stale' + required: false + type: number + default: 30 + +permissions: + contents: read + security-events: write + +jobs: + # Job 1: Validate all dependencies are SHA-pinned + validate-pinning: + name: Validate SHA Pinning Compliance + uses: ./.github/workflows/dependency-pinning-scan.yml + permissions: + contents: read + security-events: write + with: + soft-fail: true + upload-sarif: true + upload-artifact: true + + # Job 2: Check for stale SHA pins + check-staleness: + name: Check SHA Staleness + uses: ./.github/workflows/sha-staleness-check.yml + permissions: + contents: read + with: + max-age-days: ${{ inputs.max-age-days || 30 }} + + # Job 3: Run CodeQL security analysis + codeql-scan: + name: CodeQL Security Analysis + uses: ./.github/workflows/codeql-analysis.yml + permissions: + contents: read + security-events: write + actions: read + + # Job 4: Generate consolidated summary + summary: + name: Security Maintenance Summary + needs: [validate-pinning, check-staleness, codeql-scan] + if: always() + runs-on: ubuntu-latest + permissions: + contents: read + steps: + - name: Generate summary + shell: pwsh + run: | + $pinningScore = '${{ needs.validate-pinning.outputs.compliance-score }}' + $unpinnedCount = '${{ needs.validate-pinning.outputs.unpinned-count }}' + $staleCount = '${{ needs.check-staleness.outputs.stale-count }}' + $codeqlResult = '${{ needs.codeql-scan.result }}' + + # Determine overall status + $hasIssues = $false + if ($unpinnedCount -ne '0') { $hasIssues = $true } + if ($staleCount -ne '0') { $hasIssues = $true } + + @" + # 🔐 Weekly Security Maintenance Report + + **Execution Time:** $(Get-Date -Format 'yyyy-MM-dd HH:mm:ss UTC') + **Trigger:** ${{ github.event_name }} + + ## 📊 Dependency Health + + | Metric | Status | Details | + |--------|--------|---------| + | SHA Pinning Compliance | $(if ($unpinnedCount -eq '0') { '✅ Pass' } else { '⚠ī¸ Warning' }) | Score: $pinningScore% | + | Unpinned Dependencies | $(if ($unpinnedCount -eq '0') { '✅ None' } else { "⚠ī¸ $unpinnedCount found" }) | $(if ($unpinnedCount -ne '0') { 'Review warnings above' } else { 'All pinned' }) | + | Stale SHAs (>${{ inputs.max-age-days }} days) | $(if ($staleCount -eq '0') { '✅ None' } else { "⚠ī¸ $staleCount found" }) | $(if ($staleCount -ne '0') { 'Review warnings above' } else { 'All current' }) | + + ## 🛡ī¸ Security Analysis + + | Component | Status | + |-----------|--------| + | CodeQL Analysis | $(if ($codeqlResult -eq 'success') { '✅ Complete' } else { '⚠ī¸ See details' }) | + | Secret Scanning | ✅ Enabled (GitHub native) | + | Dependabot Alerts | ✅ Enabled (GitHub native) | + + $(if ($unpinnedCount -ne '0') { + @" + + ## ⚠ī¸ Action Required: Unpinned Dependencies + + **$unpinnedCount dependencies are not SHA-pinned.** This is a security risk. + + **To fix:** + ``````powershell + # Review the warnings above, then pin each dependency to a SHA + # Example: Change 'uses: actions/checkout@v4' to 'uses: actions/checkout@71cf2267d89c5cb81562390fa70a37fa40b1305e # v4.2.2' + `````` + + "@ + }) + + $(if ($staleCount -ne '0') { + # Load the staleness report to show details + # Note: Artifacts are not automatically shared between jobs + # This will only work if the file exists in the runner's filesystem + # Consider using job outputs or downloading artifacts explicitly + $stalenessReport = if (Test-Path 'logs/sha-staleness-results.json') { + Get-Content 'logs/sha-staleness-results.json' | ConvertFrom-Json + } + + $thresholdDays = ${{ inputs.max-age-days || 30 }} + $staleDetails = "" + if ($stalenessReport -and $stalenessReport.Dependencies) { + foreach ($staleDep in $stalenessReport.Dependencies) { + if ($staleDep.DaysOld -gt $thresholdDays) { + $staleDetails += "- **$($staleDep.File)**: $($staleDep.Action)@$($staleDep.CurrentVersion) ($($staleDep.DaysOld) days old, latest: $($staleDep.LatestVersion))`n" + } + } + } + + @" + + ## ℹī¸ Recommended: Update Stale SHAs + + **$staleCount SHA pins are outdated (>${{ inputs.max-age-days || 30 }} days old).** Consider updating them. + + $staleDetails + + **To update:** + ``````powershell + # Run the update script to get latest SHAs + scripts/security/Update-ActionSHAPinning.ps1 -Path .github/workflows -UpdateStale + `````` + + "@ + }) + + $(if (!$hasIssues) { + @" + + ## ✅ All Clear! + + Repository security posture is excellent: + - All dependencies are SHA-pinned + - All SHAs are current (< ${{ inputs.max-age-days || 30 }} days old) + - CodeQL analysis completed successfully + - GitHub Secret Scanning and Dependabot actively monitoring + + "@ + }) + + --- + + đŸ“Ĩ **Detailed Reports:** Download artifacts from this workflow run + 🔗 **Workflow Run:** ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} + + $(if ($hasIssues) { + @" + + ### 📋 Next Steps + + 1. Review the build warnings generated in this workflow run + 2. For unpinned dependencies: Pin them to SHAs immediately (security risk) + 3. For stale SHAs (>${{ inputs.max-age-days }} days): Update them when convenient (maintenance task) + 4. Download the JSON report artifacts for detailed analysis + + "@ + }) + "@ | Out-File -FilePath $env:GITHUB_STEP_SUMMARY -Encoding UTF8 + + - name: Set workflow conclusion + shell: pwsh + run: | + $unpinnedCount = '${{ needs.validate-pinning.outputs.unpinned-count }}' + $staleCount = '${{ needs.check-staleness.outputs.stale-count }}' + + # Informational output - workflow succeeds but logs warnings + if ($unpinnedCount -ne '0') { + Write-Output "::warning::Found $unpinnedCount unpinned dependencies. Review build warnings for details." + } + + if ($staleCount -ne '0') { + Write-Output "::warning::Found $staleCount stale SHA pins (>${{ inputs.max-age-days || 30 }} days old). Consider updating them." + } + + if ($unpinnedCount -eq '0' -and $staleCount -eq '0') { + Write-Output "::notice::All dependencies are properly pinned and up-to-date!" + } diff --git a/.gitleaks.toml b/.gitleaks.toml deleted file mode 100644 index ddc0ae4b..00000000 --- a/.gitleaks.toml +++ /dev/null @@ -1,11 +0,0 @@ -title = "HVE Core Gitleaks Config" - -[extend] -useDefault = true - -[allowlist] -description = "Allowlist for false positives" -paths = [ - '''node_modules/''', - '''package-lock.json''', -]