docs: update docs

undistro · Oct 25, 2023 · 919f3db · 919f3db
1 parent c105db7
commit 919f3db
Show file tree

Hide file tree

Showing 22 changed files with 4,728 additions and 9,259 deletions.
diff --git a/docs/assets/arch-dark.png b/docs/assets/arch-dark.png
diff --git a/docs/assets/arch-v2.excalidraw b/docs/assets/arch-v2.excalidraw
diff --git a/docs/assets/arch.excalidraw b/docs/assets/arch.excalidraw
diff --git a/docs/assets/arch.png b/docs/assets/arch.png
diff --git a/docs/assets/dashboard-arch-dark.png b/docs/assets/dashboard-arch-dark.png
diff --git a/docs/assets/dashboard-arch-light.png b/docs/assets/dashboard-arch-light.png
diff --git a/docs/assets/oss-arch-dark.png b/docs/assets/oss-arch-dark.png
diff --git a/docs/assets/oss-arch-light.png b/docs/assets/oss-arch-light.png
diff --git a/docs/assets/plugin-arch-dark.png b/docs/assets/plugin-arch-dark.png
diff --git a/docs/assets/plugin-arch-light.png b/docs/assets/plugin-arch-light.png
diff --git a/docs/assets/zora-dashboard-screenshot.png b/docs/assets/zora-dashboard-screenshot.png
diff --git a/docs/cluster-scan.md b/docs/cluster-scan.md
diff --git a/docs/custom-checks.md → docs/configuration/custom-checks.md b/docs/custom-checks.md → docs/configuration/custom-checks.md
@@ -4,14 +4,14 @@ Zora offers a declarative way to create your own checks using the `CustomCheck`
 
 Custom checks use the [Common Expression Language (CEL)](https://github.com/google/cel-spec) 
 to declare the validation rules and are performed by the [Marvin](https://github.com/undistro/marvin) plugin, 
-so it should be enabled in your cluster scans.
+which should be enabled in your cluster scans.
 
 !!! info 
     Marvin is already a default plugin and enabled by default in cluster scans since Zora 0.5.0.
 
-## `CustomCheck`
+## `CustomCheck` API
 
-The example below represents a custom check that requires the labels `mycompany.com/squad` and `mycompany.com/component` 
+The example below demonstrates a custom check that requires the labels `mycompany.com/squad` and `mycompany.com/component` 
 to be present on `Pods`, `Deployments` and `Services`.
 
 !!! example
@@ -50,10 +50,13 @@ to be present on `Pods`, `Deployments` and `Services`.
           message: "Resource without required labels"
     ```
 
-The `spec.match.resources` defines which resources will be checked by the expressions 
-defined in `spec.validations.expression` as [Common Expression Language (CEL)](https://github.com/google/cel-spec).
+The `spec.match.resources` defines which resources are checked by the expressions 
+defined in `spec.validations.expression` using [Common Expression Language (CEL)](https://github.com/google/cel-spec).
 
-If an expression evaluates to `false`, the check fails and a `ClusterIssue` is reported.
+If an expression evaluates to `false`, the check fails, and a `ClusterIssue` is reported.
+
+!!! tip "CEL Playground"
+    To quickly test CEL expressions directly from your browser, check out [CEL Playground](https://playcel.undistro.io/).
 
 ### Variables
 
@@ -64,7 +67,7 @@ The variables available in CEL expressions:
 | `object` | The object being scanned.                     |
 | `params` | The parameter defined in `spec.params` field. |
 
-If matches a `PodSpec`, the following useful variables are available:
+If the object matches a `PodSpec`, the following useful variables are available:
 
 | Variable        | Description                                                                     |
 |-----------------|---------------------------------------------------------------------------------|
@@ -83,17 +86,17 @@ The following resources matches a `PodSpec`:
 - `batch/v1/jobs`
 - `batch/v1/cronjobs`
 
-### Apply a `CustomCheck`
+### Applying custom checks
 
-Since you have a `CustomCheck` on a file, you can apply it with the command below.
+Since you have a `CustomCheck` on a file, you can apply it with the following command.
 
 ```shell
 kubectl apply -f check.yaml -n zora-system
 ```
 
-### List custom checks
+### Listing custom checks
 
-Once created, list the custom checks to see if it's ready.
+Once created, list the custom checks to see if they are ready.
 
 ```shell
 kubectl get customchecks -n zora-system
@@ -105,7 +108,7 @@ mycheck   Required labels   Low        True
 
 The `READY` column indicates when the check has successfully compiled and is ready to be used in the next Marvin scan.
 
-`ClusterIssues` reported by a custom check have are labeled `custom=true` and can be filtered by the following command:
+`ClusterIssues` reported by a custom check are labeled `custom=true` and can be filtered by the following command:
 
 ```shell
 kubectl get clusterissues -l custom=true
@@ -120,9 +123,7 @@ mycluster-mycheck-4edd75cb85a4   mycluster   mycheck   Required labels   Low
 All Marvin checks are similar to the `CustomCheck` API. 
 You can see them in the [`internal/builtins`](https://github.com/undistro/marvin/tree/main/internal/builtins) folder for examples.
 
-If you want to quickly test CEL expressions from your browser, check out the [CEL Playground](https://playcel.undistro.io/).
-
-Some examples of Marvin built-in checks expressions:
+Here are some examples of Marvin built-in checks expressions:
 
 - [HostPath volumes must be forbidden](https://github.com/undistro/marvin/blob/main/internal/builtins/pss/baseline/M-104_host_path_volumes.yml)
   ```

diff --git a/docs/configuration/scan-schedule.md b/docs/configuration/scan-schedule.md
@@ -0,0 +1,61 @@
+# Scan schedule
+
+After successfully installing Zora, vulnerability and misconfiguration scans are 
+automatically scheduled for your cluster, with each scan using different plugins.
+
+Scan schedules are defined using Cron expressions. 
+You can view the schedule for your cluster by listing `ClusterScan` resources:
+
+```shell
+kubectl get clusterscans -o wide -n zora-system
+```
+
+By default, the misconfiguration scan is scheduled to run every hour at the current minute plus 5, 
+while the vulnerability scan is scheduled to run every day at the current hour and the current minute plus 5.
+
+For example, if the installation occurred at 10:00 UTC, the scans will have the following schedules:
+
+| Scan              | Cron         | Description            |
+|:------------------|:-------------|:-----------------------|
+| Misconfigurations | `5 * * * *`  | Every hour at minute 5 |
+| Vulnerabilities   | `5 10 * * *` | Every day at 10:05     |
+
+However, you can customize the schedule for each scan 
+by directly editing the `ClusterScan` resource 
+or by providing parameters in the `helm upgrade --install` command, as shown in the example below:
+
+```shell 
+# omitted command and parameters
+
+--set scan.misconfiguration.schedule="0 * * * *" \
+--set scan.vulnerability.schedule="0 0 * * *"
+```
+
+The recommended approach is to provide parameters through Helm.
+
+!!! warning
+    If you directly edit the `ClusterScan` resource, be cautious when running the next update via Helm, as the value may be overwritten.
+
+## Cron schedule syntax
+
+Cron expression has five fields separated by a space, and each field represents a time unit.
+
+```
+┌───────────── minute (0 - 59)
+│ ┌───────────── hour (0 - 23)
+│ │ ┌───────────── day of the month (1 - 31)
+│ │ │ ┌───────────── month (1 - 12)
+│ │ │ │ ┌───────────── day of the week (0 - 6) (Sunday to Saturday;
+│ │ │ │ │                                   7 is also Sunday on some systems)
+│ │ │ │ │                                   OR sun, mon, tue, wed, thu, fri, sat
+│ │ │ │ │
+* * * * *
+```
+
+| Operator | Descriptor           | Example                                                                                            |
+|----------|----------------------|----------------------------------------------------------------------------------------------------|
+| *        | Any value            | `15 * * * *` runs at every minute 15 of every hour of every day.                                   |
+| ,        | Value list separator | `2,10 4,5 * * *` runs at minute 2 and 10 of the 4th and 5th hour of every day.                     |
+| -        | Range of values      | `30 4-6 * * *` runs at minute 30 of the 4th, 5th, and 6th hour.                                    |
+| /        | Step values          | `20/15 * * * *` runs every 15 minutes starting from minute 20 through 59 (minutes 20, 35, and 50). |
+