codeql

package
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 10, 2026 License: GPL-3.0 Imports: 11 Imported by: 0

Documentation

Overview

Package codeql provides a scanner implementation for GitHub CodeQL. CodeQL provides full inter-procedural dataflow analysis and outputs SARIF with complete codeFlows for taint tracking.

Index

Constants

View Source 
const (
	// DefaultBinary is the default CodeQL CLI binary name.
	DefaultBinary = "codeql"

	// DefaultOutputFile is the default SARIF output file name.
	DefaultOutputFile = "codeql-results.sarif"

	// DefaultTimeout is the default scan timeout.
	DefaultTimeout = 60 * time.Minute

	// DefaultQuerySuite is the default security query suite.
	DefaultQuerySuite = "security-extended"
)

Variables

This section is empty.

Functions

func ParseSARIF 

func ParseSARIF(data []byte) ([]*ctis.Finding, error)

ParseSARIF parses CodeQL SARIF data to CTIS findings.

func ParseSARIFFile 

func ParseSARIFFile(path string) ([]*ctis.Finding, error)

ParseSARIFFile parses a CodeQL SARIF file to CTIS findings.

func ParseToCTIS 

func ParseToCTIS(data []byte, opts *core.ParseOptions) (*ctis.Report, error)

ParseToCTIS is a convenience function to parse CodeQL SARIF to CTIS format. This provides a consistent API with other scanner parsers (e.g., semgrep.ParseToCTIS).

Types

type Artifact 

type Artifact struct {
	Location       *ArtifactLocation `json:"location,omitempty"`
	Length         int               `json:"length,omitempty"`
	MimeType       string            `json:"mimeType,omitempty"`
	Encoding       string            `json:"encoding,omitempty"`
	SourceLanguage string            `json:"sourceLanguage,omitempty"`
}

Artifact describes a file analyzed.

type ArtifactLocation 

type ArtifactLocation struct {
	URI       string `json:"uri,omitempty"`
	URIBaseID string `json:"uriBaseId,omitempty"`
	Index     int    `json:"index,omitempty"`
}

ArtifactLocation identifies a file.

type CodeFlow 

type CodeFlow struct {
	Message     *Message     `json:"message,omitempty"`
	ThreadFlows []ThreadFlow `json:"threadFlows"`
}

CodeFlow represents a complete data flow path (source → sink). This is the key structure for taint tracking in CodeQL.

type Database 

type Database struct {
	Path          string `json:"path"`
	Language      string `json:"language"`
	CreatedAt     string `json:"created_at,omitempty"`
	SourceRoot    string `json:"source_root,omitempty"`
	ExtractorName string `json:"extractor_name,omitempty"`
}

Database represents a CodeQL database.

type Driver 

type Driver struct {
	Name            string `json:"name"`
	Version         string `json:"version,omitempty"`
	SemanticVersion string `json:"semanticVersion,omitempty"`
	Rules           []Rule `json:"rules,omitempty"`
}

Driver describes the CodeQL driver/query pack.

type Language 

type Language string

Language represents a CodeQL-supported language. 

const (
	LanguageGo         Language = "go"
	LanguageJava       Language = "java"
	LanguageJavaScript Language = "javascript"
	LanguagePython     Language = "python"
	LanguageCPP        Language = "cpp"
	LanguageCSharp     Language = "csharp"
	LanguageRuby       Language = "ruby"
	LanguageSwift      Language = "swift"
)

func SupportedLanguages 

func SupportedLanguages() []Language

SupportedLanguages returns all CodeQL-supported languages.

func (Language) IsValid 

func (l Language) IsValid() bool

IsValid checks if the language is supported by CodeQL.

func (Language) String 

func (l Language) String() string

String returns the string representation of the language.

type Location 

type Location struct {
	ID               int               `json:"id,omitempty"`
	PhysicalLocation *PhysicalLocation `json:"physicalLocation,omitempty"`
	LogicalLocations []LogicalLocation `json:"logicalLocations,omitempty"`
	Message          *Message          `json:"message,omitempty"`
}

Location represents a location in source code.

type LogicalLocation 

type LogicalLocation struct {
	Name               string `json:"name,omitempty"`
	FullyQualifiedName string `json:"fullyQualifiedName,omitempty"`
	Kind               string `json:"kind,omitempty"` // function, method, class, module
	ParentIndex        int    `json:"parentIndex,omitempty"`
}

