Skip to main content
Amazon Elastic Container Registry (ECR) is AWS’s managed Docker container registry. CybeDefend connects to ECR to list your repositories, browse image tags, and scan images for vulnerabilities. CybeDefend supports two authentication modes:

IAM role (recommended)

CybeDefend assumes a cross-account IAM role in your AWS account. No AWS secret is ever shared — access is granted by a role you fully control and can revoke at any time.

Static AWS keys

Provide a long-lived IAM access key ID and secret access key. Simpler to set up, but the secret is stored by CybeDefend and must be rotated manually.
ECR credentials are managed at the organization level and linked to one or more projects. Only the projects a credential is linked to can browse its images and start scans. See Organization credentials & project linking.
With this mode, CybeDefend never holds an AWS secret. You create an IAM role in your own AWS account whose trust policy allows only CybeDefend’s AWS principal to assume it, gated by a unique External ID. At scan time, CybeDefend assumes that role, exchanges it for a short-lived ECR token, and hands only that token to the scanner — your AWS credentials never reach the scanning engine.

​
How it works

1

CybeDefend generates the setup

CybeDefend issues a unique External ID and produces two ready-to-paste JSON policies: a trust policy (who may assume the role) and a permission policy (read-only ECR access).
2

You create the role in AWS

You create an IAM role with that trust policy and attach the permission policy. The role lives entirely in your account.
3

CybeDefend assumes the role on demand

To list images or run a scan, CybeDefend calls sts:AssumeRole (passing the External ID) to obtain temporary credentials, then calls ecr:GetAuthorizationToken to get a short-lived Docker login. Only that registry token is injected into the scanner pod.

​
Setup

Start from your project’s Container Registries → AWS ECR integration, pick IAM role, choose the AWS region of your registry, and click Generate setup instructions. CybeDefend returns the External ID, the trusted principal, and the two policies referenced below.
Keep the setup window open until you save. Each click on Generate setup instructions mints a new External ID — a role you already created in AWS will be refused until you update its trust policy with the new value.
1

Create the role with the trust policy

AWS Console → IAM → Roles → Create role → select Custom trust policy, paste the trust policy JSON below, then click Next.
Trust policy (example)
The Principal.AWS value is CybeDefend’s AWS service account (a single, shared principal). The sts:ExternalId condition is mandatory — it is what prevents another tenant from assuming your role (the confused-deputy protection). Use the exact values from the setup window.
2

Skip the permissions screen

On Add permissions, select nothing and click Next. Give the role a name (e.g. cybedefend-ecr-scan) and click Create role.
3

Attach the permission policy

Open the role you just created → Permissions tab → Add permissions → Create inline policy → JSON tab. Paste the permission policy below, name it (e.g. cybedefend-ecr-pull), then create it.
Permission policy
These are read-only ECR permissions — enough to list repositories, inspect images, and pull layers for scanning. CybeDefend never needs write access.
4

Paste the role ARN and save

From the role’s summary page, copy its ARN (e.g. arn:aws:iam::123456789012:role/cybedefend-ecr-scan) and paste it back into CybeDefend, then click Save. CybeDefend immediately verifies it can assume the role and reach ECR before storing the integration.
The 12-digit AWS account ID and the registry URL (<account>.dkr.ecr.<region>.amazonaws.com) are derived automatically from the role ARN and region — you don’t enter them yourself in IAM-role mode.

​
Option 2 — Static AWS keys

If you prefer (or can’t use cross-account roles), provide a long-lived IAM access key. CybeDefend encrypts the secret at rest and verifies it against AWS STS before storing it.
1

Create an IAM user

AWS Console → IAM → Users → Create user.
2

Attach a read-only policy

Attach AmazonEC2ContainerRegistryReadOnly — it grants exactly the ECR read/pull access CybeDefend needs.
3

Create an access key

Security credentials → Create access key → select Application running outside AWS.
4

Copy the credentials into CybeDefend

Copy the Access Key ID and Secret Access Key and paste them into CybeDefend along with the account ID and region.
The Secret Access Key is shown only once in AWS. Copy it immediately before closing the dialog. Static keys are long-lived — rotate them regularly (every 90 days is the AWS recommendation).

​
Organization credentials & project linking

ECR credentials are stored once per organization and then linked to the projects allowed to use them:

Define once

An organization admin adds the credential (IAM role or static keys) a single time, under the organization.

Link to projects

The same credential is linked to one or more projects. Only linked projects can list images and start scans with it.

Rotate in place

Updating the credential (or switching from static keys to an IAM role) rotates it for every linked project at once.

Revoke cleanly

Deleting the credential removes it everywhere; deleting a project only drops that project’s link — the org credential stays.

​
Security best practices

Prefer IAM roles

Cross-account roles avoid sharing any secret and can be revoked instantly by deleting the role or its trust.

Keep the External ID

Never remove the sts:ExternalId condition from the trust policy — it is what scopes the role to your tenant.

Least privilege

Grant only the read-only ECR actions above (or AmazonEC2ContainerRegistryReadOnly for static keys). Write access is never required.

Rotate static keys

If you use static keys, rotate them on a schedule and store them only in AWS — CybeDefend already encrypts them at rest.

​
Troubleshooting

  • Confirm the trust policy’s Principal.AWS matches the trusted principal shown in the setup window.
  • Confirm the sts:ExternalId in the trust policy is exactly the External ID CybeDefend generated. Regenerating the instructions creates a new External ID — update the role’s trust policy if you did.
  • Make sure the role still exists and the region matches your registry.
  • The ARN must look like arn:aws:iam::<12-digit-account>:role/<name>.
  • Verify you copied the role’s ARN (not the user’s or the policy’s) from the role summary page.
  • Verify the Access Key ID and Secret Access Key are correct and still active.
  • Ensure the IAM user has the AmazonEC2ContainerRegistryReadOnly permissions.
  • Pass the image as repository:tag without the registry host — the host is derived from the credential and is prepended automatically.
  • Ensure the credential can ecr:DescribeRepositories / ecr:DescribeImages for that repository.
  • ECR repositories are region-specific. The region on the credential must match the registry that holds your images.
Related: Container Image Scanning · Registry Integrations · ECR API reference