securityscanutils

README

Trivy Security Scanning

Trivy is a security scanning tool which we use to scan our images for vulnerabilities. You can run a trivy scan identical to CI on your own command line by installing trivy and running

trivy image --severity HIGH,CRITICAL quay.io/solo-io/<IMAGE>:<VERSION>

Using securityscanutils

Using the utils here is as easy as using the CLI defined in the cli subdirectory. The snippet below shows the output the said CLI's help command.

The GITHUB_TOKEN environment variable must be set for security scanning to work.

go-utils/securityscan % go run ./cli/main.go help

CLI for identifying CVEs in images

Usage:
  cvectl [command]

Available Commands:
  format-results Pull down security scan files from gcloud bucket and generate docs markdown file
  help           Help about any command
  scan-repo      Run Trivy scans against images for the repo specified and upload scan results to a google cloud bucket
  scan-version   Run Trivy scans against images for a single version

Flags:
  -h, --help      help for cvectl
  -v, --verbose   Enable verbose logging

Use "cvectl [command] --help" for more information about a command.

Documentation

Index

• Constants
• Variables
• func GetTemplateFile(trivyTemplate string) (string, error)
• func IsImageNotFoundErr(logs string) bool
• func NewLatestPatchRepositoryReleasePredicate(releases []*github.RepositoryRelease) *latestPatchRepositoryReleasePredicate
• func NewSecurityScanRepositoryReleasePredicate(constraint *semver.Constraints) *securityScanRepositoryReleasePredicate
• type CmdExecutor
• type SarifMetadata
• type SecurityScanOpts
• type SecurityScanRepo
  • func (r *SecurityScanRepo) GetImagesToScan(versionToScan *semver.Version) ([]string, error)
  • func (r *SecurityScanRepo) RunMarkdownScan(ctx context.Context, release *github.RepositoryRelease, markdownTplFile string) error
  • func (r *SecurityScanRepo) UploadSecurityScanToGithub(fileName, versionTag string) error
• type SecurityScanner
  • func (s *SecurityScanner) GenerateSecurityScans(ctx context.Context) error
• type TrivyScanner
  • func NewTrivyScanner(executeCommand CmdExecutor) *TrivyScanner
  • func (t *TrivyScanner) ScanImage(ctx context.Context, image, templateFile, output string) (bool, bool, error)

Constants

const (
	GithubRepositoryOwner = "solo-io"
	QuayRepository        = "quay.io/solo-io"
	OutputScanDirectory   = "_output/scans"
)

const MarkdownTrivyTemplate = `` /* 505-byte string literal not displayed */

Template for markdown docs

const SarifTrivyTemplate = `` /* 3578-byte string literal not displayed */

Template for Sarif files to be uploaded to Github, which displays results on the 'Security' tab. Taken from https://github.com/aquasecurity/trivy/blob/main/contrib/sarif.tpl

const VulnerabilityFoundStatusCode = 52

Status code returned by Trivy if a vulnerability is found

Variables

var ImageNotFoundError = eris.Wrap(RecoverableErr, "❗IMAGE MISSING UNEXPECTEDLY❗")

var RecoverableErr = errors.New("Recoverable")

var UnrecoverableErr = errors.New("Unrecoverable")

Functions

func GetTemplateFile

func GetTemplateFile(trivyTemplate string) (string, error)

Create tempoarary file that contains the trivy template Trivy CLI only accepts files as input for a template, so this is a workaround

func IsImageNotFoundErr

func IsImageNotFoundErr(logs string) bool

func NewLatestPatchRepositoryReleasePredicate

func NewLatestPatchRepositoryReleasePredicate(releases []*github.RepositoryRelease) *latestPatchRepositoryReleasePredicate

func NewSecurityScanRepositoryReleasePredicate

func NewSecurityScanRepositoryReleasePredicate(constraint *semver.Constraints) *securityScanRepositoryReleasePredicate

Types

type CmdExecutor

type CmdExecutor func(cmd *exec.Cmd) ([]byte, int, error)

type SarifMetadata

type SarifMetadata struct {
	Ref       string `json:"ref"`
	CommitSha string `json:"commit_sha"`
	Sarif     string `json:"sarif"`
}