LogicalLocation represents a logical code location (function, class, etc).

type Message 

type Message struct {
	Text     string `json:"text,omitempty"`
	Markdown string `json:"markdown,omitempty"`
}

Message contains text content.

type Parser 

type Parser struct {
	// contains filtered or unexported fields
}

Parser converts CodeQL SARIF output to CTIS format.

func NewParser 

func NewParser() *Parser

NewParser creates a new CodeQL SARIF parser.

func (*Parser) Parse 

func (p *Parser) Parse(data []byte) ([]*ctis.Finding, error)

Parse parses CodeQL SARIF JSON output to CTIS findings.

func (*Parser) ParseToReport 

func (p *Parser) ParseToReport(data []byte) (*ctis.Report, error)

ParseToReport parses CodeQL SARIF to a complete CTIS report.

func (*Parser) ParseToReportWithOptions 

func (p *Parser) ParseToReportWithOptions(data []byte, opts *core.ParseOptions) (*ctis.Report, error)

ParseToReportWithOptions parses CodeQL SARIF to a complete CTIS report with options.

type PhysicalLocation 

type PhysicalLocation struct {
	ArtifactLocation *ArtifactLocation `json:"artifactLocation,omitempty"`
	Region           *Region           `json:"region,omitempty"`
	ContextRegion    *Region           `json:"contextRegion,omitempty"`
}

PhysicalLocation specifies a file location.

type QuerySuite 

type QuerySuite struct {
	Name        string   `json:"name"`
	Description string   `json:"description,omitempty"`
	Queries     []string `json:"queries"`
}

QuerySuite represents a collection of CodeQL queries.

type Region 

type Region struct {
	StartLine   int      `json:"startLine,omitempty"`
	StartColumn int      `json:"startColumn,omitempty"`
	EndLine     int      `json:"endLine,omitempty"`
	EndColumn   int      `json:"endColumn,omitempty"`
	Snippet     *Snippet `json:"snippet,omitempty"`
}

Region specifies a region within a file.

type Result 

type Result struct {
	RuleID              string            `json:"ruleId"`
	RuleIndex           int               `json:"ruleIndex,omitempty"`
	Level               string            `json:"level,omitempty"` // error, warning, note
	Kind                string            `json:"kind,omitempty"`  // fail, pass, review
	Message             Message           `json:"message"`
	Locations           []Location        `json:"locations,omitempty"`
	RelatedLocations    []Location        `json:"relatedLocations,omitempty"`
	CodeFlows           []CodeFlow        `json:"codeFlows,omitempty"`
	PartialFingerprints map[string]string `json:"partialFingerprints,omitempty"`
	Fingerprints        map[string]string `json:"fingerprints,omitempty"`
	Properties          map[string]any    `json:"properties,omitempty"`
}

Result represents a single CodeQL finding.

type Rule 

type Rule struct {
	ID                   string             `json:"id"`
	Name                 string             `json:"name,omitempty"`
	ShortDescription     *Message           `json:"shortDescription,omitempty"`
	FullDescription      *Message           `json:"fullDescription,omitempty"`
	DefaultConfiguration *RuleConfiguration `json:"defaultConfiguration,omitempty"`
	Properties           RuleProperties     `json:"properties,omitempty"`
	Help                 *Message           `json:"help,omitempty"`
}

Rule describes a CodeQL query rule.

type RuleConfiguration 

type RuleConfiguration struct {
	Level   string `json:"level,omitempty"` // error, warning, note
	Enabled bool   `json:"enabled,omitempty"`
}

RuleConfiguration contains default configuration for a rule.

type RuleProperties 

type RuleProperties struct {
	Tags             []string `json:"tags,omitempty"`
	Kind             string   `json:"kind,omitempty"`              // problem, path-problem
	Precision        string   `json:"precision,omitempty"`         // very-high, high, medium, low
	ProblemSeverity  string   `json:"problem.severity,omitempty"`  // error, warning, recommendation
	SecuritySeverity string   `json:"security-severity,omitempty"` // 0.0-10.0
	CWEIDs           []string `json:"cwe,omitempty"`
}

RuleProperties contains additional rule metadata.

type Run 

type Run struct {
	Tool      Tool       `json:"tool"`
	Results   []Result   `json:"results"`
	Artifacts []Artifact `json:"artifacts,omitempty"`
}

