ruleset

package module
v1.4.1 Latest Latest
Warning

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

 Go to latest Published: Mar 8, 2023 License: MIT Imports: 18 Imported by: 21

README

Analyzers Ruleset Library

This repository contains Go modules for implementing customization of rulesets for GitLab Secure analyzers.

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

Overview

Package ruleset provides code for the analyzer to use to load external scanner configurations. These rulesets are loaded from .gitlab/{sast}-ruleset.toml.

Index

Constants

View Source 
const (
	// EnvVarGitlabFeatures lists Gitlab features available
	EnvVarGitlabFeatures = "GITLAB_FEATURES"
	// GitlabFeatureCustomRulesetsSAST indicates that sast custom rulesets are enabled
	GitlabFeatureCustomRulesetsSAST = "sast_custom_rulesets"
	// PathSAST is the default path to custom sast rules
	PathSAST = ".gitlab/sast-ruleset.toml"
	// PathSecretDetection is the default path to custom secret detection rulesets
	PathSecretDetection = ".gitlab/secret-detection-ruleset.toml" // #nosec
	// PassthroughFile should be used when the ruleset passthrough is a file.
	PassthroughFile PassthroughType = "file"
	// PassthroughRaw should be used when the ruleset passthrough is defined inline.
	PassthroughRaw PassthroughType = "raw"
	// PassthroughGit should be used when the ruleset is pulled via git pulled via git
	PassthroughGit PassthroughType = "git"
	// PassthroughFileURL should be used to download files
	PassthroughFileURL PassthroughType = "url"

	// ValidatorJSON is used to validate JSON files
	ValidatorJSON Validator = "json"
	// ValidatorTOML is used to validate TOML files
	ValidatorTOML Validator = "toml"
	// ValidatorYAML is used to validate YAML files
	ValidatorYAML Validator = "yaml"
	// ValidatorXML is used to validate XML files
	ValidatorXML Validator = "xml"
	// ValidatorUnknown if validator is not known
	ValidatorUnknown Validator = ""

	// DefaultOverallTimeout should be used to set the overall timeout to evaluate all passthroughs in combination (seconds)
	DefaultOverallTimeout = 60

	// MaxOverallTimeout is the max allowed overall timeout for performing a sequence of passthroughs
	MaxOverallTimeout = 300

	// MaxPassthroughs limits the number of maximally allowed passthroughs (per
	// configuration)
	MaxPassthroughs = 20

	// MaxPassthroughByteSize limits the number of bytes written per (raw|file) passthrough
	MaxPassthroughByteSize = 1000000 // 1MB

	// MaxTargetByteSize limits the size of the target configuration (dir|file) for rule-pack
	// synthesis
	MaxTargetByteSize = 100000000 // 100MB

)

Variables

This section is empty.

Functions

func CleanPath added in v1.2.0 

func CleanPath(path string) string

CleanPath makes a path safe for use with filepath.Join. This is done by not only cleaning the path, but also (if the path is relative) adding a leading '/' and cleaning it (then removing the leading '/'). This ensures that a path resulting from prepending another path will always resolve to lexically be a subdirectory of the prefixed path. This is all done lexically, so paths that include symlinks won't be safe as a result of using CleanPath.

This function comes from runC (libcontainer/utils/utils.go): https://github.com/opencontainers/runc/blob/d636ad6256f9194b0f4c6ee181e75fb36e3446d8/libcontainer/utils/utils.go#L53

func DisabledIdentifiers 

func DisabledIdentifiers(rulesetPath string, analyzer string) (map[string]bool, error)

DisabledIdentifiers uses the config pre-loaded by the analyzer then constructs a list of identifiers that will be ignored when reporting vulnerabilities

func IdentifiersWithOverrides added in v1.4.0 

func IdentifiersWithOverrides(rulesetPath string, analyzer string) (map[string]Ruleset, error)

IdentifiersWithOverrides uses the config pre-loaded by the analyzer then constructs a list of identifiers that will be overridden when reporting vulnerabilities

func ProcessPassthrough added in v1.1.0 

func ProcessPassthrough(cfg *Config, passthrough Passthrough, logger GenericLogger) (string, error)

ProcessPassthrough leverages a pre-existing file (file), mints a new file (raw), downloads a file (url) or clones a git repository (git) and returns the path to the configuration file or directory

func ProcessPassthroughWithTimeout added in v1.3.0 

