AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

codeql

Comprehensive guide for setting up and configuring CodeQL code scanning via GitHub Actions workflows and the CodeQL CLI. This skill should be used when users need help with code scanning configuration, CodeQL workflow files, CodeQL CLI commands, SARIF output, security analysis setup, or troubleshooting CodeQL analysis.

Original source
github
License
MIT
Pinned revision
5269f7ea2d6c3a9bfda5ed878b6726cf509121fd

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read github--codeql at revision 5269f7ea2d6c3a9bfda5ed878b6726cf509121fd, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 7

references/sarif-output.md

CodeQL SARIF Output Reference

Detailed reference for the SARIF v2.1.0 output produced by CodeQL analysis. Use this when interpreting or processing CodeQL scan results.

About SARIF

SARIF (Static Analysis Results Interchange Format) is a standardized JSON format for representing static analysis tool output. CodeQL produces SARIF v2.1.0 (specification: sarifv2.1.0).

Top-Level Structure

sarifLog Object

| Property | Always Generated | Description | |---|:---:|---| | $schema | ✅ | Link to the SARIF schema | | version | ✅ | SARIF specification version ("2.1.0") | | runs | ✅ | Array containing a single run object per language |

run Object

| Property | Always Generated | Description | |---|:---:|---| | tool | ✅ | Tool information (toolComponent) | | artifacts | ✅ | Array of artifact objects for every file referenced in a result | | results | ✅ | Array of result objects | | newLineSequences | ✅ | Newline character sequences | | columnKind | ✅ | Column counting method | | properties | ✅ | Contains semmle.formatSpecifier identifying the format |

Tool Information

tool Object

Contains a single driver property.

toolComponent Object (Driver)

| Property | Always Generated | Description | |---|:---:|---| | name | ✅ | "CodeQL command-line toolchain" | | organization | ✅ | "GitHub" | | version | ✅ | CodeQL release version (e.g., "2.19.0") | | rules | ✅ | Array of reportingDescriptor objects for available/run rules |

Rules

reportingDescriptor Object (Rule)

| Property | Always Generated | Description | |---|:---:|---| | id | ✅ | Rule identifier from @id query property (e.g., cpp/unsafe-format-string). Uses @opaqueid if defined. | | name | ✅ | Same as @id property from the query | | shortDescription | ✅ | From @name query property | | fullDescription | ✅ | From @description query property | | defaultConfiguration | ❌ | reportingConfiguration with enabled (true/false) and level based on @severity. Omitted if no @severity specified. |

Severity Mapping

| CodeQL @severity | SARIF level | |---|---| | error | error | | warning | warning | | recommendation | note |

Results

result Object

By default, results are grouped by unique message format string and primary location. Two results at the same location with the same message appear as a single result. Disable grouping with --ungroup-results.

| Property | Always Generated | Description | |---|:---:|---| | ruleId | ✅ | Rule identifier (matches reportingDescriptor.id) | | ruleIndex | ✅ | Index into the rules array | | message | ✅ | Problem description. May contain SARIF "Message with placeholder" linking to relatedLocations. | | locations | ✅ | Array containing a single location object | | partialFingerprints | ✅ | Dictionary with at least primaryLocationLineHash for deduplication | | codeFlows | ❌ | Populated for @kind path-problem queries with one or more codeFlow objects | | relatedLocations | ❌ | Populated when message has placeholder options; each unique location included once | | suppressions | ❌ | If suppressed: single suppression object with @kind: IN_SOURCE. If not suppressed but other results are: empty array. Otherwise: not set. |

Fingerprints

partialFingerprints contains:

  • primaryLocationLineHash — fingerprint based on the context of the primary location

Used by GitHub to track alerts across commits and avoid duplicate notifications.

Locations

location Object

| Property | Always Generated | Description | |---|:---:|---| | physicalLocation | ✅ | Physical file location | | id | ❌ | Present in relatedLocations array | | message | ❌ | Present in relatedLocations and threadFlowLocation.location |

physicalLocation Object

| Property | Always Generated | Description | |---|:---:|---| | artifactLocation | ✅ | File reference | | region | ❌ | Present for text file locations | | contextRegion | ❌ | Present when location has an associated snippet |

region Object

Two types of regions may be produced:

Line/Column Offset Regions:

| Property | Always Generated | Description | |---|:---:|---| | startLine | ✅ | Starting line number | | startColumn | ❌ | Omitted if equal to default value of 1 | | endLine | ❌ | Omitted if identical to startLine | | endColumn | ✅ | Ending column number | | snippet | ❌ | Source code snippet |

