docs: add compliance contribution docs

Signed-off-by: chenk <[email protected]>

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

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
+      ]
+    }
+    ...
+  }
+}
+```

specs/compliance/docker-cis.yaml → 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 :