producers

README

Producers

A producer is a program that parses the output of a tool and converts it into Dracon compatible file that can be used by the enrichers and consumers.

Writing Producers

Producers can be written in any language that supports protobufs, we have examples in Golang and Python. They are all structured the same way:

1. Parse program arguments:
   1. in: the raw tool results file location
   2. out: where to place the Dracon compatible output file location
2. Parse the in file into Protobufs (LaunchToolResponse)
3. Add metadata to Protobufs (e.g. git/source-code information)
4. Write the protobuf bytes to the out file

Producer API

For convenience, there are helper functions in the ./producers pkg/module for Golang/Python.

The WriteDraconOut/write_dracon_out method expects a list of issues to write as the LaunchToolResponse protobuf. Your producer should parse the output of a tool results into Issue protobufs which are then passed into this method.

Documentation

Overview

Package producers provides helper functions for writing Dracon compatible producers that parse tool outputs. Subdirectories in this package have more complete example usages of this package.

Index

• Variables
• func EnsureValidPURLTarget(purlTarget string) (string, error)
• func GetPURLTarget(purlType string, namespace string, name string, version string, ...) string
• func ParseFlags() error
• func ParseMultiJSONMessages(in []byte) ([]interface{}, error)
• func ReadInFile() ([]byte, error)
• func ReadLines() (result [][]byte, err error)
• func TestEndToEnd(t *testing.T, inPath string, expectedPbPath string) error
• func WriteDraconOut(toolName string, issues []*draconapiv1.Issue) error

Variables

var (
	// InResults represents incoming tool output.
	InResults string
	// OutFile points to the protobuf file where dracon results will be written.
	OutFile string
	// Append flag will append to the outfile instead of overwriting, useful when there's multiple inresults.
	Append bool
)

Functions

func EnsureValidPURLTarget

func EnsureValidPURLTarget(purlTarget string) (string, error)

EnsureValidPURLTarget takes a purl target string from an untrusted source, e.g. a tool output, and ensures it is a valid purl target according to the packageurl-go library.

func GetPURLTarget

func GetPURLTarget(purlType string, namespace string, name string, version string, qualifiers packageurl.Qualifiers, subpath string) string

GetPURLTarget returns a purl target string for a given package. This should be used as the `Issue.Target` field of SCA producers.

Example: GetPURLTarget("deb", "debian", "curl", "7.68.0", nil, "")

func ParseFlags

func ParseFlags() error

ParseFlags will parse the input flags for the producer and perform simple validation.

func ParseMultiJSONMessages

func ParseMultiJSONMessages(in []byte) ([]interface{}, error)

ParseMultiJSONMessages provides method to parse tool results in JSON format. It allows for parsing single JSON files with multiple JSON messages in them.

func ReadInFile

func ReadInFile() ([]byte, error)

ReadInFile returns the contents of the file given by InResults. TODO: replace with os.ReadFile

func ReadLines

func ReadLines() (result [][]byte, err error)

ReadLines returns the lines of the contents of the file given by InResults.

func TestEndToEnd

func TestEndToEnd(t *testing.T, inPath string, expectedPbPath string) error

TestEndToEnd is a helper function to test the end-to-end functionality of a producer.

func WriteDraconOut

func WriteDraconOut(
	toolName string,
	issues []*draconapiv1.Issue,
) error

WriteDraconOut provides a generic method to write the resulting protobuf to the output file.