AWS Elastic Container Registry ExecModule

Overview

AwsEcrModule brings bounded Amazon Elastic Container Registry discovery, image inventory, aggregate vulnerability scan state, and carefully confirmed registry controls into ValkyrAI workflows. Platform, release, and security workflows can reconcile the repository and image they intend to use, require immutable tags and scan-on-push, start one exact scan, remove reviewed stale images, or retire one exact repository without exposing ECR authorization tokens, image manifests, layer download URLs, repository policies, lifecycle policy bodies, signing configuration, or arbitrary provider requests.

The connector implements eleven operations:

• list_repositories and get_repository discover repositories and read one exact repository's identity and security settings.
• create_repository creates one exact repository with an explicit encryption, scan-on-push, and tag-mutability posture.
• delete_repository deletes one exact repository after confirmation, with an explicit force choice.
• list_images discovers bounded image digest/tag identifiers.
• describe_images reads bounded image metadata for all images or up to 100 exact identifiers.
• describe_scan_findings reads aggregate severity counts and scan timing for one exact image without returning vulnerability descriptions.
• start_image_scan requests a scan for one exact image after confirmation.
• update_scan_on_push and update_tag_mutability change one exact repository security setting after confirmation.
• delete_images deletes one to 100 exact digest or tag identifiers after confirmation.

n8n's reusable AWS credential plus resource/operation/action workflow pattern is the functional reference. ValkyrAI follows its native IntegrationAccount contract and adds strict operation-specific allowlists, bounded identifiers and pagination, raw-credential rejection, confidential normalized output, read-only retry, and single-attempt mutations that must be reconciled before replay.

Usage

1. Identify the AWS registry, region, repository, and exact image digests or tags the workflow may inspect or change.
2. Create a least-privilege AWS principal with only the ECR actions and repository resources the reviewed workflow requires.
3. Store the access key ID and secret access key in an AWS IntegrationAccount; verify it and keep it in READY status.
4. Add AwsEcrModule and bind the account through ExecModuleConfig.authConfig.integrationAccount.
5. Use get_repository, list_images, and describe_images to reconcile the exact repository and immutable digest before a deployment decision.
6. Use describe_scan_findings to read the authoritative aggregate scan state. Do not infer scan completion from image metadata alone.
7. Set the relevant confirmation flag only after the exact target and requested mutation have been reviewed.
8. Persist the AWS request ID and returned resource identity, then use a read operation to reconcile final state.

Never put access keys, secret keys, session tokens, authorization tokens, credential objects, repository policies, lifecycle policies, registry policies, image manifests, layer content, Docker credentials, or arbitrary provider request fields in module input. Raw credential-shaped fields and every undocumented override fail before network access. Repository names, image digests and tags, registry IDs, scan counts, timestamps, request IDs, and repository URIs are confidential workflow data.

Inputs

Name	Type	Required for	Default	Constraints
operation	string	Every execution	None	One of the eleven documented operations.
region	string	Every execution	None	Valid AWS region such as us-west-2.
registryId	string	Optional read/control scope	Current account	Exactly 12 digits. Not accepted for create_repository, which creates in the caller's registry.
repositoryName	string	Exact repository/image operations	None	Lowercase ECR name, 1-256 characters, with bounded /, ., _, and - separators.
nextToken	string	Optional list field	None	Opaque provider token, at most 4,096 characters.
limit	integer	List operations	100	Total result bound from 1 through 1,000.
returnAll	boolean	List operations	false	Follow pages until limit, provider exhaustion, or 100 pages.
imageDigest	string	Optional exact-image shorthand	None	Exact sha256: digest with 64 hexadecimal characters.
imageTag	string	Optional exact-image shorthand	None	One valid tag of at most 128 characters.
imageIds	array	Optional describe_images; required delete_images unless shorthand is used	None	One to 100 objects, each with exactly one imageDigest or imageTag.
tagStatus	string	list_images, unscoped describe_images	ANY	ANY, TAGGED, or UNTAGGED.
scanOnPush	boolean	Create or scan-setting update	true	Exact desired repository setting.
tagMutability	string	Create or mutability update	IMMUTABLE	MUTABLE or IMMUTABLE.
encryptionType	string	create_repository	AES256	AES256 or KMS.
kmsKey	string	KMS-encrypted create	None	Required for KMS; forbidden for AES256; bounded to 2,048 characters.
force	boolean	Optional repository delete field	false	When true, asks ECR to delete a non-empty repository.
confirmCreateRepository	boolean	create_repository	false	Must be exactly true.
confirmDeleteRepository	boolean	delete_repository	false	Must be exactly true.
confirmStartScan	boolean	start_image_scan	false	Must be exactly true.
confirmUpdate	boolean	Repository setting updates	false	Must be exactly true.
confirmDeleteImages	boolean	delete_images	false	Must be exactly true.