type SecurityScanOpts

type SecurityScanOpts struct {
	// The following directory structure will be created in your output dir.
	/*
	   OUTPUT_DIR/
	   ├─ markdown_results/
	   │  ├─ repo1/
	   │  │  ├─ 1.4.12/
	   │  │  ├─ 1.5.0/
	   │  ├─ repo2/
	   │  │  ├─ 1.4.13/
	   │  │  ├─ 1.5.1/
	   ├─ sarif_results/
	   │  ├─ repo1/
	   │  │  ├─ 1.4.12/
	   │  │  ├─ 1.5.0/
	   │  ├─ repo2/
	   │  │  ├─ 1.4.13/
	   │  │  ├─ 1.5.1/
	   ├─ issue_results/
	   │  ├─ repo1/
	   │  │  ├─ 1.4.12.md
	   │  │  ├─ 1.5.0.md
	   │  ├─ repo2/
	   │  │  ├─ 1.4.13.md
	   │  │  ├─ 1.5.1.md
	*/
	OutputDir string
	// Output the would-be github issue Markdown to local files
	OutputResultLocally bool
	// A mapping of version constraints to images scanned.
	// If 1.6 had images "gloo", "discovery" and 1.7 introduced a new image "rate-limit",
	// the map would look like:
	/*
	   ' >= 1.6': ["gloo", "discovery"]
	   ' >= 1.7': ["gloo", "discovery", "rate-limit"]
	*/
	// where the patch number is explicitly not set so that these versions can match all
	// 1.6.x-x releases
	ImagesPerVersion map[string][]string
	// VersionConstraint on releases to security scan
	// any releases that do not pass this constraint will not be security scanned.
	// If left empty, all versions will be scanned
	VersionConstraint *semver.Constraints

	// Required: image repo (quay.io, grc.io, gchr.io)
	ImageRepo string

	// Uploads Sarif file to github security code-scanning results
	// e.g. https://github.com/solo-io/gloo/security/code-scanning
	UploadCodeScanToGithub bool

	// Creates github issue if image vulnerabilities are found
	CreateGithubIssuePerVersion bool

	// Only create github issue if:
	// 	1. Image vulnerabilities are found
	//	2. The version is the latest patch version (Major.Minor.Patch)
	// If set to true, will override the behavior of CreateGithubIssuePerVersion
	CreateGithubIssueForLatestPatchVersion bool

	// Additional context to add to the top of the generated vulnerability report.
	// Example: This could be used to provide debug instructions to developers.
	AdditionalContext string
}

type SecurityScanRepo

type SecurityScanRepo struct {
	Repo  string
	Owner string
	Opts  *SecurityScanOpts
	// contains filtered or unexported fields
}

func (*SecurityScanRepo) GetImagesToScan

func (r *SecurityScanRepo) GetImagesToScan(versionToScan *semver.Version) ([]string, error)

func (*SecurityScanRepo) RunMarkdownScan

func (r *SecurityScanRepo) RunMarkdownScan(ctx context.Context, release *github.RepositoryRelease, markdownTplFile string) error

func (*SecurityScanRepo) UploadSecurityScanToGithub

func (r *SecurityScanRepo) UploadSecurityScanToGithub(fileName, versionTag string) error

Uploads Github security scan in .sarif file format to Github Security Tab under "Code Scanning"

type SecurityScanner

type SecurityScanner struct {
	Repos []*SecurityScanRepo
	// contains filtered or unexported fields
}

func (*SecurityScanner) GenerateSecurityScans

func (s *SecurityScanner) GenerateSecurityScans(ctx context.Context) error

Main method to call on SecurityScanner which generates .md and .sarif files in OutputDir as defined above per repo. If UploadCodeScanToGithub is true, sarif files will be uploaded to the repository's code-scanning endpoint.

type TrivyScanner

type TrivyScanner struct {
	// contains filtered or unexported fields
}

func NewTrivyScanner

func NewTrivyScanner(executeCommand CmdExecutor) *TrivyScanner

func (*TrivyScanner) ScanImage

func (t *TrivyScanner) ScanImage(ctx context.Context, image, templateFile, output string) (bool, bool, error)