SaaS Security Administrator's Guide
    : Log Events API
    Focus
    Download PDF
    Focus
    1. Home
    2. SaaS Security
    3. SaaS Security Administrator's Guide
    4. Data Security
    5. Syslog and API Client Integration on Data Security
    6. API Client Integration on Data Security
    7. API References on Data Security
    8. Log Events API
    Download PDF

    SaaS Security Administrator's Guide

    Log Events API

    Table of Contents

    Log Events API

    Learn about each example response and available response fields for log events retrieved by an API client for Data Security.
    A registered API client on Data Security can long poll the log events endpoint to retrieve events as they occur:
    You can retrieve the following log events:
    All requests must use the region-specific host. The examples below use AMER region.

    Get Log Events

    A GET request to the /api/v1/log_events endpoint with api_access scope is used to access the client’s event stream. One event will be returned for each call or nothing when there is a Request Timeout.
    Example Request
    $ curl 'https://api.aperture.paloaltonetworks.com/api/v1/log_events' -i -H 

'Authorization: Bearer 

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzY29wZSI6WyJhcGlfYWNjZXNzIl0sImp0aSI6IjA5ZjljN 

DVkLTA1NTYtNDY4MS05YWFhLWM4MGNiNWQ5ZjRiYSIsInRlbmFudCI6InRlc3QgdGVuYW50IiwiY2xpZW50X2l 

kIjoiYWNtZSJ9.lQpl3taZros7xzQNVMRaOy7KIrKGkwNKmTPq667kJUQ' -H 'Accept: 

application/json'
    Example Request Body
    GET /api/v1/log_events HTTP/1.1 

Authorization: Bearer 

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzY29wZSI6WyJhcGlfYWNjZXNzIl0sImp0aSI6IjA5ZjljN 

DVkLTA1NTYtNDY4MS05YWFhLWM4MGNiNWQ5ZjRiYSIsInRlbmFudCI6InRlc3QgdGVuYW50IiwiY2xpZW50X2l 

kIjoiYWNtZSJ9.lQpl3taZros7xzQNVMRaOy7KIrKGkwNKmTPq667kJUQ 

Accept: application/json 

Host: api.aperture.paloaltonetworks.com

    Request Timeout

    Requests time out after 20 seconds and an http response with code 204 is returned. After receiving the response, you can initiate a new request.
    Example Request
    $ curl 'https://api.aperture.paloaltonetworks.com/api/v1/log_events' -i -H 

'Authorization: Bearer 

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzY29wZSI6WyJhcGlfYWNjZXNzIl0sImp0aSI6IjA5ZjljN 

DVkLTA1NTYtNDY4MS05YWFhLWM4MGNiNWQ5ZjRiYSIsInRlbmFudCI6InRlc3QgdGVuYW50IiwiY2xpZW50X2l 

kIjoiYWNtZSJ9.lQpl3taZros7xzQNVMRaOy7KIrKGkwNKmTPq667kJUQ' -H 'Accept: 

application/json'
    Example Request Body
    GET /api/v1/log_events HTTP/1.1 

Authorization: Bearer 

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzY29wZSI6WyJhcGlfYWNjZXNzIl0sImp0aSI6IjA5ZjljN 

DVkLTA1NTYtNDY4MS05YWFhLWM4MGNiNWQ5ZjRiYSIsInRlbmFudCI6InRlc3QgdGVuYW50IiwiY2xpZW50X2l 

kIjoiYWNtZSJ9.lQpl3taZros7xzQNVMRaOy7KIrKGkwNKmTPq667kJUQ 

Accept: application/json 

Host: api.aperture.paloaltonetworks.com
    Example Response
    HTTP/1.1 204 No Content 

Content-Type: application/json; charset=utf-8 

x-response-time: 1019ms
    There is no response body in the response of a request timeout.

    Activity Monitoring

    Example Response
    HTTP/1.1 200 OK 

