github.com/google/osv-scalibr@v0.4.1/annotator/annotator.go (about)

     1  // Copyright 2025 Google LLC
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  //
     7  //      http://www.apache.org/licenses/LICENSE-2.0
     8  //
     9  // Unless required by applicable law or agreed to in writing, software
    10  // distributed under the License is distributed on an "AS IS" BASIS,
    11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  // See the License for the specific language governing permissions and
    13  // limitations under the License.
    14  
    15  // Package annotator provides the interface for annotation plugins.
    16  package annotator
    17  
    18  import (
    19  	"context"
    20  
    21  	scalibrfs "github.com/google/osv-scalibr/fs"
    22  	"github.com/google/osv-scalibr/inventory"
    23  	"github.com/google/osv-scalibr/plugin"
    24  )
    25  
    26  // Annotator is the interface for an annotation plugin, used to add additional
    27  // information to scan results such as VEX statements. Annotators have access to
    28  // the filesystem but should ideally not query any external APIs. If you need to
    29  // modify the scan results based on the output of network calls you should use
    30  // the Enricher interface instead.
    31  type Annotator interface {
    32  	plugin.Plugin
    33  	// Annotate annotates the scan results with additional information.
    34  	Annotate(ctx context.Context, input *ScanInput, results *inventory.Inventory) error
    35  }
    36  
    37  // Config stores the config settings for the annotation run.
    38  type Config struct {
    39  	Annotators []Annotator
    40  	ScanRoot   *scalibrfs.ScanRoot
    41  }
    42  
    43  // ScanInput provides information for the annotator about the scan.
    44  type ScanInput struct {
    45  	// The root of the artifact being scanned.
    46  	ScanRoot *scalibrfs.ScanRoot
    47  }
    48  
    49  // Run runs the specified annotators on the scan results and returns their statuses.
    50  func Run(ctx context.Context, config *Config, inventory *inventory.Inventory) ([]*plugin.Status, error) {
    51  	var statuses []*plugin.Status
    52  	if len(config.Annotators) == 0 {
    53  		return statuses, nil
    54  	}
    55  
    56  	input := &ScanInput{
    57  		ScanRoot: config.ScanRoot,
    58  	}
    59  
    60  	for _, a := range config.Annotators {
    61  		err := a.Annotate(ctx, input, inventory)
    62  		statuses = append(statuses, plugin.StatusFromErr(a, false, err, nil))
    63  	}
    64  	return statuses, nil
    65  }