Exporting logs using API

Forcepoint ONE SSE Log Export REST API allows customers to query and pull Cloud and Access Logs.

  • Cloud (API): Logs generated by cloud apps as seen on the Analyze > Logs > API dashboard page.
    • Cloud Summary: Displays the current status of the files in the applications.
    • Cloud Audit: Displays every scan result for each file in your corporate account.
  • Access (Proxy): Logs generated by application activity as seen on the Analyze > Logs > Proxy dashboard page.
  • Admin: All admin events within the admin portal as seen on the Analyze > Logs > Admin dashboard page.
  • SWG Web: Logs generated from general web traffic from users using the SmartEdge agent, pulls logs from the Analyze > Logs > Web dashboard page.
  • SWG DLP: Logs generated from DLP specific policy actions under the Web Browsing Policy actions as seen on the Analyze > Logs > Web DLP dashboard page.
  • Health: The Health dashboard allows admins to identify if issues that users encounter are brought on by Forcepoint ONE SSE or the backend server (for example, Google, Exchange, Salesforce, etc). You can access the System and Proxy Health Logs by navigating to Analyze > Logs > Health.
  • ZTNA: The ZTNA Logs page is where all the ZTNA events by the end-users are displayed. You can access the ZTNA logs page by navigating to Analyze > Logs > ZTNA.

For authorizing users, refer to Configuring API authentication.

Note: Customers with Splunk or QRadar can instead utilize the Bitglass Splunk App or the Bitglass QRadar App instead to make pulling logs easier. You can learn how to setup each app by going to their respective pages (Integrating Splunk application with Forcepoint ONE SSE or Integrating QRadar application with Forcepoint ONE SSE). Once configured, you will be able to view any of your Forcepoint ONE SSE logs (API, Proxy, Health, Admin, etc) within your app instance.

API Calls

All calls require the following:

  • Method = HTTP POST
  • URI Params define the type of operation and action to perform
    Type:
    • type = access
    • type = cloudsummary
    • type = cloudaudit
    • type = admin
    • type = swgweb
    • type = swgwebdlp
    • type = healthproxy
    • type = healthapi
    • type = healthsystem
  • HTTP body as JSON

    URL: https://portal.bitglass.com/api/bitglassapi/logs/v1/

Query Parameters

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

Response

{
    "status": "...",
    "nextpagetoken": "...",   
    "response": {
        "dataformat": "...",
        "dataencoding": "...",
        "data": [...]
    }
}

Response Keys

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

Data Keys

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 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 Analyze > Logs.

Response Codes

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