For an image identifier, provide a digest or a tag, never both. describe_scan_findings and start_image_scan require exactly one image identifier. delete_images accepts up to 100 unique identifiers. Unexpected fields fail before provider access, preventing hidden policy, lifecycle, signing, replication, tag-exclusion, registry, manifest, token, and layer mutations.

Outputs

Every call returns stable status, operation, and attempts fields.

Name	Type	When present	Description
status	string	Always	success or error.
operation	string	Always	Normalized operation.
attempts	integer	Always	Provider calls including pages and retry-safe reads.
resultType	string	Success	Repository, image, scan, or control family.
items	array	List success	Bounded normalized repositories, image identifiers, or image details.
count	integer	List success	Number of returned items.
pages	integer	List success	Provider pages consumed.
hasMore	boolean	List success	Whether ECR returned another token.
nextToken	string	Another page exists	Opaque continuation token.
data	object	Exact read or control success	Normalized repository, scan summary, or mutation receipt.
requestId	string	AWS supplies one	Bounded provider reference for reconciliation.
error	object	Failure	Safe {code, message, httpStatus?, retryable} details.

Repository output includes identity, ARN, URI, creation time, tag mutability, scan-on-push, and encryption configuration. KMS key identity is returned as confidential configuration, not key material. Image output includes bounded registry/repository identity, digest, tags, compressed size, push/pull timing, and media types. It never returns an authorization token, image manifest, layer URL, layer bytes, repository policy, lifecycle policy, scan vulnerability descriptions, or provider error text.

describe_scan_findings returns the exact image identifier, scan status and bounded description, scan timing, aggregate counts by severity, and whether ECR indicated additional finding pages. Individual finding titles, package paths, descriptions, CVE details, reference URLs, source metadata, and remediation text are deliberately excluded from this first release.

IntegrationAccount Requirements

Bind one AWS IntegrationAccount through the normalized ExecModule authentication relationship:

Field	Requirement
Provider	Amazon Web Services / ECR
status	Must be READY.
verified	Must be true.
apiKey SecureField	AWS access key ID.
password SecureField	AWS secret access key.

Grant only actions used by the reviewed workflow:

• Repository discovery: ecr:DescribeRepositories.
• Image inventory and metadata: ecr:ListImages and ecr:DescribeImages.
• Scan state: ecr:DescribeImageScanFindings and, only when required, ecr:StartImageScan.
• Creation and security settings: ecr:CreateRepository, ecr:PutImageScanningConfiguration, and ecr:PutImageTagMutability only for approved repositories.
• Cleanup: ecr:BatchDeleteImage and/or ecr:DeleteRepository only for explicitly governed resources.
• KMS: allow the exact ECR/KMS actions required by the chosen customer-managed key when creating KMS-encrypted repositories.

Use repository resource constraints, AWS resource tags, permissions boundaries, organization service-control policies, separate read/control accounts, and KMS key policy to reduce blast radius. Prefer a read-only account unless creation, configuration change, scan initiation, image deletion, or repository deletion is an explicit workflow requirement. ecr:GetAuthorizationToken is neither required nor called by this module.

Configuration

The awsAccount relationship is the only credential configuration. Operation, exact resource identity, pagination, security settings, image identifiers, and confirmations belong in mapped input or module parameters.

{
  "version": "1.0.0",
  "authConfig": {
    "authStrategy": 1,
    "integrationAccount": "integration-account:aws-ecr-release"
  },
  "payloadConfig": {
    "parameters": "{\"operation\":\"describe_images\",\"region\":\"us-west-2\"}"
  }
}

The relationship value is illustrative. Persisted workflows bind the generated IntegrationAccount relationship, never plaintext credentials.

Operations

Operation	Provider behavior	Side effect and retry behavior
list_repositories	Lists bounded repositories in the selected registry.	Read-only; each page retries transient failures.
get_repository	Reads one exact repository's identity and security settings.	Read-only; bounded retry.
create_repository	Creates one repository with exact encryption, scan-on-push, and mutability settings.	Confirmed external mutation; exactly one attempt.
delete_repository	Deletes one exact repository; force controls non-empty deletion.	Confirmed destructive mutation; exactly one attempt.
list_images	Lists bounded digest/tag identifiers, optionally filtered by tag state.	Read-only; each page retries transient failures.
describe_images	Reads bounded image metadata for all images or exact identifiers.	Read-only; each page retries when pagination applies.
describe_scan_findings	Reads aggregate severity counts and scan timing for one image.	Read-only; bounded retry.
start_image_scan	Requests a new basic scan for one exact image.	Confirmed billable/provider-limited mutation; exactly one attempt.
update_scan_on_push	Changes the repository's scan-on-push setting.	Confirmed security-setting mutation; exactly one attempt.
update_tag_mutability	Changes repository tags between mutable and immutable.	Confirmed supply-chain setting mutation; exactly one attempt.
delete_images	Deletes one to 100 exact image identifiers.	Confirmed destructive mutation; exactly one attempt.

Errors and Failure Modes

