add codeql static analysis workflow

[nam20485]

1. Scan files with codeql during CI
2. report results
3. gate further CI actions based on result (stop on errors)
4. full integration into GitHub's native security functionality

[traycerai]

Plan

Observations

The OdbDesign repository is a C++ project (C++17) with CMake build system, using vcpkg for dependencies. It has a mature CI/CD setup with file:.github/workflows/cmake-multi-platform.yml as the main build workflow running on Windows, Linux, and macOS. The project already integrates with GitHub's security features through file:.github/workflows/scorecard.yml (SARIF uploads) and file:.github/workflows/dependency-review.yml. The codebase includes minimal JavaScript (only file:scripts/create-release.js). All workflows follow security best practices with pinned action versions and step-security/harden-runner.

Approach

Create a dedicated CodeQL workflow file that runs static analysis on both C++ and JavaScript code during CI. The workflow will use CodeQL Action v4 with autobuild mode for C++ (to leverage the existing CMake build) and none mode for JavaScript. Results will be uploaded to GitHub's Security tab via SARIF format. To gate CI actions, configure the workflow to run as a required status check on pull requests, with repository settings configured to fail on High/Critical severity findings. The workflow will integrate seamlessly with existing security workflows and follow the project's established patterns.

Implementation Steps

1. Create CodeQL Workflow File

Create a new workflow file file:.github/workflows/codeql.yml with the following configuration:

Trigger Configuration:

• Run on push to branches: development, staging, main, release, nam20485
• Run on pull requests to the same branches
• Run on schedule (weekly, e.g., every Monday at 6:00 UTC) for continuous monitoring
• Support manual workflow dispatch

Permissions:

permissions:
  contents: read
  security-events: write
  pull-requests: read
  actions: read

Job Structure:
Create a single job named analyze that runs on ubuntu-24.04 with a matrix strategy for languages:

• Matrix dimensions: language: ['cpp', 'javascript']
• Set fail-fast: false to ensure both languages are analyzed even if one fails

2. Configure CodeQL Analysis Steps

Step 1: Harden Runner

• Use step-security/harden-runner@f4a75cfd619ee5ce8d5b864b0d183aff3c69b55a (v2.13.1) with egress-policy: audit to match existing workflows

Step 2: Checkout Repository

• Use actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 (v5.0.0) to match existing workflows

Step 3: Initialize CodeQL

• Use github/codeql-action/init@v4 (use latest v4 SHA hash)
• Configure with languages: ${{ matrix.language }}
• For C++, add queries configuration: queries: security-and-quality to run both security and code quality checks
• For JavaScript, use default queries

Step 4: Build Configuration (C++ only)

• Add conditional step: if: matrix.language == 'cpp'
• Install vcpkg dependencies similar to file:.github/workflows/cmake-multi-platform.yml:
  • Clone vcpkg repository
  • Bootstrap vcpkg
  • Install Ninja build system
  • Export vcpkg cache variables
• Run CMake configure: cmake --preset linux-release
• Run CMake build: cmake --build --preset linux-release
• This leverages the existing build configuration from file:CMakeLists.txt and file:CMakePresets.json

Step 5: Autobuild (JavaScript only)

