Amazon Inspector 2016-02-16

This page describes the parameters and results for the operations of the
Amazon Inspector (2016-02-16), and shows how to use the Aws\Inspector\InspectorClient
object to call the described operations. This documentation is specific to the
2016-02-16 API version of the service.

Operation Summary

Each of the following operations can be created from a client using
$client->getCommand('CommandName'), where "CommandName" is the
name of one of the following operations. Note: a command is a value that
encapsulates an operation and the parameters used to create an HTTP request.

You can also create and send a command immediately using the magic methods
available on a client object: $client->commandName(/* parameters */).
You can send the command asynchronously (returning a promise) by appending the
word "Async" to the operation name: $client->commandNameAsync(/* parameters */).

Updates the assessment target that is specified by the ARN of the assessment target.

Paginators

Paginators handle automatically iterating over paginated API results. Paginators
are associated with specific API operations, and they accept the parameters
that the corresponding API operation accepts. You can get a paginator from a
client class using
getPaginator($paginatorName, $operationParameters). This client supports
the following paginators:

CreateAssessmentTarget

Creates a new assessment target using the ARN of the resource group that is generated by CreateResourceGroup. If resourceGroupArn is not specified, all EC2 instances in the current AWS account and region are included in the assessment target. If the service-linked role isn’t already registered, this action also creates and registers a service-linked role to grant Amazon Inspector access to AWS Services needed to perform security assessments. You can create up to 50 assessment targets per AWS account. You can run up to 500 concurrent agents per AWS account. For more information, see Amazon Inspector Assessment Targets.

Parameter Syntax

Parameter Details

Members

assessmentTargetName

Type: string

The user-defined name that identifies the assessment target that you want to create. The name must be unique within the AWS account.

resourceGroupArn

Type: string

The ARN that specifies the resource group that is used to create the assessment target. If resourceGroupArn is not specified, all EC2 instances in the current AWS account and region are included in the assessment target.

Result Syntax

[
'assessmentTargetArn' => '<string>',
]

Result Details

Members

assessmentTargetArn

Type: string

The ARN that specifies the assessment target that is created.

Errors

InternalException:

Internal server error.

InvalidInputException:

The request was rejected because an invalid or out-of-range value was supplied for an input parameter.

LimitExceededException:

The request was rejected because it attempted to create resources beyond the current AWS account limits. The error code describes the limit exceeded.

AccessDeniedException:

You do not have required permissions to access the requested resource.

NoSuchEntityException:

The request was rejected because it referenced an entity that does not exist. The error code describes the entity.

InvalidCrossAccountRoleException:

Amazon Inspector cannot assume the cross-account role that it needs to list your EC2 instances during the assessment run.

ServiceTemporarilyUnavailableException:

The serice is temporary unavailable.

Examples

Example 1: Create assessment target

Creates a new assessment target using the ARN of the resource group that is generated by CreateResourceGroup. You can create up to 50 assessment targets per AWS account. You can run up to 500 concurrent agents per AWS account.

CreateAssessmentTemplate

Creates an assessment template for the assessment target that is specified by the ARN of the assessment target. If the service-linked role isn’t already registered, this action also creates and registers a service-linked role to grant Amazon Inspector access to AWS Services needed to perform security assessments.

Parameter Details

Members

assessmentTargetArn

Type: string

The ARN that specifies the assessment target for which you want to create the assessment template.

assessmentTemplateName

Type: string

The user-defined name that identifies the assessment template that you want to create. You can create several assessment templates for an assessment target. The names of the assessment templates that correspond to a particular assessment target must be unique.

durationInSeconds

Type: int

The duration of the assessment run in seconds.

rulesPackageArns

Type: Array of strings

The ARNs that specify the rules packages that you want to attach to the assessment template.

The user-defined attributes that are assigned to every finding that is generated by the assessment run that uses this assessment template. An attribute is a key and value pair (an Attribute object). Within an assessment template, each key must be unique.

Result Syntax

[
'assessmentTemplateArn' => '<string>',
]

Result Details

Members

assessmentTemplateArn

Type: string

The ARN that specifies the assessment template that is created.

Errors