func ProcessPassthroughWithTimeout(ctx context.Context, cfg *Config, passthrough Passthrough, logger GenericLogger) (string, error)

ProcessPassthroughWithTimeout runs the ProcessPassthrough functions in a timeout context

func ProcessPassthroughs added in v1.3.0 

func ProcessPassthroughs(config *Config, logger GenericLogger) (string, error)

ProcessPassthroughs processes multiple rulesets and returns the combined results

Types

type Config 

type Config struct {
	TargetDir   string        `toml:",omitempty"`
	Description string        `toml:",omitempty"`
	Passthrough []Passthrough `toml:",omitempty"`
	Ruleset     []Ruleset     `toml:",omitempty"`
	Path        string        `toml:",omitempty"`
	Timeout     uint          `toml:",omitempty"`
	Interpolate bool          `toml:",omitempty"`
	Validate    bool          `toml:",omitempty"`
}

Config is used for overriding default scanner configurations for the analyzers.

func Load 

func Load(rulesetPath string, analyzer string) (*Config, error)

Load accepts a rulesetPath and analyzer. Rulesetpath must point to a valid {sast}-ruleset.toml file. A single analyzer rule will be returned if one is found.

type ConfigFileNotFoundError 

type ConfigFileNotFoundError struct {
	RulesetPath string
}

ConfigFileNotFoundError indicates the config file was not found

func (*ConfigFileNotFoundError) Error 

func (e *ConfigFileNotFoundError) Error() string

Error formats and returns a ConfigFileNotFoundError

type ConfigNotFoundError 

type ConfigNotFoundError struct {
	Analyzer    string
	RulesetPath string
}

ConfigNotFoundError indicates custom rule config is not found

func (*ConfigNotFoundError) Error 

func (e *ConfigNotFoundError) Error() string

Error formats and returns a ConfigNotFoundError

type GenericLogger added in v1.1.0 

type GenericLogger interface {
	Info(...interface{})
	Infof(string, ...interface{})
	Error(...interface{})
	Errorf(string, ...interface{})
	Debug(...interface{})
	Debugf(string, ...interface{})
}

GenericLogger is a simple logger interface

type Identifier 

type Identifier struct {
	Type  string
	Value string
}

Identifier is a vulnerability id. Identifier.Value is used to filter or override vulnerability information in the final report.

type InvalidConfig 

type InvalidConfig struct {
	RulesetPath string
	Err         error
}

InvalidConfig indicates an invalid toml file

func (*InvalidConfig) Error 

func (e *InvalidConfig) Error() string

Error formats and returns an InvalidConfig

type NotEnabledError 

type NotEnabledError struct{}

NotEnabledError indicates custom rulesets have not been enabled

func (*NotEnabledError) Error 

func (e *NotEnabledError) Error() string

Error formats and returns a NotEnabledError

type Override added in v1.4.0 

type Override struct {
	Name        string `toml:"name,omitempty"`
	Message     string `toml:"message,omitempty"`
	Description string `toml:"description,omitempty"`
	Severity    string `toml:"severity,omitempty"`
}

Override is used to override rules properties

type Passthrough added in v1.3.0 

type Passthrough struct {
	Type PassthroughType
	// Target is used for a target file or directory
	Target string
	// subdir cloning for git passthrough
	Subdir string `toml:",omitempty"`
	Value  string
	// examples:
	//  refs/remotes/origin/develop
	//  97f7686db058e2141c0806a477c1e04835c4f395
	Ref       string          `toml:",omitempty"`
	Mode      PassthroughMode `toml:",omitempty"`
	Validator Validator       `toml:",omitempty"`
}

Passthrough is a struct that analyzers use to load external scanner configurations. Users can define in a project's ruleset file a PassthroughType (file, raw) and a value. Depending on the type, the value will either be a scanner specific file configuration or an inline configuration.

type PassthroughMode added in v1.3.0 

type PassthroughMode string

PassthroughMode determines how the results of passthroughs should be applied: append to file or overwrite

type PassthroughType added in v1.3.0 

type PassthroughType string

PassthroughType determines how the analyzer loads the ruleset which can either be via a file or defined inline.

type Ruleset 

type Ruleset struct {
	Identifier Identifier
	Disable    bool `toml:",omitempty"`
	Override   Override
}

Ruleset is used for disabling rules

type Validator added in v1.3.0 

type Validator string

Validator is used to determine which validator to use to check the validatity of a passthrough (intermediate) result

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.