Skip to content

Reorder sections in upgrading.md to list the newest first #3000

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
J12934 merged 1 commit into from
Apr 23, 2025
Merged

Reorder sections in upgrading.md to list the newest first #3000

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
259 changes: 128 additions & 131 deletions documentation/docs/getting-started/upgrading.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,131 +10,6 @@ path: "docs/getting-started/upgrading"
sidebar_position: 3

---
## From 2.X to 3.X

### Upgraded Kubebuilder Version to v3
The CRD's are now using `apiextensions.k8s.io/v1` instead of `apiextensions.k8s.io/v1beta1` which requries at least Kubernetes Version 1.16 or higher.
The Operator now uses the new kubebuilder v3 command line flag for enabling leader election and setting the metrics port. If you are using the official secureCodeBox Helm Charts for your deployment this has been updated automatically.

If you are using a custom deployment you have to change the `--enable-leader-election` flag to `--leader-elect` and `--metrics-addr` to `--metrics-bind-address`. For more context see: https://book.kubebuilder.io/migration/v2vsv3.html#tldr-of-the-new-gov3-plugin

➡️ [Reference: #512](https://github.com/secureCodeBox/secureCodeBox/pull/512)

### Restructured the secureCodeBox HelmCharts to introduce more consistency in HelmChart Values
The secureCodeBox HelmCharts for hooks and scanners are following a new structure for all HelmChart Values:

Instead of secureCodebox Version 2 example:

```yaml
image:
# image.repository -- Container Image to run the scan
repository: owasp/zap2docker-stable
# image.tag -- defaults to the charts appVersion
tag: null

parserImage:
# parserImage.repository -- Parser image repository
repository: docker.io/securecodebox/parser-zap
# parserImage.tag -- Parser image tag
# @default -- defaults to the charts version
tag: null

parseJob:
# parseJob.ttlSecondsAfterFinished -- seconds after which the Kubernetes job for the parser will be deleted. Requires the Kubernetes TTLAfterFinished controller: https://kubernetes.io/docs/concepts/workloads/controllers/ttlafterfinished/
ttlSecondsAfterFinished: null

scannerJob:
# scannerJob.ttlSecondsAfterFinished -- seconds after which the Kubernetes job for the scanner will be deleted. Requires the Kubernetes TTLAfterFinished controller: https://kubernetes.io/docs/concepts/workloads/controllers/ttlafterfinished/
ttlSecondsAfterFinished: null
# scannerJob.backoffLimit -- There are situations where you want to fail a scan Job after some amount of retries due to a logical error in configuration etc. To do so, set backoffLimit to specify the number of retries before considering a scan Job as failed. (see: https://kubernetes.io/docs/concepts/workloads/controllers/job/#pod-backoff-failure-policy)
# @default -- 3
backoffLimit: 3
```

The new HelmChart Values structure in secureCodebox Version 3 looks like:

```yaml
parser:
image:
# parser.image.repository -- Parser image repository
repository: docker.io/securecodebox/parser-zap
# parser.image.tag -- Parser image tag
# @default -- defaults to the charts version
tag: null

# parser.ttlSecondsAfterFinished -- seconds after which the Kubernetes job for the parser will be deleted. Requires the Kubernetes TTLAfterFinished controller: https://kubernetes.io/docs/concepts/workloads/controllers/ttlafterfinished/
ttlSecondsAfterFinished: null
# @default -- 3
backoffLimit: 3

scanner:
image:
# scanner.image.repository -- Container Image to run the scan
repository: owasp/zap2docker-stable
# scanner.image.tag -- defaults to the charts appVersion
tag: null

# scanner.ttlSecondsAfterFinished -- seconds after which the Kubernetes job for the scanner will be deleted. Requires the Kubernetes TTLAfterFinished controller: https://kubernetes.io/docs/concepts/workloads/controllers/ttlafterfinished/
ttlSecondsAfterFinished: null
# scanner.backoffLimit -- There are situations where you want to fail a scan Job after some amount of retries due to a logical error in configuration etc. To do so, set backoffLimit to specify the number of retries before considering a scan Job as failed. (see: https://kubernetes.io/docs/concepts/workloads/controllers/job/#pod-backoff-failure-policy)
# @default -- 3
backoffLimit: 3
```
➡️ [Reference: #472](https://github.com/secureCodeBox/secureCodeBox/issues/472)
➡️ [Reference: #483](https://github.com/secureCodeBox/secureCodeBox/pull/483)
➡️ [Reference: #484](https://github.com/secureCodeBox/secureCodeBox/pull/484)

### Added scanner.appendName to chart values
Using `{{ .Release.name }}` in the `nmap` HelmChart Name for `scanTypes` causes issues when using this chart as a dependency of another chart. All scanners HelmCharts already used a fixed name for the `scanType` they introduce, with one exception: the `nmap` scanner HelmChart.

The nmap exception was originally introduced to make it possible configure yourself an `nmap-privilidged` scanType, which is capable of running operating system scans which requires some higher privileges: https://www.securecodebox.io/docs/scanners/nmap#operating-system-scans

This idea for extending the name of a scanType is now in Version 3 general available for all HelmCharts.

The solution was to add a new HelmChart Value `scanner.appendName` for appending a suffix to the already defined scanType name.
Example: the `scanner.nameAppend: -privileged` for the ZAP scanner will create `zap-baseline-scan-privileged`, `zap-api-scan-privileged`, `zap-full-scan-privileged` as new scanTypes instead of `zap-baseline-scan`, `zap-api-scan`, `zap-full-scan`.

➡️ [Reference: #469](https://github.com/secureCodeBox/secureCodeBox/pull/469)

### Renamed demo-apps to demo-targets
The provided vulnerable demos are renamed from `demo-apps` to `demo-targets`, this includes the namespace and the folder of the [helmcharts](https://github.com/secureCodeBox/secureCodeBox/tree/main/demo-targets).

### Renamed the hook declarative-subsequent-scans to cascading-scans
The hook responsible for cascading scans is renamed from `declarative-subsequent-scans` to `cascading-scans`.

➡️ [Reference: #481](https://github.com/secureCodeBox/secureCodeBox/pull/481)

### Fixed Name Consistency In Docker Images / Repositories
For the docker images for scanners and parsers we already had the naming convention of prefixing these images with `scanner-` or `parser-`.

Hook images however were named inconsistently (some prefixed with `hook-` some unprefixed).
To introduce more consistency we renamed all hook images and prefix them with `hook-` like we did with parser and scanner images.

Please beware of this if you are referencing some of our hook images in your own HelmCharts or custom implementations.

➡️ [Reference: #500](https://github.com/secureCodeBox/secureCodeBox/pull/500)

### Renamed `lurcher` to `lurker`

In the 3.0 release, we corrected the misspelling in `lurcher`. To remove the remains after upgrade, delete the old service accounts and roles from the namespaces where you have executed scans in the past:

```bash
# Find relevant namespaces
kubectl get serviceaccounts --all-namespaces | grep lurcher

# Delete role, role binding and service account for the specific namespace
kubectl --namespace <NAMESPACE> delete serviceaccount lurcher
kubectl --namespace <NAMESPACE> delete rolebindings lurcher
kubectl --namespace <NAMESPACE> delete role lurcher
```

➡️ [Reference: #537](https://github.com/secureCodeBox/secureCodeBox/pull/537)

### Removed Hook Teams Webhook
We implemented a more general *[notification hook](https://www.securecodebox.io/docs/hooks/notification-hook)* which can be used to notify different systems like *[MS Teams](https://www.securecodebox.io/docs/hooks/notification-hook#configuration-of-a-ms-teams-notification)* and *[Slack](https://www.securecodebox.io/docs/hooks/notification-hook#configuration-of-a-slack-notification)* and also [Email](https://www.securecodebox.io/docs/hooks/notification-hook#configuration-of-an-email-notification) based in a more flexible way with [custom message templates](https://www.securecodebox.io/docs/hooks/notification-hook#custom-message-templates). With this new hook in place it is not nessesary to maintain the preexisting MS Teams Hook any longer and therefore we removed it.

➡️ [Reference: #570](https://github.com/secureCodeBox/secureCodeBox/pull/570)

## From 3.X to 4.X

### Renamed the docker images of demo-targets to include a "demo-target-" prefix
Expand All @@ -150,12 +25,11 @@ These images are usually used for testing and demo purposes. If you use these im

### Changed name of Container AutoDiscovery scans

Previously scheduled scans generated by the container autodiscovery are named in the format `scan-image_name-at-image_hash`. The resulting scan pod will be called `scan-scan-image_name-at-image_hash`.
Previously scheduled scans generated by the container autodiscovery are named in the format `scan-image_name-at-image_hash`. The resulting scan pod will be called `scan-scan-image_name-at-image_hash`.
To avoid the duplicate “scan-scan”, the scheduled scans from the container autodiscovery are renamed. As a result, the container autodiscovery will no longer correctly “recognize” the old scans anymore. It will instead create new scans according to the new naming scheme. The old scheduled scans must be deleted manually.

➡️ [Reference: #1193](https://github.com/secureCodeBox/secureCodeBox/pull/1193)


### Cascading rules are disabled by default

Having the Cascading rules enabled by default on scanner helm install, has led to some confusion on the users side as mentioned in issue [#914](https://github.com/secureCodeBox/secureCodeBox/issues/914). As a result Cascading rules will have to be explicitly enabled by setting the `cascadingRules.enabled` value to `true`. For example as so:
Expand All @@ -165,7 +39,6 @@ helm upgrade --install nmap oci://ghcr.io/securecodebox/helm/nmap --set=cascadin

➡️ [Reference: #1347](https://github.com/secureCodeBox/secureCodeBox/pull/1347)


### Service Autodiscovery - Managed-by label assumed to be presented for all scans

Old versions of the operator did not set `app.kubernetes.io/managed-by` label. Starting with V4 the service autodiscovery will assume every scheduled scan created by the autodiscovery will have this label. This means that older scheduled scans without the label will not be detected by the service autodiscovery and new duplicate scheduled scans will be created. Old scheduled scans without the `app.kubernetes.io/managed-by` label must be deleted manually.
Expand All @@ -177,10 +50,9 @@ The `zap` and `zap-advanced` parsers where changed to increase the consistency b

➡️ [Reference: #1346](https://github.com/secureCodeBox/secureCodeBox/pull/1346)


### Container AutoDiscovery enabled by default and more consistent behavior compared to Service AutoDiscovery

The container autodiscovery will now be enabled by default. Additionally the container autodiscovery will now check if the configured scantype is installed in the namespace before it creates a scheduled scan (just like the service autodiscovery).
The container autodiscovery will now be enabled by default. Additionally the container autodiscovery will now check if the configured scantype is installed in the namespace before it creates a scheduled scan (just like the service autodiscovery).

➡️ [Reference: #1112](https://github.com/secureCodeBox/secureCodeBox/pull/1112)

Expand Down Expand Up @@ -271,6 +143,131 @@ As a example the findings for nmap has been changed like the following:

### `ssh-scan` (Mozilla ssh_scan) considered deprecated

SSH-Scan (Mozilla ssh_scan) is now considered deprecated as the tool is no longer maintained by mozilla. As a replacement we've added integration for [ssh-audit](https://github.com/jtesta/ssh-audit) as a replacement. The ssh-scan integration is still in this release but will be removed in a upcoming (feature) release. @Reet00 & @sofi0071
SSH-Scan (Mozilla ssh_scan) is now considered deprecated as the tool is no longer maintained by mozilla. As a replacement we've added integration for [ssh-audit](https://github.com/jtesta/ssh-audit) as a replacement. The ssh-scan integration is still in this release but will be removed in a upcoming (feature) release. @Reet00 & @sofi0071

➡️ [Reference: #1713](https://github.com/secureCodeBox/secureCodeBox/pull/1713)

## From 2.X to 3.X

### Upgraded Kubebuilder Version to v3
The CRD's are now using `apiextensions.k8s.io/v1` instead of `apiextensions.k8s.io/v1beta1` which requries at least Kubernetes Version 1.16 or higher.
The Operator now uses the new kubebuilder v3 command line flag for enabling leader election and setting the metrics port. If you are using the official secureCodeBox Helm Charts for your deployment this has been updated automatically.

If you are using a custom deployment you have to change the `--enable-leader-election` flag to `--leader-elect` and `--metrics-addr` to `--metrics-bind-address`. For more context see: https://book.kubebuilder.io/migration/v2vsv3.html#tldr-of-the-new-gov3-plugin

➡️ [Reference: #512](https://github.com/secureCodeBox/secureCodeBox/pull/512)

### Restructured the secureCodeBox HelmCharts to introduce more consistency in HelmChart Values
The secureCodeBox HelmCharts for hooks and scanners are following a new structure for all HelmChart Values:

Instead of secureCodebox Version 2 example:

```yaml
image:
# image.repository -- Container Image to run the scan
repository: owasp/zap2docker-stable
# image.tag -- defaults to the charts appVersion
tag: null

parserImage:
# parserImage.repository -- Parser image repository
repository: docker.io/securecodebox/parser-zap
# parserImage.tag -- Parser image tag
# @default -- defaults to the charts version
tag: null

parseJob:
# parseJob.ttlSecondsAfterFinished -- seconds after which the Kubernetes job for the parser will be deleted. Requires the Kubernetes TTLAfterFinished controller: https://kubernetes.io/docs/concepts/workloads/controllers/ttlafterfinished/
ttlSecondsAfterFinished: null

scannerJob:
# scannerJob.ttlSecondsAfterFinished -- seconds after which the Kubernetes job for the scanner will be deleted. Requires the Kubernetes TTLAfterFinished controller: https://kubernetes.io/docs/concepts/workloads/controllers/ttlafterfinished/
ttlSecondsAfterFinished: null
# scannerJob.backoffLimit -- There are situations where you want to fail a scan Job after some amount of retries due to a logical error in configuration etc. To do so, set backoffLimit to specify the number of retries before considering a scan Job as failed. (see: https://kubernetes.io/docs/concepts/workloads/controllers/job/#pod-backoff-failure-policy)
# @default -- 3
backoffLimit: 3
```

The new HelmChart Values structure in secureCodebox Version 3 looks like:

```yaml
parser:
image:
# parser.image.repository -- Parser image repository
repository: docker.io/securecodebox/parser-zap
# parser.image.tag -- Parser image tag
# @default -- defaults to the charts version
tag: null

# parser.ttlSecondsAfterFinished -- seconds after which the Kubernetes job for the parser will be deleted. Requires the Kubernetes TTLAfterFinished controller: https://kubernetes.io/docs/concepts/workloads/controllers/ttlafterfinished/
ttlSecondsAfterFinished: null
# @default -- 3
backoffLimit: 3

scanner:
image:
# scanner.image.repository -- Container Image to run the scan
repository: owasp/zap2docker-stable
# scanner.image.tag -- defaults to the charts appVersion
tag: null

# scanner.ttlSecondsAfterFinished -- seconds after which the Kubernetes job for the scanner will be deleted. Requires the Kubernetes TTLAfterFinished controller: https://kubernetes.io/docs/concepts/workloads/controllers/ttlafterfinished/
ttlSecondsAfterFinished: null
# scanner.backoffLimit -- There are situations where you want to fail a scan Job after some amount of retries due to a logical error in configuration etc. To do so, set backoffLimit to specify the number of retries before considering a scan Job as failed. (see: https://kubernetes.io/docs/concepts/workloads/controllers/job/#pod-backoff-failure-policy)
# @default -- 3
backoffLimit: 3
```
➡️ [Reference: #472](https://github.com/secureCodeBox/secureCodeBox/issues/472)
➡️ [Reference: #483](https://github.com/secureCodeBox/secureCodeBox/pull/483)
➡️ [Reference: #484](https://github.com/secureCodeBox/secureCodeBox/pull/484)

### Added scanner.appendName to chart values
Using `{{ .Release.name }}` in the `nmap` HelmChart Name for `scanTypes` causes issues when using this chart as a dependency of another chart. All scanners HelmCharts already used a fixed name for the `scanType` they introduce, with one exception: the `nmap` scanner HelmChart.

The nmap exception was originally introduced to make it possible configure yourself an `nmap-privilidged` scanType, which is capable of running operating system scans which requires some higher privileges: https://www.securecodebox.io/docs/scanners/nmap#operating-system-scans

This idea for extending the name of a scanType is now in Version 3 general available for all HelmCharts.

The solution was to add a new HelmChart Value `scanner.appendName` for appending a suffix to the already defined scanType name.
Example: the `scanner.nameAppend: -privileged` for the ZAP scanner will create `zap-baseline-scan-privileged`, `zap-api-scan-privileged`, `zap-full-scan-privileged` as new scanTypes instead of `zap-baseline-scan`, `zap-api-scan`, `zap-full-scan`.

➡️ [Reference: #469](https://github.com/secureCodeBox/secureCodeBox/pull/469)

### Renamed demo-apps to demo-targets
The provided vulnerable demos are renamed from `demo-apps` to `demo-targets`, this includes the namespace and the folder of the [helmcharts](https://github.com/secureCodeBox/secureCodeBox/tree/main/demo-targets).

### Renamed the hook declarative-subsequent-scans to cascading-scans
The hook responsible for cascading scans is renamed from `declarative-subsequent-scans` to `cascading-scans`.

➡️ [Reference: #481](https://github.com/secureCodeBox/secureCodeBox/pull/481)

### Fixed Name Consistency In Docker Images / Repositories
For the docker images for scanners and parsers we already had the naming convention of prefixing these images with `scanner-` or `parser-`.

Hook images however were named inconsistently (some prefixed with `hook-` some unprefixed).
To introduce more consistency we renamed all hook images and prefix them with `hook-` like we did with parser and scanner images.

Please beware of this if you are referencing some of our hook images in your own HelmCharts or custom implementations.

➡️ [Reference: #500](https://github.com/secureCodeBox/secureCodeBox/pull/500)

### Renamed `lurcher` to `lurker`

In the 3.0 release, we corrected the misspelling in `lurcher`. To remove the remains after upgrade, delete the old service accounts and roles from the namespaces where you have executed scans in the past:

```bash
# Find relevant namespaces
kubectl get serviceaccounts --all-namespaces | grep lurcher

# Delete role, role binding and service account for the specific namespace
kubectl --namespace <NAMESPACE> delete serviceaccount lurcher
kubectl --namespace <NAMESPACE> delete rolebindings lurcher
kubectl --namespace <NAMESPACE> delete role lurcher
```

➡️ [Reference: #537](https://github.com/secureCodeBox/secureCodeBox/pull/537)

### Removed Hook Teams Webhook
We implemented a more general *[notification hook](https://www.securecodebox.io/docs/hooks/notification-hook)* which can be used to notify different systems like *[MS Teams](https://www.securecodebox.io/docs/hooks/notification-hook#configuration-of-a-ms-teams-notification)* and *[Slack](https://www.securecodebox.io/docs/hooks/notification-hook#configuration-of-a-slack-notification)* and also [Email](https://www.securecodebox.io/docs/hooks/notification-hook#configuration-of-an-email-notification) based in a more flexible way with [custom message templates](https://www.securecodebox.io/docs/hooks/notification-hook#custom-message-templates). With this new hook in place it is not nessesary to maintain the preexisting MS Teams Hook any longer and therefore we removed it.

➡️ [Reference: #570](https://github.com/secureCodeBox/secureCodeBox/pull/570)
Loading