StartImageScanCommand

Suggest an Edit

Starts a basic image vulnerability scan.

A basic image scan can only be started once per 24 hours on an individual image. This limit includes if an image was scanned on initial push. You can start up to 100,000 basic scans per 24 hours. This limit includes both scans on initial push and scans initiated by the StartImageScan API. For more information, see Basic scanning  in the Amazon Elastic Container Registry User Guide.

Example Syntax

Use a bare-bones client and the command you need to make an API call.

import { ECRClient, StartImageScanCommand } from "@aws-sdk/client-ecr"; // ES Modules import
// const { ECRClient, StartImageScanCommand } = require("@aws-sdk/client-ecr"); // CommonJS import
const client = new ECRClient(config);
const input = { // StartImageScanRequest
  registryId: "STRING_VALUE",
  repositoryName: "STRING_VALUE", // required
  imageId: { // ImageIdentifier
    imageDigest: "STRING_VALUE",
    imageTag: "STRING_VALUE",
  },
};
const command = new StartImageScanCommand(input);
const response = await client.send(command);
// { // StartImageScanResponse
//   registryId: "STRING_VALUE",
//   repositoryName: "STRING_VALUE",
//   imageId: { // ImageIdentifier
//     imageDigest: "STRING_VALUE",
//     imageTag: "STRING_VALUE",
//   },
//   imageScanStatus: { // ImageScanStatus
//     status: "IN_PROGRESS" || "COMPLETE" || "FAILED" || "UNSUPPORTED_IMAGE" || "ACTIVE" || "PENDING" || "SCAN_ELIGIBILITY_EXPIRED" || "FINDINGS_UNAVAILABLE" || "LIMIT_EXCEEDED",
//     description: "STRING_VALUE",
//   },
// };

StartImageScanCommand Input

See StartImageScanCommandInput for more details

Parameter
Type
Description
imageId
Required
ImageIdentifier | undefined

An object with identifying information for an image in an Amazon ECR repository.

repositoryName
Required
string | undefined

The name of the repository that contains the images to scan.

registryId
string | undefined

The Amazon Web Services account ID associated with the registry that contains the repository in which to start an image scan request. If you do not specify a registry, the default registry is assumed.

StartImageScanCommand Output

See StartImageScanCommandOutput for details

Parameter
Type
Description
$metadata
Required
ResponseMetadata
Metadata pertaining to this request.
imageId
ImageIdentifier | undefined

An object with identifying information for an image in an Amazon ECR repository.

imageScanStatus
ImageScanStatus | undefined

The current state of the scan.

registryId
string | undefined

The registry ID associated with the request.

repositoryName
string | undefined

The repository name associated with the request.

Throws

Name
Fault
Details
ImageNotFoundException
client

The image requested does not exist in the specified repository.

InvalidParameterException
client

The specified parameter is invalid. Review the available parameters for the API request.

LimitExceededException
client

The operation did not succeed because it would have exceeded a service limit for your account. For more information, see Amazon ECR service quotas  in the Amazon Elastic Container Registry User Guide.

RepositoryNotFoundException
client

The specified repository could not be found. Check the spelling of the specified repository and ensure that you are performing operations on the correct registry.

ServerException
server

These errors are usually caused by a server-side issue.

UnsupportedImageTypeException
client

The image is of a type that cannot be scanned.

ValidationException
client

There was an exception validating this request.

ECRServiceException
Base exception class for all service exceptions from ECR service.