docs(misconf): Reorganize misconfiguration scan pages

[simar7]

Description

This PR updates the structure of the misconfiguration scanning docs. Also adds more info on schemas.

Checklist

• I've read the guidelines for contributing to this repository.
• I've followed the conventions in the PR title.
• I've added tests that prove my fix is effective or that my feature works.
• I've updated the documentation with the relevant information (if needed).
• I've added usage information (if the PR introduces new options)
• I've included a "before" and "after" example to the description (if the PR is a user interface change).

[itaysk]

@simar7 is this intentionally Draft or should we review it?

[nikpivkin]

LGTM, left one small comment

[itaysk]

yes I want to review it but I'll get to it only later this week

[itaysk]

I think this file deserves an e2e proof read. I cannot comment on lines outside of your changes, but a few things that caught my eye:

1. the intro is important, can we please emphasize the motivation for using input schema and it's place in trivy misconfiguration scanning? it is mentioned in other places in the doc but should be first thing.
2. the schema explorer text is added here but there are other places mentioning the avilable schemas. I think we should have an H2 of built-it schemas, which lists the schemas, the source, and the explorer.
3. I think we should spend a few words on the "defsec schema" as a unified schema (motivation, implementation etc), as opposed to other more straightforward schemas (i.e docker, k8s)
4. "policy schema" is a misnomer and should be renamed to "input schema"
5. also "policy" is still prevalent here. should be "check"
6. after the intro, the doc starts with "In Trivy we have been able to define a schema for a Dockerfile" we should clarify this is an example (or rewrite)

[simar7]

the intro is important, can we please emphasize the motivation for using input schema and it's place in trivy misconfiguration scanning? it is mentioned in other places in the doc but should be first thing.

I added that here how would you like to see it?

the schema explorer text is added here but there are other places mentioning the avilable schemas. I think we should have an H2 of built-it schemas, which lists the schemas, the source, and the explorer.

added.

I think we should spend a few words on the "defsec schema" as a unified schema (motivation, implementation etc), as opposed to other more straightforward schemas (i.e docker, k8s)

All schemas are equal in the sense that they are applicable to the resources that they scan. But I think you're trying to emphasize the common representation of variety of scan targets. I've added a small blurb about that here.

"policy schema" is a misnomer and should be renamed to "input schema"

thanks, fixed.

also "policy" is still prevalent here. should be "check"

thanks, fixed.

after the intro, the doc starts with "In Trivy we have been able to define a schema for a Dockerfile" we should clarify this is an example (or rewrite)

I rewrote this here 73af930

[itaysk]

maybe we can improve this doc while we are at it

1. start with what is misconfiguration scanning before we jump to built-in vs custom checks? just a sentence or so will do.
2. should explicitly mention the special "config" subcommand and it's purpose (compared to all other scanners which are target oriented)
3. not sure the remaining headings are helpful now

[simar7]

Is this comment for another place? We have the intro to misconfiguration scanning already mentioned at the beginning https://github.com/aquasecurity/trivy/pull/8206/files/30a4d8cd899bf48fa1c82554694de441b7784adb#diff-27a4cf648b57a6aad62225b17605a34b1e7b47b97925e1e24a311db4e22cc57fR1-R11

If not, can you describe what you'd like to see done differently?

[itaysk]

I think some of the configurations here are repeated in the "custom" section (or should be). wdyt about keeping this page for documenting only the basic usage with builtin checks, and concentrate all the the custom checks documentation (including cli usage/configuration from this page) in under the custom section?
I also don't think we need the "built-in" page under "policy". 1) policy is a misnomer 2) policy title applies alo to custom 3) there's just one page in this section.
so if you agree with this comment then the structure will look like:

• Misconfiguration
  • Overview
  • Configuration
  • Builtin Checks
  • Custom Checks
    • pages about custom checks