Okta Logs

Panther supports pulling logs directly from Okta

Overview

Panther has the ability to fetch Okta events by querying the Okta System Log API. Panther will query the System Log API every 1 minute. In order for Panther to access the API you need to create a new API token or use an existing one.

You can also enable Okta user and device profiles.

Video Walkthrough

Video walkthrough showing how to onboard Okta logs to Panther

How to Onboard Okta logs to Panther

Step 1: Create a new Okta API token

To create an Okta API token with permissions to query System Logs, you must be logged in as one of the following types of Okta administrator: a super administrator, organization administrator, or read-only administrator.

See Okta's documentation for more information on managing administrator roles.

1. Log in as Okta administrator.

2. In the Okta Admin Console, navigate to Security > API.

3. Click Create Token.

4. Enter a memorable name for your token, e.g. Panther API token

5. Copy the Token value and store it in a secure location. You will need it in the next steps.

   • Note: Okta will not display this value again.

Step 2: Create a new Okta source in Panther

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

2. Click Create New.

3. Select Okta from the list of available log sources. Click Start Source Setup.

4. Fill in the following fields:

   • Name: Enter a descriptive name for the source e.g. My Okta logs.

   • Okta subdomain: Enter the subdomain of your Okta organization domain. You can refer to Okta documentation to find out more about your Okta org domain.

   • Okta domain: Select the appropriate domain name from the Okta domain drop-down.

   • API Token: Enter the token value from the previous section of our documentation.

   • Log Types: Select the log types you would like to monitor.

   • Enable user profiles: Select to retrieve user profile information.

     • Refresh period (min): Set the frequency at which you'd like to retrieve profile updates.

     Pulling Okta user profiles is in closed beta starting with Panther version 1.69.

   • Enable device profiles: select to retrieve device profile information. (Note the prerequisite for enabling Okta device profiles.)

     • Refresh period (min): Set the frequency at which you'd like to retrieve profile updates.

     Pulling Okta device profiles is in closed beta starting with Panther version 1.69.

5. Click Setup. You will be directed to a success screen:

   

   • You can optionally enable one or more Detection Packs.

   • The Trigger an alert when no events are processed setting defaults to YES. We recommend leaving this enabled, as you will be alerted if data stops flowing from the log source after a certain period of time. The timeframe is configurable, with a default of 24 hours.

     

Panther-Built Detections

See the Panther-built rules and investigative queries for Okta in panther-analysis in Github.

• Okta Admin Role Assigned - A user has been granted administrative privileges in Okta

• Okta API Key Created - A user created an API Key in Okta

• Okta API Key Revoked - A user has revoked an API Key in Okta

• Geographically Improbable Okta Login - A user has subsequent logins from two geographic locations that are very far apart

• Okta MFA Globally Disabled - Okta system-wide MFA has been disabled by an Admin user

• Okta Support Reset Credential - Okta Support reset a password or MFA for a user

• Okta Support Access Granted - Okta support access was granted

Have other Okta detections that can be used by other customers? Consider sharing detections back to the Panther Analysis repository or work with your Customer Success team!

Custom Detections

Suspicious Behavior Reported

Description: A user has reported suspicious behavior from their account

def rule(event):
    if event.get('eventtype') == 'user.account.report_suspicious_activity_by_enduser':
        return True

Below are some common functions and example deep_get() uses when writing custom detections for Okta. Explanations on different event types can be found in the Okta documentation.

#Okta has many event types that are listed here. You can begin your detection based on one of these eventtypes
#https://developer.okta.com/docs/reference/api/event-types/
event.get('eventtype')

#To access the city, state, lat, lon etc. 
deep_get(event, 'client', 'geographicalContext', 'city')
deep_get(event, 'client', 'geographicalContext', 'state')
deep_get(event, 'client', 'geographicalContext', 'country')
deep_get(event, 'client', 'geographicalContext', 'geolocation', 'lon')
deep_get(event, 'client', 'geographicalContext', 'geolocation', 'lat')

#Details on the source of the event
deep_get(event, 'client' 'device')
deep_get(event, 'client', 'ipAddress')
deep_get(event, 'client', 'userAgent')


deep_get(event, 'actor', 'alternateId')
deep_get(event, 'actor', 'displayName')

## Global helpers that may be useful with Okta

# within panther_base_helpers
def okta_alert_context(event: dict):
    """Returns common context for automation of Okta alerts"""
    return {
        "ips": event.get("p_any_ip_addresses", []),
        "actor": event.get("actor", ""),
        "target": event.get("target", ""),
        "client": event.get("client", ""),
    }
    
# within panther_base_helpers
def is_ip_in_network(ip_addr, networks):
    """Check that a given IP is within a list of IP ranges"""
    return any(ip_address(ip_addr) in ip_network(network) for network in networks)

Supported log types

Okta.SystemLog

The Okta System Log records system events related to your organization in order to provide an audit trail that can be used to understand platform activity and to diagnose problems.

Reference: Okta Documentation on System Log APIs.

schema: Okta.SystemLog
description: |
    The Okta System Log records system events related to your organization in order to provide an audit trail that can be used to understand platform activity and to diagnose problems.
referenceURL: https://developer.okta.com/docs/reference/api/system-log/
fields:
    - name: uuid
      required: true
      description: Unique identifier for an individual event
      type: string
    - name: published
      required: true
      description: Timestamp when event was published
      type: timestamp
      timeFormat: rfc3339
      isEventTime: true
    - name: eventType
      required: true
      description: Type of event that was published
      type: string
    - name: version
      required: true
      description: Versioning indicator
      type: string
    - name: severity
      required: true
      description: 'Indicates how severe the event is: DEBUG, INFO, WARN, ERROR'
      type: string
    - name: legacyEventType
      description: Associated Events API Action objectType attribute value
      type: string
    - name: displayMessage
      description: The display message for an event
      type: string
    - name: actor
      description: Describes the entity that performed an action
      type: object
      fields:
        - name: id
          required: true
          description: ID of actor
          type: string
        - name: type
          required: true
          description: Type of actor
          type: string
        - name: alternateId
          description: Alternative id of the actor
          type: string
          indicators:
            - email
        - name: displayName
          description: Display name of the actor
          type: string
        - name: details
          description: Details about the actor
          type: json
        - name: detailEntry
          description: Detail entry
          type: json
    - name: client
      description: The client that requested an action
      type: object
      fields:
        - name: id
          description: For OAuth requests this is the id of the OAuth client making the request. For SSWS token requests, this is the id of the agent making the request.
          type: string
        - name: userAgent
          description: The user agent used by an actor to perform an action
          type: object
          fields:
            - name: browser
              description: If the client is a web browser, this field identifies the type of web browser (e.g. CHROME, FIREFOX)
              type: string
            - name: os
              description: The Operating System the client runs on (e.g. Windows 10)
              type: string
            - name: rawUserAgent
              description: A raw string representation of the user agent, formatted according to section 5.5.3 of HTTP/1.1 Semantics and Content. Both the browser and the OS fields can be derived from this field.
              type: string
        - name: geographicalContext
          description: The physical location where the client made its request from
          type: object
          fields:
            - name: geolocation
              description: Contains the geolocation coordinates (latitude, longitude)
              type: object
              fields:
                - name: lat
                  description: Latitude
                  type: float
                - name: lon
                  description: Longitude
                  type: float
            - name: city
              description: The city encompassing the area containing the geolocation coordinates, if available (e.g. Seattle, San Francisco)
              type: string
            - name: state
              description: Full name of the state/province encompassing the area containing the geolocation coordinates (e.g. Montana, Incheon)
              type: string
            - name: country
              description: Full name of the country encompassing the area containing the geolocation coordinates (e.g. France, Uganda)
              type: string
            - name: postalCode
              description: Full name of the country encompassing the area containing the geolocation coordinates (e.g. France, Uganda)
              type: string
        - name: zone
          description: The name of the Zone that the client's location is mapped to
          type: string
        - name: ipAddress
          description: Ip address that the client made its request from
          type: string
          indicators:
            - ip
        - name: device
          description: Type of device that the client operated from (e.g. Computer)
          type: string
    - name: request
      description: The request that initiated an action
      type: object
      fields:
        - name: ipChain
          description: If the incoming request passes through any proxies, the IP addresses of those proxies will be stored here in the format (clientIp, proxy1, proxy2, ...).
          type: array
          element:
            type: object
            fields:
                - name: ip
                  description: IP address
                  type: string
                  indicators:
                    - ip
                - name: geographicalContext
                  description: Geographical context of the IP address
                  type: object
                  fields:
                    - name: geolocation
                      description: Contains the geolocation coordinates (latitude, longitude)
                      type: object
                      fields:
                        - name: lat
                          description: Latitude
                          type: float
                        - name: lon
                          description: Longitude
                          type: float
                    - name: city
                      description: The city encompassing the area containing the geolocation coordinates, if available (e.g. Seattle, San Francisco)
                      type: string
                    - name: state
                      description: Full name of the state/province encompassing the area containing the geolocation coordinates (e.g. Montana, Incheon)
                      type: string
                    - name: country
                      description: Full name of the country encompassing the area containing the geolocation coordinates (e.g. France, Uganda)
                      type: string
                    - name: postalCode
                      description: Full name of the country encompassing the area containing the geolocation coordinates (e.g. France, Uganda)
                      type: string
                - name: version
                  description: IP version
                  type: string
                - name: source
                  description: Details regarding the source
                  type: string
    - name: outcome
      description: The outcome of an action
      type: object
      fields:
        - name: result
          description: 'Result of the action: SUCCESS, FAILURE, SKIPPED, ALLOW, DENY, CHALLENGE, UNKNOWN'
          type: string
        - name: reason
          description: Reason for the result, for example INVALID_CREDENTIALS
          type: string
    - name: target
      description: Zero or more targets of an action
      type: array
      element:
        type: object
        fields:
            - name: id
              required: true
              description: ID of target
              type: string
            - name: type
              required: true
              description: Type of target
              type: string
            - name: alternateId
              description: Alternative id of the target
              type: string
            - name: displayName
              description: Display name of the target
              type: string
            - name: details
              description: Details about the target
              type: json
            - name: detailEntry
              description: Detail entry
              type: json
    - name: transaction
      description: The transaction details of an action
      type: object
      fields:
        - name: id
          description: Unique identifier for this transaction.
          type: string
        - name: type
          description: Describes the kind of transaction. WEB indicates a web request. JOB indicates an asynchronous task.
          type: string
        - name: detail
          description: Details for this transaction.
          type: json
    - name: debugContext
      description: The debug request data of an action
      type: object
      fields:
        - name: debugData
          description: Dynamic field containing miscellaneous information dependent on the event type.
          type: json
    - name: authenticationContext
      description: The authentication data of an action
      type: object
      fields:
        - name: authenticationProvider
          description: The system that proves the identity of an actor using the credentials provided to it
          type: string
        - name: authenticationStep
          description: The zero-based step number in the authentication pipeline. Currently unused and always set to 0.
          type: int
        - name: credentialProvider
          description: A credential provider is a software service that manages identities and their associated credentials. When authentication occurs via credentials provided by a credential provider, that credential provider will be recorded here.
          type: string
        - name: credentialType
          description: The underlying technology/scheme used in the credential
          type: string
        - name: issuer
          description: The specific software entity that created and issued the credential.
          type: object
          fields:
            - name: id
              description: Varies depending on the type of authentication. If authentication is SAML 2.0, id is the issuer in the SAML assertion. For social login, id is the issuer of the token.
              type: string
            - name: type
              description: Information regarding issuer and source of the SAML assertion or token.
              type: string
        - name: externalSessionId
          description: A proxy for the actor's session ID
          type: string
        - name: interface
          description: The third party user interface that the actor authenticates through, if any.
          type: string
        - name: authenticatorProvider
          description: 'DEPRECATED: This field is kept here for backwards compatibility.'
          type: string
    - name: securityContext
      description: The security data of an action
      type: object
      fields:
        - name: asNumber
          description: Autonomous system number associated with the autonomous system that the event request was sourced to
          type: bigint
        - name: asOrg
          description: Organization associated with the autonomous system that the event request was sourced to
          type: string
        - name: isp
          description: Internet service provider used to sent the event's request
          type: string
        - name: domain
          description: The domain name associated with the IP address of the inbound event request
          type: string
          indicators:
            - domain
        - name: isProxy
          description: Specifies whether an event's request is from a known proxy
          type: boolean