refractionPOINT · maximelb · Sep 28, 2026 · Sep 28, 2026 · Sep 28, 2026 · Sep 28, 2026
diff --git a/docs/cloud-security/code-security/container-registries.md b/docs/cloud-security/code-security/container-registries.md
@@ -0,0 +1,24 @@
+# Scan private container images
+
+Code Security scans digest-pinned images found in your cloud inventory. Public images need no registry credential. For private images, connect the registry as described below. An image that the registry will not let LimaCharlie pull stays **unscanned** with an access reason; findings for that image are incomplete. Other images continue scanning.
+
+Registry credentials are used by the short-lived image fetch job. The scan container receives the downloaded image, without a registry credential.
+
+| Registry | Grant or credential | Where to configure it |
+|---|---|---|
+| Google Artifact Registry / GCR | `roles/artifactregistry.reader` on the image's project for the connected service account. Legacy Container Registry may also need `roles/storage.objectViewer` on its image bucket. | [Google Cloud provider](../provider-setup/gcp.md#container-image-scanning-by-code-security) |
+| Amazon ECR | `ecr:GetAuthorizationToken` on the connected assume-role, and `ecr:BatchGetImage` and `ecr:GetDownloadUrlForLayer` for each repository to scan. For member accounts, `organizations:DescribeAccount` on the connected role. | [AWS provider](../provider-setup/aws.md#private-ecr-images) |
+| Azure Container Registry | `AcrPull` on the registry for the connected app registration. | [Azure provider](../provider-setup/azure.md#private-azure-container-registry-images) |
+| Docker Hub | A token with read access to the exact private repository. | **Cloud Security → Settings → Registries** |
+| Quay.io | A read-only robot account with access to the exact repository. | **Cloud Security → Settings → Registries** |
+| GitHub Container Registry (`ghcr.io`) | A classic personal access token with `read:packages`, from a user allowed to read the package. If your GitHub organization requires SSO, authorize the token for it. | **Cloud Security → Settings → Registries** |
+
+For Docker Hub, Quay.io, and GHCR, store the token in a LimaCharlie secret and create one registry credential setting **per repository**. Enter the registry, repository name (for example, `team/app`), username, and the secret reference. The setting cannot contain a literal token. Use a read-only account or token, and grant it access only to repositories that must be scanned. A credential for `team/app` is never used to pull `team/other`.
+
+For ECR and ACR, LimaCharlie uses your existing cloud connection. It exchanges that connection for a short-lived registry pull credential; no second long-lived credential is needed. Each pull credential can read only the one repository being scanned: ACR tokens request `repository:<name>:pull`, and ECR tokens come from a session whose policy allows reads on that single repository.
+
+ECR images are pulled only from the connected AWS account, or from member accounts that AWS Organizations confirms belong to the connected organization. Images in other AWS accounts are reported as not scanned; LimaCharlie does not request credentials for them. Likewise, ACR images are pulled only from registries that LimaCharlie has inventoried through your connected Azure subscriptions.
+
+If one image cannot be pulled, the pass is **partial**, not a clean result. Open the image to see the registry and reason. `image_registry_credential` means a usable credential is missing; `image_registry_permission` means the registry refused the supplied credential. After fixing access, use **Sync now** on the source connection to retry immediately, or wait for the next scheduled attempt.
+
+See [Troubleshooting](troubleshooting.md#scanning) for other image failures.
diff --git a/docs/cloud-security/code-security/troubleshooting.md b/docs/cloud-security/code-security/troubleshooting.md
@@ -20,7 +20,8 @@ if it is shown. It names what is not set up and links to the fix. From the CLI,
 | A repository still shows `sast_ruleset_unresolved` | That result predates code rules, and `sast_ruleset` is now ignored. The next scan replaces it. |
 | GitLab projects are listed but never scanned | The connection is to a self-managed GitLab instance. Only GitLab.com projects can be scanned. The connection test reports `code_scanning_reachable`. |
 | The repository drawer says it is outside the App's installation | The GitHub App is installed on selected repositories only. Add the repository on GitHub's installation page. |
-| An image shows `registry_permission_denied`, or the status shows `image_registry_permission` | The registry refused to let us pull the image. For Google Cloud, grant the connection's service account `roles/artifactregistry.reader` on the project that hosts the image. See [Container image scanning](../provider-setup/gcp.md#container-image-scanning-by-code-security). The image is retried automatically, at most once a day after repeated failures. **Sync now** on the source-control connection retries it immediately. |
+| An image shows `registry_permission_denied`, or the status shows `image_registry_permission` | The registry refused the image pull. Grant the connected cloud role or registry credential read access to this repository. See [Scan private container images](container-registries.md). The image is retried automatically; **Sync now** on the source connection retries immediately. |
+| Status shows `image_registry_credential` | A private image has no usable registry credential. Add the appropriate cloud permission or a read-only repository credential under **Cloud Security → Settings → Registries**. Other images can still scan; this pass is partial. See [Scan private container images](container-registries.md). |
 | An image shows `image_not_found` | The registry has no image with that digest, usually because it was deleted or cleaned up. After two such answers the image is no longer retried. It is dropped when nothing references it. If you pushed it again, use **Sync now** on the source-control connection. |
 | An image shows `failure_backoff` | Recent attempts failed. The image's error says why and when it will next be tried. |
 | A finding you expected is missing entirely | Check `severity_floor`. Findings below it are never recorded, so there is nothing to filter for. |

diff --git a/docs/cloud-security/provider-setup/aws.md b/docs/cloud-security/provider-setup/aws.md
@@ -281,3 +281,12 @@ guardrails to account for.
 |---|---|---|
 | `auth` fails: `… no EC2 IMDS role found` | Secret used the wrong key names → no static creds → default chain → IMDS | Use `access_key_id` / `secret_access_key` (no `aws_` prefix) |
 | `AccessDenied` on `sts:AssumeRole` | External ID mismatch, wrong trust-policy principal, or propagation | Confirm `aws_external_id` matches the trust condition; retry after a few seconds |
+
+## Private ECR images
+
+To scan private images in Amazon ECR, add these permissions to the **assumed role** used by this connection:
+
+- `ecr:GetAuthorizationToken` (this action uses `Resource: "*"`).
+- `ecr:BatchGetImage` and `ecr:GetDownloadUrlForLayer` on each ECR repository you want scanned.
+
+For an AWS Organization connection, grant the same permissions to the member-account role in the account that owns each image, and allow the connected role `organizations:DescribeAccount` so LimaCharlie can confirm that the image's account is a member. Keep the base IAM user's permission limited to `sts:AssumeRole`. Each pull credential is limited by a session policy to the one repository being scanned. Images in AWS accounts outside the connected account and its organization are not pulled. See [AWS's ECR pull permission reference](https://docs.aws.amazon.com/AmazonECR/latest/userguide/ECR_on_ECS.html) and [private image scanning](../code-security/container-registries.md).
diff --git a/docs/cloud-security/provider-setup/azure.md b/docs/cloud-security/provider-setup/azure.md
@@ -234,3 +234,7 @@ the Azure-specific checks follow.
 | `signin_activity` fails with a licence error | Sign-in activity requires Entra ID P1/P2 | Either accept the degrade or add the licence |
 | Directory data appears twice | An `azure` **and** an `entra` record both cover the tenant | This is handled automatically: the Azure connection defers its tenant-global directory collectors to the standalone [Entra](entra.md) record |
 | A scale set / App Service is missing | The resource type may need quota or a supported SKU in that subscription | Confirm the resource is visible to the SP with `az resource list` under the same identity |
+
+## Private Azure Container Registry images
+
+To scan private images in Azure Container Registry, assign **AcrPull** on each registry to the **existing app registration** used by this connection. Subscription Reader alone does not grant image pull access. LimaCharlie exchanges the app's credential for a token limited to each image repository's `pull` action. No registry admin account is needed. See [Microsoft's service principal instructions](https://learn.microsoft.com/en-us/azure/container-registry/container-registry-auth-service-principal#use-an-existing-service-principal) and [private image scanning](../code-security/container-registries.md).
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -621,6 +621,7 @@ nav:
           - Overview: cloud-security/code-security/index.md
           - Get Started: cloud-security/code-security/getting-started.md
           - Working with Results: cloud-security/code-security/results.md
+          - Private Container Registries: cloud-security/code-security/container-registries.md
           - Scan Policy: cloud-security/code-security/policy.md
           - Code Rules: cloud-security/code-security/code-rules.md
           - Pull-Request Checks & Push Rescans: cloud-security/code-security/pull-requests.md