govex

package module
v0.9.7 Latest Latest
Warning

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

 Go to latest Published: Jan 5, 2025 License: MIT Imports: 28 Imported by: 1

README

GoVEX

Build Status Lint Status Go Report Card Docs Visualization License

Overview

govex is a vulerability reporting solution and library to create and share vulnerability reports via a variety of formats including XLSX, CSV, Markdown, and a git repository. It uses its own VEX vulnerability format that other data sources can be converted to. The reports generated can be used interally (e.g. git repo) or distributed externally (e.g. XLSX). Being written in Go, it can also be easily implemented in CI/CD pipelines and workflows.

Features

  1. Generic Vulnerability Structs: There is no widely adopted general format for vulnerabilty information across many database and scanning tools. To facilitate interoperability across different data sources, GoVEX provides its own definition of govex structs for vulnerabilities. The format used here is prioritized for use cases supported by this package, currently writing tabular and text reports.
  2. Vulnerability Reports: Reports in XLSX, CSV, or Markdown is supported via conversion of Vulnerabilities slice to a GoCharts Table via Vulnerabilities.Table() with customizable columns.
  3. Vulnerability Reports Website: Creation of a Markdown website for managing reports across multiple git-based projects with history is available using SiteWriter. This currently intended to be used with a git UI, but may have future support for a Docs-as-Code documentation generator such as MkDocs.
  4. CI/CD Integration: The Cmd wrappers provide convenient commans that can be integrated into a CI/CD pipeline with proper OS exit codes.

Integrations

  1. Grype via github.com/grokify/gogrype

Code Visualization

  1. GitHub Next Visualization (Article)

Contributing

  1. By contributing to this repository, you agree that your contributions will be licensed under the MIT License.
  2. Commits style uses Conventional Commits conventions available here: https://www.conventionalcommits.org/

Documentation

Index

Constants

View Source 
const (
	// Vulnerability source category.
	CategoryAntiVirus     = "Anti-Virus"
	CategoryCICD          = "CI/CD"
	CategoryCloudSecurity = "Cloud Security"
	CategoryContainer     = "Container"
	CategoryCSPM          = "CSPM"
	CategoryDAST          = "DAST"
	CategoryDevProcess    = "Dev Process"
	CategoryIaC           = "IaC"
	CategoryPentest       = "Pentest"
	CategoryRedTeam       = "Red Team"
	CategorySAST          = "SAST"
	CategorySCA           = "SCA"
	CategorySCI           = "Supply Chain Integrity"
	CategorySecrets       = "Secrets"
	CategorySecurityLogs  = "Security Logs"

	Priority1 = "Priority 1"
	Priority2 = "Priority 2"
	Priority3 = "Priority 3"

	P1DoNow   = "P1 - Do Now"
	P2DoNext  = "P2 - Do Next"
	P3DoLater = "P3 - Do Later"

	ReportName = "AppSec Scan Report"
)
View Source 
const (
	FilenameIndexMd   = "index.md"
	FilenameReadmeMd  = "README.md"
	FilenameVulnsJSON = "vulns.json"
	FilenameVulnsXLSX = "vulns.json"
	FilenameMetaJSON  = "meta.json"
	ReportsRepoTitle  = "AppSec Reports"
)
View Source 
const (
	// Status categories
	StatusWithinSLA      = "Within SLA"
	StatusApproachingSLA = "Approaching SLA"
	StatusOutOfSLA       = "Out of SLA"
)
View Source 
const (
	// Status fields. See `docs/status.md` for more.
	StatusIdentified    = "Identified"
	StatusAnalyzing     = "Analyzing"
	StatusValidated     = "Validated"
	StatusMitigated     = "Mitigated"
	StatusInProgress    = "In Progress"
	StatusResolved      = "Resolved"
	StatusRemediated    = "Remediated"
	StatusClosed        = "Closed"
	StatusReopened      = "Reopened"
	StatusNotApplicable = "Not Applicable"
	StatusFalsePositive = "False Positive"
	StatusDeferred      = "Deferred"      // aka postponed
	StatusRiskAccepted  = "Risk Accepted" // aka ignored
)
View Source 
const (
	FieldAcceptedTime        = "Accepted Time"
	FieldAcceptedTimeRFC3339 = "Start Date"
	FieldAgeDays             = "Age"
	FieldCategory            = "Category"
	FieldDescription         = "Description"
	FieldFixVersion          = "Fixed Version"
	FieldID                  = "ID"
	FieldLibraryName         = "Library"
	FieldLibraryVersion      = "Library Version"
	FieldLibraryVersionFixed = "Library Version Fixed"
	FieldLocationPath        = "Location"
	FieldLocationLineStart   = "Location Start Line"
	FieldLocationLineEnd     = "Location End Line"
	FieldName                = "Name"
	FieldNameAndDesc         = "Name+Desc"
	FieldNameWithURL         = "Name+URL"
	FieldReferenceURL        = "Reference URL"
	FieldReferences          = "References"
	FieldResolution          = "Resolution"
	FieldSeverity            = "Severity"
	FieldSLAOpenStatus       = "Open SLA Status"
	FieldStatus              = "Status"
)
View Source 
const (
	NameUnnamedVulerability = "Unnamed Vulnerability"
)

