Codeql

CodeQL for .NET

Trigger On

• the repo uses or wants CodeQL for .NET security analysis
• GitHub code scanning is part of the CI plan

Value

• produce a concrete project delta: code, docs, config, tests, CI, or review artifact
• reduce ambiguity through explicit planning, verification, and final validation skills
• leave reusable project context so future tasks are faster and safer

Do Not Use For

• teams that need a tool with no private-repo licensing caveat

Inputs

• the nearest AGENTS.md
• hosting model: open-source repo, private repo, or manual CLI workflow
• current GitHub Actions workflow

Quick Start

1. Read the nearest AGENTS.md and confirm scope and constraints. 2. Run this skill's Workflow through the Ralph Loop until outcomes are acceptable. 3. Return the Required Result Format with concrete artifacts and verification evidence.

Workflow

1. Treat CodeQL as a security-analysis tool, not as a style checker. 2. Make the licensing and hosting model explicit before proposing it as the default gate. 3. Prefer manual build mode for compiled .NET projects when precision matters.

Bootstrap When Missing

If CodeQL is not configured yet:

1. Detect current state:

• rg -n "codeql-action|security-events|CodeQL" .github/workflows
• command -v codeql

2. Prefer CI-first setup for repository scanning using github/codeql-action/init and github/codeql-action/analyze. 3. Configure explicit .NET build mode in workflow (manual when precision matters). 4. Add local CLI usage only when the task requires local query work. 5. Run the workflow or local analyze path and return status: configured or status: improved. 6. If licensing or hosting constraints reject CodeQL for this repo, return status: not_applicable with caveat documented.

Deliver

• explicit CodeQL setup or an explicit rejection with caveat documented
• reproducible CI or local commands for running CodeQL in this repo

Validate

• the chosen CodeQL path is allowed for the repo type
• build mode is documented and reproducible

Ralph Loop

Use the Ralph Loop for every task, including docs, architecture, testing, and tooling work.

1. Plan first (mandatory):

• analyze current state
• define target outcome, constraints, and risks
• write a detailed execution plan
• list final validation skills to run at the end, with order and reason

2. Execute one planned step and produce a concrete delta. 3. Review the result and capture findings with actionable next fixes. 4. Apply fixes in small batches and rerun the relevant checks or review steps. 5. Update the plan after each iteration. 6. Repeat until outcomes are acceptable or only explicit exceptions remain. 7. If a dependency is missing, bootstrap it or return status: not_applicable with explicit reason and fallback path.

Required Result Format

• status: complete | clean | improved | configured | not_applicable | blocked
• plan: concise plan and current iteration step
• actions_taken: concrete changes made
• validation_skills: final skills run, or skipped with reasons
• verification: commands, checks, or review evidence summary
• remaining: top unresolved items or none

For setup-only requests with no execution, return status: configured and exact next commands.

Load References

• references/codeql.md
• references/queries.md
• references/workflow.md

Example Requests

• "Set up CodeQL for this public .NET repo."
• "Explain the CodeQL caveat for private repos."

CodeQL

Open/Free Status

• open-source query packs and tooling exist
• usable on open-source codebases
• important caveat: GitHub-hosted scanning for private repositories is not universally free and may require GitHub Advanced Security

Install

For GitHub Actions, use the official action:

• github/codeql-action/init
• github/codeql-action/analyze

For CLI and query work on open-source codebases, use the CodeQL bundle and CLI from the official CodeQL docs and releases.

Verify First

Before proposing install steps, check whether the repo already has CodeQL configured:

rg -n "codeql-action|security-events|CodeQL" .github/workflows
command -v codeql

Common Usage

Typical GitHub Actions flow:

1. initialize CodeQL 2. build the .NET project in manual or autobuild mode 3. analyze and upload results

CI Fit

• strong fit for security scanning
• best used with explicit build mode for compiled .NET repos
• document the private-repo licensing caveat before standardizing on it

When Not To Use

• when the team requires a tool that is unambiguously open/free for private repos without platform caveats

Sources

• CodeQL tools
• CodeQL Action
• About code scanning with CodeQL

Common CodeQL Queries for .NET

Built-in Query Suites

CodeQL ships with pre-built query suites for C#/.NET security analysis.

Default Security Suites

# In your CodeQL workflow
queries:
  - uses: security-extended
  - uses: security-and-quality

Available suites for csharp:

Common Security Queries

SQL Injection

Query ID: cs/sql-injection

Detects unsanitized user input flowing into SQL queries.

// Vulnerable pattern detected:
string query = "SELECT * FROM Users WHERE Name = '" + userInput + "'";
cmd.CommandText = query;

// Safe pattern:
cmd.CommandText = "SELECT * FROM Users WHERE Name = @name";
cmd.Parameters.AddWithValue("@name", userInput);

Path Injection

Query ID: cs/path-injection

Detects file path manipulation from user input.

// Vulnerable pattern detected:
string path = Path.Combine(basePath, userInput);
File.ReadAllText(path);

