From da23d62e6aad5033e75c6c80e716ab64894de3bf Mon Sep 17 00:00:00 2001 From: Andoni Alonso <14891798+andoniaf@users.noreply.github.com> Date: Fri, 13 Feb 2026 11:00:03 +0100 Subject: [PATCH] docs(image): add Image provider CLI documentation (#9986) --- docs/docs.json | 6 + docs/introduction.mdx | 1 + .../github/getting-started-github.mdx | 2 +- .../providers/image/getting-started-image.mdx | 197 ++++++++++++++++++ docs/user-guide/tutorials/prowler-app-sso.mdx | 4 +- 5 files changed, 207 insertions(+), 3 deletions(-) create mode 100644 docs/user-guide/providers/image/getting-started-image.mdx diff --git a/docs/docs.json b/docs/docs.json index 2f190ac36d..8305388369 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -255,6 +255,12 @@ "user-guide/providers/cloudflare/authentication" ] }, + { + "group": "Image", + "pages": [ + "user-guide/providers/image/getting-started-image" + ] + }, { "group": "LLM", "pages": [ diff --git a/docs/introduction.mdx b/docs/introduction.mdx index 19be547497..c354f2802d 100644 --- a/docs/introduction.mdx +++ b/docs/introduction.mdx @@ -38,6 +38,7 @@ The supported providers right now are: | [MongoDB Atlas](/user-guide/providers/mongodbatlas/getting-started-mongodbatlas) | Official | Organizations | UI, API, CLI | | [OpenStack](/user-guide/providers/openstack/getting-started-openstack) | Official | Projects | CLI | | [LLM](/user-guide/providers/llm/getting-started-llm) | Official | Models | CLI | +| [Image](/user-guide/providers/image/getting-started-image) | Official | Container Images | CLI | | **NHN** | Unofficial | Tenants | CLI | For more information about the checks and compliance of each provider visit [Prowler Hub](https://hub.prowler.com). diff --git a/docs/user-guide/providers/github/getting-started-github.mdx b/docs/user-guide/providers/github/getting-started-github.mdx index a9f870269b..5a73c8355f 100644 --- a/docs/user-guide/providers/github/getting-started-github.mdx +++ b/docs/user-guide/providers/github/getting-started-github.mdx @@ -94,7 +94,7 @@ prowler github --github-app-id app_id --github-app-key-path app_key_path ### Scan Scoping -By default, Prowler scans all repositories accessible to the authenticated user or organization. To limit the scan to specific repositories or organizations, use the following flags. +Scan scoping controls which repositories and organizations Prowler includes in a security assessment. By default, Prowler scans all repositories accessible to the authenticated user or organization. To limit the scan to specific repositories or organizations, use the following flags. #### Scanning Specific Repositories diff --git a/docs/user-guide/providers/image/getting-started-image.mdx b/docs/user-guide/providers/image/getting-started-image.mdx new file mode 100644 index 0000000000..4fe509c2af --- /dev/null +++ b/docs/user-guide/providers/image/getting-started-image.mdx @@ -0,0 +1,197 @@ +--- +title: "Getting Started with the Image Provider" +--- + +import { VersionBadge } from "/snippets/version-badge.mdx" + +Prowler's Image provider enables comprehensive container image security scanning by integrating with [Trivy](https://trivy.dev/). This provider detects vulnerabilities, exposed secrets, and misconfigurations in container images, converting Trivy findings into Prowler's standard reporting format for unified security assessment. + +## How It Works + +* **Trivy integration:** Prowler leverages [Trivy](https://trivy.dev/) to scan container images for vulnerabilities, secrets, misconfigurations, and license issues. +* **Trivy required:** Trivy must be installed and available in the system PATH before running any scan. +* **Authentication:** No registry authentication is required for public images. For private registries, configure Docker credentials via `docker login` before scanning. +* **Output formats:** Results are output in the same formats as other Prowler providers (CSV, JSON, HTML, etc.). + +## Prowler CLI + + + + +The Image provider is currently available in Prowler CLI only. + + +### Install Trivy + +Install Trivy using one of the following methods: + + + + ```bash + brew install trivy + ``` + + + ```bash + sudo apt-get install trivy + ``` + + + ```bash + curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sh -s -- -b /usr/local/bin + ``` + + + +For additional installation methods, see the [Trivy installation guide](https://trivy.dev/latest/getting-started/installation/). + + +### Supported Scanners + +Prowler CLI supports the following scanners: + +* [Vulnerability](https://trivy.dev/docs/latest/guide/scanner/vulnerability/) +* [Secret](https://trivy.dev/docs/latest/guide/scanner/secret/) +* [Misconfiguration](https://trivy.dev/docs/latest/guide/scanner/misconfiguration/) +* [License](https://trivy.dev/docs/latest/guide/scanner/license/) + +By default, only vulnerability and secret scanners run during a scan. To specify which scanners to use, refer to the [Specify Scanners](#specify-scanners) section below. + +### Scan Container Images + +Use the `image` argument to run Prowler with the Image provider. Specify the images to scan using the `-I` flag or an image list file. + +#### Scan a Single Image + +To scan a single container image: + +```bash +prowler image -I alpine:3.18 +``` + +#### Scan Multiple Images + +To scan multiple images, repeat the `-I` flag: + +```bash +prowler image -I nginx:latest -I redis:7 -I python:3.12-slim +``` + +#### Scan From an Image List File + +For large-scale scanning, provide a file containing one image per line: + +```bash +prowler image --image-list images.txt +``` + +The file supports comments (lines starting with `#`) and blank lines: + +```text +# Production images +nginx:1.25 +redis:7-alpine + +# Development images +python:3.12-slim +node:20-bookworm +``` + + +Image list files are limited to a maximum of 10,000 lines. Individual image names exceeding 500 characters are automatically skipped with a warning. + + + +Image names must follow the Open Container Initiative (OCI) reference format. Valid names start with an alphanumeric character and contain only letters, digits, periods, hyphens, underscores, slashes, colons, and `@` symbols. Names containing shell metacharacters (`;`, `|`, `&`, `$`, `` ` ``) are rejected to prevent command injection. + + +Valid examples: +* **Standard tag:** `alpine:3.18` +* **Custom registry:** `myregistry.io/myapp:v1.0` +* **SHA digest:** `ghcr.io/org/image@sha256:abc123...` + +#### Specify Scanners + +To select which scanners Trivy runs, use the `--scanners` option. By default, Prowler enables `vuln` and `secret` scanners: + +```bash +# Vulnerability scanning only +prowler image -I alpine:3.18 --scanners vuln + +# All available scanners +prowler image -I alpine:3.18 --scanners vuln secret misconfig license +``` + + +#### Image Config Scanners + +To scan Dockerfile-level metadata for misconfigurations or embedded secrets, use the `--image-config-scanners` option: + +```bash +# Scan Dockerfile for misconfigurations +prowler image -I alpine:3.18 --image-config-scanners misconfig + +# Scan Dockerfile for both misconfigurations and secrets +prowler image -I alpine:3.18 --image-config-scanners misconfig secret +``` + +Available image config scanners: + +* **misconfig**: Detects Dockerfile misconfigurations (e.g., running as root, missing health checks) +* **secret**: Identifies secrets embedded in Dockerfile instructions + + +Image config scanners are disabled by default. This option is independent from `--scanners` and specifically targets the image configuration (Dockerfile) rather than the image filesystem. + + +#### Filter by Severity + +To filter findings by severity level, use the `--trivy-severity` option: + +```bash +# Only critical and high severity findings +prowler image -I alpine:3.18 --trivy-severity CRITICAL HIGH +``` + +Available severity levels: `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, `UNKNOWN`. + +#### Ignore Unfixed Vulnerabilities + +To exclude vulnerabilities without available fixes: + +```bash +prowler image -I alpine:3.18 --ignore-unfixed +``` + +#### Configure Scan Timeout + +To adjust the scan timeout for large images or slow network conditions, use the `--timeout` option: + +```bash +prowler image -I large-image:latest --timeout 10m +``` + +The timeout accepts values in seconds (`s`), minutes (`m`), or hours (`h`). Default: `5m`. + +### Authentication for Private Registries + +The Image provider relies on Trivy for registry authentication. To scan images from private registries, configure Docker credentials before running the scan: + +```bash +# Log in to a private registry +docker login myregistry.io + +# Then scan the image +prowler image -I myregistry.io/myapp:v1.0 +``` + +Trivy automatically uses credentials from Docker's credential store (`~/.docker/config.json`). + +### Troubleshooting Common Scan Errors + +The Image provider categorizes common Trivy errors with actionable guidance: + +* **Authentication failure (401/403):** Registry credentials are missing or invalid. Run `docker login` for the target registry and retry the scan. +* **Image not found (404):** The specified image name, tag, or registry is incorrect. Verify the image reference exists and is accessible. +* **Rate limited (429):** The container registry is throttling requests. Wait before retrying, or authenticate to increase rate limits. +* **Network issue:** Trivy cannot reach the registry due to connectivity problems. Check network access, DNS resolution, and firewall rules. diff --git a/docs/user-guide/tutorials/prowler-app-sso.mdx b/docs/user-guide/tutorials/prowler-app-sso.mdx index 9539bfaa45..f823fae3df 100644 --- a/docs/user-guide/tutorials/prowler-app-sso.mdx +++ b/docs/user-guide/tutorials/prowler-app-sso.mdx @@ -53,7 +53,7 @@ On the profile page, find the "SAML SSO Integration" card and click "Enable" to ![Enable SAML Integration](/images/prowler-app/saml/saml-step-2.png) -Next section will explain how to fill the IdP configuration based on your Identity Provider. +The next section explains how to configure the IdP settings based on the selected Identity Provider. #### Step 3: Configure the Identity Provider (IdP) Choose a Method: @@ -87,7 +87,7 @@ Choose a Method: |----------------|---------------------------------------------------------------------------------------------------------|----------| | `firstName` | The user's first name. | Yes | | `lastName` | The user's last name. | Yes | - | `userType` | The Prowler role to be assigned to the user (e.g., `admin`, `auditor`). If a role with that name already exists, it will be used; if it does not exist, a new role with that name will be created without permissions. If `userType` is not defined, the user is assigned the `no_permissions` role. Role permissions can be edited in the [RBAC Management tab](/user-guide/tutorials/prowler-app-rbac). | No | + | `userType` | Determines which Prowler role the user receives (e.g., `admin`, `auditor`). If a role with that name already exists, the user receives it automatically; if it does not exist, Prowler App creates a new role with that name without permissions. If `userType` is not defined, the user is assigned the `no_permissions` role. Role permissions can be edited in the [RBAC Management tab](/user-guide/tutorials/prowler-app-rbac). | No | | `companyName` | The user's company name. This is automatically populated if the IdP sends an `organization` attribute. | No |