binary

README

Adding tests for the Binary cataloger

[!TIP] TL;DR to add a test for a new classifier:

1. head to the correct directory: cd test-fixtures
2. add a new entry to config.yaml to track where to get the binary from (verify the entry with make list)
3. run make download to get the binary
4. run make add-snippet and follow the prompts (use / to search)
5. add a new test case to Test_Cataloger_PositiveCases in ../cataloger_test.go

To test the binary cataloger we run it against a set of files ("test fixtures"). There are two kinds of test fixtures:

• Full binaries: files downloaded and cached at test runtime
• Snippets: ~100 byte files checked into the repo

The upside with snippets is that they live with the test, don't necessarily require network access or hosting concerns, and are easy to add. The downside is that they are not the entire real binary so modifications may require recreating the snippet entirely.

The upside with full binaries is that they are the "Real McCoy" and allows the business logic to change without needing to update the fixture. The downside is that they require network access and take up a lot of space. For instance, downloading all binaries for testing today requires downloading ~15GB of container images and ends up being ~500MB of disk space.

You can find the test fixtures at the following locations:

syft/pkg/cataloger/binary/test-fixtures/
└── classifiers/
    ├── bin/        # full binaries
    ├── ...
    └── snippets/   # snippets

And use tooling to list and manage the fixtures:

• make list - list all fixtures
• make download - download binaries that are not covered by a snippet
• make download-all - download all binaries
• go run ./manager add-snippet - add a new snippet based off of a configured binary
• capture-snippet.sh - add a new snippet based off of a binary on your local machine (not recommended, but allowed)

There is a config.yaml that tracks all binaries that the tests can use. This makes it possible to download it at any time from a hosted source. Today the only method allowed is to download a container image and extract files out.

Here is an example entry in config.yaml for a binary reference from a container image:

from-images:
  
  # note the group-name is assumed from the single binary name extracted: "redis-server"
  - version: 7.2.3
    images:
      # note we're pulling the same binary from multiple images (representing different architectures)
      - ref: redis:7.2.3@sha256:d4c84914b872521e215f77d8845914c2268a96b0e35bacd5691e1f5e1f88b500
        platform: linux/amd64
      - ref: redis:7.2.3@sha256:a0a0c38b31011b813cddf78d997f8ccba13019c27efd386984b0cfc1e4b618ff
        platform: linux/arm64
    # the paths to extract from the binary...
    paths:
      - /usr/local/bin/redis-server

  # since there are multiple binaries in the image, we need to specify the group-name
  - name: ruby-bullseye-shared-libs
    version: 2.7.7
    images:
      - ref: ruby:2.7.7-bullseye@sha256:055191740a063f33fef1f09423e5ed8f91143aae62a3772a90910118464c5120
        platform: linux/amd64
    paths:
      - /usr/local/bin/ruby
      - /usr/local/lib/libruby.so.2.7.7
      - /usr/local/lib/libruby.so.2.7

[!NOTE]
You will need a system with go, bash, strings, and xxd installed to capture test snippets.

Testing

The test cases have been setup to allow testing against full binaries or a mix of both (default). To force running only against full binaries run with:

go test -must-use-full-binaries ./syft/pkg/cataloger/binary/test-fixtures/...

Adding a new test fixture

Adding a snippet (recommended)

Even if you are adding a snippet, it is best practice to:

• create that snippet from a full binary (not craft a snippet by hand)
• track where the binary is from and how to download it in config.yaml

1. Follow the steps above to add a full binary

2. Run go run ./manager add-snippet and follow the prompts to create a new snippet

   • you should see your binary in the list of binaries to choose from. If not, check step 2
   • if the search results in no matching snippets, you can specify your own search with --search-for <grep-pattern>
   • you should see a new snippet file created in snippets/

3. Write a test that references your new snippet by <name>/<version>/<architecture>

   • <name> is the name of the binary (e.g. curl) or the name in config.yaml if specified
   • note that your test does not know about if it's running against a snippet or a full binary