// Safe pattern:
string safePath = Path.GetFullPath(Path.Combine(basePath, userInput));
if (!safePath.StartsWith(Path.GetFullPath(basePath)))
    throw new SecurityException("Path traversal detected");

Cross-Site Scripting (XSS)

Query ID: cs/web/xss

Detects unencoded user input in web responses.

// Vulnerable pattern detected:
Response.Write(userInput);

// Safe pattern:
Response.Write(HttpUtility.HtmlEncode(userInput));

Insecure Deserialization

Query ID: cs/unsafe-deserialization-untrusted-input

Detects dangerous deserialization of untrusted data.

// Vulnerable pattern detected:
BinaryFormatter formatter = new BinaryFormatter();
object obj = formatter.Deserialize(untrustedStream);

// Safe pattern:
// Use System.Text.Json or explicitly typed serializers
var obj = JsonSerializer.Deserialize<MyType>(jsonString);

Hardcoded Credentials

Query ID: cs/hardcoded-credentials

Detects passwords and secrets in source code.

// Vulnerable pattern detected:
string connectionString = "Server=db;Password=secret123;";

// Safe pattern:
string connectionString = configuration.GetConnectionString("Default");

LDAP Injection

Query ID: cs/ldap-injection

Detects unsanitized input in LDAP queries.

// Vulnerable pattern detected:
string filter = "(uid=" + userInput + ")";
searcher.Filter = filter;

// Safe pattern:
string safeInput = userInput.Replace("\\", "\\5c").Replace("*", "\\2a");
string filter = "(uid=" + safeInput + ")";

Command Injection

Query ID: cs/command-line-injection

Detects OS command injection vulnerabilities.

// Vulnerable pattern detected:
Process.Start("cmd.exe", "/c " + userInput);

// Safe pattern:
var psi = new ProcessStartInfo("myapp.exe");
psi.ArgumentList.Add(userInput);  // Properly escaped
Process.Start(psi);

XML External Entity (XXE)

Query ID: cs/xml/insecure-dtd-handling

Detects insecure XML parsing configurations.

// Vulnerable pattern detected:
XmlReaderSettings settings = new XmlReaderSettings();
settings.DtdProcessing = DtdProcessing.Parse;

// Safe pattern:
XmlReaderSettings settings = new XmlReaderSettings();
settings.DtdProcessing = DtdProcessing.Prohibit;
settings.XmlResolver = null;

Running Custom Queries

CLI Query Execution

# Run a specific query
codeql query run path/to/query.ql --database=my-csharp-db

# Run a query suite
codeql database analyze my-csharp-db csharp-security-extended.qls \
  --format=sarif-latest \
  --output=results.sarif

Query Pack Installation

# Download standard query packs
codeql pack download codeql/csharp-queries

# List available queries
codeql resolve queries codeql/csharp-queries

Custom Query Example

Create a custom query to find specific patterns:

/**
 * @name Find Console.WriteLine calls
 * @description Finds all Console.WriteLine method calls
 * @kind problem
 * @problem.severity recommendation
 * @id custom/find-console-writeline
 */

import csharp

from MethodCall mc
where mc.getTarget().hasQualifiedName("System.Console", "WriteLine")
select mc, "Console.WriteLine call found"

Save as custom-queries/find-console.ql and run:

codeql query run custom-queries/find-console.ql --database=my-csharp-db

Filtering Results

Severity Levels

• error - Critical security issues
• warning - Potential security concerns
• recommendation - Code quality improvements
• note - Informational findings

Excluding False Positives

Create a .github/codeql/codeql-config.yml:

name: "Custom CodeQL Config"

queries:
  - uses: security-extended

paths-ignore:
  - "**/Tests/**"
  - "**/test/**"
  - "**/*.Designer.cs"
  - "**/Migrations/**"

query-filters:
  - exclude:
      id: cs/hardcoded-credentials
      tags contain: test

Sources

• CodeQL for C# documentation
• C# CodeQL queries on GitHub
• CodeQL query help

CodeQL GitHub Actions Setup for .NET

Basic Workflow

Create .github/workflows/codeql.yml:

name: "CodeQL"

on:
  push:
    branches: [main, master]
  pull_request:
    branches: [main, master]
  schedule:
    - cron: '30 5 * * 1'  # Weekly Monday 5:30 AM UTC

jobs:
  analyze:
    name: Analyze
    runs-on: ubuntu-latest
    permissions:
      actions: read
      contents: read
      security-events: write

    strategy:
      fail-fast: false
      matrix:
        language: ['csharp']

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Initialize CodeQL
        uses: github/codeql-action/init@v3
        with:
          languages: ${{ matrix.language }}

      - name: Setup .NET
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '8.0.x'

      - name: Build
        run: dotnet build --configuration Release

      - name: Perform CodeQL Analysis
        uses: github/codeql-action/analyze@v3
        with:
          category: "/language:${{ matrix.language }}"

