You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This section will guide you through the process of developing Trivy plugins.
5
+
To help you get started quickly, we have published a [plugin template repository][plugin-template].
6
+
You can use this template as a starting point for your plugin development.
7
+
8
+
### Introduction
9
+
If you are looking to start developing plugins for Trivy, read [the user guide](./user-guide.md) first.
10
+
11
+
The development process involves the following steps:
12
+
13
+
- Create a repository for your plugin, named `trivy-plugin-<name>`.
14
+
- Create an executable binary that can be invoked as `trivy <name>`.
15
+
- Place the executable binary in a repository.
16
+
- Create a `plugin.yaml` file that describes the plugin.
17
+
- (Submit your plugin to the [Trivy plugin index][trivy-plugin-index].)
18
+
19
+
After you develop a plugin with a good name following the best practices and publish it, you can submit your plugin to the [Trivy plugin index][trivy-plugin-index].
20
+
21
+
### Naming
22
+
This section describes guidelines for naming your plugins.
23
+
24
+
#### Use `trivy-plugin-` prefix
25
+
The name of the plugin repository should be prefixed with `trivy-plugin-`.
26
+
27
+
#### Use lowercase and hyphens
28
+
Plugin names must be all lowercase and separate words with hyphens.
29
+
Don’t use camelCase, PascalCase, or snake_case; use kebab-case.
30
+
31
+
- NO: `trivy OpenSvc`
32
+
- YES: `trivy open-svc`
33
+
34
+
#### Be specific
35
+
Plugin names should not be verbs or nouns that are generic, already overloaded, or likely to be used for broader purposes by another plugin.
36
+
37
+
- NO: trivy sast (Too broad)
38
+
- YES: trivy govulncheck
39
+
40
+
41
+
#### Be unique
42
+
Find a unique name for your plugin that differentiates it from other plugins that perform a similar function.
43
+
44
+
- NO: `trivy images` (Unclear how it is different from the builtin “image" command)
45
+
- YES: `trivy registry-images` (Unique name).
46
+
47
+
#### Prefix Vendor Identifiers
48
+
Use vendor-specific strings as prefix, separated with a dash.
49
+
This makes it easier to search/group plugins that are about a specific vendor.
50
+
51
+
- NO: `trivy security-hub-aws (Makes it harder to search or locate in a plugin list)
52
+
- YES: `trivy aws-security-hub (Will show up together with other aws-* plugins)
53
+
54
+
### Choosing a language
55
+
Since Trivy plugins are standalone executables, you can write them in any programming language.
56
+
57
+
If you are planning to write a plugin with Go, check out [the Report struct](https://github.com/aquasecurity/trivy/blob/787b466e069e2d04e73b3eddbda621e5eec8543b/pkg/types/report.go#L13-L24),
58
+
which is the output of Trivy scan.
59
+
60
+
61
+
### Writing your plugin
62
+
Each plugin has a top-level directory, and then a `plugin.yaml` file.
63
+
64
+
```bash
65
+
your-plugin/
66
+
|
67
+
|- plugin.yaml
68
+
|- your-plugin.sh
69
+
```
70
+
71
+
In the example above, the plugin is contained inside a directory named `your-plugin`.
72
+
It has two files: `plugin.yaml` (required) and an executable script, `your-plugin.sh` (optional).
73
+
74
+
#### Writing a plugin manifest
75
+
The plugin manifest is a simple YAML file named `plugin.yaml`.
76
+
Here is an example YAML of [trivy-plugin-kubectl][trivy-plugin-kubectl] plugin that adds support for Kubernetes scanning.
We encourage you to copy and adapt plugin manifests of existing plugins.
102
+
103
+
- [count][trivy-plugin-count]
104
+
- [referrer][trivy-plugin-referrer]
105
+
106
+
The `plugin.yaml` field should contain the following information:
107
+
108
+
- name: The name of the plugin. This also determines how the plugin will be made available in the Trivy CLI. For example, if the plugin is named kubectl, you can call the plugin with `trivy kubectl`. (required)
109
+
- version: The version of the plugin. [Semantic Versioning][semver] should be used. (required)
110
+
- repository: The repository name where the plugin is hosted. (required)
111
+
- maintainer: The name of the maintainer of the plugin. (required)
112
+
- output: Whether the plugin supports [the output mode](./user-guide.md#output-mode-support). (optional)
113
+
- usage: Deprecated: use summary instead. (optional)
114
+
- summary: A short usage description. (required)
115
+
- description: A long description of the plugin. This is where you could provide a helpful documentation of your plugin. (required)
116
+
- platforms: (required)
117
+
- selector: The OS/Architecture specific variations of a execution file. (optional)
118
+
- os: OS information based on GOOS (linux, darwin, etc.) (optional)
119
+
- arch: The architecture information based on GOARCH (amd64, arm64, etc.) (optional)
120
+
- uri: Where the executable file is. Relative path from the root directory of the plugin or remote URL such as HTTP and S3. (required)
121
+
- bin: Which file to call when the plugin is executed. Relative path from the root directory of the plugin. (required)
122
+
123
+
The following rules will apply in deciding which platform to select:
124
+
125
+
- If both `os` and `arch` under `selector` match the current platform, search will stop and the platform will be used.
126
+
- If `selector` is not present, the platform will be used.
127
+
- If `os` matches and there is no more specific `arch` match, the platform will be used.
128
+
- If no `platform` match is found, Trivy will exit with an error.
129
+
130
+
After determining platform, Trivy will download the execution file from `uri` and store it in the plugin cache.
131
+
When the plugin is called via Trivy CLI, `bin` command will be executed.
132
+
133
+
#### Plugin arguments/flags
134
+
The plugin is responsible for handling flags and arguments.
135
+
Any arguments are passed to the plugin from the `trivy` command.
136
+
137
+
#### Testing plugin installation locally
138
+
A plugin should be archived `*.tar.gz`.
139
+
After you have archived your plugin into a `.tar.gz` file, you can verify that your plugin installs correctly with Trivy.
140
+
141
+
```bash
142
+
$ tar -czvf myplugin.tar.gz plugin.yaml script.py
143
+
plugin.yaml
144
+
script.py
145
+
146
+
$ trivy plugin install myplugin.tar.gz
147
+
2023-03-03T19:04:42.026+0600 INFO Installing the plugin from myplugin.tar.gz...
148
+
2023-03-03T19:04:42.026+0600 INFO Loading the plugin metadata...
149
+
150
+
$ trivy myplugin
151
+
Hello from Trivy demo plugin!
152
+
```
153
+
154
+
## Publishing plugins
155
+
The [plugin.yaml](#writing-a-plugin-manifest) file is the core of your plugin, so as long as it is published somewhere, your plugin can be installed.
156
+
If you choose to publish your plugin on GitHub, you can make it installable by placing the plugin.yaml file in the root directory of your repository.
157
+
Users can then install your plugin with the command, `trivy plugin install github.com/org/repo`.
158
+
159
+
While the `uri` specified in the plugin.yaml file doesn't necessarily need to point to the same repository, it's a good practice to host the executable file within the same repository when using GitHub.
160
+
You can utilize GitHub Releases to distribute the executable file.
161
+
For an example of how to structure your plugin repository, refer to [the plugin template repository][plugin-template].
162
+
163
+
## Distributing plugins via the Trivy plugin index
164
+
Trivy can install plugins directly by specifying a repository, like `trivy plugin install github.com/aquasecurity/trivy-plugin-referrer`,
165
+
so you don't necessarily need to register your plugin in the Trivy plugin index.
166
+
However, we would recommend distributing your plugin via the Trivy plugin index
167
+
since it makes it easier for other users to find (`trivy plugin search`) and install your plugin (e.g. `trivy plugin install kubectl`).
168
+
169
+
### Pre-submit checklist
170
+
- Review [the plugin naming guide](#naming).
171
+
- Ensure the `plugin.yaml` file has all the required fields.
172
+
- Tag a git release with a semantic version (e.g. v1.0.0).
173
+
- [Test your plugin installation locally](#testing-plugin-installation-locally).
174
+
175
+
### Submitting plugins
176
+
Submitting your plugin to the plugin index is a straightforward process.
177
+
All you need to do is create a YAML file for your plugin and place it in the [plugins/](https://github.com/aquasecurity/trivy-plugin-index/tree/main/plugins) directory of [the index repository][trivy-plugin-index].
178
+
179
+
Once you've done that, create a pull request (PR) and have it reviewed by the maintainers.
180
+
Once your PR is merged, the index will be updated, and your plugin will be available for installation.
181
+
[The plugin index page][plugin-list] will also be automatically updated to list your newly added plugin.
182
+
183
+
The content of the YAML file is very simple.
184
+
You only need to specify the name of your plugin and the repository where it is distributed.
After your PR is merged, the CI system will automatically retrieve the `plugin.yaml` file from your repository and update [the index.yaml file][index].
192
+
If any required fields are missing from your `plugin.yaml`, the CI will fail, so make sure your `plugin.yaml` has all the required fields before creating a PR.
193
+
Once [the index.yaml][index] has been updated, running `trivy plugin update` will download the updated index to your local machine.
`trivy plugin run` installs a plugin and runs it on the fly.
124
+
If the plugin is already present in the cache, the installation is skipped.
125
+
126
+
```bash
127
+
trivy plugin run kubectl pod your-pod -- --exit-code 1
128
+
```
129
+
130
+
## Upgrading Plugins
131
+
To upgrade all plugins that you have installed to their latest versions, run:
132
+
133
+
```bash
134
+
$ trivy plugin upgrade
135
+
```
136
+
137
+
To upgrade only certain plugins, you can explicitly specify their names:
138
+
139
+
```bash
140
+
$ trivy plugin upgrade <PLUGIN1><PLUGIN2>
141
+
```
142
+
143
+
## Uninstalling Plugins
144
+
Specify a plugin name with `trivy plugin uninstall` command.
145
+
146
+
```bash
147
+
$ trivy plugin uninstall kubectl
148
+
```
149
+
150
+
Here's the revised English documentation based on your requested changes:
151
+
152
+
## Output Mode Support
153
+
While plugins are typically intended to be used as subcommands of Trivy, plugins supporting the output mode can be invoked as part of Trivy's built-in commands.
154
+
155
+
!!! warning "EXPERIMENTAL"
156
+
This feature might change without preserving backwards compatibility.
157
+
158
+
Trivy supports plugins that are compatible with the output mode, which process Trivy's output, such as by transforming the output format or sending it elsewhere.
159
+
You can determine whether a plugin supports the output mode by checking the `OUTPUT` column in the output of `trivy plugin search` or `trivy plugin list`.
160
+
161
+
```bash
162
+
$ trivy plugin search
163
+
NAME DESCRIPTION MAINTAINER OUTPUT
164
+
aqua A plugin for integration with Aqua Security SaaS platform aquasecurity
165
+
kubectl A plugin scanning the images of a kubernetes resource aquasecurity
166
+
referrer A plugin for OCI referrers aquasecurity ✓
167
+
```
168
+
169
+
In this case, the `referrer` plugin supports the output mode.
170
+
171
+
For instance, in the case of image scanning, a plugin supporting the output mode can be called as follows:
0 commit comments