Tracking changes in your AMS Accelerate accounts - AMS Accelerate User Guide
Viewing your change recordsDefault queriesChange record permissions

Tracking changes in your AMS Accelerate accounts

AWS Managed Services helps you track changes made by the AMS Accelerate Operations team and AMS Accelerate automation by providing a queryable interface using the Amazon Athena (Athena) console and AMS Accelerate log management.

Athena is an interactive query service you can use to analyze data in Amazon S3 by using standard Structured Query Language (SQL) (see SQL Reference for Amazon Athena). Athena is serverless, so there is no infrastructure to manage, and you pay only for the queries that you run. AMS Accelerate creates Athena tables with daily partitions over CloudTrail logs, and provides queries on your primary AWS Region and within the ams-change-record workgroup. You can choose any of the default queries and run them as needed. To learn more about Athena workgroups, see How Workgroups Work.

Note

Only Accelerate can query CloudTrail events for your Accelerate account using Athena when Accelerate is integrated with your CloudTrail Organization trail, unless your Organization administrator deployed an IAM Role for using Athena to query and analyze CloudTrail events in your account, during onboarding.

Using change record, you can easily answer questions like:

  • Who (AMS Accelerate Systems or AMS Accelerate Operators) has accessed your account

  • What changes have been made by AMS Accelerate in your account

  • When did AMS Accelerate perform changes in your account

  • Where to go to view changes made in your account

  • Why AMS Accelerate needed to make the changes in your account

  • How to modify queries to get answers to all those questions for any non-AMS changes too

Viewing your change records

To use Athena queries, sign in to the AWS Management console and navigate to the Athena console in your primary AWS Region.

Note

If you see the Amazon Athena Get Started page while performing any of the steps, click Get Started. This might appear for you even if your Change Record infrastructure is already in place.

  1. Choose Workgroup from the upper navigation panel in the Athena console.

  2. Choose the ams-change-record workgroup, and then click Switch Workgroup.

  3. Choose ams-change-record-database from the Database Combo box. The ams-change-record-database includes the ams-change-record-table table.

  4. Choose Saved Queries from the upper navigation panel.

  5. The Saved Queries window shows a list of queries that AMS Accelerate provides, which you can run. Choose the query you want to run from the Saved Queries list. For example, ams_session_accesses_v1 query.

    For the full list of preset AMS Accelerate queries, see Default queries.

  6. Adjust the datetime filter in the query editor box as needed; by default, the query only checks changes from the last day.

  7. Choose Run query.

Default queries

AMS Accelerate provides several default queries you can use within the Athena console; they are listed in the following table.

Note

  • All queries accept datetime range as an optional filter; all the queries run over the last 24 hours, by default. For expected input, see the following subsection, Modifying the datetime filter in queries.

  • Parameter inputs that you can or need to change are shown in the query as <PARAMETER_NAME> with angular braces. Replace the placeholder and the angular braces with your parameter value.

  • All filters are optional. In the queries, some optional filters are commented out with a double dash (--) at the start of the line. All queries will run without them, with default parameters. If you want to specify parameter values for these optional filters, remove the double dash (--) at the start of the line and replace the parameter as you want.

  • All queries return IAM PincipalId and IAM SessionId in the outputs

  • The calculated cost for running a query depends on how many CloudTrail logs are generated for the account. To calculate the cost, use the AWS Athena Pricing Calculator.

Canned queries
Purpose/Description Inputs Outputs

Query name: ams_access_session_query_v1

Tracking AMS Accelerate access sessions

Provides information about a specific AMS Accelerate access session. The query accepts the IAM Principal ID as an optional filter and returns event time, business need for accessing the account, requester, and so on.

You can filter on a specific IAM Principal ID by uncommenting the line and replacing the placeholder IAM PrincipalId with a specific ID in the query editor.

You can also list non-AMS access sessions by removing the useragent filter line in the WHERE clause of the query.

(Optional) IAM PrincipalId: The IAM Principal identifier of the resource that is trying to access. The format is UNIQUE_IDENTIFIER:RESOURCE_NAME. For details see unique identifiers. You can run the query without this filter to determine the exact IAM PrincipalId the you want to filter with.

  • EventTime: Time of gaining the access

  • EventName: AWS Event name (AssumeRole)

  • EventRegion: AWS Region that gets the request

  • EventId: CloudTrail Event ID

  • BusinessNeed Type: Business reason type to access the account. Allowed values are: SupportCase, OpsItem, Issue, Text.

  • BusinessNeed: Business need to access the account. For example, Support Case ID, Ops Item ID, and so forth.

  • Requester: Operator ID that accesses the account, or Automation system that access the account.

  • RequestAccessType: Requester type (System, OpsConsole, OpsAPI, Unset)

