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

     1  # Libindex Usage
     2  Libindex is the Go package responsible for fetching container image layers,
     3  identifying packages, distributions, and repositories within these layers, and
     4  computing a final coalesced Index Report.
     5  
     6  An Index Report is primarily used as input to Libvuln's vulnerability matching
     7  process.
     8  
     9  ## Usage
    10  Libindex is runtime constructed via the `libindex.New` method. New requires an `libindex.Opts` struct.
    11  
    12  ### Options
    13  {{# godoc libindex.Options }}
    14  
    15  The above outlines the relevant bits of the Options structure.
    16  
    17  Store is required needs to be an object that satisfies the indexer.Store interface.
    18  
    19  Locker is required and needs to satisfy the LockSource interface.
    20  
    21  FetchArena is required and needs to satify the FetchArena interface.
    22  
    23  Providing a nil "Ecosystems" slice will supply the default set, instructing
    24  Libindex to index for all supported content in a layer, and is typically
    25  desired.
    26  
    27  ### Construction
    28  Constructing Libindex is straight forward.
    29  
    30  ```go
    31  {{#include ../libindex_test.go:new}}
    32  ```
    33  
    34  The constructing code should provide a valid Context tied to some lifetime.
    35  
    36  ### Indexing
    37  Indexing is the process of submitting a manifest to Libindex, fetching the
    38  manifest's layers, indexing their contents, and coalescing a final Index
    39  Report.
    40  
    41  Coalescing is the act of computing a final set of contents (packages,
    42  distributions, repos) from a set of layers. Since layers maybe shared between
    43  many manifests, the final contents of a manifest must be computed.
    44  
    45  To perform an Index you must provide a claircore.Manifest data struture to the
    46  Index method.  The Manifest data structure describes an image manifest's layers
    47  and where they can be fetched from.
    48  
    49  ```go
    50  {{#include ../libindex_test.go:index}}
    51  ```
    52  
    53  The Index method will block until an claircore.IndexReport is returned.  The
    54  context should be bound to some valid lifetime such as a request. 
    55  
    56  As the Indexer works on the manifest it will update its database throughout the
    57  process.  You may view the status of an index report via the "IndexReport"
    58  method. 
    59  
    60  ```go
    61  {{#include ../libindex_test.go:indexreport}}
    62  ```
    63  
    64  Libindex performs its work incrementally and saves state as it goes along. If
    65  Libindex encounters an intermittent error during the index (for example, due to
    66  network failure while fetching a layer), when the manifest is resubmitted only
    67  the layers not yet indexed will be fetched and processed. 
    68  
    69  ### State
    70  Libindex treats layers as content addressable. Once a layer identified by a
    71  particular hash is indexed its contents are definitively known. A request to
    72  re-index a known layer results in returning the previous successful response.
    73  
    74  This comes in handy when dealing with base layers. The Ubuntu base layer is
    75  seen very often across container registries. Treating this layer as content
    76  addressable precludes the need to fetch and index the layer every time Libindex
    77  encounters it in a manifest.
    78  
    79  There are times where re-indexing the same layer is necessary however. At the
    80  point where Libindex realizes a new version of a component has not indexed a
    81  layer being submitted it will perform the indexing operation.
    82  
    83  A client must notice that Libindex has updated one of its components and
    84  subsequently resubmit Manifests. The State endpoint is implemented for this
    85  reason.
    86  
    87  Clients may query the State endpoint to receive an opaque string acting as a
    88  cookie, identifying a unique state of Libindex. When a client sees this cookie
    89  change it should re-submit manifests to Libindex to obtain a new index report.
    90  
    91  ```go
    92  {{#include ../libindex_test.go:state}}
    93  ```
    94  
    95  ### AffectedManifests
    96  Libindex is capable of providing a client with all manifests affected by a set
    97  of vulnerabilities.  This functionality is designed for use with a notification
    98  mechanism.
    99  
   100  ```go
   101  {{#include ../libindex_test.go:affectedmanifests}}
   102  ```
   103  
   104  The slice of vulnerabilities returned for each manifest hash will be sorted by
   105  `claircore.NormalizedSeverity` in "most severe" descending order.