AWS CloudTrail

Connecting AWS CloudTrail logs to your Panther Console

Overview

Panther supports ingesting Amazon Web Services (AWS) CloudTrail logs via AWS S3 or CloudWatch Logs. You can enrich CloudTrail logs with extra context using the TrailDiscover Enrichment Provider.

AWS CloudTrail Logs video walkthrough

Walkthrough video showing how to onboard AWS CloudTrail logs to Panther

How to onboard AWS CloudTrail logs to Panther

To pull CloudTrail logs into Panther, you will need to set up a Data Transport using either S3 or CloudWatch Logs.

1. In the lefthand navigation bar of your Panther Console, click Configure > Log Sources.

2. Click Create New.

3. Search "AWS" to see the list of available log sources.

4. Select AWS CloudTrail.

5. Click the AWS S3 Bucket or CloudWatch Logs transport method to begin setup. Follow Panther’s documentation for configuring S3 or using CloudWatch Logs for data transport.

AWS CloudTrail log latency

The latency between an event occurring in AWS and the event being sent to CloudTrail can be up to 15 minutes, but we commonly see data coming in at an average of 3.5 minutes. For more information, see AWS's documentation on how CloudTrail works.

Panther-built detections

See Panther's prewritten AWS rules in the panther-analysis Github repository.

Querying logs in Data Explorer

See example SQL queries, for use in Panther's Data Explorer, in CloudTrail logs queries.

Supported log types

Panther supports AWS.CloudTrail, AWS.CloudTrailDigest, and AWS.CloudTrailInsight.

AWS.CloudTrail

AWSCloudTrail represents the content of a CloudTrail S3 object. For more information, see AWS's documentation on CloudTrail log events.

schema: AWS.CloudTrail
parser:
  native:
    name: AWS.CloudTrail
description: AWSCloudTrail represents the content of a CloudTrail S3 object.
referenceURL: https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference.html
fields:
  - name: additionalEventData
    description: Additional data about the event that was not part of the request or response.
    type: json
  - name: apiVersion
    description: Identifies the API version associated with the AwsApiCall eventType value.
    type: string
  - name: awsRegion
    required: true
    description: The AWS region that the request was made to, such as us-east-2.
    type: string
  - name: errorCode
    description: The AWS service error if the request returns an error.
    type: string
  - name: errorMessage
    description: If the request returns an error, the description of the error. This message includes messages for authorization failures. CloudTrail captures the message logged by the service in its exception handling.
    type: string
  - name: eventID
    required: true
    description: GUID generated by CloudTrail to uniquely identify each event. You can use this value to identify a single event. For example, you can use the ID as a primary key to retrieve log data from a searchable database.
    type: string
  - name: eventName
    required: true
    description: The requested action, which is one of the actions in the API for that service.
    type: string
  - name: eventSource
    required: true
    description: The service that the request was made to. This name is typically a short form of the service name without spaces plus .amazonaws.com.
    type: string
  - name: eventTime
    required: true
    description: The date and time the request was made, in coordinated universal time (UTC).
    type: timestamp
    timeFormat: rfc3339
    isEventTime: true
  - name: eventType
    required: true
    description: 'Identifies the type of event that generated the event record. This can be the one of the following values: AwsApiCall, AwsServiceEvent, AwsConsoleSignIn'
    type: string
  - name: eventVersion
    required: true
    description: The version of the log event format.
    type: string
  - name: managementEvent
    description: 'A Boolean value that identifies whether the event is a management event. managementEvent is shown in an event record if eventVersion is 1.06 or higher, and the event type is one of the following: AwsApiCall, AwsConsoleAction, AwsConsoleSignIn,  AwsServiceEvent'
    type: boolean
  - name: readOnly
    description: Identifies whether this operation is a read-only operation.
    type: boolean
  - name: recipientAccountId
    description: Represents the account ID that received this event. The recipientAccountID may be different from the CloudTrail userIdentity Element accountId. This can occur in cross-account resource access.
    type: string
    indicators:
      - aws_account_id
  - name: requestID
    description: The value that identifies the request. The service being called generates this value.
    type: string
  - name: requestParameters
    description: The parameters, if any, that were sent with the request. These parameters are documented in the API reference documentation for the appropriate AWS service.
    type: json
  - name: resources
    description: A list of resources accessed in the event.
    type: array
    element:
      type: object
      fields:
        - name: arn
          description: ARN field
          type: string
          indicators:
            - aws_arn
        - name: accountId
          description: AccountID field
          type: string
          indicators:
            - aws_account_id
        - name: type
          description: Type field
          type: string
  - name: responseElements
    description: The response element for actions that make changes (create, update, or delete actions). If an action does not change state (for example, a request to get or list objects), this element is omitted. These actions are documented in the API reference documentation for the appropriate AWS service.
    type: json
  - name: serviceEventDetails
    description: Identifies the service event, including what triggered the event and the result.
    type: json
  - name: sharedEventID
    description: GUID generated by CloudTrail to uniquely identify CloudTrail events from the same AWS action that is sent to different AWS accounts.
    type: string
  - name: sourceIPAddress
    description: The IP address that the request was made from. For actions that originate from the service console, the address reported is for the underlying customer resource, not the console web server. For services in AWS, only the DNS name is displayed.
    type: string
    indicators:
      - hostname
  - name: userAgent
    description: The agent through which the request was made, such as the AWS Management Console, an AWS service, the AWS SDKs or the AWS CLI.
    type: string
  - name: userIdentity
    required: true
    description: Information about the user that made a request.
    type: object
    fields:
      - name: type
        description: Type field
        type: string
      - name: principalId
        description: PrincipalID field
        type: string
      - name: arn
        description: ARN field
        type: string
        indicators:
          - aws_arn
      - name: accountId
        description: AccountID field
        type: string
        indicators:
          - aws_account_id
      - name: accessKeyId
        description: AccessKeyID field
        type: string
        indicators:
          - trace_id
      - name: userName
        description: Username field
        type: string
        indicators:
          - username
      - name: sessionContext
        description: SessionContext field
        type: object
        fields:
          - name: attributes
            description: Attributes field
            type: object
            fields:
              - name: mfaAuthenticated
                description: MfaAuthenticated field
                type: string
              - name: creationDate
                description: CreationDate field
                type: string
          - name: sessionIssuer
            description: SessionIssuer field
            type: object
            fields:
              - name: type
                description: Type field
                type: string
              - name: principalId
                description: PrincipalID field
                type: string
              - name: arn
                description: Arn field
                type: string
                indicators:
                  - aws_arn
              - name: accountId
                description: AccountID field
                type: string
                indicators:
                  - aws_account_id
              - name: userName
                description: Username field
                type: string
                indicators:
                  - username
          - name: webIdFederationData
            description: WebIDFederationData field
            type: object
            fields:
              - name: federatedProvider
                description: FederatedProvider field
                type: string
              - name: attributes
                description: Attributes field
                type: json
          - name: ec2RoleDelivery
            description: Ec2RoleDelivery field
            type: string
      - name: invokedBy
        description: InvokedBy field
        type: string
      - name: identityProvider
        description: IdentityProvider field
        type: string
  - name: vpcEndpointId
    description: Identifies the VPC endpoint in which requests were made from a VPC to another AWS service, such as Amazon S3.
    type: string
  - name: eventCategory
    description: Shows the event category that is used in LookupEvents calls.
    type: string
  - name: sessionCredentialFromConsole
    description: Shows whether or not an event originated from an AWS Management Console session. It is missing when false
    type: boolean
  - name: edgeDeviceDetails
    description: Shows information about edge devices that are targets of a request.
    type: json
  - name: tlsDetails
    description: Shows information about the Transport Layer Security (TLS) version, cipher suites, and the FQDN of the client-provided host name of a service API call.
    type: object
    fields:
      - name: tlsVersion
        description: The TLS version of a request.
        type: string
      - name: cipherSuite
        description: The cipher suite (combination of security algorithms used) of a request.
        type: string
      - name: clientProvidedHostHeader
        description: The FQDN of the client that made the request.
        type: string

