Skip to content

Commit 5c3c466

Browse files
owenrumneybonddim
owenrumney
and
bonddim
authored
docs: update documentation for v2 (#161)
* docs: update documentation for v2 Signed-off-by: Owen Rumney <[email protected]> * chore: updates from review Signed-off-by: Owen Rumney <[email protected]> * docs/fix updates (#162) * Fix connection endpoint URL and main readme * fix urls on main readme * Replace emoji with GH alerts. Update examples and platform config image * Remove preview from v2 * Fix nested list an image position * fix formatting --------- Signed-off-by: Owen Rumney <[email protected]> Co-authored-by: Dmytro Bondar <[email protected]>
1 parent 5df4391 commit 5c3c466

File tree

16 files changed

+236
-55
lines changed

16 files changed

+236
-55
lines changed

‎README.md

Lines changed: 29 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,33 @@
1-
# Trivy for Azure DevOps
1+
# Aqua Trivy
22

33
An Azure DevOps Pipelines Task for [Trivy](https://github.com/aquasecurity/trivy), with an integrated UI.
44

5-
![Screenshot showing the Trivy extension in the Azure Devops UI](images/resultsview.png)
5+
![Screenshot showing the Trivy extension in the Azure DevOps UI](images/resultsview.png)
66

7-
Documentation and more information is available on the [Azure DevOps Marketplace](https://marketplace.visualstudio.com/items?itemName=AquaSecurityOfficial.trivy-official).
7+
## Installation
8+
9+
1. Install the Trivy task in your Azure DevOps organisation (hit the `Get it free` button above).
10+
11+
2. Add the task to your `azure-pipelines.yml` in a project where you'd like to run Trivy:
12+
13+
## Agents Compatibility
14+
15+
| Agent OS | Run binary | Scan FileSystem | Docker |
16+
| :------- | :--------: | :-------------: | :----: |
17+
| Linux | ✅ | ✅ | ✅ |
18+
| MacOS | ✅ | ✅ | 🔴 |
19+
| Windows | ✅ | ✅ | 🔴 |
20+
21+
### Self-Hosted Agents
22+
23+
Access to Docker Engine is required to run Trivy in docker container or scan docker images.
24+
25+
While you can attempt to scan Docker images on Windows, running the task using a Docker image will mostly fail.
26+
27+
## Configuration
28+
29+
If new to the Trivy pipeline task, you should use the newer v2 version.
30+
31+
[Trivy@1 Configuration](https://github.com/aquasecurity/trivy-azure-pipelines-task/blob/main/docs/trivyv1.md)
32+
33+
[Trivy@2 Configuration](https://github.com/aquasecurity/trivy-azure-pipelines-task/blob/main/docs/trivyv2.md)

‎docs/connectedservice.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Configuring Aqua Platform Service
2+
3+
When using the Azure Pipeline Task with Aqua Platform, previously you would configure the `AQUA_KEY` and `AQUA_SECRET` as variables and reference them in the YAML for the task. This change moves the configuration of the Aqua Platform connection to the connected settings.
4+
5+
## Configuring
6+
7+
1. Go to `Project Settings`
8+
2. Choose `Service Connections`
9+
3. Choose `New Service Connection` button on the top right of the screen
10+
4. Select `Aqua Platform Configuration` from the list of available setups and configure with the details from your account:
11+
12+
- ensure you give the Connection a sensible name
13+
- ensure that the URLs are correct regional URLs for your account
14+
- see [Aqua Documentation](https://docs.aquasec.com/saas/getting-started/welcome/saas-regions/) for more information
15+
16+
![Connected Service](../images/aquaPlatformConfig.png)

‎marketplace.md renamed to ‎docs/trivyv1.md

Lines changed: 5 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,44 +1,17 @@
1-
# Trivy
1+
# Trivy v1 Configuration
22

3-
An Azure DevOps Pipelines Task for [Trivy](https://github.com/aquasecurity/trivy), with an integrated UI.
4-
5-
![Screenshot showing the Trivy extension in the Azure DevOps UI](images/resultsview.png)
6-
7-
## Installation
8-
9-
1. Install the Trivy task in your Azure DevOps organisation (hit the `Get it free` button above).
10-
11-
2. Add the task to your `azure-pipelines.yml` in a project where you'd like to run Trivy:
12-
13-
```yaml
14-
- task: trivy@1
15-
```
16-
17-
## Agents Compatibility
18-
19-
| Agent OS | Run binary | Scan FileSystem | Docker |
20-
| :------- | :--------: | :-------------: | :----: |
21-
| Linux | ✅ | ✅ | ✅ |
22-
| MacOS | ✅ | ✅ | 🔴 |
23-
| Windows | ✅ | ✅ | 🔴 |
24-
25-
### Self-Hosted Agents
26-
27-
At least, access to Docker Engine is required to run Trivy in docker container or scan docker images.
28-
29-
While you can attempt to scan Docker images on Windows, running the task using a Docker image will mostly fail.
30-
31-
## Configuration
3+
> [!IMPORTANT]
4+
> If you are new to the Trivy Azure Pipeline task, you would be better using the [Trivy v2 task](trivyv2.md)
325
336
Configuring the task can be done directly editing the pipeline yaml or through the configuration pane on the right of the pipeline UI screen
347

358
Select the Trivy task from the installed tasks
369

37-
![Select Trivy](images/trivytask.png)
10+
![Select Trivy](../images/trivytask.png)
3811

3912
The input variables are grouped logically, expand the sections to make the required changes.
4013

41-
![Pipeline settings](images/settings.png)
14+
![Pipeline settings](../images/settings.png)
4215

4316
## Input Variables
4417

‎docs/trivyv2.md

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
# Trivy v2 Configuration
2+
3+
Configuring the task can be done directly editing the pipeline yaml or through the configuration pane on the right of the pipeline UI screen
4+
5+
Select the Trivy task from the installed tasks
6+
7+
![Select Trivy](../images/trivytask.png)
8+
9+
The input variables are grouped logically, expand the sections to make the required changes.
10+
11+
![Pipeline settings](../images/settingsv2.png)
12+
13+
## Input Variables
14+
15+
You can supply several inputs to customise the task.
16+
17+
### Aqua Platform Integration
18+
19+
For more information about creating the connected service, see [Configuring Aqua Connected Service](connectedservice.md)
20+
21+
| Input | Type | Defaults | Description |
22+
| -------------- | ----------------------------- | -------- | ----------------------------------------------------- |
23+
| `aquaPlatform` | connectedService:AquaPlatform | | Select the Aqua Security Platform service connection. |
24+
25+
### Trivy Runner
26+
27+
| Input | Type | Defaults | Description |
28+
| --------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
29+
| `method` | pickList | install | Specify how Trivy should be executed: `install` to download Trivy from GitHub releases, `docker` to run Trivy as a Docker container, or `system` to use a pre-installed Trivy executable. |
30+
| `image` | string | | Specify a custom Trivy Docker image to use. If set, the `version` option is ignored. Visible only when `method = docker`. |
31+
| `version` | string | latest | Specify the version of Trivy to use. Ignored if a custom Trivy Docker image is specified. Visible unless `method = system` or `image` is set. |
32+
| `options` | string | | Provide additional command-line options to pass to the Trivy executable. |
33+
34+
---
35+
36+
### Scan Options
37+
38+
| Input | Type | Defaults | Description |
39+
| ------------------ | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
40+
| `type` | pickList | | The type of scan to perform. Options: `filesystem`, `image`, `repository`. |
41+
| `target` | string | | The specified target will be scanned using the selected scan type. |
42+
| `scanners` | pickList | | Choose which scanners to run. Options: `license`, `misconfig`, `secret`, `vuln`. Multi-select is supported. |
43+
| `severities` | pickList | | Severities of security issues to be displayed. Options: `UNKNOWN`, `LOW`, `MEDIUM`, `HIGH`, `CRITICAL`. Multi-select is supported. |
44+
| `ignoreUnfixed` | boolean | false | Include only fixed vulnerabilities. |
45+
| `ignoreScanErrors` | boolean | false | Ignore scan errors and continue the pipeline with a `SucceededWithIssues` result. |
46+
47+
---
48+
49+
### Reports
50+
51+
| Input | Type | Defaults | Description |
52+
| ----------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
53+
| `reports` | pickList | | Select additional reports to generate. JSON report is always generated. Options: `asff`, `cosign`, `cyclonedx`, `github`, `html`, `junit`, `sarif`, `spdx`, `spdxjson`, `table`. Multi-select is supported. |
54+
| `publish` | boolean | false | Publish generated reports as pipeline artifacts. |
55+
| `templates` | string | | Specify a custom directory containing templates for the ASFF, HTML, JUnit reports. If not set, will look up in the `contrib` directory of the Trivy installation. Visible only when `method = system` and `reports` is not empty. |
56+
57+
## Examples
58+
59+
### Scanning multiple targets and publish results as test run
60+
61+
```yaml
62+
steps:
63+
- task: trivy@2
64+
name: TrivyCurrent
65+
displayName: 'Scan current repository as filesystem'
66+
inputs:
67+
version: 'latest'
68+
type: 'filesystem'
69+
target: '.'
70+
scanners: 'misconfig,vuln,secret'
71+
ignoreUnfixed: true
72+
ignoreScanErrors: true
73+
reports: 'github, html, junit'
74+
publish: true
75+
76+
- task: trivy@2
77+
name: TrivyPrivate
78+
displayName: 'Scan private GitHub repository'
79+
inputs:
80+
type: 'repository'
81+
target: 'https://github.com/owner/repo'
82+
scanners: 'secret,vuln,misconfig'
83+
ignoreUnfixed: true
84+
reports: 'github, junit, sarif'
85+
env:
86+
GITHUB_TOKEN: $(GITHUB_TOKEN)
87+
88+
- task: PublishTestResults@2
89+
inputs:
90+
testResultsFormat: 'JUnit'
91+
testResultsFiles: |
92+
$(TrivyCurrent.junitReport)
93+
$(TrivyPrivate.junitReport)
94+
searchFolder: '$(Agent.TempDirectory)'
95+
testRunTitle: 'Trivy'
96+
publishRunAttachments: false
97+
```
98+
99+
### Scanning Images in Private Registries
100+
101+
You can scan images in private registries by using the `image` input after completing a `docker login`. For example:
102+
103+
```yaml
104+
steps:
105+
- task: Docker@2
106+
displayName: Login to container registry
107+
inputs:
108+
command: login
109+
containerRegistry: containerRegistryServiceConnection
110+
111+
- task: trivy@2
112+
inputs:
113+
type: 'image'
114+
image: my.private.registry/org/my-image:latest
115+
```
116+
117+
### Scanning with Aqua Platform support
118+
119+
Configure your Connected Service using the [service endpoint docs](connectedservice.md).
120+
121+
> [!IMPORTANT]
122+
> Aqua Platform integration only works for `install` mode and does not support `image` scanning.
123+
124+
```yaml
125+
steps:
126+
- task: trivy@2
127+
inputs:
128+
aquaPlatform: 'Aqua Platform Connection'
129+
version: 'latest'
130+
type: 'filesystem'
131+
target: '.'
132+
scanners: 'misconfig,vuln,secret'
133+
ignoreUnfixed: true
134+
ignoreScanErrors: true
135+
reports: 'github, html, junit'
136+
publish: true
137+
```

‎images/aqua-logo.png

100755100644
-461 Bytes
Loading

‎images/aquaPlatformConfig.png

37.2 KB
Loading

‎images/icon.png

100644100755
461 Bytes
Loading

‎images/resultsview.png

107 KB
Loading

‎images/settingsv2.png

104 KB
Loading

‎trivy-task/trivyV1/task.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
"friendlyName": "Trivy",
66
"description": "Trivy is the world's most popular open source vulnerability and misconfiguration scanner. It is reliable, fast, extremely easy to use, and it works wherever you need it.",
77
"helpMarkDown": "[Learn more about this task](https://github.com/aquasecurity/trivy-azure-pipelines-task)",
8-
"helpUrl": "https://github.com/aquasecurity/trivy-azure-pipelines-task",
8+
"helpUrl": "https://github.com/aquasecurity/trivy-azure-pipelines-task/docs/trivyv1.md",
99
"category": "Test",
1010
"author": "Aqua Security",
1111
"version": {

‎trivy-task/trivyV1/utils.ts

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,16 @@ function validateInputs(inputs: TaskInputs): void {
7979
});
8080
}
8181

82+
if (inputs.aquaKey && inputs.image) {
83+
throw new Error('Aqua Platform is not supported for image scans.');
84+
}
85+
86+
if (inputs.aquaKey && inputs.docker) {
87+
throw new Error(
88+
'Aqua Platform is not supported when running in Docker mode.'
89+
);
90+
}
91+
8292
// validate image and path inputs
8393
if (!inputs.image && !inputs.scanPath) {
8494
throw new Error(

‎trivy-task/trivyV2/index.ts

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,11 +26,25 @@ async function run() {
2626

2727
// configure the environment variables for Aqua Plugin
2828
if (inputs.hasAquaAccount) {
29+
if (inputs.scanType === 'image') {
30+
throw new Error(
31+
'Aqua platform is not supported for image scan. Please use the filesystem scan.'
32+
);
33+
}
34+
35+
if (inputs.method === 'docker') {
36+
throw new Error(
37+
'Aqua platform is not supported for docker run. Please use the install method.'
38+
);
39+
}
40+
2941
task.rmRF(assuranceFilePath);
3042
task.debug('Configuring Aqua environment variables...');
3143
env.AQUA_ASSURANCE_EXPORT = assuranceFilePath;
3244
env.AQUA_KEY = inputs.aquaKey;
3345
env.AQUA_SECRET = inputs.aquaSecret;
46+
env.AQUA_URL = inputs.aquaUrl;
47+
env.CSPM_URL = inputs.authUrl;
3448
env.OVERRIDE_BRANCH = task.getVariable('Build.SourceBranchName');
3549
env.OVERRIDE_REPOSITORY = task.getVariable('Build.Repository.Name');
3650
env.TRIVY_RUN_AS_PLUGIN = 'aqua';

‎trivy-task/trivyV2/inputs.ts

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,8 @@ export type TaskInputs = {
1717
hasAquaAccount: boolean;
1818
aquaKey?: string;
1919
aquaSecret?: string;
20+
aquaUrl?: string;
21+
authUrl?: string;
2022
};
2123

2224
/**
@@ -55,5 +57,11 @@ export function getTaskInputs(): TaskInputs {
5557
'aquaSecret',
5658
true
5759
),
60+
aquaUrl: task.getEndpointUrl(aquaPlatform, true),
61+
authUrl: task.getEndpointAuthorizationParameter(
62+
aquaPlatform,
63+
'authUrl',
64+
true
65+
),
5866
};
5967
}

‎trivy-task/trivyV2/runner.ts

Lines changed: 0 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -41,17 +41,6 @@ async function dockerRunner(inputs: TaskInputs): Promise<ToolRunner> {
4141
runner.line(`-e TRIVY_CACHE_DIR=${tmpPath}`);
4242
runner.argIf(dockerConfig, ['-e', `DOCKER_CONFIG=${dockerConfig}`]);
4343

44-
if (inputs.hasAquaAccount) {
45-
runner.argIf(process.env.AQUA_URL, ['-e', 'AQUA_URL']);
46-
runner.argIf(process.env.CSPM_URL, ['-e', 'CSPM_URL']);
47-
runner.line('-e AQUA_ASSURANCE_EXPORT');
48-
runner.line('-e AQUA_KEY');
49-
runner.line('-e AQUA_SECRET');
50-
runner.line('-e OVERRIDE_BRANCH');
51-
runner.line('-e OVERRIDE_REPOSITORY');
52-
runner.line('-e TRIVY_RUN_AS_PLUGIN');
53-
}
54-
5544
const trivyImage =
5645
inputs.image === ''
5746
? `aquasec/trivy:${stripV(inputs.version)}`

‎trivy-task/trivyV2/task.json

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,15 +3,14 @@
33
"id": "8f9cb13f-f551-439c-83e4-fac6801c3fab",
44
"name": "trivy",
55
"friendlyName": "Trivy",
6-
"preview": true,
76
"description": "Trivy is the world's most popular open source vulnerability and misconfiguration scanner. It is reliable, fast, extremely easy to use, and it works wherever you need it.",
87
"helpMarkDown": "[Learn more about this task](https://github.com/aquasecurity/trivy-azure-pipelines-task)",
9-
"helpUrl": "https://github.com/aquasecurity/trivy-azure-pipelines-task",
8+
"helpUrl": "https://github.com/aquasecurity/trivy-azure-pipelines-task/docs/trivyv2.md",
109
"category": "Test",
1110
"author": "Aqua Security",
1211
"version": {
1312
"Major": 2,
14-
"Minor": 0,
13+
"Minor": 1,
1514
"Patch": 0
1615
},
1716
"instanceNameFormat": "Echo trivy $(version)",

‎vss-manifest.js

Lines changed: 14 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ module.exports = () => {
3838
],
3939
content: {
4040
license: { path: 'LICENSE' },
41-
details: { path: 'marketplace.md' },
41+
details: { path: 'README.md' },
4242
},
4343
links: {
4444
home: { uri: 'https://www.aquasec.com/' },
@@ -68,14 +68,23 @@ module.exports = () => {
6868
targets: ['ms.vss-endpoint.endpoint-types'],
6969
properties: {
7070
name: 'AquaPlatform',
71-
displayName: 'Aqua Security Platform',
72-
icon: 'images/aqua-logo.png',
73-
// URL is not used in task, but required for manifest validation.
74-
url: { value: 'https://api.cloudsploit.com', isVisible: false },
71+
displayName: 'Aqua Platform Configuration',
72+
icon: 'images/icon.png',
73+
url: { displayName: 'Aqua Platform URL' },
7574
authenticationSchemes: [
7675
{
7776
type: 'ms.vss-endpoint.endpoint-auth-scheme-none',
7877
inputDescriptors: [
78+
{
79+
id: 'authUrl',
80+
name: 'Aqua Platform Authentication URL',
81+
inputMode: 'textbox',
82+
isConfidential: false,
83+
validation: {
84+
isRequired: true,
85+
dataType: 'string',
86+
},
87+
},
7988
{
8089
id: 'aquaKey',
8190
name: 'Aqua Platform API Key',

0 commit comments

Comments
 (0)