docs: add info on adding compliance checks #6275

AnaisUrlichs · 2024-03-05T16:32:20Z

Adding documentation to the contributing section on writing Compliance Checks

Signed-off-by: AnaisUrlichs <urlichsanais@gmail.com>

mkdocs.yml

docs/community/contribute/compliance.md

itaysk · 2024-04-01T12:02:52Z

docs/community/contribute/compliance.md

+
+The existing compliance specs in Trivy are located under the `trivy-policies/specs/compliance/` directory ([Link](https://github.com/aquasecurity/trivy-policies/tree/main/specs/compliance)).
+
+Create a new file under `trivy-policies/specs/compliance/` and name the file in the format of "provider-resource-spectype-version.yaml". For example, the file name for AWS CIS Benchmarks for EKS version 1.4 is: `aws-eks-cis-1.4.yaml`.


it's a good idea to define a naming convention.
"provider-resource" not sure this is the best terminology, also very cloud specific (and the compliance feature is not). I think in this case the entire "aws-eks" is the subject and there's no need to specify it's components in the generic template. another example there will be CIS specs for specific k8s flavor (like open shift), which this needs to appear in the name but I don't think in the template.
so I would suggest to simplify the template as subject-spec.yaml which means: specify the subject of the compliance (what are we evaluating?). if it's a cloud service or another example of a subcomponent, include the parent too, for example aws-eks. if the spec is specific to a version, optionally include it after the subject, e.g k8s-1.21. spec is a short name for the compliance framework that people can identify, e.g cis. if the spec is versioned, include the version too cis-1.1. wdyt?

What do you mean with this sentence:

which this needs to appear in the name but I don't think in the template.

"provider-resource-spectype-version.yaml" the reasoning here was is that we call it provider and resource/service in other parts of the source code and docs

if it's a cloud service or another example of a subcomponent, include the parent too, for example aws-eks

The spec type is specific to a benchmark version e.g. CIS, I don't think it makes much sense to include the K8s version as that won't tell people more about the compliance scan and in some cases CIS
specs correspond to different k8s versions @chen-keinan thoughts?

recent CIS specs for reference

What do you mean with this sentence

For example, that opehshift needs to appear in the file name, but doesn't have to have a placeholder in the naming convention template. we can ignore this sentence :)

we call it provider and resource/service in other parts of the source code and docs

I think this is true only to cloud. for example, I wrote a k8s compliance (PSS) and didn't have to know about service/provider in trivy and didn't use it in the name

I don't think it makes much sense to include the K8s version

OK, makes sense. but just to clarify, this isn't what text you quoted says "include the parent too, for example aws-eks"

itaysk · 2024-04-01T12:06:40Z

docs/community/contribute/compliance.md

+
+Create a new file under `trivy-policies/specs/compliance/` and name the file in the format of "provider-resource-spectype-version.yaml". For example, the file name for AWS CIS Benchmarks for EKS version 1.4 is: `aws-eks-cis-1.4.yaml`.
+
+### Minimum spec structure


IMO there's too much duplication with the general compliance documentation, this should be about how to upstream a compliance, not the complete guide to write a compliance.

Does this relate to line 19 or to the minimum spec structure?

I have moved some to the normal compliance documentation but I am thinking about the following instead:

divide the compliance docs into the following two separate sections in the table of content: built-in compliance and custom compliance. The custom compliance would then also detail how to contribute the custom compliance check to Trivy

Does this relate to line 19 or to the minimum spec structure?

Minimum spec structure (and what follows)

table of content: built-in compliance and custom compliance

not sure I understand how your suggestion is different than existing?

docs/community/contribute/compliance.md

itaysk · 2024-04-01T12:10:32Z

docs/community/contribute/compliance.md

+  - `checks.id` -- Required; this is the AVD ID or AVD IDs referenced that perform the Rego check for this compliance check, more information is provided below.
+  - `severity` -- Required; more information provided below.
+
+### Populating the `control` section


there's more to say about vulnerability checks and node checks

@chen-keinan I need your help here

@chen-keinan :) help

Signed-off-by: AnaisUrlichs <urlichsanais@gmail.com>

chen-keinan

@AnaisUrlichs look good, I have added few comments

chen-keinan · 2024-05-09T10:54:11Z

docs/docs/compliance/contrib-compliance.md

@@ -0,0 +1,101 @@
+# Custom Compliance Checks


Terminology could be confusing, could be Custom Compliance Specs is more accurate ?

chen-keinan · 2024-05-09T10:54:41Z

docs/docs/compliance/contrib-compliance.md

@@ -0,0 +1,101 @@
+# Custom Compliance Checks
+
+Trivy supports several different compliance checks. The details on compliance scanning with Trivy are provided in the [compliance documentation](../../docs/compliance/compliance.md).


Suggested change

Trivy supports several different compliance checks. The details on compliance scanning with Trivy are provided in the [compliance documentation](../../docs/compliance/compliance.md).

Trivy supports several different compliance specs. The details on compliance scanning with Trivy are provided in the [compliance documentation](../../docs/compliance/compliance.md).

chen-keinan · 2024-05-09T11:14:40Z

docs/docs/compliance/contrib-compliance.md

+# Custom Compliance Checks
+
+Trivy supports several different compliance checks. The details on compliance scanning with Trivy are provided in the [compliance documentation](../../docs/compliance/compliance.md).
+All of the Compliance Checks currently available in Trivy can be found in the `trivy-policies/specs/compliance/` directory ([Link](https://github.com/aquasecurity/trivy-policies/tree/main/specs/compliance)).


trivy-policies repo on github name has been changed to trivy-checks, change should apply to all references in doc

chen-keinan · 2024-05-09T11:34:10Z

docs/docs/compliance/contrib-compliance.md

+
+```
+  - id: 2.1.1
+    name: Enable audit Logs (Automated)


in example I would put (Manual) as there is no check (nil)

docs: add info on adding compliance checks

bd90141

Signed-off-by: AnaisUrlichs <urlichsanais@gmail.com>

AnaisUrlichs requested a review from knqyf263 as a code owner March 5, 2024 16:32

docs: update contrib documentation for contributing compliance specs

d393301

Signed-off-by: AnaisUrlichs <urlichsanais@gmail.com>

AnaisUrlichs changed the title ~~WIP: docs: add info on adding compliance checks~~ docs: add info on adding compliance checks Mar 6, 2024

AnaisUrlichs requested review from chen-keinan and itaysk March 6, 2024 15:28

docs: fix changes in compliance contribution based on PR feedback

33ce15b

Signed-off-by: AnaisUrlichs <urlichsanais@gmail.com>

knqyf263 reviewed Mar 8, 2024

View reviewed changes

mkdocs.yml Outdated Show resolved Hide resolved

itaysk reviewed Apr 1, 2024

View reviewed changes

AnaisUrlichs and others added 2 commits May 9, 2024 10:00

Merge branch 'aquasecurity:main' into compliance-docs-update

aa33759

update custom compliance reports re PR comments

f9e1d5d

Signed-off-by: AnaisUrlichs <urlichsanais@gmail.com>

AnaisUrlichs requested review from itaysk and knqyf263 May 9, 2024 09:24

chen-keinan reviewed May 9, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add info on adding compliance checks #6275

docs: add info on adding compliance checks #6275

AnaisUrlichs commented Mar 5, 2024

itaysk Apr 1, 2024

AnaisUrlichs Apr 2, 2024

itaysk Apr 4, 2024 •

edited

itaysk Apr 1, 2024

AnaisUrlichs Apr 2, 2024

AnaisUrlichs Apr 2, 2024

itaysk Apr 4, 2024

itaysk Apr 4, 2024

itaysk Apr 1, 2024

AnaisUrlichs Apr 2, 2024

AnaisUrlichs May 9, 2024

chen-keinan left a comment

chen-keinan May 9, 2024

chen-keinan May 9, 2024

chen-keinan May 9, 2024

chen-keinan May 9, 2024


		The existing compliance specs in Trivy are located under the `trivy-policies/specs/compliance/` directory ([Link](https://github.com/aquasecurity/trivy-policies/tree/main/specs/compliance)).

		Create a new file under `trivy-policies/specs/compliance/` and name the file in the format of "provider-resource-spectype-version.yaml". For example, the file name for AWS CIS Benchmarks for EKS version 1.4 is: `aws-eks-cis-1.4.yaml`.


		Create a new file under `trivy-policies/specs/compliance/` and name the file in the format of "provider-resource-spectype-version.yaml". For example, the file name for AWS CIS Benchmarks for EKS version 1.4 is: `aws-eks-cis-1.4.yaml`.

		### Minimum spec structure

		@@ -0,0 +1,101 @@
		# Custom Compliance Checks

		Trivy supports several different compliance checks. The details on compliance scanning with Trivy are provided in the [compliance documentation](../../docs/compliance/compliance.md).

docs: add info on adding compliance checks #6275

Are you sure you want to change the base?

docs: add info on adding compliance checks #6275

Conversation

AnaisUrlichs commented Mar 5, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

itaysk Apr 4, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chen-keinan left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

itaysk Apr 4, 2024 •

edited