AWS.CloudTrailDigest

AWSCloudTrailDigest contains the names of the log files that were delivered to your S3 bucket during the last hour, the hash values for those log files, and the signature of the previous digest file. For more information, see AWS's documentation on CloudTrail digest file structure.

schema: AWS.CloudTrailDigest
parser:
  native:
    name: AWS.CloudTrailDigest
description: AWSCloudTrailDigest contains the names of the log files that were delivered to your Amazon S3 bucket during the last hour, the hash values for those log files, and the signature of the previous digest file.
referenceURL: https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-log-file-validation-digest-file-structure.html
version: 0
fields:
  - name: awsAccountId
    required: true
    description: The AWS account ID for which the digest file has been delivered.
    type: string
    indicators:
      - aws_account_id
  - name: digestStartTime
    required: true
    description: The starting UTC time range that the digest file covers, taking as a reference the time in which log files have been delivered by CloudTrail.
    type: timestamp
    timeFormat: rfc3339
  - name: digestEndTime
    required: true
    description: The ending UTC time range that the digest file covers, taking as a reference the time in which log files have been delivered by CloudTrail.
    type: timestamp
    timeFormat: rfc3339
    isEventTime: true
  - name: digestS3Bucket
    required: true
    description: The name of the Amazon S3 bucket to which the current digest file has been delivered.
    type: string
  - name: digestS3Object
    required: true
    description: The Amazon S3 object key (that is, the Amazon S3 bucket location) of the current digest file.
    type: string
  - name: newestEventTime
    description: The UTC time of the most recent event among all of the events in the log files in the digest.
    type: timestamp
    timeFormat: rfc3339
  - name: oldestEventTime
    description: The UTC time of the oldest event among all of the events in the log files in the digest.
    type: timestamp
    timeFormat: rfc3339
  - name: previousDigestS3Bucket
    description: The Amazon S3 bucket to which the previous digest file was delivered.
    type: string
  - name: previousDigestS3Object
    description: The Amazon S3 object key (that is, the Amazon S3 bucket location) of the previous digest file.
    type: string
  - name: previousDigestHashValue
    description: The hexadecimal encoded hash value of the uncompressed contents of the previous digest file.
    type: string
    indicators:
      - sha256
  - name: previousDigestHashAlgorithm
    description: The name of the hash algorithm that was used to hash the previous digest file.
    type: string
  - name: previousDigestSignature
    description: The hexadecimal encoded signature of the previous digest file.
    type: string
  - name: digestPublicKeyFingerprint
    required: true
    description: The hexadecimal encoded fingerprint of the public key that matches the private key used to sign this digest file.
    type: string
  - name: digestSignatureAlgorithm
    required: true
    description: The algorithm used to sign the digest file.
    type: string
  - name: logFiles
    required: true
    description: Log files delivered in this digest
    type: array
    element:
      type: object
      fields:
        - name: s3Bucket
          required: true
          description: The name of the Amazon S3 bucket for the log file.
          type: string
        - name: s3Object
          required: true
          description: The Amazon S3 object key of the current log file.
          type: string
        - name: hashValue
          required: true
          description: The hexadecimal encoded hash value of the uncompressed log file content.
          type: string
          indicators:
            - sha256
        - name: hashAlgorithm
          required: true
          description: The hash algorithm used to hash the log file.
          type: string
        - name: newestEventTime
          required: true
          description: The UTC time of the most recent event among the events in the log file.
          type: timestamp
          timeFormat: rfc3339
        - name: oldestEventTime
          required: true
          description: The UTC time of the oldest event among the events in the log file.
          type: timestamp
          timeFormat: rfc3339