X-Content-Type-Options: nosniff 

X-XSS-Protection: 1; mode=block 

Cache-Control: no-cache, no-store, max-age=0, must-revalidate 

Pragma: no-cache 

Expires: 0 

X-Frame-Options: DENY 

X-Application-Context: public_api:test:0 

Content-Type: application/json;charset=UTF-8 

Transfer-Encoding: chunked 

Date: Fri, 17 Feb 2017 00:18:59 GMT 

Content-Length: 361 

{ 

"log_type" : "activity_monitoring", 

"item_type" : "File", 

"item_name" : "My File", 

"user" : "John Smith", 

"source_ip" : "10.10.10.10", 

"location" : "Somewhere, USA", 

"action" : "delete", 

"target_name" : null, 

"target_type" : null, 

"serial" : "mySerial", 

"cloud_app_instance" : "My Cloud App", 

"timestamp" : "2017-02-17T00:18:58.961Z" 

}
    Response Fields
    Path
    Type
    Description
    log_type
    String
    Event type.
    item_type
    String
    Item type (File, Folder, or User)
    item_name
    String
    Name of the file, folder, or user associated with the event.
    item_unique_id
    String
    Unique ID number for an asset’s related asset.
    user
    String
    Cloud app user that performed the action.
    source_ip
    String
    Original session source IP address.
    location
    String
    Location of the cloud app user that performed the event.
    action
    String
    Action performed.
    target_name
    Null
    Target name.
    target_type
    Null
    Target type.
    serial
    String
    Serial number of the organization using the service (tenant).
    cloud_app_instance
    String
    Cloud app name (not cloud app type).
    timestamp
    String
    ISO8601 timestamp to show when the event occurred.

    Incidents

    Example Response
    HTTP/1.1 200 OK 

X-Content-Type-Options: nosniff 

X-XSS-Protection: 1; mode=block 

Cache-Control: no-cache, no-store, max-age=0, must-revalidate 

Pragma: no-cache 

Expires: 0 

X-Frame-Options: DENY 

X-Application-Context: public_api:test:0 

Content-Type: application/json;charset=UTF-8 

Transfer-Encoding: chunked 

Date: Fri, 17 Feb 2017 00:18:58 GMT 

Content-Length: 520 

{ 

"log_type": "incident",

"severity": 1.0, 
	
"item_type": "File", 

"item_name": "helloworld.java", 

"asset_id": "5e9e38823cedb43cb015b460", 

"item_owner": "Admin User",  

"container_name": null, 

"item_creator": "Admin User", 

"exposure": "COMPANY", 

"occurrences_by_rule": null, 

"item_owner_email": "owner@emaildomain.com",

"item_creator_email": "owner@emaildomain.com", 

"serial": null, 

"cloud_app_instance": "Office 365 8", 

"timestamp": "2020-05-08T23:50:55Z",

"incident_id": "5eb5ed492021c32b37588a6c", 

"policy_rule_name": "java", 

"incident_category": null,

"incident_owner": null, 

"collaborators": "", 

"datetime_edited": "2020-05-08T23:50:55Z", 

*"item_cloud_url": "https://www.sharepoint.com/sites/site/Shared%20Documents/foldername/helloworld.java", 

"item_owner_group": "O365_1_all", 

"item_sha256": "4953946b0bbcd10d872d09561bf0f0988e186b625e4af65c64691adf5af279d4", 

"item_size": 1335, 

"item_verdict": "not available"*

}
    Response Fields
    Path
    Type
    Description
    log_type
    String
    Event type.
    severity
    Number
    Incident severity. Values are 0 to 5.
    item_type
    String
    Item type (File, Folder, or User)
    item_name
    String
    Name of the file, folder, email subject, or user associated with the event.
    item_unique_id
    String
    Unique ID number for an asset’s related asset.
    asset_id
    String
    Unique ID number for the asset identified as a risk.
    item_owner
    String
    User who owns the asset identified as a risk.
    container_name
    String
    Value of bucket name for AWS S3, Google Cloud Platform, and Microsoft Azure assets. Value is null for the remaining apps.
    item_creator
    String
    User who created the asset identified as a risk.
    exposure
    String
    Exposure level (Public, External, Company, or Internal)
    occurrences_by_rule
    Number
    Number of times the asset violated the policy.
    item_owner_email
    String
    Email address of the item owner.
    item_creator_email
    String
    Email address of the item creator.
    serial
    String
    Serial number of the organization using the service (tenant)
    cloud_app_instance
    String
    Cloud app name (not cloud app type).
    timestamp
    String
    ISO8601 timestamp to show when the event occurred.
    incident_id
    String
    Unique ID number for the incident.
    policy_rule_name
    String
    Names of one or more policy rules (not policy types) that were matched.
    incident_category
    String
    Category of the incident. For example, Personal or Business Justified.
    incident_owner
    String
    Administrator assigned to the incident.
    collaborators
    String
    List of collaborators for file, or recipients of email.
    datetime_edited
    String
    Last time file was edited.
    item_cloud_url
    String
    File URL associated with the incident and used to download or view the asset.
    item_owner_group
    String
    AD groups to which the asset owner belongs.
    item_sha256
    String
    File in sha256 hash, as reported by WildFire.
    item_size
    String
    Size of the file as reported by WildFire.
    item_verdict
    String
    Verdict as reported by WildFire: either malware, benign, or not available.

    Remediation

    Example Response
    HTTP/1.1 200 OK 

