crawl

Documentation

Index

• Constants
• func AllFindingsSatisfiedBy(a, b Finding) bool
• func BytecodeMatchesPartialSignatures(methodBytecodes [][]byte) (string, bool)
• func SupportedVulnerableFindingValues() []string
• type AffectedVersion
• type CVEID
• type CVEResolver
  • func (r CVEResolver) CVEs(vs []Log4jVersion) []string
• type Crawler
  • func (c Crawler) Crawl(ctx context.Context, root string, process ProcessFunc) (Stats, error)
• type Finding
  • func FindingOf(v string) (Finding, error)
  • func LookForHashMatch(contents io.Reader, size int64) (Finding, string, bool)
  • func (f Finding) String() string
• type HandleFindingFunc
• type Identifier
• type JavaCVEInstance
• type Log4jIdentifier
  • func (i *Log4jIdentifier) Identify(ctx context.Context, path string, filename string) (skipped uint64, err error)
• type Log4jVersion
  • func FileNameMatchesLog4jJar(filename string) (Log4jVersion, bool)
  • func ParseLog4jVersion(version string) (Log4jVersion, bool)
  • func ParseLog4jVersions(versions Versions) ([]Log4jVersion, bool)
  • func (v Log4jVersion) Vulnerable() bool
• type Path
  • func (n Path) Joined() string
  • func (n Path) String() string
• type ProcessFunc
• type Reporter
  • func (r Reporter) FileCount() int64
  • func (r Reporter) FindingCount() int64
  • func (r *Reporter) Report(ctx context.Context, path Path, result Finding, versions Versions) bool
• type Stats
• type Versions
  • func (vs Versions) SortedList() []string

Constants

const (
	CVE202145105 = CVEID("CVE-2021-45105")
	CVE202144228 = CVEID("CVE-2021-44228")
	CVE202145046 = CVEID("CVE-2021-45046")
	CVE202144832 = CVEID("CVE-2021-44832")
)

Functions

func AllFindingsSatisfiedBy

func AllFindingsSatisfiedBy(a, b Finding) bool

AllFindingsSatisfiedBy returns true if all the findings represented by a are also represented by b

func BytecodeMatchesPartialSignatures

func BytecodeMatchesPartialSignatures(methodBytecodes [][]byte) (string, bool)

BytecodeMatchesPartialSignatures compares the given class method bytecode against snippets from known versions. A partial signature is made up of two parts: exact matches and partial matches. For an exact match to be identified the entirety of the bytecode a method must match the signature. Partial matches provide a prefix and suffix, these must both match a given method for the partial match to be a success.

func SupportedVulnerableFindingValues

func SupportedVulnerableFindingValues() []string

Types

type AffectedVersion

type AffectedVersion struct {
	CVE             CVEID
	FixedAfter      Log4jVersion
	PatchedVersions []Log4jVersion
}

type CVEID

type CVEID string

type CVEResolver

type CVEResolver struct {
	// IgnoreCVES contains the IDs of CVEs that will be omitted to CVE results.
	IgnoreCVES []CVEID
}

CVEResolver resolves the CVEs for log4j versions.

func (CVEResolver) CVEs

func (r CVEResolver) CVEs(vs []Log4jVersion) []string

type Crawler

type Crawler struct {
	Limiter ratelimit.Limiter
	// if non-nil, error output is written to this writer
	ErrorWriter                 io.Writer
	IgnoreDirs                  []*regexp.Regexp
	DirectoryEntriesPerListCall int
}

Crawler crawls filesystems, matching and conditionally processing files.

func (Crawler) Crawl

func (c Crawler) Crawl(ctx context.Context, root string, process ProcessFunc) (Stats, error)

Crawl crawls the provided root directory. Each file is passed to the provided match function, which returns true if the path should be processed by the provided process function. On encountering a directory, the path will be compared against all IgnoreDirs configured in the Crawler. If any pattern matches, the directory (and all files nested inside the directory) will be ignored.

type Finding

type Finding int

const (
	UnknownVersion = "unknown"

	NothingDetected                Finding = 0
	JndiLookupClassName            Finding = 1 << iota
	JndiLookupClassPackageAndName  Finding = 1 << iota
	JndiManagerClassName           Finding = 1 << iota
	JarName                        Finding = 1 << iota
	JarNameInsideArchive           Finding = 1 << iota
	JndiManagerClassPackageAndName Finding = 1 << iota
	JarFileObfuscated              Finding = 1 << iota
	ClassBytecodePartialMatch      Finding = 1 << iota
	ClassBytecodeInstructionMd5    Finding = 1 << iota
	ClassFileMd5                   Finding = 1 << iota
)

func FindingOf

func FindingOf(v string) (Finding, error)

FindingOf creates a finding from a string, returning an error if a corresponding finding does not exist. Conversion is case-insensitive.

func LookForHashMatch

func LookForHashMatch(contents io.Reader, size int64) (Finding, string, bool)

LookForHashMatch compares the Java class file contained within contents against known versions using a variety of approaches: - md5 hashing the entire class - comparing the bytecode for exact matches against known versions - comparing the bytecode for partial matches against known versions

func (Finding) String

func (f Finding) String() string

type HandleFindingFunc

