How can I monitor the account activity of specific IAM users, roles, and AWS access keys?

Short description

To view and monitor the account activity of specific IAM identities, you can use any of the following AWS services and features:

• AWS CloudTrail event history
• Amazon CloudWatch Logs Insights
• Amazon Athena queries

Resolution

To use CloudTrail event history

Note: You can use CloudTrail to search event history for the last 90 days.

1.    Open the CloudTrail console.

2.    Choose Event history.

3.    In Filter, select the dropdown list. Then, choose User name.
Note: You can also filter by AWS access key.

4.    In the Enter user or role name text box, enter the IAM user's "friendly name" or the assumed role session name.

Note: The role session name for a specific session is the value provided as a session name when the role is assumed. Value for "User name" field won't be the role name for calls made using the IAM role.

5.    In Time range, enter the desired time range. Then, choose Apply.

6.    In Event time, expand the event. Then, choose View event.

The userIdentity element contains details about the type of IAM identity that made the request and the credentials provided.

Example userIdentity element that includes IAM user credentials used to make an API call

Note: Replace Alice with the username that you're searching for. Enter the IAM user's "friendly name" or the assumed role's "role session name." The role session name for a specific session is the value provided as a session name when the role is assumed. For calls made using the IAM role, the value for the userName field isn't the role name.

"userIdentity": {
  "type": "IAMUser",
  "principalId": "AIDAJ45Q7YFFAREXAMPLE",
  "arn": "arn:aws:iam::123456789012:user/Alice",
  "accountId": "123456789012",
  "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
  "userName": "Alice"
}

Example userIdentity element that includes temporary security credentials

"userIdentity": {
    "type": "AssumedRole",
    "principalId": "AROAIDPPEZS35WEXAMPLE:AssumedRoleSessionName",
    "arn": "arn:aws:sts::123456789012:assumed-role/RoleToBeAssumed/AssumedRoleSessionName", 
    "accountId": "123456789012",
    "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
    "sessionContext": {
      "attributes": {
        "mfaAuthenticated": "false",
        "creationDate": "20131102T010628Z"
      },
      "sessionIssuer": {
        "type": "Role",
        "principalId": "AROAIDPPEZS35WEXAMPLE",
        "arn": "arn:aws:iam::123456789012:role/RoleToBeAssumed",
        "accountId": "123456789012",
        "userName": "RoleToBeAssumed"
      }
   }
}

Note: CloudTrail event history uses the assumed role session name as the username for filtering events.

The API call uses temporary security credentials obtained by assuming an IAM role. The element contains additional details about the role assumed to get credentials.

Note: If you don't see user activity, then verify that the AWS service is supported and the API event is recorded by CloudTrail. For more information, see AWS service topics for CloudTrail.

To use CloudWatch Logs Insights

Note: You can use CloudWatch Logs Insights to search API history beyond the last 90 days. You must have a trail created and configured to log to Amazon CloudWatch Logs. For more information, see Creating a trail.

1.    Open the CloudWatch console.

2.    Choose Logs.

3.    In Log Groups, choose your log group.

4.    Choose Search Log Group.

5.    In Filter events, enter a query to either search for a user's API calls, or specific API actions. Then, choose the refresh icon.

Example query to search logs for a user's API calls

Note: Replace Alice with the username that you're searching for. Enter the IAM user's "friendly name" or the assumed role's "role session name." The role session name for a specific session is the value provided as a session name when the role is assumed. For calls made using the IAM role, the value for the userName field isn't the role name.

{ $.userIdentity.userName = "Alice" }

Example query to search logs for specific API actions

Note: The following example query searches for the DescribeInstances API action.

{ ($.eventName = "DescribeInstances") && ($.requestParameters.userName = "Alice"  ) }

For more information, see CloudWatch Logs Insights query syntax.

To use Athena queries

Note: You can use Athena to query CloudTrail Logs over the last 90 days.

1.    Open the Athena console.

2.    Choose Query Editor.

3.    Enter one of the following example queries based on your use case. Then, choose Run query:

Example query to return all CloudTrail events performed by a specific IAM user

Important: Replace athena-table with your Athena table name. Replace Alice with the IAM user that you want to view account activity for.

SELECT *
FROM athena-table
WHERE useridentity.type = 'IAMUser'
AND useridentity.username LIKE 'Alice';

Example query to filter all the API activity performed by an IAM role

Note: Replace role-name with your IAM role name.

SELECT *
FROM athena-table
WHERE useridentity.sessionContext.sessionissuer.arn LIKE '%role-name%'
AND useridentity.sessionContext.sessionissuer.type = 'Role';

Example query to match the role ARN

SELECT *
FROM athena-table
WHERE useridentity.sessionContext.sessionissuer.arn = 'arn:aws:iam::account-id123456789:role/role-name'
AND useridentity.sessionContext.sessionissuer.type = 'Role';

Example query to filter for all activity using the IAM access key ID

SELECT eventTime, eventName, userIdentity.principalId,eventSource
FROM athena-table
WHERE useridentity.accesskeyid like 'AKIAIOSFODNN7EXAMPLE'

---

Related information

How do I use AWS CloudTrail to track API calls to my Amazon EC2 instances?

How do I use CloudTrail to see if a security group or resource was changed in my AWS account?