X-Content-Type-Options: nosniff 

X-XSS-Protection: 1; mode=block 

Cache-Control: no-cache, no-store, max-age=0, must-revalidate 

Pragma: no-cache 

Expires: 0 

X-Frame-Options: DENY 

X-Application-Context: public_api:test:0 

Content-Type: application/json;charset=UTF-8 

Transfer-Encoding: chunked 

Date: Fri, 17 Feb 2017 00:18:56 GMT 

Content-Length: 468 

{ 

"log_type" : "remediation", 

"item_type" : "File", 

"item_name" : "My File", 

"asset_id" : "ce7c9ed11e6f4891ae73c1601af7f741", 

"item_owner" : "John Smith", 

"item_creator" : "John Smith"

"container_name": "test-container",

"action_taken" : "quarantine", 

"action_taken_by" : "John Smith", 

"serial" : "mySerial", 

"cloud_app_instance" : "My Cloud App", 

"timestamp" : "2017-02-17T00:18:55.581Z", 

"incident_id" : "9610efdcd8a74a259bf031843eac0309", 

"policy_rule_name" : "PCI Policy"

"item_owner_email": "owner@email-domain.com",

"item_creator_email": "owner@email-domain.com",

}
    Response Fields
    Path
    Type
    Description
    log_type
    String
    Event type.
    item_type
    String
    Item type (File, Folder, or User).
    item_name
    String
    Name of the file, folder, or user associated with the event.
    serial
    String
    Serial number of the organization using the service (tenant).
    cloud_app_instance
    String
    Cloud app name (not cloud app type).
    timestamp
    String
    ISO8601 timestamp to show when the remediation occurred.
    incident_id
    String
    Unique ID number for the remediated incident (risk).
    asset_id
    String
    Unique ID number for the remediated asset.
    item_owner
    String
    User who owns the remediated asset.
    container_name
    		String
    Value of bucket name for AWS S3, Google Cloud Platform, and Microsoft Azure assets. Value is null for the remaining apps.
    item_creator
    String
    User who created the remediated asset.
    policy_rule_name
    String
    Names of one or more policy rules (not policy types) that were matched.
    action_taken
    String
    Action taken to remediate (Admin Quarantine, UserQuarantine, or Remove Public Links).
    action_taken_by
    String
    Cloud app user who took the remediation action. For automated remediation, value is Aperture.
    item_owner_email
    String
    Email address of the item owner.
    item_creator_email
    String
    Email address of the item creator.

    Policy Violation

    Example Resposne
    HTTP/1.1 200 OK 