Query name: ams_events_query_v1

Track all mutating actions done by AMS Accelerate

Returns all write actions done on the account using that AMS Accelerate role filter.

You can also track mutating actions done by non-AMS roles by removing the useridentity.arn filter lines from the WHERE clause of the query.

 (Optional)

Only datetime range. See Modifying the datetime filter in queries.

  • AccountId: AWS Account ID

  • RoleArn: RoleArn for the requester

  • EventTime: Time of gaining the access

  • EventName: AWS Event name (AssumeRole)

  • EventRegion: AWS Region that gets the request

  • EventId: CloudTrail Event ID

  • RequestParameters : Request parameters for the request

  • ResponseElements: Response elements for the response.

  • UserAgent: AWS CloudTrail User Agent

Query name: ams_instance_access_sessions_query_v1

Track instance accesses by AMS Accelerate

Returns a list of AMS Accelerate instance accesses; every record includes event time, event Region, instance ID, IAM Principal ID, IAM Session ID, SSM Session ID. You can use the IAM Principal ID to get more details on the business need for accessing the instance by using the ams_access_sessions_query_v1 Athena query. You can use the SSM Session ID to get more details on the instance access session, including the start and end time of the session, log details, and using the AWS Session Manager console in the instance's AWS Region.

Users can also list non-AMS instance accesses by removing the useridentity filter line in the WHERE clause of the query.

Only datetime range. See Modifying the datetime filter in queries.

  • InstanceId: Instance ID

  • SSMSession Id: SSM Session ID

  • RoleArn: RoleArn for the requester

  • EventTime: Time of gaining the access

  • EventName: AWS Event name (AssumeRole)

  • EventRegion: AWS Region that gets the request

  • EventId: CloudTrail Event ID

Query name: ams_privilege_escalation_events_query_v1

Track permission (escalation) events for AMS and non-AMS users

Provides a list of events that can directly or potentially lead to a privilege escalation. The query accepts ActionedBy as an optional filter and returns EventName, EventId, EventTime, and so forth. All fields associated with the event are also returned. Fields are blank if not applicable for that event. The ActionedBy filter is disabled, by default; to enable it, remove "-- " from that line.

By default, the ActionedBy filter is disabled (it will show privilege escalation events from all users). To show events for a particular user or role, remove the double dash (--) from the useridentity filter line in the WHERE clause and replace the placeholder ACTIONEDBY_PUT_USER_NAME_HERE with an IAM user or role name. You can run the query without the filter to determine the exact user you want to filter with.

(Optional) ACTIONEDBY_PUT_USER_NAME: Username for the actionedBy user. This can be an IAM user or role. For example, ams-access-admin.

(Optional) datetime range. See Modifying the datetime filter in queries.

  • AccountId: Account Id

  • ActionedBy: ActionedBy Username

  • EventTime: Time of gaining the access

  • EventName: AWS Event name (AssumeRole).

  • EventRegion: AWS Region that gets the request

  • EventId: CloudTrail Event ID

Query name: ams_resource_events_query_v1

Track write events for specific resources AMS or non-AMS

Provides a list of events done on a specific resource. The query accepts resource ID as part of the filters (replace placeholder RESOURCE_INFO in the WHERE clause of the query), and returns all write actions done on that resource.

(Required) RESOURCE_INFO: The resource identifier, can be an ID for any AWS resource in the account. Do not confuse this with resource ARNs. For example, an instance ID for an EC2 instance, table name for a DynamoDB table, logGroupName for a CloudWatch Log, etc.

(Optional) datetime range. See Modifying the datetime filter in queries.

  • AccountId: Account Id

  • ActionedBy: ActionedBy Username

  • EventTime: Time of gaining the access

  • EventName: AWS Event name (AssumeRole).

  • EventRegion: AWS Region that gets the request

  • EventId: CloudTrail Event ID

Query name: ams_session_events_query_v1

Track write actions performed by AMS Accelerate during specific session

Provides a list of events done on a specific session. The query accepts IAM Principal ID as part of the filters (replace the placeholder PRINCIPAL_ID in the WHERE clause of the query), and returns all write actions done on that resource.

