docs: improve databases documentation

[itaysk]

Description

• document the recently added db fallback options
• added checks db to db documentation
• removed unnecessary and and confusing section from air-gapped document

[itaysk]

the release note says: "Databases are downloaded in priority order until one is successful". does this mean that trivy will keep cycling through list "until one is successful"? or if it reaches the end it will error out

[itaysk]

I wanted to incorporate the rate limiting mitigation steps post into the documentation, but after re-reading the docs I see that there's a growing overlap between the "advanced netwrok scenatios" (aka air-gap) doc, and the "Database cofiguration" doc. The way I thought about it is that the configuration document only describes the flags avaialble and technical usage, and the air gap doc talks more about the scenario and provides recommendations. Does this make sense to you? if so, I'll need to refactor both documents accordingly

[itaysk]

I ended up reorganizing the configuration/db doc and the air-gapped doc, such that the db doc now documents everything related to trivy's databases, including purpose, requirements, and configuration options, and the air-gapped explains how to setup trivy in a network constraint environment. I also incorporated parts from the yet-to-be-published db throttling announcement into the relevant documents.

[simar7]

scanner engine but is lacking relevant security information needed to make security detections and recommendations. we repeat this in the air gap doc as well. Is this intentional?

[itaysk]

I thought it's worth reintroducing the motivation since someone might be reading one doc and not the other. I you think it's unnesessary I can remove the intro from the air gap doc.

[knqyf263]

Shouldn't we mention which one is the default?

[itaysk]

I thought that all official repos should be used by default, in the order specified. but I realize this is not the case.

[knqyf263]

I think it's more straightforward to aggregate them by artifacts so users can understand which address they can use for secondary.

• trivy-db
  • ghcr.io/aquasecurity/trivy-db (default)
  • aquasec/trivy-db
  • public.ecr.aws/aquasecurity/trivy-db
• trivy-java-db
  • ghcr.io/aquasecurity/trivy-java-db (default)
  • ...
    --

[itaysk]

I'm fine with making the change, but just thinking users might have a mirror preference based on their infrastructure, for example an AWS customer would probably prefer ECR for all of the images.

[knqyf263]

We call it "checks bundle" in all other places. Do we want to rename it officially?

[itaysk]

I'm fine with it.

[knqyf263]

@simar7 I think you named it "checks bundle." What do you think?

[simar7]

Yeah checks bundle is good with me.

[knqyf263]

@itaysk is calling it "checks database" in this PR. We should be consistent in what we call it within the project. Either is fine for me.

• Checks Bundle
• Checks Database

Note we already have a flag --checks-bundle-repository and need to rename it to --checks-db-repository if we'll go with checks database.

      --checks-bundle-repository string   OCI registry URL to retrieve checks bundle from (default "ghcr.io/aquasecurity/trivy-checks:1")

[knqyf263]

Adding a link to the page about self-hosting?

[knqyf263]

Suggested change

	The flags accepts multiple values, which can be used to specify multiple alternative repository locations. In case of a transient errors (e.g. status 429 or 5xx), Trivy will fall back to alternative registries in the order specified.
	The flags accepts multiple values, which can be used to specify multiple alternative repository locations. See [Automatic fallback](#automatic-fallback) for details.

[itaysk]

I thought that the authoritative section is this one, which describes all the db flags, and the db locations section on top should point here, not the other way around.

[knqyf263]

I think we want to add a new page for "Self-Hosting Databases". It can be used for air-gapped environments, but also useful for rate limits or network bandwidth. We can explain media types in the page.

https://github.com/aquasecurity/trivy/pull/7732/files#diff-f67fbe532cb6f906f5e2e056c318da6d0bc245f94c8cc1afbd7e72a61e2506b8R12

[itaysk]

I think we want to add a new page for "Self-Hosting Databases".

I wasn't sure what would be left in the airgap doc if we move most of the content to a shared page. Also it's currently called "Air-Gapped Environments and Self-Hosting", so I moved the media types table based there.

[knqyf263]

I wasn't sure what would be left in the airgap doc if we move most of the content to a shared page.

The page on the air-gapped environment originally showed how to download and populate databases manually. Self-hosting is not directly related to the air-gapped environment, so we can just link to it from the air-gapped environment page.

# Air-Gapped Environments

## Manual cache population
...

## Self-Hosting
You can also use self-hosted databases. Please see [here](./self-host.md) for details.

# Self-Hosting
Self-hosting databases helps you with:

- Rate limits
- Reducing outgoing network traffic
- [Air-Gapped Environments](./air-gap.md)

## Copying databases into your registry
...

## Media types
...