Variables

View Source 
var (
	ErrFieldDateTimeCannotBeNil        = errors.New("field DateTime cannot be nil")
	ErrFieldIndexFileCannotBeUndefined = errors.New("field IndexFilename cannot be undefined")
	ErrFieldRepoPathCannotBeUndefined  = errors.New("field RootFilePath cannot be undefined")
	ErrVulnerabilitySetCannotBeNil     = errors.New("vulnerability set canot be nil")
)

Functions

func CategoriesOrdered added in v0.9.6 

func CategoriesOrdered() []string

CategoriesOrdered returns a set of categories ordered by SDLC position.

func CmdSiteWriteHomeExec added in v0.9.6 

func CmdSiteWriteHomeExec() error

func ParseField 

func ParseField(field string) string

func TableColumnDefinitionSetSAST 

func TableColumnDefinitionSetSAST() table.ColumnDefinitionSet

func TableColumnDefinitionSetSASTSCA added in v0.5.0 

func TableColumnDefinitionSetSASTSCA() table.ColumnDefinitionSet

func TableColumnDefinitionSetSASTSCAReport added in v0.7.0 

func TableColumnDefinitionSetSASTSCAReport() table.ColumnDefinitionSet

func TableColumnDefinitionSetSCA added in v0.2.0 

func TableColumnDefinitionSetSCA() table.ColumnDefinitionSet

func WriteFilesSiteForRepo added in v0.9.0 

func WriteFilesSiteForRepo(rootFilePath string, vs *VulnerabilitiesSet) error

Types

type CmdMergeJSONsOptions added in v0.9.6 

type CmdMergeJSONsOptions struct {
	InputFilename     []string `short:"i" long:"inputFiles" description:"Filenames to merge" required:"true"`
	OutputFileJSON    string   `short:"o" long:"outputFile" description:"Outputfile in JSON format" required:"false"`
	OutputFileXLSX    string   `short:"x" long:"xlsxoOutputFile" description:"Outputfile in XLSX format" required:"false"`
	OutputFileMKDN    string   `short:"m" long:"markdownOutputFile" description:"Outputfile in Markdown format" required:"true"`
	SeveritySplitXLSX string   `short:"s" long:"severityfiltercutoff" description:"Outputfile" required:"false"`
	ReportRepoURL     string   `short:"r" long:"reportRepoURL" description:"Outputfile" required:"false"`
	ProjectName       string   `short:"p" long:"projectName" description:"Project name to use" required:"false"`
	ProjectRepoPath   string   `long:"repoPath" description:"Project: Repo Path" required:"false"`
	ProjectRepoURL    string   `long:"repoURL" description:"Project repoURL" required:"false"`
}