Run represents a single CodeQL analysis run.

type SARIFReport 

type SARIFReport struct {
	Schema  string `json:"$schema"`
	Version string `json:"version"`
	Runs    []Run  `json:"runs"`
}

SARIFReport represents a SARIF 2.1.0 report from CodeQL.

type Scanner 

type Scanner struct {
	// Configuration
	Binary     string        // Path to codeql binary (default: "codeql")
	OutputFile string        // Output file path (default: "codeql-results.sarif")
	Timeout    time.Duration // Scan timeout (default: 60 minutes)
	Verbose    bool          // Enable verbose output

	// CodeQL-specific options
	Language       Language // Target language (required)
	DatabasePath   string   // Path to CodeQL database (optional, will create if not provided)
	QueryPacks     []string // Query packs to use (default: security-extended)
	QueryFiles     []string // Specific .ql files to run
	Threads        int      // Number of threads (0 = auto)
	RAMPerThread   int      // RAM per thread in MB (0 = default)
	Format         string   // Output format (sarif-latest, csv, json)
	SkipDBCreation bool     // Skip database creation (use existing)
	// contains filtered or unexported fields
}

Scanner implements the SAST scanner interface for CodeQL. CodeQL provides full inter-procedural dataflow analysis, making it ideal for detecting vulnerabilities that require taint tracking across functions and files.

func NewFullScanner 

func NewFullScanner(lang Language) *Scanner

NewFullScanner creates a scanner that runs all available queries.

func NewQualityScanner 

func NewQualityScanner(lang Language) *Scanner

NewQualityScanner creates a scanner for code quality issues.

func NewScanner 

func NewScanner() *Scanner

NewScanner creates a new CodeQL scanner with default settings.

func NewSecurityScanner 

func NewSecurityScanner(lang Language) *Scanner

NewSecurityScanner creates a scanner focused on security vulnerabilities.

func (*Scanner) AnalyzeExistingDatabase 

func (s *Scanner) AnalyzeExistingDatabase(ctx context.Context, dbPath string, opts *core.ScanOptions) (*core.ScanResult, error)

AnalyzeExistingDatabase analyzes a pre-built CodeQL database.

func (*Scanner) Capabilities 

func (s *Scanner) Capabilities() []string

Capabilities returns the scanner capabilities.

func (*Scanner) IsInstalled 

func (s *Scanner) IsInstalled(ctx context.Context) (bool, string, error)

IsInstalled checks if CodeQL is installed.

func (*Scanner) Name 

func (s *Scanner) Name() string

Name returns the scanner name.

func (*Scanner) Scan 

func (s *Scanner) Scan(ctx context.Context, target string, opts *core.ScanOptions) (*core.ScanResult, error)

Scan performs a CodeQL scan on the target.

func (*Scanner) SetVerbose 

func (s *Scanner) SetVerbose(v bool)

SetVerbose enables/disables verbose output.

func (*Scanner) Type 

func (s *Scanner) Type() core.ScannerType

Type returns the scanner type.

func (*Scanner) Version 

func (s *Scanner) Version() string

Version returns the scanner version.

type Snippet 

type Snippet struct {
	Text string `json:"text,omitempty"`
}

Snippet contains the source code text.

type ThreadFlow 

type ThreadFlow struct {
	ID        string               `json:"id,omitempty"`
	Message   *Message             `json:"message,omitempty"`
	Locations []ThreadFlowLocation `json:"locations"`
}

ThreadFlow represents a sequence of code locations in a single thread.

type ThreadFlowLocation 

type ThreadFlowLocation struct {
	Index          int            `json:"index,omitempty"`
	Location       *Location      `json:"location,omitempty"`
	Kinds          []string       `json:"kinds,omitempty"` // source, sink, sanitizer
	NestingLevel   int            `json:"nestingLevel,omitempty"`
	ExecutionOrder int            `json:"executionOrder,omitempty"`
	Importance     string         `json:"importance,omitempty"` // essential, important, unimportant
	State          map[string]any `json:"state,omitempty"`
}

ThreadFlowLocation represents a single step in the data flow.

type Tool 

type Tool struct {
	Driver     Driver   `json:"driver"`
	Extensions []Driver `json:"extensions,omitempty"`
}

Tool describes the CodeQL tool.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.