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.
For each of the toggles set to ON, set a Refresh period (min). This represents the cadence at which Panther will update profile data with what is stored in Okta.
Click Setup. You will be directed to a success screen:
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.
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.
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: rootSessionId
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