InternalException:

Internal server error.

InvalidInputException:

The request was rejected because an invalid or out-of-range value was supplied for an input parameter.

LimitExceededException:

The request was rejected because it attempted to create resources beyond the current AWS account limits. The error code describes the limit exceeded.

AccessDeniedException:

You do not have required permissions to access the requested resource.

NoSuchEntityException:

The request was rejected because it referenced an entity that does not exist. The error code describes the entity.

ServiceTemporarilyUnavailableException:

The serice is temporary unavailable.

Examples

Example 1: Create assessment template

Creates an assessment template for the assessment target that is specified by the ARN of the assessment target.

CreateExclusionsPreview

Starts the generation of an exclusions preview for the specified assessment template. The exclusions preview lists the potential exclusions (ExclusionPreview) that Inspector can detect before it runs the assessment.

CreateResourceGroup

Creates a resource group using the specified set of tags (key and value pairs) that are used to select the EC2 instances to be included in an Amazon Inspector assessment target. The created resource group is then used to create an Amazon Inspector assessment target. For more information, see CreateAssessmentTarget.

Parameter Details

Members

A collection of keys and an array of possible values, '[{"key":"key1","values":["Value1","Value2"]},{"key":"Key2","values":["Value3"]}]'.

For example,'[{"key":"Name","values":["TestEC2Instance"]}]'.

Result Syntax

[
'resourceGroupArn' => '<string>',
]

Result Details

Members

resourceGroupArn

Type: string

The ARN that specifies the resource group that is created.

Errors

InternalException:

Internal server error.

InvalidInputException:

The request was rejected because an invalid or out-of-range value was supplied for an input parameter.

LimitExceededException:

The request was rejected because it attempted to create resources beyond the current AWS account limits. The error code describes the limit exceeded.

AccessDeniedException:

You do not have required permissions to access the requested resource.

ServiceTemporarilyUnavailableException:

The serice is temporary unavailable.

Examples

Example 1: Create resource group

Creates a resource group using the specified set of tags (key and value pairs) that are used to select the EC2 instances to be included in an Amazon Inspector assessment target. The created resource group is then used to create an Amazon Inspector assessment target.

Result Syntax

Result Details

Members

Specifies the URL where you can find the generated assessment report. This parameter is only returned if the report is successfully generated.

Errors

InternalException:

Internal server error.

InvalidInputException:

The request was rejected because an invalid or out-of-range value was supplied for an input parameter.

AccessDeniedException:

You do not have required permissions to access the requested resource.

NoSuchEntityException:

The request was rejected because it referenced an entity that does not exist. The error code describes the entity.

AssessmentRunInProgressException:

You cannot perform a specified action if an assessment run is currently in progress.

UnsupportedFeatureException:

Used by the GetAssessmentReport API. The request was rejected because you tried to generate a report for an assessment run that existed before reporting was supported in Amazon Inspector. You can only generate reports for assessment runs that took place or will take place after generating reports in Amazon Inspector became available.

Parameter Details

Members

The ARN that specifies the assessment template for which the exclusions preview was requested.

locale

Type: string

The locale into which you want to translate the exclusion's title, description, and recommendation.

maxResults

Type: int

You can use this parameter to indicate the maximum number of items you want in the response. The default value is 100. The maximum value is 500.

nextToken

Type: string

You can use this parameter when paginating results. Set the value of this parameter to null on your first call to the GetExclusionsPreviewRequest action. Subsequent calls to the action fill nextToken in the request with the value of nextToken from the previous response to continue listing data.

Result Details

Members

When a response is generated, if there is more data to be listed, this parameters is present in the response and contains the value to use for the nextToken parameter in a subsequent pagination request. If there is no more data to be listed, this parameter is set to null.

previewStatus

Type: string

Specifies the status of the request to generate an exclusions preview.

Errors

InvalidInputException:

The request was rejected because an invalid or out-of-range value was supplied for an input parameter.

InternalException:

Internal server error.

AccessDeniedException:

You do not have required permissions to access the requested resource.

NoSuchEntityException:

The request was rejected because it referenced an entity that does not exist. The error code describes the entity.