{ 

"log_type" : "policy_violation", 

"severity" : 3.0, 

"item_type" : "File", 

"item_name" : "My File", 

"item_owner" : "John Smith", 

"item_creator" : "John Smith", 

"action_taken" : "download", 

"action_taken_by" : "John Smith", 

"asset_id" : "ce7c9ed11e6f4891ae73c1601af7f741", 

"serial" : "serial", 

"cloud_app_instance" : "My Cloud App", 

"timestamp" : "2017-01-06T19:04:06Z", 

"policy_rule_name" : "Policy Rule", 

"incident_id" : "9610efdcd8a74a259bf031843eac0309"

"item_owner_email": "owner@email-domain.com",

"item_creator_email": "owner@email-domain.com",
    Response Fields
    Path
    Type
    Description
    log_type
    String
    Event type.
    item_type
    String
    Item type (File, Folder, or User).
    item_name
    String
    Name of the file, folder, or user associated with the event.
    serial
    String
    Serial number of the organization using the service (tenant).
    cloud_app_instance
    String
    Cloud app name (not cloud app type)
    timestamp
    String
    ISO8601 timestamp to show when the policy violation occurred
    incident_id
    String
    Unique ID number for the policy violation incident (risk).
    asset_id
    String
    Unique ID number for the asset which violated the policy.
    item_owner
    String
    User who owns the asset which violated the policy.
    item_creator
    String
    User who created the asset which violated the policy.
    policy_rule_name
    String
    Names of one or more policy rules (not policy types) that were matched.
    action_taken
    String
    Action taken to fix the policy violation. For example, Alerted Admin, Removed PublicLinks, Quarantine, or EmailOwner.
    action_taken_by
    String
    Cloud app user who took the action. For automated remediation, the value is Aperture.
    severity
    Number
    Incident severity. Values are 0 to 5.
    item_owner_email
    String
    Email address of the item owner. This value is null for now.
    item_creator_email
    String
    Email address of the item creator. This value is null for now.

    Admin Audit

    Example Response
    HTTP/1.1 200 OK 

Content-Type: application/json; charset=utf-8 

Content-Length: 380 

x-response-time: 297ms 

{ 

"log_type" : "admin_audit", 

"admin_id" : "admin id", 

"admin_role" : "admin role", 

"ip" : "ip address", 

"event_type" : "event type", 

"item_type" : "File", 

"item_name" : "My File", 

"field" : "field", 

"action" : "action", 

"resource_value_old" : "old val", 

"resource_value_new" : "new val", 

"timestamp" : "2017-04-06T21:35:10.025Z", 

"serial" : "mySerial" 

}
    Response Fields
    Path
    Type
    Description
    log_type
    String
    Event type.
    timestamp
    String
    ISO8601 timestamp to show when the event occurred.
    serial
    String
    Serial number of the organization using the service (tenant).
    admin_id
    String
    Email account associated with the administrative user.
    admin_role
    String
    Role assigned to the administrative user: super_admin, admin, limited_admin, read_only
    ip
    String
    IP address of the administrative user who performed the action.
    event_type
    String
    Type of configuration change event: settings, policy, remediationlogin
    item_type
    String
    Type of item in the configuration that changed: user, apps, settings, content_policy, file, risk, general_settings
    item_name
    String
    Name of the item that changed in the configuration.
    field
    String
    Name of the field associated with the configuration change.
    action
    String
    Configuration change activity that occurred: create, edit, delete, login, logout
    resource_value_old
    String
    Value before the configuration change occurred.
    resource_value_new
    String
    Value after the configuration change occurred.

    © 2024 Palo Alto Networks, Inc. All rights reserved.