codeql

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. The SARIF is converted by the SDK's SARIF parser (the ctis importer), not here.

Index

• Constants
• Variables
• type Database
• type Language
  • func SupportedLanguages() []Language
  • func (l Language) IsValid() bool
  • func (l Language) String() string
• type QuerySuite
• type Scanner
  • func NewFullScanner(lang Language) *Scanner
  • func NewQualityScanner(lang Language) *Scanner
  • func NewScanner() *Scanner
  • func NewSecurityScanner(lang Language) *Scanner
  • func (s *Scanner) AnalyzeExistingDatabase(ctx context.Context, dbPath string, opts *core.ScanOptions) (*core.ScanResult, error)
  • func (s *Scanner) Capabilities() []string
  • func (s *Scanner) IsInstalled(ctx context.Context) (bool, string, error)
  • func (s *Scanner) Name() string
  • func (s *Scanner) RoutesEgress() bool
  • func (s *Scanner) Scan(ctx context.Context, target string, opts *core.ScanOptions) (*core.ScanResult, error)
  • func (s *Scanner) SetVerbose(v bool)
  • func (s *Scanner) SetVersion(v string)
  • func (s *Scanner) SettingsSchema() *core.SettingsSchema
  • func (s *Scanner) TakesCapabilityJobs() bool
  • func (s *Scanner) ToolContract() *core.ToolContract
  • func (s *Scanner) Type() core.ScannerType
  • func (s *Scanner) Version() string

Constants

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

var ContractTool = toolrun.Register(tool.New(ToolManifest, runTool))

ContractTool runs codeql in the tool child (Tool is the SARIF tool type).

var ToolManifest = toolrun.MustManifest(ToolYAML)

ToolManifest describes the codeql tool.

var ToolYAML []byte

ToolYAML is the tool's descriptor (OpenCTEM Tool Contract v1): the one place its contract is written. The sensor loads it at start and reports it to the platform by digest.

Types

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 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 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 Scanner

type Scanner struct {
	// Configuration
	Binary     string        // Path to codeql binary (default: "codeql")
	OutputFile string        // Report file: an absolute path is used as is; otherwise the base name, in a temporary directory removed after the scan
	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: when empty, built in a temporary directory removed after the scan)
	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) RoutesEgress

func (s *Scanner) RoutesEgress() bool

RoutesEgress reports whether a job's proxy pool carries every connection of the tool (core.EgressScanner): the tool runs out of process, behind the task forwarder; the in-process path would go direct, so a pooled job is refused there.

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.

The scan runs out of process, in the task sandbox (tool.go), unless SENSOR_TOOL_RUNTIME=in-process.

func (*Scanner) SetVerbose

func (s *Scanner) SetVerbose(v bool)

SetVerbose enables/disables verbose output.

func (*Scanner) SetVersion

func (s *Scanner) SetVersion(v string)

SetVersion sets the version IsInstalled found (a tool child that did not probe the binary itself reports the parent's).

func (*Scanner) SettingsSchema

func (s *Scanner) SettingsSchema() *core.SettingsSchema

SettingsSchema returns codeql's settings schema (core.SettingsSchemaProvider).

func (*Scanner) TakesCapabilityJobs

func (s *Scanner) TakesCapabilityJobs() bool

TakesCapabilityJobs reports whether the tool runs capability jobs (core.CapabilityScanner): its descriptor implements capabilities.

func (*Scanner) ToolContract

func (s *Scanner) ToolContract() *core.ToolContract

ToolContract names codeql's tool manifest in the sensor manifest.

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.