awesome-copilot/skills/codeql/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).

• Specification: OASIS SARIF v2.1.0
• Schema: sarif-schema-2.1.0.json
• Format type: sarifv2.1.0 (passed to --format flag)

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