• Add conditional step: if: matrix.language == 'javascript'
• Use github/codeql-action/autobuild@v4 for JavaScript (though it's minimal, this ensures consistency)

Step 6: Perform CodeQL Analysis

• Use github/codeql-action/analyze@v4
• Configure with category: "/language:${{ matrix.language }}"
• Set upload: true to upload SARIF results to GitHub Security tab
• Set output: sarif-results to save SARIF files as artifacts

Step 7: Upload SARIF Artifacts

• Use actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 (v4.6.2) to match existing workflows
• Upload SARIF files with name: codeql-results-${{ matrix.language }}
• Set retention to 30 days for compliance and debugging

3. Configure CI Gating

Repository Settings Configuration:

• Navigate to repository Settings → Security and Analysis → Code Scanning
• Enable "Check Runs" for CodeQL
• Configure failing commit status to block PRs on findings with severity:
  • Error severity
  • Security severity: Critical or High
• Optionally configure to fail on Medium severity based on project requirements

Branch Protection Rules:

• Add the CodeQL workflow (CodeQL / analyze (cpp) and CodeQL / analyze (javascript)) as required status checks for protected branches: development, staging, main, release
• This ensures PRs cannot be merged until CodeQL analysis passes

4. Integration with Existing Workflows

Coordinate with cmake-multi-platform.yml:

• The CodeQL workflow runs independently and in parallel with the main build workflow
• Both workflows will run on the same triggers (push/PR)
• CodeQL uses a single platform (Linux) for analysis to optimize CI time, while the main build workflow continues multi-platform testing

Align with Security Workflows:

• CodeQL results will appear in the same Security tab as Scorecard results from file:.github/workflows/scorecard.yml
• Both workflows use security-events: write permission
• SARIF upload format is consistent across security workflows

5. Documentation and Monitoring

Update Repository Documentation:

• Add a section to file:README-SETUP.md or create .github/workflows/README.md explaining:
  • CodeQL workflow purpose and triggers
  • How to view CodeQL results in the Security tab
  • How to address CodeQL findings
  • Link to CodeQL documentation for C++ and JavaScript

Configure Notifications:

• Ensure GitHub notifications are enabled for security alerts
• Configure Dependabot alerts integration (already present via file:.github/workflows/dependency-review.yml)

Monitoring:

• Review CodeQL alerts weekly via the Security tab
• Monitor workflow execution times and optimize if needed
• Review false positives and configure CodeQL query filters if necessary using .github/codeql/codeql-config.yml

6. Optional Advanced Configuration

Custom Query Suites (if needed):

• Create file:.github/codeql/codeql-config.yml to customize:
  • Exclude specific paths (e.g., OdbDesignTests/, vcpkg/, out/)
  • Add custom queries from github/codeql repository
  • Configure query filters to reduce false positives

SARIF Post-Processing:

• If additional reporting is needed, add a step to parse SARIF files and generate custom reports
• Use github/codeql-action/upload-sarif@v4 for manual SARIF uploads if needed

Workflow Diagram

sequenceDiagram
    participant Dev as Developer
    participant GH as GitHub
    participant CQL as CodeQL Workflow
    participant Build as Build Workflow
    participant Sec as Security Tab

    Dev->>GH: Push/PR to branch
    GH->>CQL: Trigger CodeQL workflow
    GH->>Build: Trigger build workflow (parallel)
    
    CQL->>CQL: Initialize CodeQL (C++ & JS)
    CQL->>CQL: Build C++ code (autobuild)
    CQL->>CQL: Analyze JavaScript (no build)
    CQL->>CQL: Perform CodeQL analysis
    CQL->>Sec: Upload SARIF results
    CQL->>GH: Report status (pass/fail)
    
    Build->>Build: Multi-platform build & test
    Build->>GH: Report status (pass/fail)
    
    alt CodeQL finds Critical/High issues
        GH->>Dev: Block PR merge (required check failed)
        Dev->>Dev: Fix security issues
        Dev->>GH: Push fixes
    else CodeQL passes
        GH->>Dev: Allow PR merge (if all checks pass)
    end
    
    Dev->>Sec: Review detailed findings

Loading

Expected Outcomes

1. Automated Security Scanning: Every push and PR will be scanned for security vulnerabilities and code quality issues in C++ and JavaScript
2. GitHub Security Integration: Results appear in the Security tab under Code Scanning alerts with full context and remediation guidance
3. CI Gating: PRs with Critical or High severity findings will be blocked from merging until issues are resolved
4. Continuous Monitoring: Weekly scheduled scans ensure ongoing security posture even without code changes
5. Compliance: SARIF artifacts retained for 30 days provide audit trail for security compliance

Import In IDE

🤖 Prompt for AI Agents

## Observations

The OdbDesign repository is a C++ project (C++17) with CMake build system, using vcpkg for dependencies. It has a mature CI/CD setup with `file:.github/workflows/cmake-multi-platform.yml` as the main build workflow running on Windows, Linux, and macOS. The project already integrates with GitHub's security features through `file:.github/workflows/scorecard.yml` (SARIF uploads) and `file:.github/workflows/dependency-review.yml`. The codebase includes minimal JavaScript (only `file:scripts/create-release.js`). All workflows follow security best practices with pinned action versions and step-security/harden-runner.

## Approach

Create a dedicated CodeQL workflow file that runs static analysis on both C++ and JavaScript code during CI. The workflow will use CodeQL Action v4 with `autobuild` mode for C++ (to leverage the existing CMake build) and `none` mode for JavaScript. Results will be uploaded to GitHub's Security tab via SARIF format. To gate CI actions, configure the workflow to run as a required status check on pull requests, with repository settings configured to fail on High/Critical severity findings. The workflow will integrate seamlessly with existing security workflows and follow the project's established patterns.

## Implementation Steps

### 1. Create CodeQL Workflow File

Create a new workflow file `file:.github/workflows/codeql.yml` with the following configuration:

**Trigger Configuration:**
- Run on push to branches: `development`, `staging`, `main`, `release`, `nam20485`
- Run on pull requests to the same branches
- Run on schedule (weekly, e.g., every Monday at 6:00 UTC) for continuous monitoring
- Support manual workflow dispatch

**Permissions:**
```yaml
permissions:
  contents: read
  security-events: write
  pull-requests: read
  actions: read
```

**Job Structure:**
Create a single job named `analyze` that runs on `ubuntu-24.04` with a matrix strategy for languages:
- Matrix dimensions: `language: ['cpp', 'javascript']`
- Set `fail-fast: false` to ensure both languages are analyzed even if one fails

### 2. Configure CodeQL Analysis Steps

**Step 1: Harden Runner**
- Use `step-security/harden-runner@f4a75cfd619ee5ce8d5b864b0d183aff3c69b55a` (v2.13.1) with `egress-policy: audit` to match existing workflows

**Step 2: Checkout Repository**
- Use `actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8` (v5.0.0) to match existing workflows

**Step 3: Initialize CodeQL**
- Use `github/codeql-action/init@v4` (use latest v4 SHA hash)
- Configure with `languages: ${{ matrix.language }}`
- For C++, add queries configuration: `queries: security-and-quality` to run both security and code quality checks
- For JavaScript, use default queries

**Step 4: Build Configuration (C++ only)**
- Add conditional step: `if: matrix.language == 'cpp'`
- Install vcpkg dependencies similar to `file:.github/workflows/cmake-multi-platform.yml`:
  - Clone vcpkg repository
  - Bootstrap vcpkg
  - Install Ninja build system
  - Export vcpkg cache variables
- Run CMake configure: `cmake --preset linux-release`
- Run CMake build: `cmake --build --preset linux-release`
- This leverages the existing build configuration from `file:CMakeLists.txt` and `file:CMakePresets.json`

**Step 5: Autobuild (JavaScript only)**
- Add conditional step: `if: matrix.language == 'javascript'`
- Use `github/codeql-action/autobuild@v4` for JavaScript (though it's minimal, this ensures consistency)

**Step 6: Perform CodeQL Analysis**
- Use `github/codeql-action/analyze@v4`
- Configure with `category: "/language:${{ matrix.language }}"`
- Set `upload: true` to upload SARIF results to GitHub Security tab
- Set `output: sarif-results` to save SARIF files as artifacts

**Step 7: Upload SARIF Artifacts**
- Use `actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02` (v4.6.2) to match existing workflows
- Upload SARIF files with name: `codeql-results-${{ matrix.language }}`
- Set retention to 30 days for compliance and debugging

### 3. Configure CI Gating

**Repository Settings Configuration:**
- Navigate to repository Settings → Security and Analysis → Code Scanning
- Enable "Check Runs" for CodeQL
- Configure failing commit status to block PRs on findings with severity:
  - Error severity
  - Security severity: Critical or High
- Optionally configure to fail on Medium severity based on project requirements

**Branch Protection Rules:**
- Add the CodeQL workflow (`CodeQL / analyze (cpp)` and `CodeQL / analyze (javascript)`) as required status checks for protected branches: `development`, `staging`, `main`, `release`
- This ensures PRs cannot be merged until CodeQL analysis passes

### 4. Integration with Existing Workflows

**Coordinate with cmake-multi-platform.yml:**
- The CodeQL workflow runs independently and in parallel with the main build workflow
- Both workflows will run on the same triggers (push/PR)
- CodeQL uses a single platform (Linux) for analysis to optimize CI time, while the main build workflow continues multi-platform testing

**Align with Security Workflows:**
- CodeQL results will appear in the same Security tab as Scorecard results from `file:.github/workflows/scorecard.yml`
- Both workflows use `security-events: write` permission
- SARIF upload format is consistent across security workflows

### 5. Documentation and Monitoring

**Update Repository Documentation:**
- Add a section to `file:README-SETUP.md` or create `.github/workflows/README.md` explaining:
  - CodeQL workflow purpose and triggers
  - How to view CodeQL results in the Security tab
  - How to address CodeQL findings
  - Link to CodeQL documentation for C++ and JavaScript

**Configure Notifications:**
- Ensure GitHub notifications are enabled for security alerts
- Configure Dependabot alerts integration (already present via `file:.github/workflows/dependency-review.yml`)

**Monitoring:**
- Review CodeQL alerts weekly via the Security tab
- Monitor workflow execution times and optimize if needed
- Review false positives and configure CodeQL query filters if necessary using `.github/codeql/codeql-config.yml`

### 6. Optional Advanced Configuration

**Custom Query Suites (if needed):**
- Create `file:.github/codeql/codeql-config.yml` to customize:
  - Exclude specific paths (e.g., `OdbDesignTests/`, `vcpkg/`, `out/`)
  - Add custom queries from `github/codeql` repository
  - Configure query filters to reduce false positives

**SARIF Post-Processing:**
- If additional reporting is needed, add a step to parse SARIF files and generate custom reports
- Use `github/codeql-action/upload-sarif@v4` for manual SARIF uploads if needed

## Workflow Diagram

```mermaid
sequenceDiagram
    participant Dev as Developer
    participant GH as GitHub
    participant CQL as CodeQL Workflow
    participant Build as Build Workflow
    participant Sec as Security Tab

    Dev->>GH: Push/PR to branch
    GH->>CQL: Trigger CodeQL workflow
    GH->>Build: Trigger build workflow (parallel)
    
    CQL->>CQL: Initialize CodeQL (C++ & JS)
    CQL->>CQL: Build C++ code (autobuild)
    CQL->>CQL: Analyze JavaScript (no build)
    CQL->>CQL: Perform CodeQL analysis
    CQL->>Sec: Upload SARIF results
    CQL->>GH: Report status (pass/fail)
    
    Build->>Build: Multi-platform build & test
    Build->>GH: Report status (pass/fail)
    
    alt CodeQL finds Critical/High issues
        GH->>Dev: Block PR merge (required check failed)
        Dev->>Dev: Fix security issues
        Dev->>GH: Push fixes
    else CodeQL passes
        GH->>Dev: Allow PR merge (if all checks pass)
    end
    
    Dev->>Sec: Review detailed findings
```

## Expected Outcomes

1. **Automated Security Scanning**: Every push and PR will be scanned for security vulnerabilities and code quality issues in C++ and JavaScript
2. **GitHub Security Integration**: Results appear in the Security tab under Code Scanning alerts with full context and remediation guidance
3. **CI Gating**: PRs with Critical or High severity findings will be blocked from merging until issues are resolved
4. **Continuous Monitoring**: Weekly scheduled scans ensure ongoing security posture even without code changes
5. **Compliance**: SARIF artifacts retained for 30 days provide audit trail for security compliance

---

Execution Information

Branch: development
Commit: d9df51e

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.