Usage

The Decoration Pipeline

Beyond scanning, pkg/scanoss is the SDK for the SCANOSS decoration services, the same ones behind SCANOSS-CLI’s decoration commands. The pipeline runs a configurable set of them over the same PURLs (Package URLs, the pkg:type/namespace/name@version scheme identifying each component) in parallel, reports per-service progress, and returns one object keyed by service. Chunking and the worker pool are handled internally.

import "github.com/scanoss/scanoss.go/pkg/scanoss"

client, err := scanoss.New(scanoss.Config{
	APIKey:    os.Getenv("SCANOSS_API_KEY"),
	ChunkSize: 20, // PURLs per request
	Workers:   10, // max concurrent requests
})
if err != nil {
	return err
}

comps := scanoss.Components("pkg:github/scanoss/engine")

pipe := client.DecorationPipeline(
	scanoss.ServiceVulnerabilities,
	scanoss.ServiceLicenses,
)
pipe.Add(scanoss.ServiceCryptographyAlgorithms, scanoss.ServiceGeoprovenanceOrigin)

res, err := pipe.Run(context.Background(), comps)
if err != nil {
	log.Fatal(err) // only if every service failed
}
fmt.Println(res.String())

for svc, e := range res.Errors { // per-service failures are recorded, not fatal
	log.Printf("%s failed: %v", svc, e)
}

pipe.Run only returns an error when every service in the pipeline failed. A partial failure, one service down, the rest fine, comes back as a successful result with the failing service’s error recorded in res.Errors, so one bad service doesn’t discard the results you did get.

Component Version Requirements

scanoss.Components(...), used above, is a shorthand that builds a component list from bare PURLs, no version attached. That’s fine for lookups where the latest or any version will do. When a version matters, build the components directly instead:

comps := []scanoss.Component{
	{Purl: "pkg:github/scanoss/engine", Requirement: "4.17.21"},
	{Purl: "pkg:github/scanoss/engine", Requirement: "5.4.7"},
}

Either form of comps works anywhere a decoration call takes one, the pipeline, a single service, or WithDecorationReporter, shown next.

Per-Service Progress

Implement DecorationReporter and hand it to the call. Every update carries the service that produced it, so one receiver renders them all, and since services run concurrently, it must be safe for concurrent use:

type bars struct{ mu sync.Mutex }

func (b *bars) Decorating(service string, done, total int) {
	b.mu.Lock()
	defer b.mu.Unlock()
	fmt.Printf("%-26s %d/%d purls\n", service, done, total)
}

res, err := pipe.Run(ctx, comps, scanoss.WithDecorationReporter(&bars{}))

The per-service methods take it too:

res, err := client.Vulnerabilities.Components(ctx, comps, scanoss.WithDecorationReporter(&bars{}))

A Single Service, Without the Pipeline

Each decoration service is a grouped handle on the client, useful when you only need one and the pipeline’s parallel fan-out would be overkill:

res, err := client.Vulnerabilities.Components(ctx, comps) // *scanossapi.VulnerabilitiesResponse
// also: client.Licenses.Attribution, client.Cryptography.Algorithms,
//       client.Geoprovenance.Origin, client.Copyright.Evidence, ...

Scanning from the SDK

client, err := scanoss.New(scanoss.Config{APIKey: os.Getenv("SCANOSS_API_KEY")})
result, err := client.Scan.Folder(ctx, "./my-project")
// resume by id: client.Scan.Wait(ctx, scanID)

Scan.Folder and Scan.Files take further options:

Option	Behaviour
`scanoss.WithBOMReport`	Returns what the BOM selection rules concluded for the scan alongside its results.
`scanoss.WithFingerprintOptions(...)`	Tunes fingerprinting. Licence headers, documentation comments, and leading imports are skipped by default. Pass `wfp.WithoutSkipHeaders()` to fingerprint each file whole, or `wfp.WithSkipHeaders(limit)` to skip headers with a line limit. If both are passed, the last one wins.
`scanoss.WithRankingThreshold` / `postprocess.WithRankingThreshold`	Drops matches below a component-ranking threshold client-side before results are returned.
`scansource.WithIdentified`	Writes identify-rule verdicts onto `sbom.FileEvidence.Identified` and `sbom.Component.Identified`.

Each matched file’s sbom.FileEvidence also carries MatchIndex: where its component stood among the candidates the scan returned for that file, after the BOM rules, with 0 being the component the file originates from. IsPrimary() reports whether it’s 0. MatchIndex is nil on declared evidence and in documents written before the field existed.

Breaking change in v0.8.2. The library now skips licence headers by default, matching the CLI. Callers of pkg/wfp, pkg/scanoss, and pkg/scanpipeline that pass no fingerprint options now produce filtered fingerprints, which don’t match fingerprints taken with headers included. Some files can match a different component or version, or stop matching. To keep the previous output, pass wfp.WithoutSkipHeaders(). The libscanoss C exports GenerateWFP and GenerateWFPJSON also filter headers now, and don’t yet offer a way to opt out.

Scan.Wait on a resumed scan now applies BOM rules the same way a fresh scan does, so results from results <id> match what a fresh scan of the same source would produce.

Logging

The SDK writes nothing until you ask it to, it won’t put lines in your program’s output uninvited. One call covers every package it’s built from, not just the client:

scanoss.SetLogger(slog.Default())      // fold into your own stream
scanoss.SetLogger(slog.New(myHandler)) // keep them apart, or drop them
scanoss.SetLogger(nil)                 // back to silence

At Debug this also explains file selection, which rules a collection applied, and which rule excluded each file:

level=DEBUG msg="filters applied"  builtinFolderRules=true gitignore=true matchers=51
level=DEBUG msg="file excluded"    path=CHANGELOG.md rule=ext:.md
level=DEBUG msg="directory pruned" path=node_modules rule=dir:node_modules

Call SetLogger during initialisation: it’s process-wide, so changing it while calls are in flight can split a run’s output across two destinations.

Request Tuning

Beyond APIKey, APIURL, and the proxy/TLS fields covered in Authentication, Config exposes the request behaviour itself:

Field	Default	Behaviour
`ChunkSize`	`10`	PURLs per decoration request, shared by every decoration service.
`Workers`	`5`	Max concurrent requests. Never larger than the number of chunks.
`Timeout`	`120s`	Bounds one request attempt, body transfer included. A negative value disables it. Retry-After waits happen between attempts, so this doesn’t cut them short.
`MaxRetries`	`5`	Caps retries for a transient failure, a network error, a truncated response, or a `429`/`5xx` status. A negative value disables retries entirely.
`RetryBackoffBase`	`250ms`	The first wait the SDK computes itself, doubled per attempt. A `Retry-After` the server sent takes precedence over it.
`MaxServerRetryWait`	`5m`	Caps a single `Retry-After` wait, bounding a pathological server value. Doesn’t bound `RetryBackoffBase`’s own waits.

All are zero-value-safe: an unset field falls back to its default, so you only need to set what you’re overriding.

Get Started

Development

Pull Requests & CI

Governance

Evidence & Audit

Administration

Migrating

API Reference

The Decoration Pipeline

Component Version Requirements

Per-Service Progress

A Single Service, Without the Pipeline

Scanning from the SDK

Logging

Request Tuning

​The Decoration Pipeline

​Component Version Requirements

​Per-Service Progress

​A Single Service, Without the Pipeline

​Scanning from the SDK

​Logging

​Request Tuning

The Decoration Pipeline

Component Version Requirements

Per-Service Progress

A Single Service, Without the Pipeline

Scanning from the SDK

Logging

Request Tuning