type CmdMergeJSONsResponse added in v0.9.6 

type CmdMergeJSONsResponse struct {
	RequestOptions       *CmdMergeJSONsOptions
	Sheet1Len            int
	Sheet2Len            int
	FilesWritten         []string
	SeverityCountsString string
	ReportRepoUpdated    bool
}

func CmdMergeJSONsExec added in v0.9.6 

func CmdMergeJSONsExec() (*CmdMergeJSONsResponse, error)

type CmdSiteWriteHomeOptions added in v0.9.6 

type CmdSiteWriteHomeOptions struct {
	ReportRepoURL            string `short:"r" long:"reportRepoURL" description:"Outputfile" required:"true"`
	RootIndexShieldsMarkdown string `short:"s" long:"shieldsMarkdown" description:"Shields Markdown" required:"false"`
}

type Library added in v0.2.0 

type Library struct {
	Name         string `json:"name"`
	Description  string `json:"description"`
	Type         string `json:"type"` // corresponds with Grype.
	Version      string `json:"version"`
	VersionFixed string `json:"versionFixed"`
}

type Location 

type Location struct {
	Path      *string
	LineStart *uint
	LineEnd   *uint
}

Location provides information on where a vulnerability occurs.

func (Location) LineEndString 

func (l Location) LineEndString() string

func (Location) LineStartString 

func (l Location) LineStartString() string

func (Location) PathString 

func (l Location) PathString() string

type SLAMap 

type SLAMap map[string]int64

SLAMap provides a commen representation of SLAs by severity and day.

func SLAMapFedRAMP 

func SLAMapFedRAMP() SLAMap

func (SLAMap) MustSLAStatusTimesString 

func (slaMap SLAMap) MustSLAStatusTimesString(severity string, startTime *time.Time, evalTime time.Time, unknownString string) string

func (SLAMap) SLAStatusOverdue 

func (slaMap SLAMap) SLAStatusOverdue(sev string, dur time.Duration) (bool, error)

func (SLAMap) SLAStatusTimesString 

func (slaMap SLAMap) SLAStatusTimesString(severity string, startTime *time.Time, evalTime time.Time, unknownString string) (string, error)

type SiteWriter added in v0.9.0 

type SiteWriter struct {
	IndexFilename              string
	RootFilePath               string
	FilesPerm                  os.FileMode
	SeverityCutoff             string
	RootIndexWrite             bool
	RootIndexFileTable         bool
	RootIndexName              string
	RootIndexShieldsMarkdown   string
	ShieldsWrite               bool
	ShieldFontSize             int
	MetaWrite                  bool
	MkdnWriteFileVulns         bool
	MkdnWriteFileVulnsAsIndex  bool
	MkdnColDefsSet             table.ColumnDefinitionSet
	MkdnAddColLinNum           bool
	JSONWriteFileVulns         bool
	JSONWriteFileVulnsAsLatest bool
	JSONPrefix                 string
	JSONIndent                 string
	XLSXWriteFileVulns         bool
	XLSXSheetName1             string
	XLSXSheetName2             string
	XLSXColDefsSet             table.ColumnDefinitionSet
}

SiteWriter is designed to write files that are read from a git repo web UI.

func DefaultSiteWriterHome added in v0.9.3 

func DefaultSiteWriterHome(rootIndexPath, rootIndexShieldsMarkdown string) SiteWriter

func DefaultSiteWriterRepo added in v0.9.3 

func DefaultSiteWriterRepo() SiteWriter

DefaultSiteWriterRepo returns a `SiteWriter{}`. Typically, `RootFilePath` still needs to be set.

func (SiteWriter) WriteFileHome added in v0.9.3 

func (sw SiteWriter) WriteFileHome() error

func (SiteWriter) WriteFiles added in v0.9.0 

