StartExportJobV2

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 AWS Key Management Service (AWS 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 AWS KMS key by adding the bucket policy and key policy statements shown in the Examples section.

Two identities use your AWS 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.

Request Syntax

POST /exportjobsv2 HTTP/1.1
Content-type: application/json

{
   "ClientToken": "string",
   "Destination": { ... },
   "Name": "string",
   "OutputConfiguration": { ... },
   "Scopes": { 
      "AwsOrganizations": [ 
         { 
            "OrganizationalUnitId": "string",
            "OrganizationId": "string"
         }
      ]
   }
}

URI Request Parameters

The request does not use any URI parameters.

Request Body

The request accepts the following data in JSON format.

Response Syntax

HTTP/1.1 202
Content-type: application/json

{
   "ExportJobId": "string"
}

Response Elements

If the action is successful, the service sends back an HTTP 202 response.

The following data is returned in JSON format by the service.

Errors

For information about the errors that are common to all actions, see Common Error Types.

Examples

Example – Grant Security Hub permission to write to your S3 bucket

Before you start an export, attach a policy like the following to the destination Amazon S3 bucket. It allows the Security Hub export service principal (exportv2.securityhub.amazonaws.com) to write export objects to your bucket. The aws:SourceAccount condition key restricts access to export jobs that your own account starts. This protects against the confused deputy problem.

Each permission in the statement is required for the following reasons:

Specify both the bucket ARN and the object ARN in the Resource element. s3:ListBucket acts on the bucket itself and matches only the bucket ARN. The remaining permissions act on objects and match only the ARN that ends with /*.

In the following example, replace amzn-s3-demo-bucket with the name of your destination bucket, and 111122223333 with your AWS account ID.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowSecurityHubExportsWrite",
            "Effect": "Allow",
            "Principal": {
                "Service": "exportv2.securityhub.amazonaws.com"
            },
            "Action": [
                "s3:PutObject",
                "s3:GetObject",
                "s3:AbortMultipartUpload",
                "s3:ListBucket"
            ],
            "Resource": [
                "arn:aws:s3:::amzn-s3-demo-bucket",
                "arn:aws:s3:::amzn-s3-demo-bucket/*"
            ],
            "Condition": {
                "StringEquals": {
                    "aws:SourceAccount": "111122223333"
                }
            }
        }
    ]
}

Example – Grant Security Hub permission to use your KMS key

Add a statement like the following to the key policy of the AWS KMS key that you specify in KmsKeyArn. It allows the Security Hub export service principal to use the key, through Amazon S3 only, to write export objects to your bucket with server-side encryption. In a key policy, a Resource value of * refers to the key that the policy is attached to, not to all keys.

Each permission and condition key in the statement is required for the following reasons:

In the following example, replace aa-example-1 with your AWS Region, 111122223333 with your AWS account ID, and amzn-s3-demo-bucket with the name of your destination bucket.

{
    "Sid": "AllowSecurityHubExportSseKmsWriteViaS3",
    "Effect": "Allow",
    "Principal": {
        "Service": "exportv2.securityhub.amazonaws.com"
    },
    "Action": [
        "kms:GenerateDataKey",
        "kms:Decrypt"
    ],
    "Resource": "*",
    "Condition": {
        "StringEquals": {
            "kms:ViaService": "s3.aa-example-1.amazonaws.com",
            "aws:SourceAccount": "111122223333",
            "kms:EncryptionContext:aws:s3:arn": "arn:aws:s3:::amzn-s3-demo-bucket"
        }
    }
}

Example – Grant the calling principal permission to use your KMS key

Any principal that assigns a customer managed AWS KMS key to an export job must have permission to generate and decrypt data keys for that key. This requirement applies to the StartExportJobV2 operation.

Add a statement like the following to the key policy of the AWS KMS key that you specify in KmsKeyArn.

Each permission and condition key in the statement is required for the following reasons:

In the following example, replace 111122223333 with your AWS account ID, ExportCallerRole with the name of the role that calls StartExportJobV2, and amzn-s3-demo-bucket with the name of your destination bucket.

{
    "Sid": "AllowSecurityHubExportCallerKeyAccess",
    "Effect": "Allow",
    "Principal": {
        "AWS": "arn:aws:iam::111122223333:role/ExportCallerRole"
    },
    "Action": [
        "kms:GenerateDataKey",
        "kms:Decrypt"
    ],
    "Resource": "*",
    "Condition": {
        "StringEquals": {
            "kms:EncryptionContext:aws:s3:arn": "arn:aws:s3:::amzn-s3-demo-bucket"
        }
    }
}

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: