docs: add compliance contribution docs

ARCHITECTURE.md

@@ -8,6 +8,7 @@ The directory structure is broken down as follows:
 
 - `cmd/` - These CLI tools are primarily used during development for end-to-end testing without needing to pull the library into trivy/tfsec etc.
 - `checks` - All of the checks are defined in this directory.
+- `commands` - All Node-collector commands are defined in this directory.
 - `pkg/spec` - Logic to handle standardized specs such as CIS.
 - `pkg/rules` - This package exposes internal rules, and imports them accordingly (see _rules.go_).
 - `specs/` - Standaridized compliance specs such as CIS.

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.
 
@@ -47,10 +47,10 @@ A simple rule looks like the following example:
 package builtin.aws.rds.aws0176
 
 deny[res] {
-	instance := input.aws.rds.instances[_]
-	instance.engine.value == ["postgres", "mysql"][_]
-	not instance.iamauthenabled.value
-	res := result.new("Instance does not have IAM Authentication enabled", instance.iamauthenabled)
+ instance := input.aws.rds.instances[_]
+ instance.engine.value == ["postgres", "mysql"][_]
+ not instance.iamauthenabled.value
+ res := result.new("Instance does not have IAM Authentication enabled", instance.iamauthenabled)
 }
 ```
 
@@ -65,23 +65,23 @@ Let's break the metadata down.
 - `scope` is used to define the scope of the policy. In this case, we are defining a policy that applies to the entire package. _defsec_ only supports using package scope for metadata at the moment, so this should always be the same.
 - `schemas` tells Rego that it should use the `AWS` schema to validate the use of the input data in the policy. We currently support [these](https://github.com/aquasecurity/defsec/tree/9b3cc255faff5dc57de5ff77ed0ce0009c80a4bb/pkg/rego/schemas) schemas. Using a schema can help you validate your policy faster for syntax issues.
 - `custom` is used to define custom fields that can be used by defsec to provide additional context to the policy and any related detections. This can contain the following:
-    - `avd_id` is the ID of the rule in the [AWS Vulnerability Database](https://avd.aquasec.com/). This is used to link the rule to the AVD entry. You can generate an ID to use for this field using `make id`.
-    - `provider` is the name of the provider the rule targets. This should be the same as the provider name in the `pkg/providers` directory, e.g. `aws`.
-    - `service` is the name of the service the rule targets. This should be the same as the service name in the `pkg/providers` directory, e.g. `rds`.
-    - `severity` is the severity of the rule. This should be one of `LOW`, `MEDIUM`, `HIGH`, or `CRITICAL`.
-    - `short_code` is a short code for the rule. This should be a short, descriptive name for the rule, separating words with hyphens. You should omit provider/service from this.
-    - `recommended_action` is a recommended remediation action for the rule. This should be a short, descriptive sentence describing what the user should do to resolve the issue.
-    - `input` tells _defsec_ what inputs this rule should be applied to. Cloud provider rules should always use the `selector` input, and should always use the `type` selector with `cloud`. Rules targeting Kubernetes yaml can use `kubenetes`, RBAC can use `rbac`, and so on.
-    - `subtypes` aid the engine to determine if it should load this policy or not for scanning. This can aid with the performance of scanning, especially if you have a lot of checks but not all apply to the IaC that you are trying to scan.
+  - `avd_id` is the ID of the rule in the [AWS Vulnerability Database](https://avd.aquasec.com/). This is used to link the rule to the AVD entry. You can generate an ID to use for this field using `make id`.
+  - `provider` is the name of the provider the rule targets. This should be the same as the provider name in the `pkg/providers` directory, e.g. `aws`.
+  - `service` is the name of the service the rule targets. This should be the same as the service name in the `pkg/providers` directory, e.g. `rds`.
+  - `severity` is the severity of the rule. This should be one of `LOW`, `MEDIUM`, `HIGH`, or `CRITICAL`.
+  - `short_code` is a short code for the rule. This should be a short, descriptive name for the rule, separating words with hyphens. You should omit provider/service from this.
+  - `recommended_action` is a recommended remediation action for the rule. This should be a short, descriptive sentence describing what the user should do to resolve the issue.
+  - `input` tells _defsec_ what inputs this rule should be applied to. Cloud provider rules should always use the `selector` input, and should always use the `type` selector with `cloud`. Rules targeting Kubernetes yaml can use `kubenetes`, RBAC can use `rbac`, and so on.
+  - `subtypes` aid the engine to determine if it should load this policy or not for scanning. This can aid with the performance of scanning, especially if you have a lot of checks but not all apply to the IaC that you are trying to scan.
 
 Now you'll need to write the rule logic. This is the code that will be executed to detect the issue. You should define a rule named `deny` and place your code inside this.
 
 ```rego
 deny[res] {
-	instance := input.aws.rds.instances[_]
-	instance.engine.value == ["postgres", "mysql"][_]
-	not instance.iamauthenabled.value
-	res := result.new("Instance does not have IAM Authentication enabled", instance.iamauthenabled)
+ instance := input.aws.rds.instances[_]
+ instance.engine.value == ["postgres", "mysql"][_]
+ not instance.iamauthenabled.value
+ res := result.new("Instance does not have IAM Authentication enabled", instance.iamauthenabled)
 }
 ```
 
@@ -94,3 +94,26 @@ 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,223 @@
+# Add New Compliance Report
+
+## Define a Compliance spec, based on cis benchmark or other specs
+
+here is an example for cis compliance report:
+
+```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 ID
+
+Specify the check ID 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 under ./checks folder:
+
+```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 ID
+
+***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 under ./commands folder:
+
+```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.
+
+```sh
+make command-id
+```
+
+#### 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
+
+### 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
+      ]
+    }
+    ...
+  }
+}
+```