diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 20ebad0e..37a5bb84 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,7 +4,7 @@ Welcome, and thank you for considering contributing to trivy-checks! The following guide gives an overview of the project and some directions on how to make common types of contribution. If something is missing, or you get stuck, please [start a discussion](https://github.com/aquasecurity/trivy/discussions/new) and we'll do our best to help. -### Writing Checks +## Writing Checks Writing a new rule can be relatively simple, but there are a few things to keep in mind. The following guide will help you get started. @@ -94,3 +94,27 @@ You should also write a test for your rule(s). There are many examples of these Finally, you'll want to generate documentation for your newly added rule. Please run `make docs` to generate the documentation for your new policy and submit a PR for us to take a look at. You can see a full example PR for a new rule being added here: [https://github.com/aquasecurity/defsec/pull/1000](https://github.com/aquasecurity/defsec/pull/1000). + + +## Writing Compliance reports + +To write a compliance report please check the following [compliance guide](./docs/compliance.md) + +Supported compliance report IDs include: + +### AWS + +- aws-cis-1.2 +- aws-cis-1.4 + +### Docker + +- docker-cis-1.6.0 + +## Kubernetes + +- eks-cis-1.4 +- k8s-cis-1.23 +- k8s-nsa-1.0 +- k8s-pss-baseline-0.1 +- k8s-pss-restricted-0.1 diff --git a/docs/compliance.md b/docs/compliance.md new file mode 100644 index 00000000..d8890790 --- /dev/null +++ b/docs/compliance.md @@ -0,0 +1,229 @@ +# Add New Compliance Report + +## Define a Compliance spec, based on cis benchmark or other specs + +example: + +```yaml +--- +spec: + id: k8s-cis-1.23 + title: CIS Kubernetes Benchmarks v1.23 + description: CIS Kubernetes Benchmarks + platform: k8s + type: cis + version: '1.23' + relatedResources: + - https://www.cisecurity.org/benchmark/kubernetes + controls: + - id: 1.1.1 + name: Ensure that the API server pod specification file permissions are set to + 600 or more restrictive + description: Ensure that the API server pod specification file has permissions + of 600 or more restrictive + checks: + - id: AVD-KCV-0073 + commands: + - id: CMD-0001 + severity: HIGH + +``` + +### Compliance ID + +id field is the name used to execute the compliance scan via trivy +example: + +```sh +trivy k8s --compliance k8s-cis-1.23 +``` + +id naming convension: {platform}-{type}-{version} + +### Compliance Platform + +The platform field specifies the type of platform on which to run this compliance report. +supported platforms: + +- k8s (native kubernetes cluster) +- eks (elastic kubernetes service) +- aks (azure kubernetes service) +- gke (google kubernetes engine) +- rke2 (rancher kubernetes engine v2) +- ocp (OpenShift Container Platform) +- docker (docker engine) +- aws (amazon web services) + +### Compliance Type + +The type field specifies the kind compliance report. + +- cis (Center for Internet Security) +- nsa (National Security Agency) +- pss (Pod Security Standards) + +### Compliance Version + +The version field specifies the version of the compliance report. + +- 1.23 + +### Compliance Check + +Specify the check that needs to be evaluated based on the information collected from the command data output to assess the control. + +Example of how to define check data: + +```sh +# METADATA +# title: "Ensure that the --kubeconfig kubelet.conf file permissions are set to 600 or more restrictive" +# description: "Ensure that the kubelet.conf file has permissions of 600 or more restrictive." +# scope: package +# schemas: +# - input: schema["kubernetes"] +# related_resources: +# - https://www.cisecurity.org/benchmark/kubernetes +# custom: +# id: KCV0073 +# avd_id: AVD-KCV-0073 +# severity: HIGH +# short_code: ensure-kubelet.conf-file-permissions-600-or-more-restrictive. +# recommended_action: "Change the kubelet.conf file permissions to 600 or more restrictive if exist" +# input: +# selector: +# - type: kubernetes +package builtin.kubernetes.KCV0073 + +import data.lib.kubernetes + +types := ["master", "worker"] + +validate_kubelet_file_permission(sp) := {"kubeletConfFilePermissions": violation} { + sp.kind == "NodeInfo" + sp.type == types[_] + violation := {permission | permission = sp.info.kubeletConfFilePermissions.values[_]; permission > 600} + count(violation) > 0 +} + +deny[res] { + output := validate_kubelet_file_permission(input) + msg := "Ensure that the --kubeconfig kubelet.conf file permissions are set to 600 or more restrictive" + res := result.new(msg, output) +} +``` + +for additional info on writing checks look at [contribution guide](../CONTRIBUTING.md) + +### Compliance Command + +***Note:*** This field is not mandatory, it relevant to k8s compliance report when node-collector is in use + +Specify the command ID (#ref) that needs to be executed to collect the information required to evaluate the control. + +Example of how to define command data: + +```yaml +--- +- id: CMD-0001 + key: kubeletConfFilePermissions + title: kubelet.conf file permissions + nodeType: worker + audit: stat -c %a $kubelet.kubeconfig + platfroms: + - k8s + - aks +``` + +#### Command ID + +Find the next command ID by running the command [ID generator](https://github.com/aquasecurity/trivy-checks/blob/main/cmd/command_id/main.go) + +#### Command Key + +- Re-use an existing key or specifiy a new one (make sure key name has no spaces) + +Note: The key value should match the key name evaluated by the Rego check. + +### Command Title + +Represent the purpose of the command + +### Command NodeType + +Specify the node type on which the command is supposed to run. + +- worker +- master + +### Command Audit + +Specifiy here the shell command to be used please make sure to add error supression (2>/dev/null) + +### Command Platforms + +The list of platforms that support this command , name should be taken from this list [Platforms](#compliance-platform) + +### Command Config Files + +The commands use a configuration file that helps obtain the paths to binaries and configuration files based on different platforms (e.g., Rancher, native Kubernetes, etc.). + +For example: + +```yaml +kubelet: + bins: + - kubelet + - hyperkube kubelet + confs: + - /etc/kubernetes/kubelet-config.yaml + - /var/lib/kubelet/config.yaml +``` + +### Commands Files Location + +currently checks files location are :`https://github.com/aquasecurity/trivy-checks/tree/main/checks` + +proposed command files location: `https://github.com/aquasecurity/trivy-checks/tree/main/commands` +under command file + +Note: command config files will be located under `https://github.com/aquasecurity/trivy-checks/tree/main/commands` as well + +### Preparing commands data for compliance report as input for node-colector + +When the Trivy command is executed: `trivy k8s --compliance k8s-cis`, the relevant compliance specification will be parsed based on the spec name `k8s-cis` and `k8s_version`. It will build a list of command files to be passed to the node-collector, which will parse and execute them, returning the appropriate output. + +### Preparing commands data for cluster infra assessments + +When the Trivy command is executed: `trivy k8s --report summary`, the report will include a cluster infrastructure assessment. + +Trivy-Kubernetes will detect the running platform, build a list of command files to be passed to the node-collector, which will parse and execute them, and return the appropriate output. + +### Node-collector output + +The node collector will read commands and execute each command, and incorporate the output into the NodeInfo resource. + +example: + +```json +{ + "apiVersion": "v1", + "kind": "NodeInfo", + "metadata": { + "creationTimestamp": "2023-01-04T11:37:11+02:00" + }, + "type": "master", + "info": { + "adminConfFileOwnership": { + "values": [ + "root:root" + ] + }, + "adminConfFilePermissions": { + "values": [ + 600 + ] + } + ... + } +} +``` diff --git a/specs/compliance/docker-cis.yaml b/specs/compliance/docker-cis-1.6.0.yaml similarity index 99% rename from specs/compliance/docker-cis.yaml rename to specs/compliance/docker-cis-1.6.0.yaml index 851c8dc1..40d4a766 100644 --- a/specs/compliance/docker-cis.yaml +++ b/specs/compliance/docker-cis-1.6.0.yaml @@ -1,6 +1,6 @@ --- spec: - id: docker-cis + id: docker-cis-1.6.0 title: CIS Docker Community Edition Benchmark v1.6.0 description: CIS Docker Community Edition Benchmark relatedResources : diff --git a/specs/compliance/k8s-pss-baseline.yaml b/specs/compliance/k8s-pss-baseline-0.1.yaml similarity index 100% rename from specs/compliance/k8s-pss-baseline.yaml rename to specs/compliance/k8s-pss-baseline-0.1.yaml diff --git a/specs/compliance/k8s-pss-restricted.yaml b/specs/compliance/k8s-pss-restricted-0.1.yaml similarity index 100% rename from specs/compliance/k8s-pss-restricted.yaml rename to specs/compliance/k8s-pss-restricted-0.1.yaml