Parameter Details

Members

You can use this parameter to specify a subset of data to be included in the action's response.

For a record to match a filter, all specified filter attributes must match. When multiple values are specified for a filter attribute, any of the values can match.

maxResults

Type: int

You can use this parameter to indicate the maximum number of items that you want in the response. The default value is 10. The maximum value is 500.

nextToken

Type: string

You can use this parameter when paginating results. Set the value of this parameter to null on your first call to the ListAssessmentRunAgents action. Subsequent calls to the action fill nextToken in the request with the value of NextToken from the previous response to continue listing data.

Result Details

Members

When a response is generated, if there is more data to be listed, this parameter is present in the response and contains the value to use for the nextToken parameter in a subsequent pagination request. If there is no more data to be listed, this parameter is set to null.

Errors

InternalException:

Internal server error.

InvalidInputException:

The request was rejected because an invalid or out-of-range value was supplied for an input parameter.

AccessDeniedException:

You do not have required permissions to access the requested resource.

NoSuchEntityException:

The request was rejected because it referenced an entity that does not exist. The error code describes the entity.

Examples

Example 1: List assessment run agents

Lists the agents of the assessment runs that are specified by the ARNs of the assessment runs.

Parameter Details

Members

You can use this parameter to specify a subset of data to be included in the action's response.

For a record to match a filter, all specified filter attributes must match. When multiple values are specified for a filter attribute, any of the values can match.

maxResults

Type: int

You can use this parameter to indicate the maximum number of items that you want in the response. The default value is 10. The maximum value is 500.

nextToken

Type: string

You can use this parameter when paginating results. Set the value of this parameter to null on your first call to the ListAssessmentRuns action. Subsequent calls to the action fill nextToken in the request with the value of NextToken from the previous response to continue listing data.

Result Syntax

Result Details

Members

assessmentRunArns

Type: Array of strings

A list of ARNs that specifies the assessment runs that are returned by the action.

nextToken

Type: string

When a response is generated, if there is more data to be listed, this parameter is present in the response and contains the value to use for the nextToken parameter in a subsequent pagination request. If there is no more data to be listed, this parameter is set to null.

Errors

InternalException:

Internal server error.

InvalidInputException:

The request was rejected because an invalid or out-of-range value was supplied for an input parameter.

AccessDeniedException:

You do not have required permissions to access the requested resource.

NoSuchEntityException:

The request was rejected because it referenced an entity that does not exist. The error code describes the entity.

Examples

Example 1: List assessment runs

Lists the assessment runs that correspond to the assessment templates that are specified by the ARNs of the assessment templates.

Parameter Details

Members

You can use this parameter to specify a subset of data to be included in the action's response.

For a record to match a filter, all specified filter attributes must match. When multiple values are specified for a filter attribute, any of the values can match.

maxResults

Type: int

You can use this parameter to indicate the maximum number of items you want in the response. The default value is 10. The maximum value is 500.

nextToken

Type: string

You can use this parameter when paginating results. Set the value of this parameter to null on your first call to the ListAssessmentTargets action. Subsequent calls to the action fill nextToken in the request with the value of NextToken from the previous response to continue listing data.

Result Syntax

Result Details

Members

assessmentTargetArns

Type: Array of strings

A list of ARNs that specifies the assessment targets that are returned by the action.

nextToken

Type: string

When a response is generated, if there is more data to be listed, this parameter is present in the response and contains the value to use for the nextToken parameter in a subsequent pagination request. If there is no more data to be listed, this parameter is set to null.

Errors

InternalException:

Internal server error.

InvalidInputException:

The request was rejected because an invalid or out-of-range value was supplied for an input parameter.

AccessDeniedException:

You do not have required permissions to access the requested resource.

Parameter Details

Members

You can use this parameter to specify a subset of data to be included in the action's response.

For a record to match a filter, all specified filter attributes must match. When multiple values are specified for a filter attribute, any of the values can match.

maxResults

Type: int

You can use this parameter to indicate the maximum number of items you want in the response. The default value is 10. The maximum value is 500.

nextToken

Type: string

You can use this parameter when paginating results. Set the value of this parameter to null on your first call to the ListAssessmentTemplates action. Subsequent calls to the action fill nextToken in the request with the value of NextToken from the previous response to continue listing data.

Result Syntax

Result Details

Members

assessmentTemplateArns

Type: Array of strings

A list of ARNs that specifies the assessment templates returned by the action.

nextToken

Type: string

When a response is generated, if there is more data to be listed, this parameter is present in the response and contains the value to use for the nextToken parameter in a subsequent pagination request. If there is no more data to be listed, this parameter is set to null.

Errors

InternalException:

Internal server error.

InvalidInputException:

The request was rejected because an invalid or out-of-range value was supplied for an input parameter.

AccessDeniedException:

You do not have required permissions to access the requested resource.

NoSuchEntityException:

The request was rejected because it referenced an entity that does not exist. The error code describes the entity.

Examples

Example 1: List assessment templates

Lists the assessment templates that correspond to the assessment targets that are specified by the ARNs of the assessment targets.

Parameter Syntax

Parameter Details

Members

maxResults

Type: int

You can use this parameter to indicate the maximum number of items you want in the response. The default value is 10. The maximum value is 500.

nextToken

Type: string

You can use this parameter when paginating results. Set the value of this parameter to null on your first call to the ListEventSubscriptions action. Subsequent calls to the action fill nextToken in the request with the value of NextToken from the previous response to continue listing data.

resourceArn

Type: string

The ARN of the assessment template for which you want to list the existing event subscriptions.

Result Details

Members

nextToken

Type: string

When a response is generated, if there is more data to be listed, this parameter is present in the response and contains the value to use for the nextToken parameter in a subsequent pagination request. If there is no more data to be listed, this parameter is set to null.

Parameter Syntax

Parameter Details

Members

The ARN of the assessment run that generated the exclusions that you want to list.

maxResults

Type: int

You can use this parameter to indicate the maximum number of items you want in the response. The default value is 100. The maximum value is 500.

nextToken

Type: string

You can use this parameter when paginating results. Set the value of this parameter to null on your first call to the ListExclusionsRequest action. Subsequent calls to the action fill nextToken in the request with the value of nextToken from the previous response to continue listing data.

Result Syntax

[
'exclusionArns' => ['<string>', ...],
'nextToken' => '<string>',
]

Result Details

Members

exclusionArns

Type: Array of strings

A list of exclusions' ARNs returned by the action.

nextToken

Type: string

When a response is generated, if there is more data to be listed, this parameters is present in the response and contains the value to use for the nextToken parameter in a subsequent pagination request. If there is no more data to be listed, this parameter is set to null.

Errors

InternalException:

Internal server error.

InvalidInputException:

The request was rejected because an invalid or out-of-range value was supplied for an input parameter.

AccessDeniedException:

You do not have required permissions to access the requested resource.

NoSuchEntityException:

The request was rejected because it referenced an entity that does not exist. The error code describes the entity.

Parameter Details

Members

You can use this parameter to specify a subset of data to be included in the action's response.

For a record to match a filter, all specified filter attributes must match. When multiple values are specified for a filter attribute, any of the values can match.

maxResults

Type: int

You can use this parameter to indicate the maximum number of items you want in the response. The default value is 10. The maximum value is 500.

nextToken

Type: string

You can use this parameter when paginating results. Set the value of this parameter to null on your first call to the ListFindings action. Subsequent calls to the action fill nextToken in the request with the value of NextToken from the previous response to continue listing data.

Result Syntax

[
'findingArns' => ['<string>', ...],
'nextToken' => '<string>',
]

Result Details

Members

findingArns

Type: Array of strings

A list of ARNs that specifies the findings returned by the action.

nextToken

Type: string

When a response is generated, if there is more data to be listed, this parameter is present in the response and contains the value to use for the nextToken parameter in a subsequent pagination request. If there is no more data to be listed, this parameter is set to null.

Errors

InternalException:

Internal server error.

InvalidInputException:

The request was rejected because an invalid or out-of-range value was supplied for an input parameter.

AccessDeniedException:

You do not have required permissions to access the requested resource.

