github.com/google/osv-scalibr@v0.4.1/docs/new_enricher.md (about)

     1  # Adding a new SCALIBR Enricher
     2  
     3  Enrichers are plugins that SCALIBR uses to enrich results from other plugins
     4  (e.g. Extractors, Detectors) with data from external sources (e.g. package
     5  information from deps.dev or vulnerabilities from osv.dev). They all implement
     6  the `Enricher` interface which provides the ability to:
     7  
     8  -   Access files on the filesystem being scanned through the
     9      [enrich parameters](#enrich-parameters) (āš ļø **discouraged: Detectors or
    10      Annotators should be used if possible**).
    11  -   Mutate results from other plugins.
    12  
    13  <!--  See enricher/enricher.go symbol \bEnricher\b -->
    14  
    15  <!--  See plugin/plugin.go symbol Plugin -->
    16  
    17  ## Implementation Steps
    18  
    19  See the
    20  [Base Image Enricher](/enricher/baseimage/baseimage.go)
    21  as an example.
    22  
    23  1.  Set up your enricher package in an [appropriate location](#code-location).
    24  1.  Create a struct that implements
    25      [`Enricher`](/enricher/enricher.go):
    26      *   Implement `Name()` to return a unique name, e.g. `baseimage`.
    27      *   Implement `Version()` to return 0. Increase it in the future whenever
    28          larger changes are made to the enricher.
    29      *   Implement `Enrich()` (see [param list](#enrich-parameters)) to run your
    30          enricher logic and augment [update inventory](#update-inventory) with
    31          new data.
    32  1.  Write tests.
    33  1.  Register your enricher in
    34      [list.go](/enricher/enricherlist/list.go)
    35      so you can use it in the CLI.
    36  1.  Update `docs/supported_inventory_types.md` to include your new enricher.
    37  1.  If you added new dependencies, regenerate the go.mod file by running
    38  
    39      ```sh
    40      $ `go mod tidy`
    41      ```
    42  
    43  1.  Test your new enricher on a local machine, using the plugin `Name()` to
    44      enable it, e.g.
    45  
    46      ```
    47      scalibr --plugins=baseimage ...
    48      ```
    49  
    50      See the
    51      [README](/README.md#as-a-standalone-binary)
    52      for more details on how to run SCALIBR locally.
    53  
    54  1.  Send the code out for review.
    55  
    56  ## Code location
    57  
    58  All new enrichers should be in a sub-folder of
    59  [enricher/](/enricher/). If there's already a
    60  directory that fits the enricher's category (e.g. `enricher/java` for enrichers
    61  that add data to Java packages) place it in there. Otherwise, feel free to
    62  create a new directory.
    63  
    64  ## Enrich parameters
    65  
    66  Enrichers accept two parameters:
    67  
    68  -   `ScanInput`: access to the filesystem or on-host information.
    69  -   `Inventory`: the output of other plugins.
    70  
    71  Although Enrichers can optionally access the filesystem, this is discouraged in
    72  most cases, and `ScanInput` should be `nil`.
    73  
    74  ## Network access
    75  
    76  Enrichers are primarily used to access APIs and update scan results. Because of
    77  this, Enrichers must explicitly convey this in their `Requirements`:
    78  
    79  ```
    80  // Requirements of the my enricher.
    81  func (*Enricher) Requirements() *plugin.Capabilities {
    82      return &plugin.Capabilities{Network: plugin.NetworkOnline}
    83  }
    84  ```
    85  
    86  ## Update inventory
    87  
    88  Enrichers mutate inventory returned by other plugins. They can:
    89  
    90  -   Add new objects or fields.
    91  -   Update existing objects or fields.
    92  -   Delete objects or fields.
    93  
    94  Below is an illustrative example. In the example the:
    95  
    96  1.  Java Reachability Enricher adds whether certain packages are reachable (can
    97      be run).
    98  1.  OSV Enricher adds new vulnerability findings from osv.dev.
    99  1.  VEX Enricher filters out vulnerabilities that are unreachable (cannot be
   100      exploited).
   101  
   102  šŸŸ¢ denotes objects or fields mutated (add, update, delete) by the previous
   103  enricher.
   104  
   105  ```sequence-diagram
   106  Title: Flow of inventory\nthrough plugins
   107  
   108  Java Extractor->>Java Reachability Enricher: {{package: "foo", version: "1.2"},\n{package: "bar", version: "2.3"}}
   109  Java Reachability Enricher->>OSV Enricher: {{package: "foo", version: "1.2" šŸŸ¢ reachable: "true"},\n{package: "bar", version: "2.3", šŸŸ¢ reachable: "false"}}
   110  OSV Enricher->>VEX Enricher: {{package: "foo", version: "1.2" reachable: "true"},\n{package: "bar", version: "2.3", reachable: "false"},\nšŸŸ¢ finding: {id: "CVE-123", package: "foo"},\nšŸŸ¢ finding: {id: "CVE-456", package: "bar"}}
   111  VEX Enricher->>Output: {{package: "foo", version: "1.2" reachable: "true"},\n{package: "bar", version: "2.3", reachable: "false"},\nfinding: {id: "CVE-123", package: "foo"},\nšŸŸ¢ \[REMOVED CVE-456\]}
   112  ```
   113  
   114  ## Questions
   115  
   116  In case you have any questions or feedback, feel free to open an issue.