AWS Tools for Windows PowerShell
Command Reference

AWS services or capabilities described in AWS Documentation may vary by region/location. Click Getting Started with Amazon AWS to see specific differences applicable to the China (Beijing) Region.

Synopsis

Calls the AWS Security Hub StartExportJobV2 API operation.

Syntax

Start-SHUBExportJobV2
-Name <String>
-Scopes_AwsOrganization <AwsOrganizationScope[]>
-Destination_S3_BucketArn <String>
-OutputConfiguration_Findings_Filters_CompositeFilter <CompositeFilter[]>
-OutputConfiguration_Findings_Filters_CompositeOperator <AllowedOperators>
-OutputConfiguration_Findings_Format <FindingsExportFormat>
-Destination_S3_KmsKeyArn <String>
-Destination_S3_ObjectPrefix <String>
-OutputConfiguration_Findings_SelectedField <String[]>
-ClientToken <String>
-Select <String>
-Force <SwitchParameter>
-ClientConfig <AmazonSecurityHubConfig>

Description

Starts an ad hoc export job that writes Security Hub findings to an Amazon Simple Storage Service (Amazon S3) bucket that you own. Because the export runs asynchronously, this operation returns only the ExportJobId of the new job; it doesn't wait for the export to finish. Use GetExportJobV2 to poll the job, and ListExportJobsV2 to view the export jobs in your account. Security Hub allows only one export job in the RUNNING state per account at a time. If an export job is already running, this operation returns a ServiceQuotaExceededException. Wait for the running job to finish, or cancel it with CancelExportJobV2, before you start a new one. Specify the destination bucket and Amazon Web Services Key Management Service (Amazon Web Services KMS) key in the Destination parameter, and the output format (CSV or OCSF_JSON), optional filters, and field selection in the OutputConfiguration parameter. Before you call this operation, you must grant Security Hub permission to write to your bucket and use your Amazon Web Services KMS key by adding the bucket policy and key policy statements shown in the Examples section. Two identities use your Amazon Web Services KMS key, and each needs its own permission. Security Hub uses the key when it writes the export objects to your bucket. The IAM principal that calls StartExportJobV2 must also have kms:GenerateDataKey and kms:Decrypt permissions on the key. The Examples section shows both grants. A delegated administrator can use the optional Scopes parameter to export findings for specific organizations or organizational units (OUs). To make the request idempotent, provide a ClientToken. If you retry a StartExportJobV2 request with the same ClientToken and the same request parameters, Security Hub returns the ExportJobId of the original job instead of starting a new one. If you reuse a ClientToken with different request parameters, this operation returns a ConflictException.

Parameters

-ClientConfig <AmazonSecurityHubConfig>
Amazon.PowerShell.Cmdlets.SHUB.AmazonSecurityHubClientCmdlet.ClientConfig
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-ClientToken <String>
A unique identifier used to ensure idempotency.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-Destination_S3_BucketArn <String>
The Amazon Resource Name (ARN) of the Amazon S3 bucket that Security Hub writes the export to. You must own the bucket, and its bucket policy must grant the Security Hub service principal (exportv2.securityhub.amazonaws.com) permission to write objects. For the required bucket policy, see the Examples section of StartExportJobV2.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-Destination_S3_KmsKeyArn <String>
The ARN of the Amazon Web Services KMS key that Security Hub uses to encrypt the export objects with server-side encryption. The key policy must allow the Security Hub service principal (exportv2.securityhub.amazonaws.com) to use the key through Amazon S3. For the required key policy, see the Examples section of StartExportJobV2.The key must meet all of the following requirements:
  • It must be a symmetric key with a key usage of ENCRYPT_DECRYPT.
  • It must be a single-Region key. Multi-Region keys, whose key IDs begin with mrk-, are rejected.
  • You must specify the full key ARN. Key IDs and aliases are rejected.
  • The key must be in the same Amazon Web Services account as the export job.
  • The key must be in the same Amazon Web Services Region as the export job.
  • The key must be in the aws, aws-cn, or aws-us-gov partition.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-Destination_S3_ObjectPrefix <String>
An optional key prefix that Security Hub prepends to the Amazon S3 object keys of the export output. Use a prefix to organize exports within the bucket. The value can be up to 512 characters.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-Force <SwitchParameter>
This parameter overrides confirmation prompts to force the cmdlet to continue its operation. This parameter should always be used with caution.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-Name <String>
An optional, user-provided name for the export job that helps you identify it in ListExportJobsV2 results. The value can be 1–256 characters. Alphanumeric characters, spaces, and the following ASCII characters are permitted: . _ , : ( ) / + -.
Required?False
Position?1
Accept pipeline input?True (ByValue, ByPropertyName)
-OutputConfiguration_Findings_Filters_CompositeFilter <CompositeFilter[]>
Enables the creation of complex filtering conditions by combining filter criteria. Starting with version 4 of the SDK this property will default to null. If no data for this property is returned from the service the property will also be null. This was changed to improve performance and allow the SDK and caller to distinguish between a property not set or a property being empty to clear out a value. To retain the previous SDK behavior set the AWSConfigs.InitializeCollections static property to true.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesOutputConfiguration_Findings_Filters_CompositeFilters
-OutputConfiguration_Findings_Filters_CompositeOperator <AllowedOperators>
The logical operators used to combine the filtering on multiple CompositeFilters.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-OutputConfiguration_Findings_Format <FindingsExportFormat>
The output format of the export. CSV produces comma-separated rows that are suitable for spreadsheets and analysis tools. OCSF_JSON produces newline-delimited JSON records in the Open Cybersecurity Schema Framework (OCSF) format used elsewhere in Security Hub.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-OutputConfiguration_Findings_SelectedField <String[]>
The OCSF finding fields to include in the export, specified as OCSF field paths (for example, finding_info.title or severity). You can specify from 1 to 50 fields.Whether this parameter is required depends on the value of Format:
  • CSV – Required. The field paths that you specify become the columns of the output, in the order that you provide them. If you omit this parameter, the request returns a ValidationException.
  • OCSF_JSON – Not supported. This format includes each finding in full, so field selection doesn't apply. If you specify this parameter, the request returns a ValidationException.