NoSuchEntityException:

The request was rejected because it referenced an entity that does not exist. The error code describes the entity.

Examples

Example 1: List findings

Lists findings that are generated by the assessment runs that are specified by the ARNs of the assessment runs.

Parameter Syntax

Parameter Details

Members

maxResults

Type: int

You can use this parameter to indicate the maximum number of items you want in the response. The default value is 10. The maximum value is 500.

nextToken

Type: string

You can use this parameter when paginating results. Set the value of this parameter to null on your first call to the ListRulesPackages action. Subsequent calls to the action fill nextToken in the request with the value of NextToken from the previous response to continue listing data.

Result Syntax

Result Details

Members

nextToken

Type: string

When a response is generated, if there is more data to be listed, this parameter is present in the response and contains the value to use for the nextToken parameter in a subsequent pagination request. If there is no more data to be listed, this parameter is set to null.

rulesPackageArns

Type: Array of strings

The list of ARNs that specifies the rules packages returned by the action.

Errors

InternalException:

Internal server error.

InvalidInputException:

The request was rejected because an invalid or out-of-range value was supplied for an input parameter.

AccessDeniedException:

You do not have required permissions to access the requested resource.

Parameter Syntax

Parameter Details

Members

maxResults

Type: int

You can use this parameter to indicate the maximum number of items you want in the response. The default value is 10. The maximum value is 500.

nextToken

Type: string

You can use this parameter when paginating results. Set the value of this parameter to null on your first call to the PreviewAgents action. Subsequent calls to the action fill nextToken in the request with the value of NextToken from the previous response to continue listing data.

Result Details

Members

When a response is generated, if there is more data to be listed, this parameter is present in the response and contains the value to use for the nextToken parameter in a subsequent pagination request. If there is no more data to be listed, this parameter is set to null.

Errors

InternalException:

Internal server error.

InvalidInputException:

The request was rejected because an invalid or out-of-range value was supplied for an input parameter.

AccessDeniedException:

You do not have required permissions to access the requested resource.

NoSuchEntityException:

The request was rejected because it referenced an entity that does not exist. The error code describes the entity.

InvalidCrossAccountRoleException:

Amazon Inspector cannot assume the cross-account role that it needs to list your EC2 instances during the assessment run.

Examples

Example 1: Preview agents

Previews the agents installed on the EC2 instances that are part of the specified assessment target.

Parameter Syntax

Parameter Details

Members

assessmentRunArn

Type: string

The ARN of the assessment run that you want to stop.

stopAction

Type: string

An input option that can be set to either START_EVALUATION or SKIP_EVALUATION. START_EVALUATION (the default value), stops the AWS agent from collecting data and begins the results evaluation and the findings generation process. SKIP_EVALUATION cancels the assessment run immediately, after which no findings are generated.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InternalException:

Internal server error.

InvalidInputException:

The request was rejected because an invalid or out-of-range value was supplied for an input parameter.

AccessDeniedException:

You do not have required permissions to access the requested resource.

NoSuchEntityException:

The request was rejected because it referenced an entity that does not exist. The error code describes the entity.

ServiceTemporarilyUnavailableException:

The serice is temporary unavailable.

Examples

Example 1: Stop assessment run

Stops the assessment run that is specified by the ARN of the assessment run.

AssessmentRunFilter

Description

Members

For a record to match a filter, the value that is specified for this data type property must inclusively match any value between the specified minimum and maximum values of the completedAt property of the AssessmentRun data type.

For a record to match a filter, the value that is specified for this data type property must inclusively match any value between the specified minimum and maximum values of the durationInSeconds property of the AssessmentRun data type.

namePattern

Type: string

For a record to match a filter, an explicit value or a string containing a wildcard that is specified for this data type property must match the value of the assessmentRunName property of the AssessmentRun data type.

rulesPackageArns

Type: Array of strings

For a record to match a filter, the value that is specified for this data type property must be contained in the list of values of the rulesPackages property of the AssessmentRun data type.

For a record to match a filter, the value that is specified for this data type property must inclusively match any value between the specified minimum and maximum values of the startTime property of the AssessmentRun data type.

