Validate saved query results with the Amazon CLI - Amazon CloudTrail
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Validate saved query results with the Amazon CLI

You can validate the integrity of the query result files and sign file by using the aws cloudtrail verify-query-results command.

Prerequisites

To validate query results integrity with the command line, the following conditions must be met:

  • You must have online connectivity to Amazon.

  • You must use Amazon CLI version 2.

  • To validate query result files and sign file locally, the following conditions apply:

    • You must put the query result files and sign file in the specified file path. Specify the file path as the value for the --local-export-path parameter.

    • You must not rename the query result files and sign file.

  • To validate the query result files and sign file in the S3 bucket, the following conditions apply:

    • You must not rename the query result files and sign file.

    • You must have read access to the Amazon S3 bucket that contains the query result files and sign file.

    • The specified S3 prefix must contain the query result files and sign file. Specify the S3 prefix as the value for the --s3-prefix parameter.

verify-query-results

The verify-query-results command verifies the hash value of each query result file by comparing the value with the fileHashValue in the sign file, and then validating the hashSignature in the sign file.

When you verify query results, you can use either the --s3-bucket and --s3-prefix command line options to validate the query result files and sign file stored in an S3 bucket, or you can use the --local-export-path command line option to perform a local validation of the downloaded query result files and sign file.

Note

The verify-query-results command is Region specific. You must specify the --region global option to validate query results for a specific Amazon Web Services Region.

The following are the options for the verify-query-results command.

--s3-bucket <string>

Specifies the S3 bucket name that stores the query result files and sign file. You cannot use this parameter with --local-export-path.

--s3-prefix <string>

Specifies the S3 path of the S3 folder that contains the query result files and sign file (for example, s3/path/). You cannot use this parameter with --local-export-path. You do not need to provide this parameter if the files are located in the root directory of the S3 bucket.

--local-export-path <string>

Specifies the local directory that contains the query result files and sign file (for example, /local/path/to/export/file/). You cannot use this parameter with --s3-bucket or --s3-prefix.

Examples

The following example validates query results using the --s3-bucket and --s3-prefix command line options to specify the S3 bucket name and prefix containing the query result files and sign file.

aws cloudtrail verify-query-results --s3-bucket bucket_name --s3-prefix prefix --region region

The following example validates downloaded query results using the --local-export-path command line option to specify the local path for the query result files and sign file. For more information about downloading query result files, see Download your CloudTrail Lake saved query results.

aws cloudtrail verify-query-results --local-export-path local_file_path --region region

Validation results

The following table describes the possible validation messages for query result files and sign file.

File Type Validation Message Description
Sign file Successfully validated sign and query result files The sign file signature is valid. The query result files it references can be checked.
Query result file

ValidationError: "File file_name has inconsistent hash value with hash value recorded in sign file, hash value in sign file is expected_hash, but get computed_hash

Validation failed because the hash value for the query result file did not match the fileHashValue in the sign file.
Sign file

ValidationError: Invalid signature in sign file

Validation for the sign file failed because the signature is not valid.