# Plugins

The tool can load plugins to add support for more
[CVE databases](cve-database.md), [export](export.md) and [SBOM](sbom.md)
types.

## Search locations

The tool searches for plugins in the following locations:
 - In the paths specified by the command-line argument `--plugins`. This option
   can be specified multiple times to add multiple search paths.
 - In the paths specified in TOML configuration files, using the `plugins=`
   option. This option should be an array. If this option is specified in
   multiple configuration files, the list of search paths is extended with new
   values.
 - In the paths specified by the environment variable `SBOM_CVE_CHECK_PLUGINS`,
   which functions like the PATH environment variable, this variable is a list
   of search paths separated by colons.

The search path can contain:
 - A path to a Python module: A path to a `.py` file, which should be a simple
   standalone Python module.
 - A path to a Python package: A directory with a `__init__.py` file at the
   root of it. This method allows for a more complex plugin to be provided.
 - A path, to a directory or to a `.zip` file, containing Python modules and/or
   Python packages at the root of it. Be aware that the search is not done
   recursively.

## Plugin namespace

When the plugin is loaded, it will be located in the following namespace:
`sbom_cve_check.plugins`. Therefore, if you load a module named `my_module` or
a package named `my_package`, these will be loaded into
`sbom_cve_check.plugins.my_module` and `sbom_cve_check.plugins.my_package`
respectively.

## Python package as plugin

In the case of a Python package as a plugin, the `__init__.py` file should
import the classes, or the Python files, which contain the classes, that need
to be registered.

For example, for a plugin provided as a package, which provides a custom export
class named `MyExport` declared in `my_export.py` file, and which has the
following directory structure:

```
plugins
└── my_pkg
    ├── __init__.py
    └── my_export.py
```

The `__init__.py` file should contain either:
 - `from . import my_export`
 - `from .my_export import MyExport`

In the search path, we could specify either:
 - The path to the `plugins` directory,
 - Or the path to the `plugins/my-pkg` directory.

## Minimal examples

The examples below must implement all abstract methods of the base class.

The classes declared in the examples below are automatically registered in
the associated registry thanks to the associated decorator.

For more details on how to implement these classes and how the decorator allows
the class to be registered in the registry, see the section titled
[design](design.md).

### CVE database

```py
from sbom_cve_check.cve_db.annot_base import AnnotDatabase
from sbom_cve_check.cve_db.registry import register_cve_db

@register_cve_db('my-annotation')
class MyAnnotation(AnnotDatabase):
    def __init__(self, path, name, **kwargs):
        super().__init__(name, **kwargs)

    ...
```

### SBOM

```py
from sbom_cve_check.sbom.registry import register_sbom
from sbom_cve_check.sbom.sbom_base import Sbom

@register_sbom('my-sbom')
class MySbom(Sbom):
    def __init__(self, path):
        super().__init__(path)

    ...
```

### Export

```py
from sbom_cve_check.export.export_base import BaseExport
from sbom_cve_check.export.registry import register_export

@register_export('my-export')
class MyExport(BaseExport):
    ...
```