Understand the Security Importance of CloudTrail Event Fields

AWS CloudTrail event fields provide granular details about API activities, user identities, and resource interactions, enabling precise tracking and analysis during security investigations. This section outlines the critical CloudTrail event fields, their security significance, and recommended use cases for forensic analysis and incident response.

Key CloudTrail Event Fields for Security Investigations

Below is a detailed breakdown of the most critical CloudTrail event fields, their importance in security investigations, and how to leverage them effectively during incident response.

Discover CloudTrail Record Contents

To explore the full details of AWS CloudTrail record contents, including key fields like eventName, eventSource, and requestParameters, check our comprehensive documentation. Enhance your security forensics and incident response with complete log insights.

Critical Event Fields

• 1. userIdentity

  • Description: Contains details about the IAM identity making the request, including type (e.g., IAMUser, AssumedRole, Root), principalId, arn, accountId, userName, and sessionContext.
  • Security Importance: Identifies the actor behind an incident, enabling determination of whether a compromised user, role, or root account was involved. It also supports tracing cross-account access.
  • Use Case: Use userIdentity to pinpoint if a bad actor used stolen IAM credentials or assumed a role to escalate privileges. If type is Root, escalate immediately due to the high risk of root account compromise.

• 2. userIdentity.accessKeyId

  • Description: Identifies the access key used in the request.
  • Security Importance: Tracks compromised credentials across multiple events, as bad actors often reuse stolen access keys.
  • Use Case: Correlate suspicious activities using accessKeyId to determine the scope of a breach. If empty (e.g., for console actions), cross-reference with userIdentity.sessionContext to confirm session type.

• 3. userIdentity.userName

  • Description: Specifies the IAM user's name.
  • Security Importance: Tracks user-specific activity, especially with multiple access keys.
  • Use Case: Cross-reference userName with userIdentity.principalId for consistent identity tracking.

• 4. userIdentity.principalId

  • Description: Provides a unique identifier for the entity making the request.
  • Security Importance: Correlates actions across sessions, especially for temporary credentials.
  • Use Case: Track bad actor movement across assumed roles or sessions using principalId.

• 5. userIdentity.sessionContext

  • Description: Details assumed roles or federated sessions, including sessionIssuer and sourceIdentity.
  • Security Importance: Critical for understanding cross-account access or role-chaining attacks. If the request was made with temporary security credentials, sessionContext provides information about the session created for those credentials. You create a session when you call any API that returns temporary credentials. Users also create sessions when they work in the console and make requests with APIs that include multi-factor authentication.
  • Use Case: Analyze sessionContext.sourceIdentity to trace the attack's origin in role assumption scenarios.

• 6. userIdentity.type

  • Description: Specifies the identity type (e.g., IAMUser, Root, AssumedRole).
  • Security Importance: Identifies high-risk actions, such as Root usage, requiring immediate escalation.
  • Use Case: Filter by userIdentity.type to prioritize investigations involving privileged identities.

• 7. userIdentity.arn

  • Description: Provides the Amazon Resource Name of the principal.
  • Security Importance: Ensures precise identification of actors in complex environments.
  • Use Case: Trace actions to specific IAM entities using arn.

• 8. userIdentity.accountId

  • Description: Identifies the AWS account owning the entity.
  • Security Importance: Isolates the source account in cross-account scenarios.
  • Use Case: Cross-reference with recipientAccountId to detect unauthorized access.

• 9. userIdentity.sessionIssuer

  • Description: Identifies the entity issuing session credentials (e.g., a role).
  • Security Importance: Tracks the source of temporary credentials in role-based attacks. If a user makes a request with temporary security credentials, sessionIssuer provides information about how the user obtained credentials. For example, if they obtained temporary security credentials by assuming a role, this element provides information about the assumed role. If they obtained credentials with root or IAM user credentials to call AWS STS GetFederationToken, the element provides information about the root account or IAM user.
  • Use Case: Analyze sessionIssuer in AssumedRole events for privilege escalation analysis.

• 10. userIdentity.invokedBy

  • Description: Indicates if an AWS service (e.g., Lambda) made the request.
  • Security Importance: Distinguishes service-initiated actions from user activity, identifying misconfigurations or exploited roles.
  • Use Case: Investigate invokedBy for anomalies in service behavior.

• 11. eventTime

  • Description: Records the UTC timestamp of the activity.
  • Security Importance: Establishes the timeline of an attack, identifying the initial point of compromise and correlating events across systems.
  • Use Case: Sequence bad actor actions and determine the duration of unauthorized access. A spike in API calls at unusual times may indicate malicious activity.

• 12. eventName

  • Description: Specifies the AWS API action (e.g., GetCallerIdentity, CreateAccessKey, DeleteBucket).
  • Security Importance: Reveals bad actor techniques, such as reconnaissance (ListUsers) or privilege escalation (CreateAccessKey).
  • Use Case: Analyze eventName to identify high-risk actions like modifying IAM policies or disabling logging, indicating intent to persist or evade detection.

• 13. eventSource

  • Description: Identifies the AWS service targeted (e.g., iam.amazonaws.com, s3.amazonaws.com).
  • Security Importance: Determines affected services, helping prioritize remediation efforts.
  • Use Case: Investigate eventSource for sts.amazonaws.com with eventName AssumeRole to detect role-chaining attacks. Filter logs to focus on compromised services.

