Forcepoint ONE SSE Log Export REST API allows customers to query and pull Cloud and Access Logs.
For authorizing users, refer to Configuring API authentication.
All calls require the following:
URL: https://portal.bitglass.com/api/bitglassapi/logs/v1/
| Parameter Name | Value | Description | Notes | Cloud | Access | Web Proxy | Web DLP | Health |
|---|---|---|---|---|---|---|---|---|
| startdate | datetime | Specifies the start datetime for which the logs need to be returned. The first request must always include this parameter | UTC | X | X | X | X | X |
| responseformat | Specifies the format in which the user expects the response Acceptable values are: "json" "csv" | Default - csv | X | X | X | X | X | |
| type | string | Specifies the type of logs to be fetched.Acceptable values are: "cloudsummary", "cloudaudit", " access", "admin", "swgweb", "swgwebdlp", "healthproxy", "healthapi", "healthsystem" | X | X | X | X | X | |
| nextpagetoken | string | Should be a part of subsequent requests after the first one. Opaque token used for pagination. | X | X | X | X | X | |
| cv (collector version) | string | Is required to specify the version of the log collector. | X | X | X | X | X |
{
"status": "...",
"nextpagetoken": "...",
"response": {
"dataformat": "...",
"dataencoding": "...",
"data": [...]
}
}
| Key | Description |
|---|---|
| status | Success, Unauthorized |
| nextpagetoken | Pagination token |
| response | container for response |
| dataformat | csv or json |
| dataencoding | utf-8 |
| data | Described in Data Keys table below |
| Key | Description | Notes | Cloud (API) | Access (Proxy) | Admin | Web Proxy | Web DLP | Health | API Version |
|---|---|---|---|---|---|---|---|---|---|
| syslogheader | Syslog header | X | X | X | 1.0.1 | ||||
| filename | Name of the file scanned via the application api | X | X | X | 1.0.1 | ||||
| time | Log creation time - UTC | YYYY-MM-DDThh:mm:ssZ | X | X | X | X | X | X | 1.0.1 |
| size | Size of the file | X | 1.0.1 | ||||||
| owner | Owner of the file | Owner's email address | X | X | 1.0.1 | ||||
| application | The application to which the file belongs | X | X | X | X | X | X | 1.0.1 | |
| status |
Current status of the file. Can have below values "Private", "Public", "Internal", "External", "DLP", "Renamed", "Moved" |
X | 1.0.1 | ||||||
| action |
The action enforced by Forcepoint ONE SSE according to the set policy. Can have values "Allowed", "Quarantined", "Alert", "NotifyAdmin", "NotifyOwner" |
X | X | X | X | X | 1.0.1 | ||
| folder | The location of the file | X | 1.0.1 | ||||||
| fileid | The unique id for identifying a file. Can be used to dedup logs. | X | X | 1.0.1 | |||||
| patterns | DLP patterns matched with the file along with the keywords matched for each file. | for example, Sensitive Keywords (confidential) | X | 1.0.1 | |||||
| filelink | Link to view the file. | X | 1.0.1 | ||||||
| sharedwith | Users with whom the current file is shared | X | 1.0.1 | ||||||
| user | Name of the Forcepoint ONE SSE user initiating the transaction | X | X | X | 1.0.1 | ||||
| Email of the Forcepoint ONE SSE user initiating the transaction | X | X | X | X | X | 1.0.1 | |||
| device | OS and Version parsed from user agent by cloud dataplane | need version 1.1.0 for web dlp logs | X | X | X | X | 1.0.1 | ||
| ipaddress | Device IP Address of the user internal to the customers network | X | X | X | X | X | 1.0.1 | ||
| location | Location of the user | X | X | X | 1.0.1 | ||||
| activity |
Specifies the activity that the user performs. Can have values: Access, Accounts, Attachment, Downloaded, Email, Edit, Files, Report, Uploaded, Users etc. |
X | X | X | 1.0.1 | ||||
| useragent | User agent string | X | X | X | X | X | 1.0.1 | ||
| request | X | X | 1.0.1 | ||||||
| transactionid | Unique identifier for every transaction. Can be used to dedup logs. | need version 1.1.0 for web dlp logs | X | X | X | X | 1.0.1 | ||
| emailfrom | Email address of the user sending the email | X | X | 1.0.1 | |||||
| emailto | Email addresses of the recipients | X | X | 1.0.1 | |||||
| emailsubject | Email subject | X | X | 1.0.1 | |||||
| emailcc | Email address of the recipients in CC | X | X | 1.0.1 | |||||
| emailbcc | Email addresses of the recipients in Bcc | X | X | 1.0.1 | |||||
| emailsenttime | The time the email was sent | X | X | 1.0.1 | |||||
| filename | The name of the file | X | 1.0.1 | ||||||
| dlppattern | The DLP patterns that matched the content in the file, email subject or body along with the keywords that matched | X | X | X | 1.0.1 | ||||
| pagetitle | X | X | 1.0.1 | ||||||
| url | X | X | X | 1.0.1 | |||||
| orgid | The Salesforce Org ID | X | 1.0.2 | ||||||
| instancename | The App Instance Name the event occurred in. | X | 1.0.2 | ||||||
| activity | Displays the current activity under the cloud audit logs. | X | 1.0.3 | ||||||
| usergroup | List of groups the user belongs to | X | X | X | X | 1.0.4 | |||
| deviceguid | User's device GUID (if applicable) | X | X | X | X | 1.0.4 | |||
| attachments | Lists attachments contained in the event | X | 1.0.5 | ||||||
| dlpmatchlocations | Displays the location of a DLP triggered match | X | 1.0.5 | ||||||
| organization | Displays the organization the file belongs to in Cisco Spark | X | 1.0.6 | ||||||
| copies | Displays the info of the copied file generated from a "create copy" action (filename, owner, path, status, link) | Use Cloud Audit | X | 1.0.7 | |||||
| originalfolder | Displays info about the origin folder of a file that was moved due to a quarantine action | Use Cloud Summary | X | 1.0.8 | |||||
| originalpatterns | Displays the pattern matched that triggered a quarantine action. | Use Cloud Summary | X | 1.0.8 | |||||
| policyid | Displays the policyid of the policy line that was triggered. | Use Cloud Audit | X | X | X | X | 1.0.9 | ||
| arguments | Resuest Args | X | X | 1.1.0 | |||||
| bgcategories | Domain Categories from Forcepoint ONE SSE Shadow IT Discovery Database | X | X | 1.1.0 | |||||
| bgcloudscore | Domain based cloud score from Forcepoint ONE SSE | X | X | 1.1.0 | |||||
| customcategories | Custom categories defined by customer | X | X | 1.1.0 | |||||
| countrycode | Country code based on gateway_ip | X | X | 1.1.0 | |||||
| country | Country based on gateway_ip | X | X | 1.1.0 | |||||
| customlocation | Custom location name | X | X | X | X | 1.1.0 | |||
| city | City based on gateway_ip | X | X | X | 1.1.0 | ||||
| requestdomain | Request domain | X | X | 1.1.0 | |||||
| devicehostname | 1.1.0 | ||||||||
| gatewayip | The public IP of the gateway which Forcepoint ONE SSE sees | X | X | 1.1.0 | |||||
| lat | latitude based on gateway_ip | X | X | 1.1.0 | |||||
| long | Longitude based on gateway_ip | X | X | 1.1.0 | |||||
| requestport | Request Port | X | X | 1.1.0 | |||||
| protocol | Application layer protocol, e.g: http, ftp, etc | X | X | 1.1.0 | |||||
| referrer | Referrer header of request | X | X | 1.1.0 | |||||
| size | Same as downloaded_bytes | X | X | 1.1.0 | |||||
| region | Region based on gateway_ip | X | X | 1.1.0 | |||||
| regioncode | Region code based on gateway_ip | X | X | 1.1.0 | |||||
| requestmethod | HTTP request method Post/Get etc. | X | X | 1.1.0 | |||||
| uploadedbytes | Same as uploaded bytes | X | X | 1.1.0 | |||||
| firstname | First name of the user | X | X | 1.1.0 | |||||
| lastname | Last name of the user | X | X | 1.1.0 | |||||
| url | request URI (URL = domain+URI+args) | X | X | 1.1.0 | |||||
| webcategoryclass | Web Category class | X | X | 1.1.0 | |||||
| webreputation | Web Reputation | X | X | 1.1.0 | |||||
| dlpaction | DLP action | X | 1.1.0 | ||||||
| doctype | Type of the document | X | 1.1.0 | ||||||
| docextension | File extension of the document | X | 1.1.0 | ||||||
| docsha1 | Document SHA1 hash | X | 1.1.0 | ||||||
| docsha256 | Document SHA256 hash | X | 1.1.0 | ||||||
| docmd5 | Document MD5 hash | X | 1.1.0 | ||||||
| keyword | DLP keywords (comma separated string) | X | 1.1.0 | ||||||
| threatindicator | Malware threat indicators | X | 1.1.0 | ||||||
| dlpip | IP from the DLP engine logs | X | 1.1.0 | ||||||
| application | Application accessed over SmartEdge agent | X | X | 1.1.1 | |||||
| requestport | Port user was going over | X | X | 1.1.1 | |||||
| url | URL being accessed | X | X | 1.1.1 | |||||
| policyid | SWG Policy ID hit | X | X | 1.1.1 | |||||
| filename | Name of file that was being uploaded/downloaded | X | 1.1.1 | ||||||
| activity | The activity the user was performing | X | 1.1.1 | ||||||
| classifylabels | Classify label of the file scanned via the application API | Use Cloud Summary | X | 1.1.2 | |||||
| responsecode | HTTPs response code generated by the application or Forcepoint ONE SSE | X | 1.1.4 | ||||||
| httpmethod | The HTTP method being used | X | 1.1.4 | ||||||
| enterprisename | The Slack enterprise name pulled from API logs | X | 1.1.5 | ||||||
| creationtime | Time at which the file was created. | X | 1.1.6 | ||||||
| modificationtime | Last modified time of the file. | X | 1.1.6 | ||||||
| actor | The person who performed the given activity | Use Cloud Audit | X | 1.1.7 | |||||
| actoripaddress | IP address of the actor | Use Cloud Audit | X | 1.1.7 |
To see what specific user Activity's and Action's Forcepoint ONE SSE tracks, view the respective event logs under .
| Response Code | Message | Notes | Cloud | Access |
|---|---|---|---|---|
| 503 | Temporarily unavailable | X | X | |
| 429 | You have exceeded your allowance of 300 requests per day for <log type> logs. Limit will reset at <Current Date +1> 00:00:00+00:00 |
Too many requests. You will need to wait for the limit to reset before proceeding. Information regarding the rate limit can be seen in the X-RateLimit-* headers. X-RateLimit-Limit: max amount of requests allowed X-RateLimit-Remaining: How many requests left X-RateLimit-Reset: Time your limit will reset. |
X | X |
| 403 | Unauthorized | User is not a sysadmin or API livesetting is not enabled for the company | X | X |
| 401 | Invalid credentials | User does not exist or invalid password | X | X |
| 401 | Authorization required | Authorization header missing | X | X |
| 401 | Basic auth required | Authorization is not basic | X | X |
| 400 | Invalid responseformat: <response format>. Supported values: csv, json | Invalid response format | X | X |
| 400 | Start date and nextpagetoken is missing | startdate and nextpagetoken missing | X | X |
| 400 | Provide either the start date or nextpagetoken | Both startdate and nextpagetoken provided | X | X |
| 400 | Invalid type: <type>. Supported types are: cloudsummary, cloudaudit, and access | Invalid value for type | X | X |
| 400 | Invalid start date format <user startdate> Expected format: %Y-%m-%dT%H:%M:%SZ | Invalid start date format | X | X |
| 400 | Invalid next page token | Invalid next page token | X | X |
| 200 | Request was successful | X | X |