(Required) PRINCIPAL_ID: Principal ID for the session. The format is UNIQUE_IDENTIFIER:RESOURCE_NAME. For details see unique identifiers. You can run the query "ams_session_ids_by_requester_v1" to get list of IAM Principal IDs for a requester. You can also run the query without this filter to determine the exact IAM PrincipalId you want to filter with.

(Optional) datetime range. See Modifying the datetime filter in queries.

  • AccountId: Account Id

  • ActionedBy: ActionedBy Username

  • EventTime: Time of gaining the access

  • EventName: AWS Event name (AssumeRole)

  • EventRegion: AWS Region that gets the request

  • EventId: CloudTrail Event ID

Query name: ams_session_ids_by_requester_v1

Track IAM Principal/Session IDs for a specific requester.

The query accepts "requester" (replace the placeholder Requester in the WHERE clause of the query), and returns all IAM Principal Ids by that requester during the specified time range.

(Required) Requester: Operator ID that accesses the account (for example: alias of an operator), or Automation system that access the account (for example: OsConfiguration, AlarmManager, etc.).

(Optional) datetime range. See Modifying the datetime filter in queries.

  • IAM PrincipalId - IAM Principal Id of the session. The format is UNIQUE_IDENTIFIER:RESOURCE_NAME. For details see unique identifiers. You can run the query without this filter to determine the exact IAM PrincipalId you want to filter with.

  • IAM SessionId - IAM Session Id for the access session

  • EventTime: Time of gaining the access

Modifying the datetime filter in queries

All queries accept datetime range as an optional filter. All the queries run over the last one day by default.

The format used for the datetime field is yyyy/MM/dd (for example: 2021/01/01). Remember that it only stores the date and not the entire timestamp. For the entire timestamp, use the field eventime, which stores the timestamp in the ISO 8601 format yyyy-MM-ddTHH:mm:ssZ (for example: 2021-01-01T23:59:59Z). However, since the table is partitioned on the datetime field, you’ll need to pass in both the datetime and eventtime filter to the query. See the following examples.

Note

To see all the accepted ways you can modify the range, see the latest Presto function documentation based on the Athena engine version currently used for the Date and Time Functions and Operators to see all the accepted ways you can modify the range.

Date Level: Last 1 day or last 24 hours (Default) example: If the CURRENT_DATE='2021/01/01' , the filter will subtract one day from the current date and format it as datetime > '2020/12/31'

datetime > date_format(date_add('day', - 1, CURRENT_DATE), '%Y/%m/%d')

Date Level: Last 2 months example:

datetime > date_format(date_add('month', - 2, CURRENT_DATE), '%Y/%m/%d')

Date Level: Between 2 dates example:

datetime > '2021/01/01'
      AND
      datetime < '2021/01/10'

Timestamp Level: Last 12 hours example:

Partition data scanned to last 1 day and then filter all events within the last 12 hours

datetime > date_format(date_add('day', - 1, CURRENT_DATE), '%Y/%m/%d')
      AND
      eventtime > date_format(date_add('hour', - 12, CURRENT_TIMESTAMP), '%Y-%m-%dT%H:%i:%sZ')

Timestamp Level: Between 2 timestamps example:

Get events between Jan 1, 2021 12:00PM and Jan 10, 2021 3:00PM.

datetime > '2021/01/01' AND datetime < '2021/01/10'
      AND
      eventtime > '2021-01-01T12:00:00Z' AND eventtime < '2021-01-10T15:00:00Z'

Change record permissions

The following permissions are needed to run change record queries:

  • Athena

    • athena:GetWorkGroup

    • athena:StartQueryExecution

    • athena:ListDataCatalogs

    • athena:GetQueryExecution

    • athena:GetQueryResults

    • athena:BatchGetNamedQuery

    • athena:ListWorkGroups

    • athena:UpdateWorkGroup

    • athena:GetNamedQuery

    • athena:ListQueryExecutions

    • athena:ListNamedQueries

  • AWS KMS

    • kms:Decrypt

    • AWS KMS key ID of AMSCloudTrailLogManagement, or your AWS KMS key ID(s), if Accelerate is using your CloudTrail trail events Amazon S3 bucket data store using SSE-KMS encryption.

  • AWS Glue

    • glue:GetDatabase

    • glue:GetTables

    • glue:GetDatabases

    • glue:GetTable

  • Amazon S3 read access

    • Amazon S3 bucket CloudTrail datastore: ams-aAccountId-cloudtrail-primary region, or your Amazon S3 bucket name, CloudTrail trail events Amazon S3 bucket data store.

  • Amazon S3 write access

    • Athena events query results Amazon S3 bucket: ams-aAccountIdathena-results-primary region