command

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:

• a match function that implements command.MatchFunc
• a conversion function that implements command.ConvertFunc
• an analyze function and a function that lists the flags for the analyze sub-command

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
• func Analyze(cfg Config) *cli.Command
• func Convert(cfg Config) *cli.Command
• func EliminateRedundancies(notOptimized *report.Report, flagPrependPath string) (*report.Report, error)
• func NewApp(analyzer report.AnalyzerDetails) *cli.App
• func NewCommands(cfg Config) []*cli.Command
• func Run(cfg Config) *cli.Command
• func Search(cfg Config) *cli.Command
• func SerializeJSONToFile(report *report.Report, artifactPath string, flagPrependPath string, ...) error
• func SerializeJSONToWriter(report *report.Report, writer io.Writer, flagPrependPath string, indent bool, ...) error
• type AnalyzeFunc
• type Config
• type ConvertFunc
• type ErrInvalidArgs
  • func (e ErrInvalidArgs) Error() string
  • func (e ErrInvalidArgs) ExitCode() int
• type SerializerFunc

Constants

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"
)

Functions

func Analyze

func Analyze(cfg Config) *cli.Command

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

func Convert

func Convert(cfg Config) *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(cfg Config) []*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(cfg Config) *cli.Command

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

func Search

func Search(cfg Config) *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 AnalyzeFunc

type AnalyzeFunc func(c *cli.Context, path string) (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 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.
	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.

type ConvertFunc

type ConvertFunc func(input io.Reader, prependPath string) (*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 SerializerFunc

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

SerializerFunc function for serializing and optimizing report output