AWS.CloudTrailInsight

AWSCloudTrailInsight represents the content of a CloudTrail Insight event record S3 object. For more information, see AWS's documentation on CloudTrail log events.

schema: AWS.CloudTrailInsight
parser:
  native:
    name: AWS.CloudTrailInsight
description: AWSCloudTrailInsight represents the content of a CloudTrail Insight event record S3 object.
referenceURL: https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference.html
version: 0
fields:
  - name: eventVersion
    required: true
    description: The version of the log event format.
    type: string
  - name: eventTime
    required: true
    description: The date and time the request was made, in coordinated universal time (UTC).
    type: timestamp
    timeFormat: rfc3339
    isEventTime: true
  - name: awsRegion
    required: true
    description: The AWS region that the request was made to, such as us-east-2.
    type: string
  - name: eventId
    required: true
    description: GUID generated by CloudTrail to uniquely identify each event. You can use this value to identify a single event. For example, you can use the ID as a primary key to retrieve log data from a searchable database.
    type: string
  - name: eventType
    required: true
    description: 'Identifies the type of event that generated the event record. This can be the one of the following values: AwsApiCall, AwsServiceEvent, AwsConsoleSignIn'
    type: string
  - name: recipientAccountId
    description: Represents the account ID that received this event. The recipientAccountID may be different from the CloudTrail userIdentity Element accountId. This can occur in cross-account resource access.
    type: string
    indicators:
      - aws_account_id
  - name: sharedEventId
    required: true
    description: A GUID that is generated by CloudTrail Insights to uniquely identify an Insights event. sharedEventID is common between the start and the end Insights events.
    type: string
    indicators:
      - trace_id
  - name: insightDetails
    required: true
    description: Shows information about the underlying triggers of an Insights event, such as event source, statistics, API name, and whether the event is the start or end of the Insights event.
    type: object
    fields:
      - name: state
        required: true
        description: Shows whether the event represents the start or end of the insight (the start or end of unusual activity). Values are Start or End.
        type: string
      - name: eventSource
        required: true
        description: The AWS API for which unusual activity was detected.
        type: string
      - name: eventName
        required: true
        description: The AWS API for which unusual activity was detected.
        type: string
      - name: insightType
        required: true
        description: The type of Insights event. Value is ApiCallRateInsight.
        type: string
      - name: insightContext
        description: Data about the rate of calls that triggered the Insights event compared to the normal rate of calls to the subject API per minute.
        type: object
        fields:
          - name: statistics
            description: A container for data about the typical average rate of calls to the subject API by an account, the rate of calls that triggered the Insights event, and the duration, in minutes, of the Insights event.
            type: object
            fields:
              - name: baseline
                description: Shows the typical average rate of calls to the subject API by an account within a specific AWS Region.
                type: object
                fields:
                  - name: average
                    description: Average value for the insight metric
                    type: float
              - name: insight
                description: Shows the unusual rate of calls to the subject API that triggers the logging of an Insights event.
                type: object
                fields:
                  - name: average
                    description: Average value for the insight metric
                    type: float
              - name: insightDuration
                description: The duration, in minutes, of an Insights event (the time period from the start to the end of unusual activity on the subject API). insightDuration only occurs in end Insights events.
                type: float
  - name: eventCategory
    required: true
    description: Shows the event category that is used in LookupEvents calls. In Insights events, the value is insight.
    type: string