Starting with version 4 of the SDK this property will default to null. If no data for this property is returned from the service the property will also be null. This was changed to improve performance and allow the SDK and caller to distinguish between a property not set or a property being empty to clear out a value. To retain the previous SDK behavior set the AWSConfigs.InitializeCollections static property to true.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesOutputConfiguration_Findings_SelectedFields
-Scopes_AwsOrganization <AwsOrganizationScope[]>
A list of Organizations scopes to include in the export. Each entry in the list specifies an organization or organizational unit to include for the delegated administrator's account. If the list specifies multiple entries, the entries are combined using OR logic. Starting with version 4 of the SDK this property will default to null. If no data for this property is returned from the service the property will also be null. This was changed to improve performance and allow the SDK and caller to distinguish between a property not set or a property being empty to clear out a value. To retain the previous SDK behavior set the AWSConfigs.InitializeCollections static property to true.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesScopes_AwsOrganizations
-Select <String>
Use the -Select parameter to control the cmdlet output. The default value is 'ExportJobId'. Specifying -Select '*' will result in the cmdlet returning the whole service response (Amazon.SecurityHub.Model.StartExportJobV2Response). Specifying the name of a property of type Amazon.SecurityHub.Model.StartExportJobV2Response will result in that property being returned. Specifying -Select '^ParameterName' will result in the cmdlet returning the selected cmdlet parameter value.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)

Common Credential and Region Parameters

-AccessKey <String>
The AWS access key for the user account. This can be a temporary access key if the corresponding session token is supplied to the -SessionToken parameter.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesAK
-Credential <AWSCredentials>
An AWSCredentials object instance containing access and secret key information, and optionally a token for session-based credentials.
Required?False
Position?Named
Accept pipeline input?True (ByValue, ByPropertyName)
-EndpointUrl <String>
The endpoint to make the call against.Note: This parameter is primarily for internal AWS use and is not required/should not be specified for normal usage. The cmdlets normally determine which endpoint to call based on the region specified to the -Region parameter or set as default in the shell (via Set-DefaultAWSRegion). Only specify this parameter if you must direct the call to a specific custom endpoint.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-NetworkCredential <PSCredential>
Used with SAML-based authentication when ProfileName references a SAML role profile. Contains the network credentials to be supplied during authentication with the configured identity provider's endpoint. This parameter is not required if the user's default network identity can or should be used during authentication.
Required?False
Position?Named
Accept pipeline input?True (ByValue, ByPropertyName)
-ProfileLocation <String>
Used to specify the name and location of the ini-format credential file (shared with the AWS CLI and other AWS SDKs)If this optional parameter is omitted this cmdlet will search the encrypted credential file used by the AWS SDK for .NET and AWS Toolkit for Visual Studio first. If the profile is not found then the cmdlet will search in the ini-format credential file at the default location: (user's home directory)\.aws\credentials.If this parameter is specified then this cmdlet will only search the ini-format credential file at the location given.As the current folder can vary in a shell or during script execution it is advised that you use specify a fully qualified path instead of a relative path.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesAWSProfilesLocation, ProfilesLocation
-ProfileName <String>
The user-defined name of an AWS credentials or SAML-based role profile containing credential information. The profile is expected to be found in the secure credential file shared with the AWS SDK for .NET and AWS Toolkit for Visual Studio. You can also specify the name of a profile stored in the .ini-format credential file used with the AWS CLI and other AWS SDKs.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesStoredCredentials, AWSProfileName
-Region <Object>
The system name of an AWS region or an AWSRegion instance. This governs the endpoint that will be used when calling service operations. Note that the AWS resources referenced in a call are usually region-specific.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesRegionToCall
-SecretKey <String>
The AWS secret key for the user account. This can be a temporary secret key if the corresponding session token is supplied to the -SessionToken parameter.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesSK, SecretAccessKey
-SessionToken <String>
The session token if the access and secret keys are temporary session-based credentials.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesST

Outputs

System.String or Amazon.SecurityHub.Model.StartExportJobV2Response
This cmdlet returns a System.String object. The service call response (type Amazon.SecurityHub.Model.StartExportJobV2Response) can be returned by specifying '-Select *'.
Service API Reference
User Guide
AWS Tools for PowerShell User Guide

Supported Version

AWS Tools for PowerShell: 2.x.y.z