engines

Documentation

Index

• Constants
• Variables
• func ExtensionsForEngine(e Engine) map[string]bool
• func ExtensionsForEngines(engs []Engine) map[string]bool
• func IsRelevantFile(path string, exts map[string]bool) bool
• func ProbeVersion(binaryPath string) string
• type Engine
• type ScanMode
• type ScanOptions
• type Tier
  • func (t Tier) String() string

Constants

const Tier3SCA = Tier3Formal

Tier3SCA is an alias for Tier3Formal used by SCA/supply-chain engines.

Variables

var LanguageExtensions = map[string][]string{

	"c":          {".c", ".h"},
	"cpp":        {".cpp", ".cc", ".cxx", ".c++", ".hpp", ".hh", ".hxx", ".h++", ".inl"},
	"go":         {".go", ".mod", ".sum"},
	"java":       {".java", ".kt", ".kts", ".gradle", ".gradle.kts", ".xml"},
	"kotlin":     {".kt", ".kts"},
	"scala":      {".scala", ".sbt"},
	"python":     {".py", ".pyi", ".pyw"},
	"ruby":       {".rb", ".rake", ".gemspec"},
	"rust":       {".rs", ".toml"},
	"javascript": {".js", ".mjs", ".cjs"},
	"typescript": {".ts", ".tsx", ".mts", ".cts"},
	"swift":      {".swift"},
	"objc":       {".m", ".mm"},
	"php":        {".php", ".php3", ".php4", ".php5", ".phtml"},
	"csharp":     {".cs", ".csx", ".csproj", ".fsproj", ".vbproj", ".sln"},
	"dotnet":     {".cs", ".csx", ".vb", ".fs", ".csproj", ".fsproj", ".vbproj", ".sln"},

	"yaml":       {".yaml", ".yml"},
	"json":       {".json"},
	"properties": {".properties"},
	"env":        {},
	"toml":       {".toml"},
	"xml":        {".xml", ".config"},
	"ini":        {".ini", ".cfg", ".cnf"},
	"hcl":        {".tf", ".hcl", ".tfvars"},

	"(artifacts)": {},
}

LanguageExtensions maps language names (as returned by Engine.SupportedLanguages) to the file extensions (with dot prefix) that belong to that language.

SCA manifest filenames are included as extensions so that SCA engines which declare a language (e.g. "java") automatically filter in the manifest files for that ecosystem (e.g. pom.xml, build.gradle).

"(artifacts)" has an empty slice — it signals "scan everything" and is handled specially by ExtensionsForEngine/ExtensionsForEngines.

Functions

func ExtensionsForEngine

func ExtensionsForEngine(e Engine) map[string]bool

ExtensionsForEngine returns the deduplicated set of file extensions relevant to an engine, derived from its SupportedLanguages() return values and the LanguageExtensions table.

Returns nil when the engine should match all files — i.e., when:

• The engine advertises "(artifacts)" in SupportedLanguages, or
• The engine supports "env" (matched by basename, not extension), or
• The resulting extension set is empty after consulting the table.

Callers must treat a nil return as "no filter — include all files".

func ExtensionsForEngines

func ExtensionsForEngines(engs []Engine) map[string]bool

ExtensionsForEngines returns the union of extension sets across all provided engines. Returns nil if any engine has no extension filter (meaning at least one engine must scan all files, so no filtering is possible).

func IsRelevantFile

func IsRelevantFile(path string, exts map[string]bool) bool

IsRelevantFile reports whether path is relevant given the extension filter set exts.

Special cases handled:

• nil exts means "match all" — always returns true.
• Files whose basename starts with ".env" are matched regardless of extension.
• The comparison uses filepath.Ext, which returns the last dot-prefixed suffix.

func ProbeVersion

func ProbeVersion(binaryPath string) string

ProbeVersion runs `<binaryPath> --version` with a 5-second timeout and returns the trimmed first line of output. Returns "unknown" on any failure. This is a convenience helper for subprocess-based engines implementing Version().

Types

type Engine

type Engine interface {
	// Name returns the engine identifier (e.g. "cipherscope").
	Name() string

	// Tier returns the analysis depth tier.
	Tier() Tier

	// SupportedLanguages returns the set of languages this engine can scan.
	SupportedLanguages() []string

	// Available reports whether the engine binary is accessible.
	Available() bool

	// Version returns the engine version string. Subprocess engines probe
	// the binary via --version; embedded engines return a fixed string.
	// Returns "unknown" if the version cannot be determined.
	Version() string

	// Scan runs the engine and returns normalized findings.
	Scan(ctx context.Context, opts ScanOptions) ([]findings.UnifiedFinding, error)
}

Engine is the interface every scanner engine must implement.

type ScanMode

type ScanMode string

ScanMode represents the scan execution mode.

const (
	ModeFull  ScanMode = "full"  // Scan all files
	ModeQuick ScanMode = "quick" // Tier 1 only, no taint
	ModeDiff  ScanMode = "diff"  // Only changed files
)

type ScanOptions

type ScanOptions struct {
	TargetPath      string
	Languages       []string // empty = all supported
	Timeout         int      // seconds, 0 = no timeout
	MaxFileMB       int      // max file size in MB, 0 = engine default
	EngineNames     []string // empty = all available engines
	ExcludePatterns []string // glob patterns to exclude from scan
	Mode            ScanMode // full, quick, or diff
	ChangedFiles    []string // for diff mode: only scan these files (relative to TargetPath)
	ImpactGraph     bool     // enable Tier 2.5 forward impact analysis
	MaxImpactHops   int      // maximum forward hops for impact analysis (0 = default 10)
	ScanType        string   // "source" (default), "binary", or "all"
	BinaryPaths     []string // explicit binary artifact paths to scan

	// Incremental scan options (Phase 9).
	Incremental bool   // enable incremental mode: skip unchanged files using cache
	CachePath   string // override default cache path; default: <TargetPath>/.oqs-scanner-cache.json
	NoCache     bool   // force full scan, ignore and do not update cache

	// Suppression options (Phase 13).
	NoSuppress bool // disable oqs:ignore and .oqs-ignore filtering (for audits)

	// TLS probe options (Phase: TLS Network Scan).
	TLSTargets     []string // host:port targets to probe (empty = skip tls-probe engine)
	TLSInsecure    bool     // skip manual certificate verification after capture
	TLSDenyPrivate bool     // reject RFC 1918 / loopback / link-local target IPs
	TLSTimeout     int      // per-target dial+handshake timeout in seconds (0 = default 10s)
	TLSCACert      string   // path to custom CA cert PEM for manual verification
}

ScanOptions configures a scan run.

type Tier

type Tier int

Tier represents the analysis depth of an engine.

const (
	Tier1Pattern Tier = iota + 1 // Pattern/AST matching
	Tier2Flow                    // Data-flow / taint analysis
	Tier3Formal                  // Formal verification / deep semantic
	Tier4Binary                  // Binary artifact scanning
)

const Tier5Network Tier = 5

Tier5Network is for engines that probe live network endpoints (e.g., TLS). Defined outside the iota block to avoid shifting existing tier values.

func (Tier) String

func (t Tier) String() string