ruleset

package module
v2.0.9 Latest Latest
Warning

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

 Go to latest Published: Apr 22, 2024 License: MIT Imports: 22 Imported by: 3

README

Analyzers Ruleset Library

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

Testing
go test ./...

Certain unit tests require additional credentials in order to test authenticated fetching of private repositories. By default the unit tests will assert an "authentication required" error but fetching can be enabled by passing in the necessary credentials:

GITLAB_AUTH="theoretick:glpat-notarealtoken" go test ./...

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
	// GitReferenceSAST indicates a remote ruleset reference is defined
	GitReferenceSAST = "SAST_RULESET_GIT_REFERENCE"
	// GitReferenceSecretDetection indicates a remote ruleset reference is defined
	GitReferenceSecretDetection = "SECRET_DETECTION_RULESET_GIT_REFERENCE"
	// 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 = 10000000 // 10MB

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

)
View Source 
const (
	// GitProtocol is currently limited to cloning over https only
	GitProtocol = "https://"
)

Variables

This section is empty.

Functions

func CleanPath 

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 

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 

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 

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

ProcessPassthroughWithTimeout runs the ProcessPassthrough functions in a timeout context

func ProcessPassthroughs 

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, logger GenericLogger) (*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.

func LoadRelative 

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

LoadRelative 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.

func LoadRemote 

func LoadRemote(rulesetRef string, analyzer string, logger GenericLogger) (*Config, error)

LoadRemote accepts a rulesetRef string and analyzer. rulesetRef must point to an accessible remote repository to be cloned and have its ruleset path evaluated. The remote repository must contain the default ruleset path with 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 

type GenericLogger interface {
	Info(...interface{})
	Infof(string, ...interface{})
	Warn(...interface{})
	Warnf(string, ...interface{})
	Error(...interface{})
	Errorf(string, ...interface{})
	Debug(...interface{})
	Debugf(string, ...interface{})
	Fatal(...interface{})
	Fatalf(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 

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 

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"`
	// (Optional) Authentication
	Auth  string
	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.

func ParseRulesetRef 

func ParseRulesetRef(refString string) (*Passthrough, error)

ParseRulesetRef parses a ruleset reference string into a Passthrough containing an Auth, Value, and Ref property. These are used to fetch a remote ruleset using an SCP-style reference;

For example:

"username:password@gitlab.example.com/group/project@v1.1.1

Returns: 

Passthrough{
	Auth: "username:password",
	Value: "gitlab.example.com/group/project",
	Ref: "v1.1.1",
}

type PassthroughMode 

type PassthroughMode string

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

type PassthroughType 

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 

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.