func (sw SiteWriter) WriteFiles(vs *VulnerabilitiesSet) error

type ValueOpts 

type ValueOpts struct {
	SLAMap *SLAMap
}

type Vulnerabilities 

type Vulnerabilities []Vulnerability

func (*Vulnerabilities) CVE20Vulnerabilities 

func (vs *Vulnerabilities) CVE20Vulnerabilities() cve20.Vulnerabilities

func (*Vulnerabilities) Dedupe added in v0.8.0 

func (vs *Vulnerabilities) Dedupe() (Vulnerabilities, error)

func (*Vulnerabilities) FilterFixedInVersion 

func (vs *Vulnerabilities) FilterFixedInVersion(fixVersions []string, severity string) (Vulnerabilities, error)

FilterFixedInVersion returns a filtered subset with a fix version match, including empty string.

func (*Vulnerabilities) FilterFixedInVersionAge 

func (vs *Vulnerabilities) FilterFixedInVersionAge(fixVersion, baseSeverity string, slaDays uint, slaElapsed bool) Vulnerabilities

FilterFixedInVersion returns a filtered subset with a fix version match, including empty string.

func (*Vulnerabilities) FilterFunc 

func (vs *Vulnerabilities) FilterFunc(fnFilterIncl func(vn Vulnerability) (bool, error)) (Vulnerabilities, error)

func (*Vulnerabilities) FilterSeverities added in v0.2.0 

func (vs *Vulnerabilities) FilterSeverities(severitiesIncl []string) (Vulnerabilities, error)

func (*Vulnerabilities) FilterSeveritiesHigher added in v0.6.0 

func (vs *Vulnerabilities) FilterSeveritiesHigher(sev string, incl bool) (Vulnerabilities, error)

func (*Vulnerabilities) FilterSeveritiesLower added in v0.6.0 

func (vs *Vulnerabilities) FilterSeveritiesLower(sev string, incl bool) (Vulnerabilities, error)

func (*Vulnerabilities) IDs 

func (vs *Vulnerabilities) IDs(unique bool) []string

func (*Vulnerabilities) Len added in v0.4.0 

func (vs *Vulnerabilities) Len() int

func (*Vulnerabilities) LenFunc added in v0.4.0 

func (vs *Vulnerabilities) LenFunc(fnFilter func(v Vulnerability) (bool, error)) (int, error)

func (*Vulnerabilities) LenSeverities added in v0.4.0 

func (vs *Vulnerabilities) LenSeverities(severitiesIncl ...string) (int, error)

func (*Vulnerabilities) OrderedListMarkdownBytes added in v0.4.0 

func (vs *Vulnerabilities) OrderedListMarkdownBytes(opts *ValueOpts) []byte

func (*Vulnerabilities) OrderedListMarkdownLines added in v0.4.0 

func (vs *Vulnerabilities) OrderedListMarkdownLines(opts *ValueOpts) []string

func (*Vulnerabilities) ReportMarkdownLinesFixedVersion 

func (vs *Vulnerabilities) ReportMarkdownLinesFixedVersion(fixVersion string, releaseDate *time.Time) ([]string, error)

func (*Vulnerabilities) ReportMarkdownLinesVulnsFixed 

func (vs *Vulnerabilities) ReportMarkdownLinesVulnsFixed(fixVersion string, releaseDate *time.Time, baseSeverity string) ([]string, error)

func (*Vulnerabilities) SeverityCounts added in v0.4.0 

func (vs *Vulnerabilities) SeverityCounts() maputil.Records

func (*Vulnerabilities) SeverityCountsString added in v0.7.0 

func (vs *Vulnerabilities) SeverityCountsString(sep string) string

func (*Vulnerabilities) SeverityHistogram added in v0.4.0 

func (vs *Vulnerabilities) SeverityHistogram() histogram.Histogram

func (*Vulnerabilities) SortByID 

func (vs *Vulnerabilities) SortByID()