AssessmentTargetFilter

Description

Members

assessmentTargetNamePattern

Type: string

For a record to match a filter, an explicit value or a string that contains a wildcard that is specified for this data type property must match the value of the assessmentTargetName property of the AssessmentTarget data type.

AssessmentTemplate

Description

Contains information about an Amazon Inspector assessment template. This data type is used as the response element in the DescribeAssessmentTemplates action.

Members

arn

Type: string

The ARN of the assessment template.

assessmentRunCount

Type: int

The number of existing assessment runs associated with this assessment template. This value can be zero or a positive integer.

assessmentTargetArn

Type: string

The ARN of the assessment target that corresponds to this assessment template.

createdAt

Type: timestamp (string|DateTime or anything parsable by strtotime)

The time at which the assessment template is created.

durationInSeconds

Type: int

The duration in seconds specified for this assessment template. The default value is 3600 seconds (one hour). The maximum value is 86400 seconds (one day).

lastAssessmentRunArn

Type: string

The Amazon Resource Name (ARN) of the most recent assessment run associated with this assessment template. This value exists only when the value of assessmentRunCount is greaterpa than zero.

AssessmentTemplateFilter

Description

Members

For a record to match a filter, the value specified for this data type property must inclusively match any value between the specified minimum and maximum values of the durationInSeconds property of the AssessmentTemplate data type.

namePattern

Type: string

For a record to match a filter, an explicit value or a string that contains a wildcard that is specified for this data type property must match the value of the assessmentTemplateName property of the AssessmentTemplate data type.

rulesPackageArns

Type: Array of strings

For a record to match a filter, the values that are specified for this data type property must be contained in the list of values of the rulesPackageArns property of the AssessmentTemplate data type.

AssetAttributes

Description

A collection of attributes of the host from which the finding is generated.

Members

agentId

Type: string

The ID of the agent that is installed on the EC2 instance where the finding is generated.

amiId

Type: string

The ID of the Amazon Machine Image (AMI) that is installed on the EC2 instance where the finding is generated.

autoScalingGroup

Type: string

The Auto Scaling group of the EC2 instance where the finding is generated.

hostname

Type: string

The hostname of the EC2 instance where the finding is generated.

ipv4Addresses

Type: Array of strings

The list of IP v4 addresses of the EC2 instance where the finding is generated.

InternalException

Description

Members

InvalidCrossAccountRoleException

Description

Amazon Inspector cannot assume the cross-account role that it needs to list your EC2 instances during the assessment run.

Members

canRetry

Type: boolean

You can immediately retry your request.

errorCode

Type: string

Code that indicates the type of error that is generated.

message

Type: string

Details of the exception error.

InvalidInputException

Description

The request was rejected because an invalid or out-of-range value was supplied for an input parameter.

Members

canRetry

Type: boolean

You can immediately retry your request.

errorCode

Type: string

Code that indicates the type of error that is generated.

message

Type: string

Details of the exception error.

LimitExceededException

Description

The request was rejected because it attempted to create resources beyond the current AWS account limits. The error code describes the limit exceeded.

Members

canRetry

Type: boolean

You can immediately retry your request.

errorCode

Type: string

Code that indicates the type of error that is generated.

message

Type: string

Details of the exception error.

NoSuchEntityException

Description

The request was rejected because it referenced an entity that does not exist. The error code describes the entity.

Members

canRetry

Type: boolean

You can immediately retry your request.

errorCode

Type: string

Code that indicates the type of error that is generated.

message

Type: string

Details of the exception error.

PreviewGenerationInProgressException

Description

The request is rejected. The specified assessment template is currently generating an exclusions preview.

Members

message

Type: string

ResourceGroup

Description

Contains information about a resource group. The resource group defines a set of tags that, when queried, identify the AWS resources that make up the assessment target. This data type is used as the response element in the DescribeResourceGroups action.

UnsupportedFeatureException

Description

Used by the GetAssessmentReport API. The request was rejected because you tried to generate a report for an assessment run that existed before reporting was supported in Amazon Inspector. You can only generate reports for assessment runs that took place or will take place after generating reports in Amazon Inspector became available.