scalibr

README

OSV-SCALIBR

Note: The code in this repo is subject to change in the near future as we're merging SCALIBR with OSV-scanner to provide a single tool that unifies the two scanners' extraction and vuln scanning capabilities.

SCALIBR (Software Composition Analysis Library) is an extensible file system scanner used to extract software inventory data (e.g. installed language packages) and detect vulnerabilities.

The scanner can either be used as a standalone binary to scan the local machine or as a library with a custom wrapper to perform scans on e.g. container images or remote hosts. It comes with built-in plugins for inventory extraction and vulnerability detection and it also allows users to run their custom plugins.

See here for the list of currently supported software inventory types.

Prerequisites

To build SCALIBR, you'll need to have the following installed:

• go: Follow https://go.dev/doc/install
• protoc: Install the appropriate precompiled protoc binary.
  • For Mac, you can also install via HomeBrew.
• protoc-gen-go: Run go install google.golang.org/protobuf/cmd/protoc-gen-go

How to use

As a standalone binary

1. make
2. ./scalibr --result=result.textproto

See the result proto definition for details about the scan result format.

Run ./scalibr --help for a list of additional CLI args.

As a library:

1. Import github.com/google/osv-scalibr into your Go project
2. Create a new scalibr.ScanConfig struct, configure the extraction and detection plugins to run
3. Call scalibr.New().Scan() with the config
4. Parse the returned scalibr.ScanResults

See below for an example code snippet.

On a container image

See the run_scalibr_on_image.sh script for an example of how to run SCALIBR on container images.

SPDX generation

SCALIBR supports generating the result of inventory extraction as an SPDX v2.3 file in json, yaml or tag-value format. Example usage:

./scalibr -o spdx23-json=result.spdx.json

Some fields in the generated SPDX can be overwritten:

./scalibr -spdx-document-name="Custom name" --spdx-document-namespace="Custom-namespace" --spdx-creators=Organization:Google -o spdx23-json=result.spdx.json

Running built-in plugins

With the standalone binary

The binary runs SCALIBR's "recommended" internal plugins by default. You can enable more plugins with the --extractors= and --detectors= flags. See the the definition files for a list of all built-in plugins and their CLI flags (extractors (fs), detectors).

With the library

A collection of all built-in plugin modules can be found in the definition files (extractors, detectors). To enable them, just import the module and add the appropriate plugins to the scan config, e.g.

import (
  scalibr "github.com/google/osv-scalibr"
  el "github.com/google/osv-scalibr/extractor/filesystem/list"
  dl "github.com/google/osv-scalibr/detector/list"
)
cfg := &scalibr.ScanConfig{
  ScanRoot:             "/",
  FilesystemExtractors: el.Python,
  Detectors:            dl.CIS,
}
results := scalibr.New().Scan(context.Background(), cfg)

Creating + running custom plugins

Custom plugins can only be run when using SCALIBR as a library.

1. Create an implementation of the SCALIBR Extractor or Detector interface.
2. Add the newly created struct to the scan config and run the scan, e.g.

import (
  "github.com/google/osv-scalibr/extractor/filesystem"
  scalibr "github.com/google/osv-scalibr"
)
cfg := &scalibr.ScanConfig{
  ScanRoot:             "/",
  FilesystemExtractors: []extractor.Extractor{&myExtractor{}},
}
results := scalibr.New().Scan(context.Background(), cfg)

Custom logging

You can make the SCALIBR library log using your own custom logger by passing an implementation of the log.Logger interface to log.SetLogger():

import (
  customlog "path/to/custom/log"
  "github.com/google/osv-scalibr/log"
  scalibr "github.com/google/osv-scalibr"
)
cfg := &scalibr.ScanConfig{ScanRoot: "/"}
log.SetLogger(&customlog.Logger{})
results := scalibr.New().Scan(context.Background(), cfg)
log.Info(results)

Contributing

Read how to contribute to SCALIBR.

Disclaimers

SCALIBR is not an official Google product.

Documentation

Overview

Package scalibr provides an interface for running software inventory extraction and security finding detection on a machine.

Index

• type ScanConfig
  • func (cfg *ScanConfig) EnableRequiredExtractors() error
• type ScanResult
• type Scanner
  • func New() *Scanner
  • func (Scanner) Scan(ctx context.Context, config *ScanConfig) (sr *ScanResult)

Types

type ScanConfig

type ScanConfig struct {
	FilesystemExtractors []filesystem.Extractor
	StandaloneExtractors []standalone.Extractor
	Detectors            []detector.Detector
	// ScanRoot is the root dir used by file walking during extraction.
	// All extractors and detectors will assume files are relative to this dir.
	// Example use case: Scanning a container image or source code repo that is
	// mounted to a local dir.
	ScanRoot string
	// Optional: Individual files to extract inventory from. If specified, the
	// extractors will only look at these files during the filesystem traversal.
	// Note that these are not relative to ScanRoot and thus need to be in
	// sub-directories of ScanRoot.
	FilesToExtract []string
	// Optional: Directories that the file system walk should ignore.
	// Note that these are not relative to ScanRoot and thus need to be
	// sub-directories of ScanRoot.
	// TODO(b/279413691): Also skip local paths, e.g. "Skip all .git dirs"
	DirsToSkip []string
	// Optional: If the regex matches a directory, it will be skipped.
	SkipDirRegex *regexp.Regexp
	// Optional: stats allows to enter a metric hook. If left nil, no metrics will be recorded.
	Stats stats.Collector
	// Optional: Whether to read symlinks.
	ReadSymlinks bool
	// Optional: Limit for visited inodes. If 0, no limit is applied.
	MaxInodes int
}

ScanConfig stores the config settings of a scan run such as the plugins to use and the dir to consider the root of the scanned system.

func (*ScanConfig) EnableRequiredExtractors

func (cfg *ScanConfig) EnableRequiredExtractors() error

EnableRequiredExtractors adds those extractors to the config that are required by enabled detectors but have not been explicitly enabled.

type ScanResult

type ScanResult struct {
	Version   string
	StartTime time.Time
	EndTime   time.Time
	// Status of the overall scan.
	Status *plugin.ScanStatus
	// Status and versions of the inventory+vuln plugins that ran.
	PluginStatus []*plugin.Status
	Inventories  []*extractor.Inventory
	Findings     []*detector.Finding
}

ScanResult stores the software inventory and security findings that a scan run found.

type Scanner

type Scanner struct{}

Scanner is the main entry point of the scanner.

func New

func New() *Scanner

New creates a new scanner instance.

func (Scanner) Scan

func (Scanner) Scan(ctx context.Context, config *ScanConfig) (sr *ScanResult)

Scan executes the extraction and detection using the provided scan config.