command

package module
v4.0.0 Latest Latest
Warning

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

 Go to latest Published: Aug 5, 2025 License: MIT Imports: 20 Imported by: 0

README

Analyzers Command Library

This repository contains Go modules for implementing a command interface for GitLab Secure analyzers.

How to use the library

Analyzer relies on the command Go package to implement a command line that implements these sub-commands:

  • search searches for a project that is supported by the analyzer.
  • analyze performs the analysis in a given directory.
  • convert converts the output to a gl-sast-report.json artifact.
  • run performs all the previous steps consecutively.

All you need to do is to implement:

Support

This is an internal package used for developing GitLab-specific features. This package is not meant for public consumption, and breaking changes might be introduced at any time. See publicly available internal tooling for more details.

Contributing

Contributions are welcome, see CONTRIBUTING.md for more details.

License

This code is distributed under the MIT Expat license, see the LICENSE file.

Documentation

Index

Constants

View Source 
const (
	// ArtifactNameSAST holds the default name for SAST tool report file.
	ArtifactNameSAST = "gl-sast-report.json"
	// ArtifactNameDependencyScanning holds the default name for Dependency Scanning tool report file.
	ArtifactNameDependencyScanning = "gl-dependency-scanning-report.json"
	// ArtifactNameContainerScanning holds the default name for Container Scanning tool report file.
	ArtifactNameContainerScanning = "gl-container-scanning-report.json"
	// ArtifactNameSecretDetection holds the default name for Secret Detection tool report file.
	ArtifactNameSecretDetection = "gl-secret-detection-report.json"
	// ArtifactNameClusterImageScanning hold the default name for the Cluster Image Scanning report file.
	ArtifactNameClusterImageScanning = "gl-cluster-image-scanning-report.json"

	// EnvVarIndentReport is the env var (without prefix) for enabling/disabling indentation
	EnvVarIndentReport = "ANALYZER_INDENT_REPORT"
	// EnvVarOptimizeReport is the env var (without prefix) for enabling/disabling optimization
	EnvVarOptimizeReport = "ANALYZER_OPTIMIZE_REPORT"
	// EnvVarTargetDir is the env var (without prefix) for setting the analyzer target directory.
	EnvVarTargetDir = "ANALYZER_TARGET_DIR"
	// EnvVarArtifactDir is the env var (without prefix) for setting the analyzer artifacts directory.
	EnvVarArtifactDir = "ANALYZER_ARTIFACT_DIR"
	// EnvVarCIProjectDir is the env var that holds the project dir path
	// and usually is propagated from GitLab Runner. It's used as
	// default value for target directory and artifact directory in case
	// EnvVarTargetDir or EnvVarArtifactDir are not set.
	EnvVarCIProjectDir = "CI_PROJECT_DIR"
)

Variables

This section is empty.

Functions

func Analyze 

func Analyze(analyzer Analyzer) *cli.Command

Analyze returns a cli sub-command that wraps the analyzing the project and generating the report.

func Convert 

func Convert(analyzer Analyzer) *cli.Command

Convert returns a cli sub-command that converts the analyzer output into an artifact.

func EliminateRedundancies 

func EliminateRedundancies(notOptimized *report.Report, flagPrependPath string) (*report.Report, error)

EliminateRedundancies is a function that helps to remove redundancies automatically from reports these optimizations include: - only include findings that refer to (git) tracked files - remove redundant LineEnd information

func NewApp 

func NewApp(analyzer report.AnalyzerDetails) *cli.App

NewApp creates a new cli app with the given details describing the analyzer

func NewCommands 

func NewCommands(analyzer Analyzer) []*cli.Command

NewCommands function creates a slice of CLI command structs that contains all required analyzer commands: run, search, analyze, convert.

func Run 

func Run(analyzer Analyzer) *cli.Command

Run returns a cli sub-command that implements the full analyzer execution cycle. 

func Search(analyzer Analyzer) *cli.Command

Search returns a cli sub-command that implements project search.

func SerializeJSONToFile 

func SerializeJSONToFile(report *report.Report, artifactPath string, flagPrependPath string, indent bool, optimize bool) error

SerializeJSONToFile will write a report to a path

func SerializeJSONToWriter 

func SerializeJSONToWriter(report *report.Report, writer io.Writer, flagPrependPath string, indent bool, optimize bool) error

SerializeJSONToWriter optimizes the report based on the optimize flag and then encodes the report

Types

type Analysis 

type Analysis interface {
	MatchProject(path string, info os.FileInfo) (bool, error)
	AnalyzeProject(c *cli.Context, path string) (io.ReadCloser, error)
	ConvertReport(input io.Reader, prependPath string) (*report.Report, error)
	LoadRuleset(projectPath string) error
	Ruleset() *ruleset.Config
	Serialize(report *report.Report, artifactPath string, flagPrependPath string, indent bool, optimize bool) error
}

Analysis provides the actions performed in the steps of a command.

type AnalyzeFunc 

type AnalyzeFunc func(c *cli.Context, path string, config *ruleset.Config) (io.ReadCloser, error)

AnalyzeFunc is a type for a function that runs the analyzer command against the files in project dir and emits the analyzer's output for further processing.

type Analyzer 

type Analyzer interface {
	Details() report.AnalyzerDetails
	GeneratedArtifactName() string
	Flags() []cli.Flag
	AnalyzeAllProjects() bool
	CertOptions() cacert.ImportOptions
	Category() report.Category
	ScannerDetails() report.ScannerDetails

	NewAnalysis() Analysis
}

Analyzer describes the required implementation details an analyzer must provide to generate appropriate CLI commands for it to expose.

type CIVarBlock 

type CIVarBlock struct {
	Name, Value string
	IsFlag      bool
}