Adding a full binary

1. Add a new entry to config.yaml with the following fields

• if you are adding a single binary, the name field does not need to be specified
• the name field is useful for distinguishing a quality about the binary (e.g. java vs java-jre-ibm)

1. Run make download and ensure your new binary is downloaded

Adding a custom snippet

If you need to add a snippet that is not based off of a full binary, you can use the capture-snippet.sh script.

./capture-snippet.sh <binary-path> <version> [--search-for <pattern>] [--length <length>] [--prefix-length <prefix_length>] [--group <name>]

This is not recommended because it is not reproducible and does not allow for the test to be run against a full binary.

Documentation

Overview

Package binary provides a concrete Cataloger implementations for surfacing possible packages based on signatures found within binary files.

Index

• func NewCataloger(cfg CatalogerConfig) pkg.Cataloger
• type Cataloger
  • func (c Cataloger) Catalog(resolver file.Resolver) ([]pkg.Package, []artifact.Relationship, error)
  • func (c Cataloger) Name() string
• type CatalogerConfig
  • func DefaultCatalogerConfig() CatalogerConfig
  • func (cfg CatalogerConfig) MarshalJSON() ([]byte, error)
• type Classifier
  • func DefaultClassifiers() []Classifier
  • func (cfg Classifier) MarshalJSON() ([]byte, error)
• type EvidenceMatcher
  • func FileContentsVersionMatcher(pattern string) EvidenceMatcher

Functions

func NewCataloger

func NewCataloger(cfg CatalogerConfig) pkg.Cataloger

Types

type Cataloger

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

Cataloger is the cataloger responsible for surfacing evidence of a very limited set of binary files, which have been identified by the classifiers. The Cataloger is _NOT_ a place to catalog any and every binary, but rather the specific set that has been curated to be important, predominantly related to toolchain- related runtimes like Python, Go, Java, or Node. Some exceptions can be made for widely-used binaries such as busybox.

func (Cataloger) Catalog

func (c Cataloger) Catalog(resolver file.Resolver) ([]pkg.Package, []artifact.Relationship, error)

Catalog is given an object to resolve file references and content, this function returns any discovered Packages after analyzing the catalog source.

func (Cataloger) Name

func (c Cataloger) Name() string

Name returns a string that uniquely describes the Cataloger

type CatalogerConfig

type CatalogerConfig struct {
	Classifiers []Classifier `yaml:"classifiers" json:"classifiers" mapstructure:"classifiers"`
}

func DefaultCatalogerConfig

func DefaultCatalogerConfig() CatalogerConfig

func (CatalogerConfig) MarshalJSON

func (cfg CatalogerConfig) MarshalJSON() ([]byte, error)

type Classifier

type Classifier struct {
	Class string `json:"class"`

	// FileGlob is a selector to narrow down file inspection using the **/glob* syntax
	FileGlob string `json:"fileGlob"`

	// EvidenceMatcher is what will be used to match against the file in the source
	// location. If the matcher returns a package, the file will be considered a candidate.
	EvidenceMatcher EvidenceMatcher `json:"-"`

	// Package is the name to use for the package
	Package string `json:"package"`

	// PURL is the Package URL to use when generating a package
	PURL packageurl.PackageURL `json:"purl"`

	// CPEs are the specific CPEs we want to include for this binary with updated version information
	CPEs []cpe.CPE `json:"cpes"`
}

Classifier is a generic package classifier that can be used to match a package definition to a file that meets the given content criteria of the EvidenceMatcher.

func DefaultClassifiers

func DefaultClassifiers() []Classifier

func (Classifier) MarshalJSON

func (cfg Classifier) MarshalJSON() ([]byte, error)

type EvidenceMatcher

type EvidenceMatcher func(resolver file.Resolver, classifier Classifier, location file.Location) ([]pkg.Package, error)

EvidenceMatcher is a function called to catalog Packages that match some sort of evidence

func FileContentsVersionMatcher

func FileContentsVersionMatcher(pattern string) EvidenceMatcher