Code	Typical cause	Retryable	Resolution
VALIDATION_ERROR	Missing/malformed region, registry, repository, image, bound, setting, or confirmation; ambiguous image identifier; or undocumented override.	No	Correct the named input; no AWS request was sent.
UNSUPPORTED_OPERATION	Unknown operation.	No	Select a documented operation.
INTEGRATION_ACCOUNT_ERROR	Account missing, unverified, not READY, or missing key material.	No	Repair and bind the AWS account.
AWS_ECR_HTTP_400	Invalid resource, incompatible setting, unsupported image state, scan state, or provider request.	Usually no	Read the exact repository and image before deciding.
AWS_ECR_HTTP_403	IAM, SCP, KMS, repository, tag, or resource policy denied the request.	No	Grant only the missing action or revise the governed workflow.
AWS_ECR_HTTP_404	Exact repository or image does not exist in the selected registry and region.	No	Reconcile region, registry, repository, digest, and tag.
AWS_ECR_HTTP_409	Repository or image state conflicts with the requested mutation.	No	Read current state and choose whether the action remains appropriate.
AWS_ECR_HTTP_429 / 500 / 503	Throttle or transient provider pressure.	Reads retry; writes remain single-attempt	Reconcile registry state before mutation replay.
NETWORK_ERROR	DNS, TLS, timeout, or connectivity failure.	Reads retry; writes report ambiguity	Treat mutation acceptance as unknown until state is read.
EXECUTION_ERROR	Unexpected bounded runtime failure.	No automatic replay	Preserve operation and request evidence for investigation.

Provider exception messages are never copied into workflow output. This prevents credentials, repository policy data, image identity, KMS configuration, registry topology, and provider state from leaking through failures.

Example

Read one release image by immutable digest:

{
  "operation": "describe_images",
  "region": "us-west-2",
  "registryId": "012345678910",
  "repositoryName": "valkyrai/app",
  "imageDigest": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
}

Expected result shape:

{
  "status": "success",
  "operation": "describe_images",
  "attempts": 1,
  "resultType": "images",
  "items": [
    {
      "registryId": "012345678910",
      "repositoryName": "valkyrai/app",
      "imageDigest": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
      "imageTags": ["release-2026-10-23"],
      "imageSizeBytes": 184320000,
      "pushedAt": "2026-10-23T02:00:00Z"
    }
  ],
  "count": 1,
  "pages": 1,
  "hasMore": false,
  "requestId": "aws-request-reference"
}

Use the exact digest with describe_scan_findings. Continue only after the returned scan state and aggregate severity counts meet the workflow's separately reviewed release policy. Image existence or a successful scan request does not prove that the image is safe, signed, deployable, or currently used by a service.

Notes

• Pagination: repository and image list operations accept an opaque nextToken; all loops stop at limit, provider exhaustion, or 100 pages. Exact imageIds requests are sent as one bounded batch and are not paginated.
• Rate limits: AWS SDK internal retries are disabled. ValkyrAI applies bounded backoff only to reads and honors ExecModule retry attempts from 1 through 5.
• Idempotency: reads are retry-safe. Create, delete, update, start-scan, and batch-delete operations are issued exactly once. Preserve the exact target and request ID, then reconcile before any manual replay.
• API limits: imageIds is capped at 100. The module's total list limit is capped at 1,000 and its page loop at 100 even when ECR has more results.
• Eventual consistency: newly created repositories, setting changes, scans, and deletions may not appear uniformly at once. A successful mutation response proves provider acceptance, not every downstream registry or deployment observation.
• Image identity: mutable tags can move. Production release workflows should resolve and persist an immutable digest, set IMMUTABLE where appropriate, and compare the deployed digest rather than trust a tag alone.
• Scanning: Amazon ECR scanning modes and quotas vary. describe_scan_findings is authoritative for the supported aggregate scan result; describe_images deliberately does not infer current scan findings.
• Destructive behavior: delete_images can remove tags or manifests depending on the identifier and registry state. delete_repository with force: true can remove every image in the repository. Both require explicit confirmation and remain single-attempt.
• Encryption: ECR repository encryption configuration is chosen at creation. KMS behavior depends on key policy and AWS service permissions; the module validates bounded syntax but AWS remains authoritative.
• Secret safety: the module never calls GetAuthorizationToken, never outputs Docker credentials, and does not accept image manifests, layer bytes, repository policies, lifecycle policies, signing configuration, or arbitrary provider payloads.
• Deferred scope: authorization-token retrieval, Docker push/pull, manifest upload/download, layer transfer, repository/lifecycle/registry policy management, replication, pull-through cache, signing, resource tags, enhanced finding details, scan configuration at registry scope, tag-mutability exclusion filters, and waiters are intentionally excluded.
• External verification: repository tests use a deterministic transport and make no AWS call. Provider behavior requires a separately authorized least-privilege AWS account plus reviewed registry, repository, image, KMS, and mutation scope.