CIVarBlock represents one arg with value or a flag from the sequence of args/flags

func ParseCIVar 

func ParseCIVar(argStr string) (args []CIVarBlock, invalidArgs []string)

ParseCIVar parses the sequence of arg values/flags that are forwarded to upstream scanners. More detail about this usecase is explained here: https://gitlab.com/gitlab-org/gitlab/-/issues/368565

This function parses `argStr` to sequence args/flags separated by spaces and returns it in a slice of CIVarArg. An arg name is represented with a prefix of `-` or `--`. An arg without value is treated as "CLI flag". Arg's value is represented by placing right after its arg name separated by a space or equals(=).

NOTE: If any char is used as value separator other than space or equal(=), the string will be treated as flag.

Some of the input to output examples:

1. "--arg1" >> CLIArg {name: --arg1, flag: true} 2. "--arg1 val" >> CLIArg {name: --arg1, value: val, flag: false} 3. "--arg1=val" >> CLIArg {name: --arg1, value: val, flag: false} 4. "-flag1" >> CLIArg {name: -flag1, flag: true} 5. "-arg1 val" >> CLIArg {name: -arg1, value: val, flag: false} 6. "-a=val" >> CLIArg {name: -a, value: val, flag: false}

type Config 

type Config struct {
	Analyzer            report.AnalyzerDetails // Details about the analyzer which wraps the scanner
	ArtifactName        string                 // Name of the generated artifact
	Match               search.MatchFunc       // Match is a function that detects a compatible project.
	Analyze             AnalyzeFunc            // Analyze is a function that performs the analysis where a project was detected.
	AnalyzeFlags        []cli.Flag             // AnalyzeFlags is a set command line options used by the analyze function (optional).
	AnalyzeAll          bool                   // AnalyzeAll instructs the run command to analyze the root directory (false by default).
	Convert             ConvertFunc            // Convert is a function that turns the analyzer output into a compatible artifact.
	CACertImportOptions cacert.ImportOptions   // CACertImportOptions are options for the import of CA certificates.
	LoadRulesetConfig   RulesetConfigFunc      // LoadRulesetConfig is the method to load the configuration for the ruleset used by the analyzer and report.
	RulesetConfig       *ruleset.Config        // RulesetConfig is the configuration for the ruleset used by the analyzer and report.
	Scanner             report.ScannerDetails  // Scanner contains detailed information about the scanner
	ScanType            report.Category        // ScanType is the type of the scan (container_scanning, dependency_scanning, dast, sast)
	Serializer          SerializerFunc         // Serializer implements a function for serializing and optimizing report output
}

Config struct describes the required implementation details an analyzer must provide to generate appropriate CLI commands for it to expose.

func (Config) AnalyzeAllProjects 

func (c Config) AnalyzeAllProjects() bool

AnalyzeAllProjects implements AnalyzerAPI.

func (*Config) AnalyzeProject 

func (c *Config) AnalyzeProject(ctx *cli.Context, path string) (io.ReadCloser, error)

AnalyzeProject implements Analysis.

func (Config) Category 

func (c Config) Category() report.Category

Category implements AnalyzerAPI.

func (Config) CertOptions 

func (c Config) CertOptions() cacert.ImportOptions

CertOptions implements AnalyzerAPI.

func (*Config) ConvertReport 

func (c *Config) ConvertReport(input io.Reader, prependPath string) (*report.Report, error)

ConvertReport implements Analysis.

func (Config) Details 

func (c Config) Details() report.AnalyzerDetails

Details implements AnalyzerAPI.

func (Config) Flags 

func (c Config) Flags() []cli.Flag

Flags implements AnalyzerAPI.

func (Config) GeneratedArtifactName 

func (c Config) GeneratedArtifactName() string

GeneratedArtifactName implements AnalyzerAPI.

func (*Config) LoadRuleset 

func (c *Config) LoadRuleset(target string) error

LoadRuleset implements Analysis.

func (*Config) MatchProject 

func (c *Config) MatchProject(path string, info os.FileInfo) (bool, error)

MatchProject implements Analysis.

func (Config) NewAnalysis 

func (c Config) NewAnalysis() Analysis

NewAnalysis implements AnalyzerAPI.

func (*Config) Ruleset 

func (c *Config) Ruleset() *ruleset.Config

Ruleset implements Analysis.

func (Config) ScannerDetails 

func (c Config) ScannerDetails() report.ScannerDetails

ScannerDetails implements AnalyzerAPI.

func (*Config) Serialize 

func (c *Config) Serialize(report *report.Report, artifactPath string, flagPrependPath string, indent bool, optimize bool) error

Serialize implements Analysis.

type ConvertFunc 

type ConvertFunc func(input io.Reader, prependPath string, rulesetConfig *ruleset.Config) (*report.Report, error)

ConvertFunc is a type for a function that parses the analyzer binary raw output and converts it into the report data structure provided by the library.

type ErrInvalidArgs 

type ErrInvalidArgs struct{}

ErrInvalidArgs is an error that occurs when any of the analyzer CLI commands receives unexpected arguments.

func (ErrInvalidArgs) Error 

func (e ErrInvalidArgs) Error() string

func (ErrInvalidArgs) ExitCode 

func (e ErrInvalidArgs) ExitCode() int

ExitCode returns the analyzer CLI application exit code which should be returned upon analyzer termination when ErrInvalidArgs occurs.

type RulesetConfigFunc 

type RulesetConfigFunc func(projectPath string) (*ruleset.Config, error)

RulesetConfigFunc is a type for a function that loads the analyzer's ruleset from the project dir and returns the Ruleset.

type SerializerFunc 

type SerializerFunc func(report *report.Report, artifactPath string, flagPrependPath string, indent bool, optimize bool) error

SerializerFunc function for serializing and optimizing report output

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.