type HandleFindingFunc func(ctx context.Context, path Path, result Finding, version Versions) bool

HandleFindingFunc is called with the given findings and versions when Log4jIdentifier identifies a log4j vulnerability whilst crawling the filesystem. The bool returned by HandleFindingFunc, indicates whether identification within the file should continue or not. For example, if the identification of a file has already yielded results that are desired for a given file, then there may be no need for the identification of the file to continue.

type Identifier

type Identifier interface {
	Identify(ctx context.Context, path string, d fs.DirEntry) (Finding, Versions, error)
}

type JavaCVEInstance

type JavaCVEInstance struct {
	Message       string   `json:"message"`
	FilePath      string   `json:"filePath"`
	DetailedPath  string   `json:"detailedPath"`
	CVEsDetected  []string `json:"cvesDetected"`
	Findings      []string `json:"findings"`
	Log4JVersions []string `json:"log4jVersions"`
}

type Log4jIdentifier

type Log4jIdentifier struct {
	Logger                             log.Logger
	Limiter                            ratelimit.Limiter
	IdentifyObfuscation                bool
	ObfuscatedClassNameAverageLength   int
	ObfuscatedPackageNameAverageLength int
	OpenFile                           func(string) (*os.File, error)
	ArchiveWalkTimeout                 time.Duration
	ArchiveMaxDepth                    uint
	ArchiveWalkers                     func(string) (archive.WalkerProvider, bool)
	HandleFinding                      HandleFindingFunc
}

Log4jIdentifier identifies files that are vulnerable to Log4J-related CVEs.

func (*Log4jIdentifier) Identify

func (i *Log4jIdentifier) Identify(ctx context.Context, path string, filename string) (skipped uint64, err error)

Identify identifies vulnerable files, passing each finding along with its versions to the Log4jIdentifier's HandleFindingFunc.

type Log4jVersion

type Log4jVersion struct {
	Original string
	Major    int
	Minor    int
	Patch    int
}

func FileNameMatchesLog4jJar

func FileNameMatchesLog4jJar(filename string) (Log4jVersion, bool)

func ParseLog4jVersion

func ParseLog4jVersion(version string) (Log4jVersion, bool)

func ParseLog4jVersions

func ParseLog4jVersions(versions Versions) ([]Log4jVersion, bool)

ParseLog4jVersions parses all Versions represented as strings, returning a slice of all valid versions found. A bool is returned that will be true if there were any invalid versions provided and the invalid versions will be omitted from the returns Log4jVersion slice.

func (Log4jVersion) Vulnerable

func (v Log4jVersion) Vulnerable() bool

type Path

type Path []string

Path represents the path taken to get to a given file that is being walked, where the path could be nested within any number of archives. Each element of the slice represents a single walking layer, which could be a file or archive. For example, ["/path/to/archive", "path/to/nested_archive", "path/to/file"] would represent a file being walked that is nested into two layers of archive.

func (Path) Joined

func (n Path) Joined() string

Joined provides a string representation of the given Path, where each layer is separated by a '!'.

func (Path) String

func (n Path) String() string

type ProcessFunc

type ProcessFunc func(ctx context.Context, path string, filename string) (uint64, error)

ProcessFunc is called on all files encountered when crawling the a filesystem.

type Reporter

type Reporter struct {
	// if non-nil, reported output is written to this writer
	OutputWriter io.Writer
	// True if reported output should be JSON, false otherwise
	OutputJSON bool
	// True if the reported output should consist of only the path to the file with the CVE, false otherwise. Only has
	// an effect if OutputJSON is false.
	OutputFilePathOnly bool

	// Disables results only matching JndiLookup classes
	DisableFlaggingJndiLookup bool
	// CVEResolver contains config for ignoring specific CVEs from reporting
	CVEResolver CVEResolver
	// Disables flagging issues where version of log4j is not known
	DisableFlaggingUnknownVersions bool
	// contains filtered or unexported fields
}

func (Reporter) FileCount

func (r Reporter) FileCount() int64

FileCount returns the number of unique files that have been reported.

func (Reporter) FindingCount

func (r Reporter) FindingCount() int64

FindingCount returns the number of unique findings that have been reported.

func (*Reporter) Report

func (r *Reporter) Report(ctx context.Context, path Path, result Finding, versions Versions) bool

Report the finding based on the configuration of the Reporter. The fileCount will be incremented if the finding is a new finding, i.e. a consecutive finding based on the same file when The findingCount will be incremented for every finding reported. OutputFilePathOnly is set to true will not cause the counter to be incremented. The returned boolean will always be true to represent that further inspection of the same file should continue.

type Stats

type Stats struct {
	// Total number of files scanned.
	FilesScanned uint64 `json:"filesScanned"`
	// Number of paths that were not considered due to "permission denied" errors
	PermissionDeniedCount uint64 `json:"permissionDeniedErrors"`
	// Number of paths that were attempted to be processed but encountered errors.
	PathErrorCount uint64 `json:"pathErrors"`
	// Number of paths that were skipped due to config/size limits
	PathSkippedCount uint64 `json:"pathsSkipped"`
}

type Versions

type Versions map[string]struct{}

func (Versions) SortedList

func (vs Versions) SortedList() []string