Character Offset Regions:

| Property | Always Generated | Description | |---|:---:|---| | charOffset | ✅ | Character offset from start of file | | charLength | ✅ | Length in characters | | snippet | ❌ | Source code snippet |

Consumers should handle both region types robustly.

Artifacts

artifact Object

| Property | Always Generated | Description | |---|:---:|---| | location | ✅ | artifactLocation object | | index | ✅ | Index of the artifact | | contents | ❌ | Populated with artifactContent when using --sarif-add-file-contents |

artifactLocation Object

| Property | Always Generated | Description | |---|:---:|---| | uri | ✅ | File path (relative or absolute) | | index | ✅ | Index reference | | uriBaseId | ❌ | Set when file is relative to a known abstract location (e.g., source root) |

Code Flows (Path Problems)

For queries of @kind path-problem, results include code flow information showing the data flow path.

codeFlow Object

| Property | Always Generated | Description | |---|:---:|---| | threadFlows | ✅ | Array of threadFlow objects |

threadFlow Object

| Property | Always Generated | Description | |---|:---:|---| | locations | ✅ | Array of threadFlowLocation objects |

threadFlowLocation Object

| Property | Always Generated | Description | |---|:---:|---| | location | ✅ | A location object for this step in the flow |

Automation Details

The category value from github/codeql-action/analyze appears as <run>.automationDetails.id in the SARIF output.

Example:

{
  "automationDetails": {
    "id": "/language:javascript-typescript"
  }
}

Key CLI Flags for SARIF

| Flag | Effect | |---|---| | --format=sarif-latest | Produce SARIF v2.1.0 output | | --sarif-category=<cat> | Set automationDetails.id for result categorization | | --sarif-add-file-contents | Include source file content in artifact.contents | | --ungroup-results | Report every occurrence separately (no deduplication by location + message) | | --output=<file> | Write SARIF to specified file |

Third-Party SARIF Support

When uploading SARIF from non-CodeQL tools, ensure these properties are populated for best results on GitHub.

Recommended reportingDescriptor Properties

| Property | Required | Description | |---|:---:|---| | id | ✅ | Unique rule identifier | | name | ❌ | Rule name (max 255 chars) | | shortDescription.text | ✅ | Concise description (max 1024 chars) | | fullDescription.text | ✅ | Full description (max 1024 chars) | | defaultConfiguration.level | ❌ | Default severity: note, warning, error | | help.text | ✅ | Documentation in text format | | help.markdown | ❌ | Documentation in Markdown (displayed if available) | | properties.tags[] | ❌ | Tags for filtering (e.g., security) | | properties.precision | ❌ | very-high, high, medium, low — affects display ordering | | properties.problem.severity | ❌ | Non-security severity: error, warning, recommendation | | properties.security-severity | ❌ | Score 0.0–10.0 for security queries. Maps to: >9.0=critical, 7.0–8.9=high, 4.0–6.9=medium, 0.1–3.9=low |

Source File Location Requirements

  • Use relative paths (relative to repository root) when possible
  • Absolute URIs are converted to relative using the source root
  • Source root can be set via:
    • checkout_path input to github/codeql-action/analyze
    • checkout_uri parameter to SARIF upload API
    • invocations[0].workingDirectory.uri in the SARIF file
  • Consistent file paths are required across runs for fingerprint stability
  • Symlinked files must use resolved (non-symlink) URIs

Fingerprint Requirements

  • partialFingerprints with primaryLocationLineHash prevents duplicate alerts across commits
  • CodeQL SARIF automatically includes fingerprints
  • Third-party SARIF: the upload-sarif action computes fingerprints if missing
  • API uploads without fingerprints may produce duplicate alerts

Upload Limits

File Size

  • Maximum: 10 MB (gzip-compressed)
  • If too large: reduce query scope, remove --sarif-add-file-contents, or split into multiple uploads

Object Count Limits

| Object | Maximum | |---|---| | Runs per file | 20 | | Results per run | 25,000 | | Rules per run | 25,000 | | Tool extensions per run | 100 | | Thread flow locations per result | 10,000 | | Locations per result | 1,000 | | Tags per rule | 20 |

Files exceeding these limits are rejected. Split analysis across multiple SARIF uploads with different --sarif-category values.

Validation

Validate SARIF files before upload using the Microsoft SARIF validator.

Backwards Compatibility

  • Fields marked "always generated" will never be removed in future versions
  • Fields not always generated may change circumstances under which they appear
  • New fields may be added without breaking changes
  • Consumers should be robust to both presence and absence of optional fields