Skip to content

Commit f857066

Browse files
author
awstools
committed
feat(client-cloudtrail): AWS CloudTrail now supports Insights for data events, expanding beyond management events to automatically detect unusual activity on data plane operations.
1 parent c754b24 commit f857066

18 files changed

+842
-157
lines changed

‎clients/client-cloudtrail/README.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -482,6 +482,14 @@ ListImports
482482

483483
[Command API Reference](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/cloudtrail/command/ListImportsCommand/) / [Input](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-cloudtrail/Interface/ListImportsCommandInput/) / [Output](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-cloudtrail/Interface/ListImportsCommandOutput/)
484484

485+
</details>
486+
<details>
487+
<summary>
488+
ListInsightsData
489+
</summary>
490+
491+
[Command API Reference](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/cloudtrail/command/ListInsightsDataCommand/) / [Input](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-cloudtrail/Interface/ListInsightsDataCommandInput/) / [Output](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-cloudtrail/Interface/ListInsightsDataCommandOutput/)
492+
485493
</details>
486494
<details>
487495
<summary>

‎clients/client-cloudtrail/src/CloudTrail.ts‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -136,6 +136,11 @@ import {
136136
ListImportFailuresCommandOutput,
137137
} from "./commands/ListImportFailuresCommand";
138138
import { ListImportsCommand, ListImportsCommandInput, ListImportsCommandOutput } from "./commands/ListImportsCommand";
139+
import {
140+
ListInsightsDataCommand,
141+
ListInsightsDataCommandInput,
142+
ListInsightsDataCommandOutput,
143+
} from "./commands/ListInsightsDataCommand";
139144
import {
140145
ListInsightsMetricDataCommand,
141146
ListInsightsMetricDataCommandInput,
@@ -265,6 +270,7 @@ const commands = {
265270
ListEventDataStoresCommand,
266271
ListImportFailuresCommand,
267272
ListImportsCommand,
273+
ListInsightsDataCommand,
268274
ListInsightsMetricDataCommand,
269275
ListPublicKeysCommand,
270276
ListQueriesCommand,
@@ -761,6 +767,23 @@ export interface CloudTrail {
761767
cb: (err: any, data?: ListImportsCommandOutput) => void
762768
): void;
763769

770+
/**
771+
* @see {@link ListInsightsDataCommand}
772+
*/
773+
listInsightsData(
774+
args: ListInsightsDataCommandInput,
775+
options?: __HttpHandlerOptions
776+
): Promise<ListInsightsDataCommandOutput>;
777+
listInsightsData(
778+
args: ListInsightsDataCommandInput,
779+
cb: (err: any, data?: ListInsightsDataCommandOutput) => void
780+
): void;
781+
listInsightsData(
782+
args: ListInsightsDataCommandInput,
783+
options: __HttpHandlerOptions,
784+
cb: (err: any, data?: ListInsightsDataCommandOutput) => void
785+
): void;
786+
764787
/**
765788
* @see {@link ListInsightsMetricDataCommand}
766789
*/

‎clients/client-cloudtrail/src/CloudTrailClient.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -111,6 +111,7 @@ import {
111111
} from "./commands/ListEventDataStoresCommand";
112112
import { ListImportFailuresCommandInput, ListImportFailuresCommandOutput } from "./commands/ListImportFailuresCommand";
113113
import { ListImportsCommandInput, ListImportsCommandOutput } from "./commands/ListImportsCommand";
114+
import { ListInsightsDataCommandInput, ListInsightsDataCommandOutput } from "./commands/ListInsightsDataCommand";
114115
import {
115116
ListInsightsMetricDataCommandInput,
116117
ListInsightsMetricDataCommandOutput,
@@ -215,6 +216,7 @@ export type ServiceInputTypes =
215216
| ListEventDataStoresCommandInput
216217
| ListImportFailuresCommandInput
217218
| ListImportsCommandInput
219+
| ListInsightsDataCommandInput
218220
| ListInsightsMetricDataCommandInput
219221
| ListPublicKeysCommandInput
220222
| ListQueriesCommandInput
@@ -279,6 +281,7 @@ export type ServiceOutputTypes =
279281
| ListEventDataStoresCommandOutput
280282
| ListImportFailuresCommandOutput
281283
| ListImportsCommandOutput
284+
| ListInsightsDataCommandOutput
282285
| ListInsightsMetricDataCommandOutput
283286
| ListPublicKeysCommandOutput
284287
| ListQueriesCommandOutput

‎clients/client-cloudtrail/src/commands/CreateEventDataStoreCommand.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -233,6 +233,11 @@ export interface CreateEventDataStoreCommandOutput extends CreateEventDataStoreR
233233
* that is not a member of an organization. To make this request, sign in using the
234234
* credentials of an account that belongs to an organization.</p>
235235
*
236+
* @throws {@link ThrottlingException} (client fault)
237+
* <p>
238+
* This exception is thrown when the request rate exceeds the limit.
239+
* </p>
240+
*
236241
* @throws {@link UnsupportedOperationException} (client fault)
237242
* <p>This exception is thrown when the requested operation is not supported.</p>
238243
*

‎clients/client-cloudtrail/src/commands/DeleteTrailCommand.ts‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,18 @@ export interface DeleteTrailCommandOutput extends DeleteTrailResponse, __Metadat
3030
* <p>Deletes a trail. This operation must be called from the Region in which the trail was
3131
* created. <code>DeleteTrail</code> cannot be called on the shadow trails (replicated trails
3232
* in other Regions) of a trail that is enabled in all Regions.</p>
33+
* <important>
34+
* <p>
35+
* While deleting a CloudTrail trail is an irreversible action, CloudTrail does not
36+
* delete log files in the Amazon S3 bucket for that trail, the Amazon S3 bucket itself, or the
37+
* CloudWatchlog group to which the trail delivers events. Deleting a multi-Region trail
38+
* will stop logging of events in all Amazon Web Services Regions enabled in your Amazon Web Services account. Deleting a
39+
* single-Region trail will stop logging of events in that Region only. It will not stop
40+
* logging of events in other Regions even if the trails in those other Regions have
41+
* identical names to the deleted trail.
42+
* </p>
43+
* <p>For information about account closure and deletion of CloudTrail trails, see <a href="https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-account-closure.html">https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-account-closure.html</a>.</p>
44+
* </important>
3345
* @example
3446
* Use a bare-bones client and the command you need to make an API call.
3547
* ```javascript

‎clients/client-cloudtrail/src/commands/GetInsightSelectorsCommand.ts‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,8 +28,8 @@ export interface GetInsightSelectorsCommandOutput extends GetInsightSelectorsRes
2828

2929
/**
3030
* <p>Describes the settings for the Insights event selectors that you configured for your
31-
* trail or event data store. <code>GetInsightSelectors</code> shows if CloudTrail Insights event logging
32-
* is enabled on the trail or event data store, and if it is, which Insights types are enabled. If you run
31+
* trail or event data store. <code>GetInsightSelectors</code> shows if CloudTrail Insights logging is enabled
32+
* and which Insights types are configured with corresponding event categories. If you run
3333
* <code>GetInsightSelectors</code> on a trail or event data store that does not have Insights events enabled,
3434
* the operation throws the exception <code>InsightNotEnabledException</code>
3535
* </p>
@@ -55,6 +55,9 @@ export interface GetInsightSelectorsCommandOutput extends GetInsightSelectorsRes
5555
* // InsightSelectors: [ // InsightSelectors
5656
* // { // InsightSelector
5757
* // InsightType: "ApiCallRateInsight" || "ApiErrorRateInsight",
58+
* // EventCategories: [ // SourceEventCategories
59+
* // "Management" || "Data",
60+
* // ],
5861
* // },
5962
* // ],
6063
* // EventDataStoreArn: "STRING_VALUE",

‎clients/client-cloudtrail/src/commands/ListInsightsDataCommand.ts‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
// smithy-typescript generated code
2+
import { getEndpointPlugin } from "@smithy/middleware-endpoint";
3+
import { Command as $Command } from "@smithy/smithy-client";
4+
import { MetadataBearer as __MetadataBearer } from "@smithy/types";
5+
6+
import { CloudTrailClientResolvedConfig, ServiceInputTypes, ServiceOutputTypes } from "../CloudTrailClient";
7+
import { commonParams } from "../endpoint/EndpointParameters";
8+
import { ListInsightsDataRequest, ListInsightsDataResponse } from "../models/models_0";
9+
import { ListInsightsData } from "../schemas/schemas_0";
10+
11+
/**
12+
* @public
13+
*/
14+
export type { __MetadataBearer };
15+
export { $Command };
16+
/**
17+
* @public
18+
*
19+
* The input for {@link ListInsightsDataCommand}.
20+
*/
21+
export interface ListInsightsDataCommandInput extends ListInsightsDataRequest {}
22+
/**
23+
* @public
24+
*
25+
* The output of {@link ListInsightsDataCommand}.
26+
*/
27+
export interface ListInsightsDataCommandOutput extends ListInsightsDataResponse, __MetadataBearer {}
28+
29+
/**
30+
* <p>Returns Insights events generated on a trail that logs data events. You can list Insights events that occurred in a Region within the last 90 days.</p>
31+
* <p>ListInsightsData supports the following Dimensions for Insights events:</p>
32+
* <ul>
33+
* <li>
34+
* <p>Event ID</p>
35+
* </li>
36+
* <li>
37+
* <p>Event name</p>
38+
* </li>
39+
* <li>
40+
* <p>Event source</p>
41+
* </li>
42+
* </ul>
43+
* <p>All dimensions are optional. The default number of results returned is 50, with a
44+
* maximum of 50 possible. The response includes a token that you can use to get the next page
45+
* of results.</p>
46+
* <p>The rate of ListInsightsData requests is limited to two per second, per account, per Region. If
47+
* this limit is exceeded, a throttling error occurs.</p>
48+
* @example
49+
* Use a bare-bones client and the command you need to make an API call.
50+
* ```javascript
51+
* import { CloudTrailClient, ListInsightsDataCommand } from "@aws-sdk/client-cloudtrail"; // ES Modules import
52+
* // const { CloudTrailClient, ListInsightsDataCommand } = require("@aws-sdk/client-cloudtrail"); // CommonJS import
53+
* // import type { CloudTrailClientConfig } from "@aws-sdk/client-cloudtrail";
54+
* const config = {}; // type is CloudTrailClientConfig
55+
* const client = new CloudTrailClient(config);
56+
* const input = { // ListInsightsDataRequest
57+
* InsightSource: "STRING_VALUE", // required
58+
* DataType: "InsightsEvents", // required
59+
* Dimensions: { // ListInsightsDataDimensions
60+
* "<keys>": "STRING_VALUE",
61+
* },
62+
* StartTime: new Date("TIMESTAMP"),
63+
* EndTime: new Date("TIMESTAMP"),
64+
* MaxResults: Number("int"),
65+
* NextToken: "STRING_VALUE",
66+
* };
67+
* const command = new ListInsightsDataCommand(input);
68+
* const response = await client.send(command);
69+
* // { // ListInsightsDataResponse
70+
* // Events: [ // EventsList
71+
* // { // Event
72+
* // EventId: "STRING_VALUE",
73+
* // EventName: "STRING_VALUE",
74+
* // ReadOnly: "STRING_VALUE",
75+
* // AccessKeyId: "STRING_VALUE",
76+
* // EventTime: new Date("TIMESTAMP"),
77+
* // EventSource: "STRING_VALUE",
78+
* // Username: "STRING_VALUE",
79+
* // Resources: [ // ResourceList
80+
* // { // Resource
81+
* // ResourceType: "STRING_VALUE",
82+
* // ResourceName: "STRING_VALUE",
83+
* // },
84+
* // ],
85+
* // CloudTrailEvent: "STRING_VALUE",
86+
* // },
87+
* // ],
88+
* // NextToken: "STRING_VALUE",
89+
* // };
90+
*
91+
* ```
92+
*
93+
* @param ListInsightsDataCommandInput - {@link ListInsightsDataCommandInput}
94+
* @returns {@link ListInsightsDataCommandOutput}
95+
* @see {@link ListInsightsDataCommandInput} for command's `input` shape.
96+
* @see {@link ListInsightsDataCommandOutput} for command's `response` shape.
97+
* @see {@link CloudTrailClientResolvedConfig | config} for CloudTrailClient's `config` shape.
98+
*
99+
* @throws {@link InvalidParameterException} (client fault)
100+
* <p>The request includes a parameter that is not valid.</p>
101+
*
102+
* @throws {@link OperationNotPermittedException} (client fault)
103+
* <p>This exception is thrown when the requested operation is not permitted.</p>
104+
*
105+
* @throws {@link UnsupportedOperationException} (client fault)
106+
* <p>This exception is thrown when the requested operation is not supported.</p>
107+
*
108+
* @throws {@link CloudTrailServiceException}
109+
* <p>Base exception class for all service exceptions from CloudTrail service.</p>
110+
*
111+
*
112+
* @public
113+
*/
114+
export class ListInsightsDataCommand extends $Command
115+
.classBuilder<
116+
ListInsightsDataCommandInput,
117+
ListInsightsDataCommandOutput,
118+
CloudTrailClientResolvedConfig,
119+
ServiceInputTypes,
120+
ServiceOutputTypes
121+
>()
122+
.ep(commonParams)
123+
.m(function (this: any, Command: any, cs: any, config: CloudTrailClientResolvedConfig, o: any) {
124+
return [getEndpointPlugin(config, Command.getEndpointParameterInstructions())];
125+
})
126+
.s("CloudTrail_20131101", "ListInsightsData", {})
127+
.n("CloudTrailClient", "ListInsightsDataCommand")
128+
.sc(ListInsightsData)
129+
.build() {
130+
/** @internal type navigation helper, not in runtime. */
131+
protected declare static __types: {
132+
api: {
133+
input: ListInsightsDataRequest;
134+
output: ListInsightsDataResponse;
135+
};
136+
sdk: {
137+
input: ListInsightsDataCommandInput;
138+
output: ListInsightsDataCommandOutput;
139+
};
140+
};
141+
}

‎clients/client-cloudtrail/src/commands/ListInsightsMetricDataCommand.ts‎

Lines changed: 35 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,8 +42,17 @@ export interface ListInsightsMetricDataCommandOutput extends ListInsightsMetricD
4242
* <p>Data points with a period of 3600 seconds (1 hour) are available for 90 days.</p>
4343
* </li>
4444
* </ul>
45-
* <p>Access to the <code>ListInsightsMetricData</code> API operation is linked to the <code>cloudtrail:LookupEvents</code> action. To use this operation,
45+
* <p>To use <code>ListInsightsMetricData</code> operation, you must have the following permissions:</p>
46+
* <ul>
47+
* <li>
48+
* <p>If <code>ListInsightsMetricData</code> is invoked with <code>TrailName</code> parameter, access to the <code>ListInsightsMetricData</code> API operation is linked to the <code>cloudtrail:LookupEvents</code> action and <code>cloudtrail:ListInsightsData</code>. To use this operation,
49+
* you must have permissions to perform the <code>cloudtrail:LookupEvents</code> and <code>cloudtrail:ListInsightsData</code> action on the specific trail.</p>
50+
* </li>
51+
* <li>
52+
* <p>If <code>ListInsightsMetricData</code> is invoked without <code>TrailName</code> parameter, access to the <code>ListInsightsMetricData</code> API operation is linked to the <code>cloudtrail:LookupEvents</code> action only. To use this operation,
4653
* you must have permissions to perform the <code>cloudtrail:LookupEvents</code> action.</p>
54+
* </li>
55+
* </ul>
4756
* @example
4857
* Use a bare-bones client and the command you need to make an API call.
4958
* ```javascript
@@ -53,6 +62,7 @@ export interface ListInsightsMetricDataCommandOutput extends ListInsightsMetricD
5362
* const config = {}; // type is CloudTrailClientConfig
5463
* const client = new CloudTrailClient(config);
5564
* const input = { // ListInsightsMetricDataRequest
65+
* TrailName: "STRING_VALUE",
5666
* EventSource: "STRING_VALUE", // required
5767
* EventName: "STRING_VALUE", // required
5868
* InsightType: "ApiCallRateInsight" || "ApiErrorRateInsight", // required
@@ -67,6 +77,7 @@ export interface ListInsightsMetricDataCommandOutput extends ListInsightsMetricD
6777
* const command = new ListInsightsMetricDataCommand(input);
6878
* const response = await client.send(command);
6979
* // { // ListInsightsMetricDataResponse
80+
* // TrailARN: "STRING_VALUE",
7081
* // EventSource: "STRING_VALUE",
7182
* // EventName: "STRING_VALUE",
7283
* // InsightType: "ApiCallRateInsight" || "ApiErrorRateInsight",
@@ -91,6 +102,29 @@ export interface ListInsightsMetricDataCommandOutput extends ListInsightsMetricD
91102
* @throws {@link InvalidParameterException} (client fault)
92103
* <p>The request includes a parameter that is not valid.</p>
93104
*
105+
* @throws {@link InvalidTrailNameException} (client fault)
106+
* <p>This exception is thrown when the provided trail name is not valid. Trail names must
107+
* meet the following requirements:</p>
108+
* <ul>
109+
* <li>
110+
* <p>Contain only ASCII letters (a-z, A-Z), numbers (0-9), periods (.), underscores
111+
* (_), or dashes (-)</p>
112+
* </li>
113+
* <li>
114+
* <p>Start with a letter or number, and end with a letter or number</p>
115+
* </li>
116+
* <li>
117+
* <p>Be between 3 and 128 characters</p>
118+
* </li>
119+
* <li>
120+
* <p>Have no adjacent periods, underscores or dashes. Names like
121+
* <code>my-_namespace</code> and <code>my--namespace</code> are not valid.</p>
122+
* </li>
123+
* <li>
124+
* <p>Not be in IP address format (for example, 192.168.5.4)</p>
125+
* </li>
126+
* </ul>
127+
*
94128
* @throws {@link OperationNotPermittedException} (client fault)
95129
* <p>This exception is thrown when the requested operation is not permitted.</p>
96130
*

‎clients/client-cloudtrail/src/commands/PutInsightSelectorsCommand.ts‎

Lines changed: 26 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,15 +27,33 @@ export interface PutInsightSelectorsCommandInput extends PutInsightSelectorsRequ
2727
export interface PutInsightSelectorsCommandOutput extends PutInsightSelectorsResponse, __MetadataBearer {}
2828

2929
/**
30-
* <p>Lets you enable Insights event logging by specifying the Insights selectors that you
30+
* <p>Lets you enable Insights event logging on specific event categories by specifying the Insights selectors that you
3131
* want to enable on an existing trail or event data store. You also use <code>PutInsightSelectors</code> to turn
3232
* off Insights event logging, by passing an empty list of Insights types. The valid Insights
3333
* event types are <code>ApiErrorRateInsight</code> and
34-
* <code>ApiCallRateInsight</code>.</p>
34+
* <code>ApiCallRateInsight</code>, and valid EventCategories are <code>Management</code> and <code>Data</code>.</p>
35+
* <note>
36+
* <p>
37+
* Insights on data events are not supported on event data stores. For event data stores, you can only enable Insights on management events.
38+
* </p>
39+
* </note>
3540
* <p>To enable Insights on an event data store, you must specify the ARNs (or ID suffix of the ARNs) for the source event data store (<code>EventDataStore</code>) and the destination event data store (<code>InsightsDestination</code>). The source event data store logs management events and enables Insights.
3641
* The destination event data store logs Insights events based upon the management event activity of the source event data store. The source and destination event data stores must belong to the same Amazon Web Services account.</p>
3742
* <p>To log Insights events for a trail, you must specify the name (<code>TrailName</code>) of the CloudTrail trail for which you want to change or add Insights
3843
* selectors.</p>
44+
* <ul>
45+
* <li>
46+
* <p>
47+
* For Management events Insights: To log CloudTrail Insights on the API call rate, the trail or event data store must log <code>write</code> management events.
48+
* To log CloudTrail Insights on the API error rate, the trail or event data store must log <code>read</code> or <code>write</code> management events.
49+
* </p>
50+
* </li>
51+
* <li>
52+
* <p>
53+
* For Data events Insights: To log CloudTrail Insights on the API call rate or API error rate, the trail must log <code>read</code> or <code>write</code> data events. Data events Insights are not supported on event data store.
54+
* </p>
55+
* </li>
56+
* </ul>
3957
* <p>To log CloudTrail Insights events on API call volume, the trail or event data store
4058
* must log <code>write</code> management events. To log CloudTrail
4159
* Insights events on API error rate, the trail or event data store must log <code>read</code> or
@@ -56,6 +74,9 @@ export interface PutInsightSelectorsCommandOutput extends PutInsightSelectorsRes
5674
* InsightSelectors: [ // InsightSelectors // required
5775
* { // InsightSelector
5876
* InsightType: "ApiCallRateInsight" || "ApiErrorRateInsight",
77+
* EventCategories: [ // SourceEventCategories
78+
* "Management" || "Data",
79+
* ],
5980
* },
6081
* ],
6182
* EventDataStore: "STRING_VALUE",
@@ -68,6 +89,9 @@ export interface PutInsightSelectorsCommandOutput extends PutInsightSelectorsRes
6889
* // InsightSelectors: [ // InsightSelectors
6990
* // { // InsightSelector
7091
* // InsightType: "ApiCallRateInsight" || "ApiErrorRateInsight",
92+
* // EventCategories: [ // SourceEventCategories
93+
* // "Management" || "Data",
94+
* // ],
7195
* // },
7296
* // ],
7397
* // EventDataStoreArn: "STRING_VALUE",

0 commit comments

Comments
 (0)