func (*Vulnerabilities) Table 

func (vs *Vulnerabilities) Table(colDefs table.ColumnDefinitionSet, opts *ValueOpts) (*table.Table, error)

func (*Vulnerabilities) TableSet added in v0.2.0 

func (vs *Vulnerabilities) TableSet(colDefs table.ColumnDefinitionSet, filters VulnerabilitiesFilters, addCountsToNames bool, opts *ValueOpts) (*table.TableSet, error)

func (*Vulnerabilities) TableSetSplitSeverity added in v0.6.0 

func (vs *Vulnerabilities) TableSetSplitSeverity(colDefs table.ColumnDefinitionSet, sevCutoff string, sevInclWithHigher bool, name1, name2 string, addCountsToNames bool, opts *ValueOpts) (*table.TableSet, error)

func (*Vulnerabilities) WriteFileXLSX added in v0.6.0 

func (vs *Vulnerabilities) WriteFileXLSX(filename, sheetname string, colDefs table.ColumnDefinitionSet, opts *ValueOpts) error

func (*Vulnerabilities) WriteFileXLSXSplitSeverity added in v0.6.0 

func (vs *Vulnerabilities) WriteFileXLSXSplitSeverity(filename string, colDefs table.ColumnDefinitionSet, sevCutoff, name1, name2 string, opts *ValueOpts) (int, int, error)

type VulnerabilitiesFilter added in v0.2.0 

type VulnerabilitiesFilter struct {
	Name           string
	SeveritiesIncl []string
}

type VulnerabilitiesFilters added in v0.2.0 

type VulnerabilitiesFilters []VulnerabilitiesFilter

func BuildVulnerabilitiesFiltersSplit added in v0.6.0 

func BuildVulnerabilitiesFiltersSplit(sevCutoff string, sevInclWithHigher bool, name1, name2 string) (VulnerabilitiesFilters, error)

func (VulnerabilitiesFilters) HasSeverityFullCoverage added in v0.2.0 

func (vfs VulnerabilitiesFilters) HasSeverityFullCoverage() bool

type VulnerabilitiesSet added in v0.3.0 

type VulnerabilitiesSet struct {
	Name            string          `json:"name"`
	RepoPath        string          `json:"repoPath"`
	RepoURL         string          `json:"repoURL"`
	DateTime        *time.Time      `json:"dateTime"`
	VulnValueOpts   *ValueOpts      `json:"vulnValueOpts"`
	Vulnerabilities Vulnerabilities `json:"vulnerabilities"`
}

func NewVulnerabilitiesSet added in v0.5.0 

func NewVulnerabilitiesSet() *VulnerabilitiesSet

func ReadFilesVulnerabilitiesSet added in v0.3.0 

func ReadFilesVulnerabilitiesSet(filenames ...string) (*VulnerabilitiesSet, error)

func (*VulnerabilitiesSet) Meta added in v0.9.0 

func (vs *VulnerabilitiesSet) Meta() VulnerabilitiesSetMeta

func (*VulnerabilitiesSet) SetRepoURL added in v0.9.0 

func (vs *VulnerabilitiesSet) SetRepoURL(s string)

func (*VulnerabilitiesSet) WriteFileJSON added in v0.3.0 

func (vs *VulnerabilitiesSet) WriteFileJSON(filename string, prefix, indent string, perm os.FileMode) error

func (*VulnerabilitiesSet) WriteFileMeta added in v0.9.0 

func (vs *VulnerabilitiesSet) WriteFileMeta(filename string, perm os.FileMode) error

func (*VulnerabilitiesSet) WriteReportMarkdownTables added in v0.9.0 

func (vs *VulnerabilitiesSet) WriteReportMarkdownTables(w io.Writer, shieldsMkdn string, colDefs table.ColumnDefinitionSet, addColLineNum bool, opts *ValueOpts) error

func (*VulnerabilitiesSet) WriteReportMarkdownTablesToFile added in v0.9.0 

func (vs *VulnerabilitiesSet) WriteReportMarkdownTablesToFile(filename string, perm os.FileMode, shieldsMkdn string, colDefs table.ColumnDefinitionSet, addColLineNum bool, opts *ValueOpts) error

type VulnerabilitiesSetMeta added in v0.9.0 

type VulnerabilitiesSetMeta struct {
	Name           string         `json:"name"`
	RepoPath       string         `json:"repoPath"`
	RepoURL        string         `json:"repoURL"`
	DateTime       *time.Time     `json:"dateTime"`
	SeverityCounts map[string]int `json:"severityCounts"`
}

func ReadFileVulnerabilitiesSetMeta added in v0.9.0 

func ReadFileVulnerabilitiesSetMeta(filename string) (VulnerabilitiesSetMeta, error)

func (VulnerabilitiesSetMeta) MissingFields added in v0.9.0 

func (meta VulnerabilitiesSetMeta) MissingFields() []string

func (VulnerabilitiesSetMeta) WriteFile added in v0.9.0 

func (meta VulnerabilitiesSetMeta) WriteFile(filename string, perm os.FileMode) error

type Vulnerability 

type Vulnerability struct {
	App                 string         `json:"app,omitempty"`
	ID                  string         `json:"id,omitempty"`
	Category            string         `json:"category,omitempty"`
	CVSS3Score          *float32       `json:"cvss3Score"`
	CVSS3Vector         string         `json:"cvss3Vector"`
	Description         string         `json:"description,omitempty"`
	DescriptionLang     string         `json:"descriptionLanguage,omitempty"`
	Fixed               bool           `json:"fixed,omitempty"`
	Library             Library        `json:"library"`
	Location            *Location      `json:"location,omitempty"`
	Metrics             cve20.Metrics  `json:"metrics,omitempty"`
	Name                string         `json:"name,omitempty"`
	References          markdown.Links `json:"references,omitempty"`
	ReferenceURL        string         `json:"referenceURL,omitempty"`
	Resolution          string         `json:"resolution,omitempty"`
	ResolutionTime      *time.Time     `json:"resolutionDate,omitempty"`
	Severity            string         `json:"severity,omitempty"`
	SLATimeStart        *time.Time     `json:"slaTimeStart,omitempty"`
	SLAStatus           string         `json:"slaStatus,omitempty"`
	SourceIdentifier    string         `json:"sourceIdentifier"`
	StartTime           *time.Time     `json:"startDate,omitempty"`
	Status              string         `json:"status,omitempty"`
	VersionEndExcluding string         `json:"versionEndExcluding,omitempty"`

	ProcSLAEvalTime time.Time
}

func (*Vulnerability) AgeDays 

func (vn *Vulnerability) AgeDays(evalTime time.Time, unknownDays int) int

func (*Vulnerability) BuildSLAStatusString 

func (vn *Vulnerability) BuildSLAStatusString(slaMapDays SLAMap, slaEvalTime time.Time, unknownString string) string

func (*Vulnerability) CVE 

func (vn *Vulnerability) CVE() cve20.CVE

func (*Vulnerability) InflateSeverity added in v0.2.0 

func (vn *Vulnerability) InflateSeverity(sm severity.SeverityMapCVSS) error

func (*Vulnerability) StartTimeString 

func (vn *Vulnerability) StartTimeString(layout string, unsetTimeString string) string

func (*Vulnerability) Value 

func (vn *Vulnerability) Value(field, defaultValue string, opts *ValueOpts) string

func (*Vulnerability) Values 

func (vn *Vulnerability) Values(colDefs table.ColumnDefinitions, opts *ValueOpts) []string

func (*Vulnerability) ValuesStrings 

func (vn *Vulnerability) ValuesStrings(fields []string, opts *ValueOpts) []string

Source Files

View all Source files

Directories

Path Synopsis

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.