Build Modes

Manual Build (Recommended for .NET)

Explicit control over the build process:

- name: Initialize CodeQL
  uses: github/codeql-action/init@v3
  with:
    languages: csharp
    build-mode: manual

- name: Build
  run: |
    dotnet restore
    dotnet build --no-restore --configuration Release

Autobuild

Let CodeQL detect and run the build:

- name: Initialize CodeQL
  uses: github/codeql-action/init@v3
  with:
    languages: csharp
    build-mode: autobuild

Autobuild limitations:

• May not find all projects in complex solutions
• Custom build steps are not executed
• May miss conditional compilation

None (Interpreted Languages Only)

Not applicable for C#/.NET compiled code.

Advanced Configuration

Custom Query Suite

Create .github/codeql/codeql-config.yml:

name: "Custom CodeQL Config"

queries:
  - uses: security-extended
  - uses: security-and-quality

paths:
  - src

paths-ignore:
  - "**/Tests/**"
  - "**/*.Designer.cs"
  - "**/Migrations/**"
  - "**/obj/**"
  - "**/bin/**"

Reference in workflow:

- name: Initialize CodeQL
  uses: github/codeql-action/init@v3
  with:
    languages: csharp
    config-file: .github/codeql/codeql-config.yml

Multi-Project Solutions

For solutions with multiple projects:

- name: Build Solution
  run: |
    dotnet restore MySolution.sln
    dotnet build MySolution.sln --no-restore -c Release

# Or build specific projects
- name: Build Projects
  run: |
    dotnet build src/Api/Api.csproj -c Release
    dotnet build src/Core/Core.csproj -c Release

.NET Framework Projects

For legacy .NET Framework:

jobs:
  analyze:
    runs-on: windows-latest

    steps:
      - uses: actions/checkout@v4

      - name: Initialize CodeQL
        uses: github/codeql-action/init@v3
        with:
          languages: csharp
          build-mode: manual

      - name: Setup MSBuild
        uses: microsoft/setup-msbuild@v2

      - name: Setup NuGet
        uses: NuGet/setup-nuget@v2

      - name: Restore NuGet packages
        run: nuget restore MySolution.sln

      - name: Build
        run: msbuild MySolution.sln /p:Configuration=Release

      - name: Perform CodeQL Analysis
        uses: github/codeql-action/analyze@v3

Workflow Triggers

On Pull Request

on:
  pull_request:
    branches: [main]
    paths:
      - '**.cs'
      - '**.csproj'
      - '**.sln'

Scheduled Scans

on:
  schedule:
    # Daily at 2 AM UTC
    - cron: '0 2 * * *'

Manual Trigger

on:
  workflow_dispatch:
    inputs:
      query-suite:
        description: 'Query suite to use'
        required: false
        default: 'security-extended'

SARIF Upload and Results

Upload to GitHub Security Tab

Automatic with github/codeql-action/analyze:

- name: Perform CodeQL Analysis
  uses: github/codeql-action/analyze@v3
  with:
    category: "/language:csharp"
    output: sarif-results
    upload: always  # or 'failure-only' or 'never'

Upload Custom SARIF

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif
    category: "custom-analysis"

Artifact Storage

- name: Upload SARIF as artifact
  uses: actions/upload-artifact@v7
  with:
    name: sarif-results
    path: sarif-results
    retention-days: 5

Performance Optimization

Caching Dependencies

- name: Cache NuGet packages
  uses: actions/cache@v4
  with:
    path: ~/.nuget/packages
    key: ${{ runner.os }}-nuget-${{ hashFiles('**/*.csproj') }}
    restore-keys: |
      ${{ runner.os }}-nuget-

Parallel Analysis

strategy:
  fail-fast: false
  matrix:
    include:
      - project: src/Api/Api.csproj
        name: api
      - project: src/Web/Web.csproj
        name: web

Timeout Configuration

jobs:
  analyze:
    timeout-minutes: 60

Security Permissions

Minimum Required Permissions

permissions:
  actions: read        # Required for workflow runs
  contents: read       # Required to checkout code
  security-events: write  # Required to upload SARIF

For Pull Requests from Forks

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

Troubleshooting

Debug Logging

- name: Initialize CodeQL
  uses: github/codeql-action/init@v3
  with:
    languages: csharp
    debug: true

Build Failures

Check autobuild logs:

- name: Autobuild
  uses: github/codeql-action/autobuild@v3
  continue-on-error: true

- name: Manual build fallback
  if: failure()
  run: dotnet build

Database Verification

- name: Check database
  run: |
    ls -la ${{ runner.temp }}/codeql_databases/

Private Repository Licensing

For private repositories:

• GitHub Advanced Security license required for GitHub-hosted scanning
• Self-hosted runners with CodeQL CLI may have different licensing
• Verify licensing requirements with GitHub before enabling

Sources

• CodeQL Action documentation
• Configuring CodeQL scanning
• CodeQL CLI manual