1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
|
---
stage: Secure
group: Composition analysis
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
---
# Operational Container Scanning **(ULTIMATE ALL)**
> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6346) in GitLab 14.8.
> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/368828) the starboard directive in GitLab 15.4. The starboard directive is scheduled for removal in GitLab 16.0.
## Enable operational container scanning
You can use operational container scanning to scan container images in your cluster for security vulnerabilities. You
can enable the scanner to run on a cadence as configured via the `agent config`, or setup `scan execution policies` within a
project that houses the agent.
NOTE:
If both `agent config` and `scan execution policies` are configured, the configuration from `scan execution policy` takes precedence.
### Enable via agent configuration
To enable scanning of images within your Kubernetes cluster via the agent configuration, add a `container_scanning` configuration block to your agent
configuration with a `cadence` field containing a [CRON expression](https://en.wikipedia.org/wiki/Cron) for when the scans are run.
```yaml
container_scanning:
cadence: '0 0 * * *' # Daily at 00:00 (Kubernetes cluster time)
```
The `cadence` field is required. GitLab supports the following types of CRON syntax for the cadence field:
- A daily cadence of once per hour at a specified hour, for example: `0 18 * * *`
- A weekly cadence of once per week on a specified day and at a specified hour, for example: `0 13 * * 0`
NOTE:
Other elements of the [CRON syntax](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm) may work in the cadence field if supported by the [cron](https://github.com/robfig/cron) we are using in our implementation, however, GitLab does not officially test or support them.
NOTE:
The CRON expression is evaluated in [UTC](https://www.timeanddate.com/worldclock/timezone/utc) using the system-time of the Kubernetes-agent pod.
By default, operational container scanning does not scan any workloads for vulnerabilities.
You can set the `vulnerability_report` block with the `namespaces`
field which can be used to select which namespaces are scanned. For example,
if you would like to scan only the `default`, `kube-system` namespaces, you can use this configuration:
```yaml
container_scanning:
cadence: '0 0 * * *'
vulnerability_report:
namespaces:
- default
- kube-system
```
### Enable via scan execution policies
To enable scanning of all images within your Kubernetes cluster via scan execution policies, we can use the
[scan execution policy editor](../../application_security/policies/scan-execution-policies.md#scan-execution-policy-editor)
To create a new schedule rule.
NOTE:
The Kubernetes agent must be running in your cluster to scan running container images
Here is an example of a policy which enables operational container scanning within the cluster the Kubernetes agent is attached to:
```yaml
- name: Enforce Container Scanning in cluster connected through my-gitlab-agent for default and kube-system namespaces
enabled: true
rules:
- type: schedule
cadence: '0 10 * * *'
agents:
<agent-name>:
namespaces:
- 'default'
- 'kube-system'
actions:
- scan: container_scanning
```
The keys for a schedule rule are:
- `cadence` (required): a [CRON expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm) for when the scans are run
- `agents:<agent-name>` (required): The name of the agent to use for scanning
- `agents:<agent-name>:namespaces` (optional): The Kubernetes namespaces to scan. If omitted, all namespaces are scanned
NOTE:
Other elements of the [CRON syntax](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm) may work in the cadence field if supported by the [cron](https://github.com/robfig/cron) we are using in our implementation, however, GitLab does not officially test or support them.
NOTE:
The CRON expression is evaluated in [UTC](https://www.timeanddate.com/worldclock/timezone/utc) using the system-time of the Kubernetes-agent pod.
You can view the complete schema within the [scan execution policy documentation](../../application_security/policies/scan-execution-policies.md#scan-execution-policies-schema).
## Configure scanner resource requirements
By default the scanner pod's default resource requirements are:
```yaml
requests:
cpu: 100m
memory: 100Mi
limits:
cpu: 500m
memory: 500Mi
```
You can customize it with a `resource_requirements` field.
```yaml
container_scanning:
resource_requirements:
requests:
cpu: '0.2'
memory: 200Mi
limits:
cpu: '0.7'
memory: 700Mi
```
When using a fractional value for CPU, format the value as a string.
NOTE:
Resource requirements can only be set up using the agent configuration. If you enabled `Operational Container Scanning` through `scan execution policies`, you would need to define the resource requirements within the agent configuration file.
## View cluster vulnerabilities
To view vulnerability information in GitLab:
1. On the left sidebar, select **Search or go to** and find the project that contains the agent configuration file.
1. Select **Operate > Kubernetes clusters**.
1. Select the **Agent** tab.
1. Select an agent to view the cluster vulnerabilities.
This information can also be found under [operational vulnerabilities](../../../user/application_security/vulnerability_report/index.md#operational-vulnerabilities).
NOTE:
You must have at least the Developer role.
## Scanning private images
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/415451) in GitLab 16.4.
To scan private images, the scanner relies on the image pull secrets (direct references and from the service account) to pull the image.
## Troubleshooting
### `Error running Trivy scan. Container terminated reason: OOMKilled`
OCS might fail with an OOM error if there are too many resources to be scanned or if the images being scanned are large.
To resolve this, [configure the resource requirement](#configure-scanner-resource-requirements) to increase the amount of memory available.
|
