github.com/quay/claircore@v1.5.28/docs/getting_started/libvuln_usage.md (about)

     1  # Libvuln Usage
     2  Libvuln is the Go package responsible for keeping the database of
     3  vulnerabilities consistent, matching container image contents with
     4  vulnerabilities, and reporting diffs between updates of the same security
     5  database. 
     6  
     7  ## Usage 
     8  `Libvuln` is runtime constructed via the `libvuln.New` method. `New` requires a
     9  `libvuln.Opts` struct.
    10  
    11  ### Options
    12  {{# godoc libvuln.Options }}
    13  
    14  The above outlines the relevant bits of the Opts structure.
    15  
    16  ### Construction
    17  Constructing Libvuln is straight forward.
    18  
    19  ```go
    20  {{#include ../libvuln_test.go:new}}
    21  ```
    22  
    23  The constructing code should provide a valid Context tied to some lifetime.
    24  
    25  On construction, `New` will block until the security databases are initialized.
    26  Expect some delay before this method returns.
    27  
    28  ### Scanning
    29  Scanning is the process of taking a `claircore.IndexReport` comprised of a
    30  Manifest's content and determining which vulnerabilities affect the Manifest. A
    31  `claircore.VulnerabilityReport` will be returned with these details.
    32  
    33  ```go
    34  {{#include ../libvuln_test.go:scan}}
    35  ```
    36  
    37  In the above example, `Libindex` is used to generate a `claircore.IndexReport`.
    38  The index report is then provided to `Libvuln` and a subsequent vulnerability
    39  report identifying any vulnerabilities affecting the manifest is returned.
    40  
    41  ### Updates API
    42  By default, Libvuln manages a set of long running updaters responsible for
    43  periodically fetching and loading new advisory contents into its database. The
    44  Updates API allows a client to view and manipulate aspects of the update
    45  operations that updaters perform.
    46  
    47  In this getting started guide, we will only cover the two methods most
    48  interesting to new users.
    49  
    50  #### UpdateOperations
    51  This API provides a list of recent update operations performed by implemented updaters. 
    52  The `UpdateOperation` slice returned will be sorted by latest timestamp descending. 
    53  ```go
    54  {{#include ../libvuln_test.go:ops}}
    55  {{#include ../libvuln_test.go:ops_print}}
    56  ```
    57  
    58  #### UpdateDiff
    59  Mostly used by the Clair v4 notification subsystem, this endpoint will provide the
    60  caller with any removed or added vulnerabilities between two update operations.
    61  Typically a diff takes places against two versions of the same data source. This
    62  is useful to inform downstream applications what new vulnerabilities have
    63  entered the system.
    64  
    65  ```go
    66  {{#include ../libvuln_test.go:ops}}
    67  {{#include ../libvuln_test.go:ops_diff}}
    68  ```