add docs for vulnerability scanning

docs/build.md

@@ -111,6 +111,7 @@ The `Build` definition supports the following fields:
     - Use string `SourceTimestamp` to set the image timestamp to the source timestamp, i.e. the timestamp of the Git commit that was used.
     - Use string `BuildTimestamp` to set the image timestamp to the timestamp of the build run.
     - Use any valid UNIX epoch seconds number as a string to set this as the image timestamp.
+  - `spec.output.vulnerabilityScan` to provides configurations about running a scan for your generated image. Furthur options in vulnerability scanning are defined [here](#defining-the-vulnerabilityscan)
   - `spec.env` - Specifies additional environment variables that should be passed to the build container. The available variables depend on the tool that is being used by the chosen build strategy.
   - `spec.retention.atBuildDeletion` - Defines if all related BuildRuns needs to be deleted when deleting the Build. The default is false.
   - `spec.retention.ttlAfterFailed` - Specifies the duration for which a failed buildrun can exist.
@@ -592,6 +593,44 @@ spec:
     timestamp: SourceTimestamp
 ```
 
+### Defining the vulnerabilityScan
+
+`vulnerabilityScan` provides configurations about running a scan for your generated image.
+- `vulnerabilityScan.enabled` - Specify whether to run vulnerability scan for image. The supported types are true and false.
+- `vulnerabilityScan.fail` - indicates whether to fail the build run if the vulnerability scan results in vulnerabilities. The supported types are true and false.
+- `vulnerabilityScan.ignore.issues` - references the security issues to be ignored in vulnerability scan
+- `vulnerabilityScan.ignore.severity` - indicates the severities of security issues to be ignored (comma separated). Supported types are : Low, Medium, High, Critical.
+- `vulnerabilityScan.ignore.unfixed` - indicates to ignore vulnerabilities for which no fix exists. The supported types are true and false.
+
+Example of user specified image vulnerability scanning options:
+
+```yaml
+apiVersion: shipwright.io/v1beta1
+kind: Build
+metadata:
+  name: sample-go-build
+spec:
+  source:
+    type: Git
+    git:
+      url: https://github.com/shipwright-io/sample-go
+    contextDir: source-build
+  strategy:
+    name: buildkit
+    kind: ClusterBuildStrategy
+  output:
+    image: some.registry.com/namespace/image:tag
+    pushSecret: credentials
+    vulnerabilityScan:
+      enabled: true
+      fail: true
+      ignore:
+        issues:
+          - CVE-2022-12345
+        severity: Low
+        unfixed: true
+```
+
 Annotations added to the output image can be verified by running the command:
 
 ```sh

docs/buildrun.md

@@ -70,6 +70,7 @@ The `BuildRun` definition supports the following fields:
   - `spec.output.image` - Refers to a custom location where the generated image would be pushed. The value will overwrite the `output.image` value defined in `Build`. (**Note**: other properties of the output, for example, the credentials, cannot be specified in the buildRun spec. )
   - `spec.output.pushSecret` - Reference an existing secret to get access to the container registry. This secret will be added to the service account along with the ones requested by the `Build`.
   - `spec.output.timestamp` - Overrides the output timestamp configuration of the referenced build to instruct the build to change the output image creation timestamp to the specified value. When omitted, the respective build strategy tool defines the output image timestamp.
+  - `spec.output.vulnerabilityScan` - Overrides the output vulnerabilityScan configuration of the referenced build to run the vulnerability scan for the generated image.
   - `spec.env` - Specifies additional environment variables that should be passed to the build container. Overrides any environment variables that are specified in the `Build` resource. The available variables depend on the tool used by the chosen build strategy.
 
 **Note**: The `spec.build.name` and `spec.build.spec` are mutually exclusive. Furthermore, the overrides for `timeout`, `paramValues`, `output`, and `env` can only be combined with `spec.build.name`, but **not** with `spec.build.spec`.
@@ -417,6 +418,24 @@ status:
     reason: GitRemotePrivate
 ```
 
+### Understanding failed BuildRuns due to VulnerabilitiesFound
+A buildrun can be failed, if the vulnerability scan finds vulnerabilities in the generated image and fail is set to true in the vulnerabilityScan. For setting vulnerabilityScan, see [here](build.md#defining-the-vulnerabilityscan).
+
+Example of failed BuildRun due to vulnerabilities present in the image:
+
+```yaml
+# [...]
+status:
+  # [...]
+  conditions:
+  - type: Succeeded
+    lastTransitionTime: "2024-03-12T20:00:38Z"
+    status: "False"
+    reason: VulnerabilitiesFound
+    message: "Vulnerabilities have been found in the output image. For detailed information, check buildrun status or see kubectl --namespace default logs vuln-s6skc-v7wd2-pod --container step-image-processing"
+```
+
+
 #### Understanding failed git-source step
 
 All git-related operations support error reporting via `status.failureDetails`. The following table explains the possible
@@ -476,6 +495,24 @@ status:
 
 **Note**: The digest and size of the output image are only included if the build strategy provides them. See [System results](buildstrategies.md#system-results).
 
+Another example of a `BuildRun` with surfaced results for vulnerability scanning.
+```yaml
+# [...]
+status:
+  buildSpec:
+    # [...]
+  status:
+  output:
+    digest: sha256:1023103
+    size: 12310380
+    vulnerabilities:
+    - id: CVE-2022-12345
+      severity: high
+    - id: CVE-2021-54321
+      severity: medium
+```
+**Note**: The vulnerability scan will only run if it is specified in the build or buildrun spec. See [Defining the vulnerabilityScan](build.md#defining-the-vulnerabilityscan).
+
 ### Build Snapshot
 
 For every BuildRun controller reconciliation, the `buildSpec` in the status of the `BuildRun` is updated if an existing owned `TaskRun` is present. During this update, a `Build` resource snapshot is generated and embedded into the `status.buildSpec` path of the `BuildRun`. A `buildSpec` is just a copy of the original `Build` spec, from where the `BuildRun` executed a particular image build. The snapshot approach allows developers to see the original `Build` configuration.