• 14. sourceIPAddress

  • Description: Indicates the IP address from which the request originated.
  • Security Importance: Identifies the geographic origin of an attack and potential threat actors.
  • Use Case: Cross-reference sourceIPAddress with threat intelligence feeds to detect suspicious origins. If it shows "AWS Internal/#", investigate service roles or misconfigurations.

• 15. userAgent

  • Description: Details the application or tool used (e.g., aws-cli, aws-sdk-java).
  • Security Importance: Identifies suspicious tools or non-standard applications used by bad actors.
  • Use Case: Monitor userAgent for anomalies, such as non-AWS SDKs, which may indicate malicious tooling that deviates from normal organizational patterns.

• 16. errorCode and errorMessage

  • Description: Indicates if an API call failed and why (e.g., AccessDenied).
  • Security Importance: Reveals failed attack attempts and permission boundaries, providing insight into a bad actor's scope.
  • Use Case: Multiple AccessDenied errors for CreateAccessKey may indicate permission testing. Use these fields to refine security controls.

• 17. requestParameters

  • Description: Contains parameters sent with the API call, such as resource names or configurations. The response elements, if any, for actions that make changes (create, update, or delete actions). For readOnly APIs, this field is null. If the action doesn't return response elements, this field is null. The response elements for actions are documented in the API reference documentation for the appropriate AWS service.
  • Security Importance: Reveals the specific inputs of an API call and configuration details sent by a bad actor's actions.
  • Use Case: Analyze requestParameters in a CreateBucket call to identify the bucket name for remediation.

• 18. responseElements

  • Description: Includes the API call's output, such as newly created access keys or resource ARNs. The response elements, if any, for actions that make changes (create, update, or delete actions). For readOnly APIs, this field is null. If the action doesn't return response elements, this field is null. The response elements for actions are documented in the API reference documentation for the appropriate AWS service.
  • Security Importance: Contains critical information like newly created resources, access keys, and other artifacts.
  • Use Case: Use responseElements in a CreateAccessKey event to deactivate new keys and reverse unauthorized changes.

• 19. resources

  • Description: Lists AWS resources accessed or modified, including ARNs and resource types.
  • Security Importance: Identifies affected assets, such as S3 buckets or IAM roles, for remediation.
  • Use Case: Use resources in a DeleteObject event to pinpoint the affected S3 object and prioritize recovery.

• 20. eventType

  • Description: Categorizes the event (e.g., AwsApiCall, AwsConsoleSignIn).
  • Security Importance: Distinguishes API-based attacks, console logins, or service-initiated actions.
  • Use Case: Filter AwsConsoleSignIn events to detect unauthorized console access and verify MFA.

• 21. recipientAccountId

  • Description: Identifies the AWS account receiving the request.
  • Security Importance: Tracks cross-account activity in multi-account organizations.
  • Use Case: Investigate if recipientAccountId differs from userIdentity.accountId for unauthorized cross-account access.

• 22. awsRegion

  • Description: Specifies the AWS region of the request.
  • Security Importance: Establishes geographic patterns and incident scope.
  • Use Case: Filter logs by awsRegion to identify anomalies in unused regions.

• 23. readOnly

  • Description: Indicates whether the API call was read-only (true) or write (false).
  • Security Importance: Distinguishes reconnaissance from modification actions.
  • Use Case: Focus on write operations for potential data tampering or persistence.

• 24. eventID

  • Description: Uniquely identifies each CloudTrail event.
  • Security Importance: Enables referencing specific events and correlating with external systems like SIEM tools.
  • Use Case: Use eventID as a primary key for log aggregation and tracking.

• 25. serviceEventDetails

  • Description: Provides service-specific context, such as IAM Identity Center federation events.
  • Security Importance: Enhances investigations with specialized service details.
  • Use Case: Analyze serviceEventDetails for IAM Identity Center events to audit federated user actions.

Explore the userIdentity Element

For a comprehensive guide to understanding the userIdentity element in AWS CloudTrail logs, including its fields (e.g., type, userName, arn), visit our detailed documentation. Unlock insights for effective security forensics and incident response.

Best Practices for CloudTrail

To maximize the effectiveness of CloudTrail for security investigations, enable CloudTrail for all regions and accounts in your AWS Organization. Ensure logs are stored securely in an S3 bucket with restricted access and enable log file integrity validation to detect tampering. Regularly analyze these fields using tools like Amazon Athena or CloudTrail Lake to identify anomalies and respond promptly to incidents.

Example Analysis Workflow for Compromised AWS Access Key

1. Identify the Actor: Use userIdentity fields (type, userName, arn, accountId, principalId) to determine the identity involved. Escalate if Root is detected.
2. Establish Timeline: Use eventTime to sequence events and identify the attack's duration.
3. Analyze Actions: Review eventName, eventSource, and readOnly to understand bad actor techniques and affected services.
4. Track Resources: Use resources, requestParameters, and responseElements to identify targeted or modified assets for remediation.
5. Investigate Access: Cross-reference sourceIPAddress, userAgent, recipientAccountId, and sessionContext to detect unauthorized access or role-chaining.
6. Review Errors: Analyze errorCode and errorMessage to identify attempted actions blocked by IAM policies.
7. Correlate Events: Use eventID and serviceEventDetails to integrate with SIEM tools and perform detailed forensic analysis.