Add documentation

Shopify · May 24, 2022 · 1d5bea1 · 1d5bea1
1 parent ca646bd
commit 1d5bea1
Show file tree

Hide file tree

Showing 3 changed files with 119 additions and 16 deletions.
diff --git a/README.md b/README.md
@@ -190,21 +190,22 @@ For all the ways kubeaudit can be customized, see [Global Flags](#global-flags).
 
 Auditors can also be run individually.
 
-| Command        | Description                                                                                                    | Documentation                         |
-| :------------- | :------------------------------------------------------------------------------------------------------------- | :------------------------------------ |
-| `apparmor`     | Finds containers running without AppArmor.                                                                     | [docs](docs/auditors/apparmor.md)     |
-| `asat`         | Finds pods using an automatically mounted default service account                                              | [docs](docs/auditors/asat.md)         |
-| `capabilities` | Finds containers that do not drop the recommended capabilities or add new ones.                                | [docs](docs/auditors/capabilities.md) |
-| `hostns`       | Finds containers that have HostPID, HostIPC or HostNetwork enabled.                                            | [docs](docs/auditors/hostns.md)       |
-| `image`        | Finds containers which do not use the desired version of an image (via the tag) or use an image without a tag. | [docs](docs/auditors/image.md)        |
-| `limits`       | Finds containers which exceed the specified CPU and memory limits or do not specify any.                       | [docs](docs/auditors/limits.md)       |
-| `mounts`       | Finds containers that have sensitive host paths mounted.                                                       | [docs](docs/auditors/mounts.md)       |
-| `netpols`      | Finds namespaces that do not have a default-deny network policy.                                               | [docs](docs/auditors/netpols.md)      |
-| `nonroot`      | Finds containers running as root.                                                                              | [docs](docs/auditors/nonroot.md)      |
-| `privesc`      | Finds containers that allow privilege escalation.                                                              | [docs](docs/auditors/privesc.md)      |
-| `privileged`   | Finds containers running as privileged.                                                                        | [docs](docs/auditors/privileged.md)   |
-| `rootfs`       | Finds containers which do not have a read-only filesystem.                                                     | [docs](docs/auditors/rootfs.md)       |
-| `seccomp`      | Finds containers running without Seccomp.                                                                      | [docs](docs/auditors/seccomp.md)      |
+| Command          | Description                                                                                                    | Documentation                           |
+| :--------------- | :------------------------------------------------------------------------------------------------------------- | :-------------------------------------- |
+| `apparmor`       | Finds containers running without AppArmor.                                                                     | [docs](docs/auditors/apparmor.md)       |
+| `asat`           | Finds pods using an automatically mounted default service account                                              | [docs](docs/auditors/asat.md)           |
+| `capabilities`   | Finds containers that do not drop the recommended capabilities or add new ones.                                | [docs](docs/auditors/capabilities.md)   |
+| `deprecatedapis` | Finds containers that do not drop the recommended capabilities or add new ones.                                | [docs](docs/auditors/deprecatedapis.md) |
+| `hostns`         | Finds containers that have HostPID, HostIPC or HostNetwork enabled.                                            | [docs](docs/auditors/hostns.md)         |
+| `image`          | Finds containers which do not use the desired version of an image (via the tag) or use an image without a tag. | [docs](docs/auditors/image.md)          |
+| `limits`         | Finds containers which exceed the specified CPU and memory limits or do not specify any.                       | [docs](docs/auditors/limits.md)         |
+| `mounts`         | Finds containers that have sensitive host paths mounted.                                                       | [docs](docs/auditors/mounts.md)         |
+| `netpols`        | Finds namespaces that do not have a default-deny network policy.                                               | [docs](docs/auditors/netpols.md)        |
+| `nonroot`        | Finds containers running as root.                                                                              | [docs](docs/auditors/nonroot.md)        |
+| `privesc`        | Finds containers that allow privilege escalation.                                                              | [docs](docs/auditors/privesc.md)        |
+| `privileged`     | Finds containers running as privileged.                                                                        | [docs](docs/auditors/privileged.md)     |
+| `rootfs`         | Finds containers which do not have a read-only filesystem.                                                     | [docs](docs/auditors/rootfs.md)         |
+| `seccomp`        | Finds containers running without Seccomp.                                                                      | [docs](docs/auditors/seccomp.md)        |
 
 ### Global Flags
 
@@ -235,6 +236,7 @@ enabledAuditors:
   apparmor: false
   asat: false
   capabilities: true
+  deprecatedapis: true
   hostns: true
   image: true
   limits: true
@@ -249,6 +251,11 @@ auditors:
   capabilities:
     # add capabilities needed to the add list, so kubeaudit won't report errors
     allowAddList: ['AUDIT_WRITE', 'CHOWN']
+  deprecatedapis:
+    # If no versions are specified and the'deprecatedapis' auditor is enabled, WARN
+    # results will be genereted for the resources defined with a deprecated API.
+    currentVersion: '1.22'
+    targetedVersion: '1.25'
   image:
     # If no image is specified and the 'image' auditor is enabled, WARN results
     # will be generated for containers which use an image without a tag

diff --git a/cmd/commands/deprecatedapis.go b/cmd/commands/deprecatedapis.go
@@ -35,7 +35,7 @@ kubeaudit deprecatedapis --current-k8s-version 1.22 --targeted-k8s-version 1.24`
 }
 
 func setdeprecatedapisFlags(cmd *cobra.Command) {
-	cmd.Flags().StringVar(&deprecatedapisConfig.CurrentVersion, currentVersionFlagName, "", "Kubernetes current version to migrate to (eg 1.22)")
+	cmd.Flags().StringVar(&deprecatedapisConfig.CurrentVersion, currentVersionFlagName, "", "Kubernetes current version (eg 1.22)")
 	cmd.Flags().StringVar(&deprecatedapisConfig.TargetedVersion, targetedVersionFlagName, "", "Kubernetes version to migrate to (eg 1.24)")
 }
 

diff --git a/docs/auditors/deprecatedapis.md b/docs/auditors/deprecatedapis.md
@@ -0,0 +1,96 @@
+# Kubernetes Deprecated API Auditor (deprecatedapis)
+
+Finds any resource defined with adeprecated API version.
+
+## General Usage
+
+```
+kubeaudit deprecatedapis [flags]
+```
+
+### Flags
+| Short   | Long                   | Description                                   | Default             |
+| :------ | :--------------------- | :-------------------------------------------- | :------------------ |
+|         | --current-k8s-version  | Kubernetes current version                    |                     |
+|         | --targeted-k8s-version | Kubernetes version to migrate to              |                     |
+
+
+Also see [Global Flags](/README.md#global-flags)
+
+## Examples
+
+The `deprecatedapis` auditor allows to find the deprecated APIs in use and indicates the versions where they will be removed and replacement APIs.
+```
+$ kubeaudit deprecatedapis -f "auditors/deprecatedapis/fixtures/cronjob.yml"
+
+---------------- Results for ---------------
+
+  apiVersion: batch/v1beta1
+  kind: CronJob
+  metadata:
+    name: hello
+
+--------------------------------------------
+
+-- [warning] DeprecatedAPIUsed
+   Message: batch/v1beta1 CronJob is deprecated in v1.21+, unavailable in v1.25+; use batch/v1 CronJob
+   Metadata:
+      DeprecatedMajor: 1
+      DeprecatedMinor: 21
+      RemovedMajor: 1
+      RemovedMinor: 25
+      ReplacementKind: CronJob
+      ReplacementGroup: batch/v1
+```
+
+The `deprecatedapis` auditor can be used `--targeted-k8s-version` flag. If the API is not yet deprecated for this version the auditor will produce an `info` otherwise a `warning`.
+```
+$ kubeaudit deprecatedapis --current-k8s-version 1.20  -f "auditors/deprecatedapis/fixtures/cronjob.yml"
+
+---------------- Results for ---------------
+
+  apiVersion: batch/v1beta1
+  kind: CronJob
+  metadata:
+    name: hello
+
+--------------------------------------------
+
+-- [info] DeprecatedAPIUsed
+   Message: batch/v1beta1 CronJob is deprecated in v1.21+, unavailable in v1.25+; use batch/v1 CronJob
+   Metadata:
+      DeprecatedMajor: 1
+      DeprecatedMinor: 21
+      RemovedMajor: 1
+      RemovedMinor: 25
+      ReplacementKind: CronJob
+      ReplacementGroup: batch/v1
+```
+
+The `deprecatedapis` auditor can be used `--targeted-k8s-version` flag. If the API is not available for the targeted version the auditor will produce an `error` otherwise a `warning` or `info` if the API is not yet deprecated for this version. 
+```
+$ kubeaudit deprecatedapis --current-k8s-version 1.20 --targeted-k8s-version 1.25 -f "auditors/deprecatedapis/fixtures/cronjob.yml"
+
+---------------- Results for ---------------
+
+  apiVersion: batch/v1beta1
+  kind: CronJob
+  metadata:
+    name: hello
+
+--------------------------------------------
+
+-- [error] DeprecatedAPIUsed
+   Message: batch/v1beta1 CronJob is deprecated in v1.21+, unavailable in v1.25+; use batch/v1 CronJob
+   Metadata:
+      DeprecatedMajor: 1
+      DeprecatedMinor: 21
+      RemovedMajor: 1
+      RemovedMinor: 25
+      ReplacementKind: CronJob
+      ReplacementGroup: batch/v1
+```
+
+## Override Errors
+
+Overrides are not currently supported for `deprecatedapis`.