Carbon Black App Control is the new name for the product formerly called CB Protection.

Introduction

App Control Public API Reference v1.0 - This document is intended for programmers who want to write code to interact with the App Control Platform using custom scripts or integrate with other applications. The App Control API is a RESTful API that can be consumed over the HTTPS protocol using any language that can issue GET/POST/PUT URI requests and interpret JSON responses.

Versioning

Current version of App Control API is v1. All API calls are based in address https://<your server name>/api/bit9platform/v1. Please check this address for up-to-date information on the APIs available on your server. This document describes the API as of App Control release 8.0.

Authentication

App Control APIs are authenticated through the API token. This token has to be placed inside each HTTP request 'X-Auth-Token' header. The API token is tied to the console user. To obtain the API token, ask the App Control Server administrator to generate special user and token for you. A good practice is to have separate console users with minimum required access controls for each API client.

Access Controls

An API client has the same access level as its corresponding console user. For example, in order to get access to the ‘event’ object, the user associated with API token will need permission to view events. Required permissions are listed with each API in this document. If caller lacks the required permissions, HTTP error 401 - Unauthorized will be returned.

Responses

Successful calls will return either HTTP 200 - OK or HTTP 201 - Created, depending if request modified/deleted an existing object or created a new object, respectively. In case of POST and PUT, the response will contain the body of the modified or created object in the content, and the URI of the created or modified object in URL property of the response. In the case of GET, the response will contain the body of the searched object(s) in the content. Failed calls will return errors in the range 400-599. This is usually one of the following:

• HTTP 400 - Bad request - Usually means that request contains unexpected parameters. More details about error can be found in the response content.
• HTTP 401 - Unauthorized - Either authentication (invalid token) or access control (missing RBAC) error.
• HTTP 403 - Forbidden - Specified object cannot be accessed or changed.
• HTTP 404 - Not found - Object referenced in the request cannot be found.
• HTTP 503 - Service unavailable - Cannot return object at this moment because service is unavailable. This can happen if too many file downloads are happening at the same time. You can try later.

Searching

Searching is done through the GET request, by passing search elements as URL query parts: v1/computer?q=_<query condition 1>_&q=_<query condition 1>_...&group=_<optional group term>_&sort=_<optional sort term>_&offset=_<optional offset>_&offset=_<optional limit>_ The following sections describe these query parts.

Query Condition

Multiple conditions can be added, and each has to be satisfied for the result set. Individual conditions can have one or multiple subconditions, separated with ‘|’ (pipe) symbol. A condition contains three parts: name, operator and value.

• Name is any valid field in the object that is being queried.
• Operator is any of valid operators (see below). All operators consist of a single character.
• Value is compared with operator and depends on field type. Values can be empty to reflect searching for null values and empty strings.

Possible operators are:

• : results in LIKE comparison for strings, and = comparisons for other types. Note that LIKE comparison for strings results in ‘=’ comparison if the string doesn’t contain wildchars. String comparison is case insensitive.
• ! results in NOT LIKE comparison for strings, and <> comparison for other types. Note that NOT LIKE comparison for strings results in ‘<>’ comparison if the string doesn’t contain wildchars. String comparison is case insensitive.
• < Less than - can be used for both strings and numerical values
• > Greater than - can be used for both strings and numerical values
• + logical AND operation (valid only for numerical values). True if value has all bits set as in operand. This can be used to check existence of given flag in a field. Bitwise operations on integer fields cannot use indices and can result in slow queries if done on large datasets.
• - logical NAND operation (valid only for numerical values). True if value has none of the bits in the operand. This can be used to check non-existence of given flag in a field. Bitwise operations on integer fields cannot use indices and can result in slow queries if done on large datasets.
• | separating values with | (pipe) symbol will cause both values to be included in the condition. Example “q=fileName:test1.exe|test2.exe” will match all objects where filename is either test1.exe or test2.exe. Note that negative conditions (- and !) will exclude entries that match either of included values.

Special relative date comparison operator: X[s|m|h|d|w] Indicates relative date to NOW. Units X can be expressed in (s)econds, (m)inutes, (h)ours, (d)ays or (w)eeks. For example, -3w indicates three weeks ago, while 2d indicates two days in the future.

Following characters need to be escaped when used in query conditions to avoid conflicting with reserved characters:

• \ => \\
• | => \|
• * => \*

Example of a complex search filter that uses several described operators and one escape sequence: Search all computers that have ipAddress that (starts with fe00 or ff00) AND have non-empty computer tag AND were created less than 10 hours ago AND have policy name that contains character ‘*'

Request:

[GET] https://myServer/api/bit9platform/v1/Computer?q=ipAddress:fe00*|ff00*&q=computerTag!&q=dateCreated>-10h&q=policyName:*\**

Resulting SQL query condition evaluated:

... WHERE (ipAddress LIKE 'fe00%' OR ipAddress LIKE 'ff00%')
AND computerTag NOT LIKE ''
AND dateCreated>DATEADD(HOUR, -10, GETUTCDATE())
AND policyName LIKE'%*%'

Limiting Results and Getting Result Count

Attributes: &offset=x&limit=y, where x is zero-offset in data set, and y is maximum number of results to retrieve

Special values for limit are:

• If not specified: First 1000 results will be returned.
• If set to -1: Only result count will be returned, without actual results. Offset parameter is ignored in this case.
• If set to 0: All results will be returned. Offset parameter is ignored in this case. Note that some result sets could be very large, resulting in query timeout. Therefore, unless you know that query will not return more than 1000 results, it is recommended to retrieve data in chunks using offset and limit.

Here is an example on how to get result count from a query:

Request:

[GET] https://myServer/api/bit9platform/computer?limit=-1

Response:

{"count": 1284}

Note that the result count returned by the server may be negative. If the result count returned by the server is negative, that means the server timed out attempting to determine the count and the total number of results is greater than the absolute value of the negative count value. For example, if the server returns a count of -1000, that means the number of results for that query is greater than 1,000.

Sorting

Sorting is optional and can be defined with a single attribute: &sort=xyz [ASC|DESC]

• There can be only one sorting field
• Default sort order (if omitted) is ASC
• xyz is field name from the result set

Grouping

Grouping is optional and can be defined with a single attribute: &group=xyz

• There can be only one grouping field
• When grouping is specified, sorting is ignored – output is automatically sorted by grouping field

Output of grouping is always array of objects with value and count fields. “Value” is group field value, and “count” is number of rows that have that name for the grouped field. Here is example:

Request:

[GET] https://myServer/api/bit9platform/v1/Computer?group=osShortName

Response:

[
	{"value": "CentOS 5", "count": 53},
	{"value": "CentOS 6", "count": 826},
	{"value": "Mac", "count": 2311},
	{"value": "Windows 7", "count": 1330}
]

Grouping by Time Windows

Window grouping is special version of grouping that is available only on time-based fields: &group=<field> <sort>&groupType=<type>groupStep=<step>.

• <field> is field to group by. There can be only one grouping field
• <sort> is optional and determines how results are sorted by time. It can be ASC or DESC. Default value is ASC
• <type> is time unit for grouping. can be one of: s,m,h,d,w,n, which are abbreviations for (s)econds, (m)inutes, (h)ours, (d)ays, (w)eeks or mo(n)ths.
• <step> is step of the time window, indicating how many time units to group by. If not supplied, it defaults to 1

Output of grouping is always array of objects with dateFrom, dateTo and count fields. dateFrom and dateTo are start and end of time window, while “count” is number of results in given time window. Note that empty time windows will be listed as well.

Number of results is limited to 5000, and offset/limit can be used in order to get more results in separate queries.

Here is example that returns number of events grouped by 2-month periods:

Request:

[GET] https://myServer/api/bit9platform/v1/event?group=timestamp&groupType=n&groupStep=2

Response:

[
	{"dateFrom":"2014-10-01T00:00:00Z","dateTo":"2014-12-01T00:00:00Z","count":3177},
	{"dateFrom":"2014-12-01T00:00:00Z","dateTo":"2015-02-01T00:00:00Z","count":0},
	{"dateFrom":"2015-02-01T00:00:00Z","dateTo":"2015-04-01T00:00:00Z","count":2069703},
	{"dateFrom":"2015-04-01T00:00:00Z","dateTo":"2015-06-01T00:00:00Z","count":6065022},
	{"dateFrom":"2015-06-01T00:00:00Z","dateTo":"2015-08-01T00:00:00Z","count":462729}
]

Field Expansion

Expanding is a way to get associated foreign-key values for any API entry. It is optional and can be defined with one or more attributes: &expand=<field>

• <field> is field to expand on. It has to be one of foreign keys defined for this object. Separate “expand” parameter can be suplied for the each available foreign key.

Expanding also exposes all fields from the related object, prefixed by foreign key name and underscore (_). You can use the newly exposed fields for grouping and searching as you would use native object fields. Fileds that are eligible for expanding are listed as “foreign keys” for each API object.

For example, expanding on certificateId for fileCatalog will expose additional fields, including: certificateId_name, certificateId_serialNumber.

With certificateId expanded, following request will return the top 100 files that have a certificate with public key size less than 1024:

Request:

[GET] https://myServer/api/bit9platform/v1/fileCatalog?expand=certificateId&q=certificateId_publicKeySize<1024&limit=100

Performance warning: Filtering and grouping on expanded fields is more expensive because it requires underlying SQL Server queries to be more complex. It can slow down API response or, in some cases, cause a response timeout.

Code Examples

Here are several code examples, written in Python 3, using requests and JSON libraries.

Approve Publisher

This code approves publisher with id=12 for all policies

import requests, json
# --- Prepare our request header and url ---
authJson = {
    # replace with actual user token
    'X-Auth-Token': '8F97E8CB-1DCD-40D2-817B-7CECDD79CA67',
    'content-type': 'application/json'
    }
b9StrongCert = True # Set to False if your Server has self-signed IIS certificate
# replace with actual server address
url = 'https://myserver/api/bit9platform/v1/publisher/12'
# --- Here is our request ---

data = { 'publisherState': 2 } # 2 means 'approved'
r = requests.put( url, json.dumps(data), headers=authJson, verify=b9StrongCert)
r.raise_for_status() # Make sure the call succeeded
publisher = r.json()# get resulting publisher object

Ban File per Policy

This code bans file with Md5 hash ‘64a4f54d6863d59f1121a91554b55e9a’ for policies id 10 and 11

import requests, json

# --- Prepare our request header and url ---
authJson = {
    # replace with actual user token
    'X-Auth-Token': '8F97E8CB-1DCD-40D2-817B-7CECDD79CA67',
    'content-type': 'application/json'
    }

# Set to False if your Server has self-signed IIS certificate
b9StrongCert = True

# replace with actual server address
url = 'https://myserver/api/bit9platform/v1/fileRule'

# --- Here is our request ---
data = {
'hash': '64a4f54d6863d59f1121a91554b55e9a',
'fileState': 3, # 3 means 'banned'
'policyIds': '10,11'
}

r = requests.post(url, json.dumps(data), headers=authJson, verify=b9StrongCert)

# Make sure the call succeeded
r.raise_for_status()

# get resulting file rule object
fileRule = r.json()

Disable Tamper Protection for Computers

This code disables tamper protection for computers with IP address starting with 10.201.2, and moves them into policy 8

import requests, json
# --- Prepare our request header and url ---
uthJson = {
    'X-Auth-Token': '8F97E8CB-1DCD-40D2-817B-7CECDD79CA67', # replace with actual user token
    'content-type': 'application/json'
    }
apiUrl = 'https://myserver/api/bit9platform' # replace with actual server address

# Set to False if your Server has self-signed IIS certificate
# Get computers. Here we assume that count is reasonable
# We can get all of them at once (no limit specified)
b9StrongCert = True

comps = requests.get(apiUrl + '/v1/computer?q=ipAddress:10.201.2.*' ,headers=authJson, verify= b9StrongCert).json()

for c in comps:    # For each returned computer...
    c['policyId'] = 8    # Move to policy 8

# Tamper protection can be disabled only through URI:
requests.post(apiUrl + '/v1/computer?newTamperProtectionActive=false', json.dumps(c), headers=authJson, verify=b9StrongCert)

Locally Approve Files

This code locally approves all unapproved files for Windows computer in policy 8, if file prevalence is 10 or greater

import requests, json

# --- Prepare our request header and url ---

authJson = {
    'X-Auth-Token': '8F97E8CB-1DCD-40D2-817B-7CECDD79CA67',    # replace with actual user token
    'content-type': 'application/json'
    }

apiUrl = 'https://myserver/api/bit9platform'    # replace with actual server address
b9StrongCert = True    # Set to False if your Server has self-signed IIS certificate

# Get all Windows computers in policy 8
comps = requests.get(apiUrl + '/v1/computer?q=policyId:8&q=platformId:1', headers=authJson, verify=b9StrongCert).json()

for c in comps: # For each returned computer, get list of locally unapproved files
    files = requests.get( apiUrl + '/v1/fileInstance?q=computerId:' + str(c['id']) + '&q=localState:1',headers=authJson, verify=b9StrongCert).json()

for finst in files: # For each returned file...

# Get its file catalog entry to get prevalence
fcat = requests.get(apiUrl + '/v1/fileCatalog/' + str(finst['fileCatalogId']), headers=authJson,   verify=b9StrongCert).json()

if fcat['prevalence'] >= 10: # if prevalent enough...
    finst['localState'] = 2  # Approve locally
    requests.post(apiUrl + '/v1/fileInstance', json.dumps(finst), headers=authJson, verify=b9StrongCert  )

API Reference

This section lists all API objects and their properties that are listed in table with each object. Some subset of properties for each object are modifiable through POST/PUT requests and those are called in a separate table.

Each API object can have associated GET, PUT, POST or DELETE requests with their individual parameters. GET and DELETE request parameters are entirely passed in the request URI. POST and PUT request parameters accept entire object that is passed in the body of the request (as JSON), and some additional parameters that are passed through the request URI.

ApprovalRequest

v1/approvalRequest object exposes workflow for approval requests and justifications. Note that approvalRequests cannot be created from the API. Only modifications of existing approval requests generated by the endpoint are supported.

All Object Properties for approvalRequest

Properties modifiable Using PUT/POST Request for approvalRequest

POST Request for approvalRequest

Description: Updates approval request

Required permissions: ‘View approval requests’, ‘Manage approval requests’

Call syntax: bit9platform/v1/approvalRequest

PUT Request for approvalRequest

Description: Updates approval request

Required permissions: ‘View approval requests’, ‘Manage approval requests’

Call syntax: bit9platform/v1/approvalRequest/{id}

GET Request for approvalRequest

Description: Returns object instance of this class

Required permissions: ‘View approval requests’

Call syntax: bit9platform/v1/approvalRequest/{id}

GET Request for approvalRequest

Description: Returns objects that match given criteria

Required permissions: ‘View approval requests’

Call syntax: bit9platform/v1/approvalRequest?q={q1}&q={q2}...&group={group}&sort={sort}&offset={offset}&limit={limit}

AppTemplate

v1/appTemplate object exposes appTemplate information. It allows enabling/disabling and changing policyIds.

Properties modifiable Using PUT/POST Request for appTemplate

POST Request for appTemplate

Description: Change appTemplate state

Required permissions: ‘View software rules pages’

Call syntax: bit9platform/v1/appTemplate

PUT Request for appTemplate

Description: Change appTemplate state

Required permissions: ‘View software rules pages’

Call syntax: bit9platform/v1/appTemplate/{id}

GET Request for appTemplate

Description: Returns object instance of this class

Required permissions: ‘View software rules pages’

Call syntax: bit9platform/v1/appTemplate/{id}

GET Request for appTemplate

Description: Returns objects that match given criteria

Required permissions: ‘View software rules pages’

Call syntax: bit9platform/v1/appTemplate?q={q1}&q={q2}...&group={group}&groupType={groupType}&groupStep={groupStep}&sort={sort}&offset={offset}&limit={limit}&expand={expand1}&expand={expand2}...

Certificate

v1/certificate object exposes certificates found on endpoints and allows changing certificate state.

All Object Properties for certificate

Properties modifiable Using PUT/POST Request for certificate

POST Request for certificate

Description: Change certificate state

Required permissions: ‘View software rules pages’, ‘Manage publisher rules’

Call syntax: bit9platform/v1/certificate

PUT Request for certificate

Description: Change certificate state

Required permissions: ‘View software rules pages’, ‘Manage publisher rules’

Call syntax: bit9platform/v1/certificate/{id}

DELETE Request for certificate

Description: Delete certificate approval

Required permissions: ‘View software rules pages’, ‘Manage publisher rules’

Call syntax: bit9platform/v1/certificate/{id}

GET Request for certificate

Description: Returns object instance of this class

Required permissions: ‘View software rules pages’

Call syntax: bit9platform/v1/certificate/{id}

GET Request for certificate

Description: Returns objects that match given criteria

Required permissions: ‘View software rules pages’

Call syntax: bit9platform/v1/certificate?q={q1}&q={q2}...&group={group}&sort={sort}&offset={offset}&limit={limit}

Computer

v1/computer object exposes computer-related properties for App Control Agent. It allows following modifications:

• Moving computers to different policies
• Upgrading App Control Agent
• Templating computers for VDI
• Changing debugging properties of computers
• Requesting advanced computer actions

All Object Properties for computer

Properties modifiable Using PUT/POST Request for computer

POST Request for computer

Description: Updates computer object. Note that some computer properties can be changed only if specific boolean param is set, as noted below.

Required permissions: ‘View computers’, ‘Manage computers’

Call syntax: bit9platform/v1/computer?changeDiagnostics={changeDiagnostics}&changeTemplate={changeTemplate}&delete={delete}&resetCLIPassword={resetCLIPassword}&newTamperProtectionActive={newTamperProtectionActive}

PUT Request for computer

Description: Updates computer object. Note that some computer properties can be changed only if specific boolean param is set, as noted below.

Required permissions: ‘View computers’, ‘Manage computers’

Call syntax: bit9platform/v1/computer/{id}?changeDiagnostics={changeDiagnostics}&changeTemplate={changeTemplate}&delete={delete}&resetCLIPassword={resetCLIPassword}&newTamperProtectionActive={newTamperProtectionActive}

DELETE Request for computer

Description: Delete computer

Required permissions: ‘View computers’, ‘Manage computers’

Call syntax: bit9platform/v1/computer/{id}

GET Request for computer

Description: Returns object instance of this class

Required permissions: ‘View computers’

Call syntax: bit9platform/v1/computer/{id}

GET Request for computer

Description: Returns objects that match given criteria

Required permissions: ‘View computers’

Call syntax: bit9platform/v1/computer?q={q1}&q={q2}...&group={group}&sort={sort}&offset={offset}&limit={limit}

Connector

v1/connector object exposes Network Connectors for App Control Platform. Note that internal connectors can only be accessed as read-only (GET requests), while external connectors can also be modified (PUT/POST requests)

All Object Properties for connector

Properties modifiable Using PUT/POST Request for connector

PUT Request for connector

Description: Updates registration for existing connector

Required permissions: ‘View system configuration’, ‘Extend connectors through API’

Call syntax: bit9platform/v1/connector/{id}?unregister={unregister}&deleteData={deleteData}

POST Request for connector

Description: Registers a new connector, or updates registration for existing connector

Required permissions: ‘View system configuration’, ‘Extend connectors through API’

Call syntax: bit9platform/v1/connector?unregister={unregister}&deleteData={deleteData}

DELETE Request for connector

Description: Unregisters a custom connector

Required permissions: ‘View system configuration’, ‘Extend connectors through API’

Call syntax: bit9platform/v1/connector/{id}?deleteData={deleteData}

GET Request for connector

Description: Returns object instance of this class

Required permissions: ‘View system configuration’

Call syntax: bit9platform/v1/connector/{id}

GET Request for connector

Description: Returns objects that match given criteria

Required permissions: ‘View system configuration’

Call syntax: bit9platform/v1/connector?q={q1}&q={q2}...&group={group}&sort={sort}&offset={offset}&limit={limit}

DriftReport

v1/driftReport object exposes information about drift reports. Note that this is read-only API.

All Object Properties for driftReport

driftReport is a read-only object and has no modifiable properties.

GET Request for driftReport

Description: Returns object instance of this class

Required permissions: ‘View drift reports and snapshots’

Call syntax: bit9platform/v1/driftReport/{id}

GET Request for driftReport

Description: Returns objects that match given criteria

Required permissions: ‘View drift reports and snapshots’

Call syntax: bit9platform/v1/driftReport?q={q1}&q={q2}...&group={group}&groupType={groupType}&groupStep={groupStep}&sort={sort}&offset={offset}&limit={limit}&expand={expand1}&expand={expand2}...

DriftReportContents

v1/driftReportContents object provides access to drift report results. Contents are read-only.

All Object Properties for driftReportContents

driftReportContents is a read-only object and has no modifiable properties.

GET Request for driftReportContents

Description: Returns drift report contents that match given criteria

Required permissions: ‘View drift reports and snapshots’

Call syntax: bit9platform/v1/driftReportContents?q={q1}&q={q2}...&group={group}&groupType={groupType}&sort={sort}&offset={offset}&limit={limit}&driftReportId={driftReportId}

Event

v1/event object exposes public events.

All Object Properties for event

event is a read-only object and has no modifiable properties.

GET Request for event

Description: Returns object instance of this class

Required permissions: ‘View events’

Call syntax: bit9platform/v1/event/{id}

GET Request for event

Description: Returns objects that match given criteria

Required permissions: ‘View events’

Call syntax: bit9platform/v1/event?q={q1}&q={q2}...&group={group}&sort={sort}&offset={offset}&limit={limit}

FileAnalysis

v1/fileAnalysis object exposes all files sent to analysis with Network Connectors. It also allows requesting or canceling file analysis.

All Object Properties for fileAnalysis

Properties modifiable Using PUT/POST Request for fileAnalysis

POST Request for fileAnalysis

Description: Creates or updates file analysis request

Required permissions: ‘View files’, ‘Submit files for analysis’

Call syntax: bit9platform/v1/fileAnalysis

PUT Request for fileAnalysis

Description: Updates existing file analysis request

Required permissions: ‘View files’, ‘Submit files for analysis’

Call syntax: bit9platform/v1/fileAnalysis/{id}

GET Request for fileAnalysis

Description: Returns object instance of this class

Required permissions: ‘View files’

Call syntax: bit9platform/v1/fileAnalysis/{id}

GET Request for fileAnalysis

Description: Returns objects that match given criteria

Required permissions: ‘View files’

Call syntax: bit9platform/v1/fileAnalysis?q={q1}&q={q2}...&group={group}&sort={sort}&offset={offset}&limit={limit}

FileCatalog

v1/fileCatalog object exposes all unique files found by App Control Agents and metadata related to files. Note that this is read-only API. In order to change state of the file, you need to use fileRule object.

All Object Properties for fileCatalog

POST Request for fileCatalog

Description: Change file catalog acknowledgement state

Required permissions: ‘View files and applications’, ‘Manage files’

Call syntax: bit9platform/v1/fileCatalog

PUT Request for fileCatalog

Description: Updates fileCatalog entry

Required permissions: ‘View files and applications’, ‘Manage files’

Call syntax: bit9platform/v1/fileCatalog/{id}?acknowledge={acknowledge}&changeLocalStateForComputerId={changeLocalStateForComputerId}&newApprovalState={newApprovalState}

GET Request for fileCatalog

Description: Returns object instance of this class

Required permissions: ‘View files’

Call syntax: bit9platform/v1/fileCatalog/{id}

GET Request for fileCatalog

Description: Returns objects that match given criteria

Required permissions: ‘View files’

Call syntax: bit9platform/v1/fileCatalog?q={q1}&q={q2}...&group={group}&sort={sort}&offset={offset}&limit={limit}

FileInstance

v1/fileInstance object exposes live file inventory on all App Control Agents. It also allows local approvals of files.

All Object Properties for fileInstance

Properties modifiable Using PUT/POST Request for fileInstance

POST Request for fileInstance

Description: Change local file instance state

Required permissions: ‘View files’, ‘Change local state’

Call syntax: bit9platform/v1/fileInstance

PUT Request for fileInstance

Description: Change local file instance state

Required permissions: ‘View files’, ‘Change local state’

Call syntax: bit9platform/v1/fileInstance/{id}

GET Request for fileInstance

Description: Returns object instance of this class

Required permissions: ‘View files’

Call syntax: bit9platform/v1/fileInstance/{id}

GET Request for fileInstance

Description: Returns objects that match given criteria

Required permissions: ‘View files’

Call syntax: bit9platform/v1/fileInstance?q={q1}&q={q2}...&group={group}&sort={sort}&offset={offset}&limit={limit}

FileInstanceDeleted

v1/fileInstanceDeleted object exposes deleted file inventory on all App Control Agents.

All Object Properties for fileInstanceDeleted

fileInstanceDeleted is a read-only object and has no modifiable properties.

GET Request for fileInstanceDeleted

Description: Returns object instance of this class

Required permissions: ‘View files’

Call syntax: bit9platform/v1/fileInstanceDeleted/{id}

GET Request for fileInstanceDeleted

Description: Returns objects that match given criteria

Required permissions: ‘View files’

Call syntax: bit9platform/v1/fileInstanceDeleted?q={q1}&q={q2}...&group={group}&sort={sort}&offset={offset}&limit={limit}

FileInstanceGroup

v1/fileInstanceGroup object exposes grouping of file inventory from App Control Agents. Grouping can be based on installed programs reported by system, or automatic, based on installations seen by the agent.

All Object Properties for fileInstanceGroup

fileInstanceGroup is a read-only object and has no modifiable properties.

GET Request for fileInstanceGroup

Description: Returns object instance of this class

Required permissions: ‘View files’

Call syntax: bit9platform/v1/fileInstanceGroup/{id}

GET Request for fileInstanceGroup

Description: Returns objects that match given criteria

Required permissions: ‘View files’

Call syntax: bit9platform/v1/fileInstanceGroup?q={q1}&q={q2}...&group={group}&sort={sort}&offset={offset}&limit={limit}

FileRule

v1/fileRule object exposes rules related to unique files. It allows creation and editing of file Approvals and Bans.

All Object Properties for fileRule

Properties modifiable Using PUT/POST Request for fileRule

POST Request for fileRule

Description: Creates or updates file rule

Required permissions: ‘View files’, ‘Manage files’

Call syntax: bit9platform/v1/fileRule?delete={delete}

PUT Request for fileRule

Description: Updates existing file rule

Required permissions: ‘View files’, ‘Manage files’

Call syntax: bit9platform/v1/fileRule/{id}

DELETE Request for fileRule

Description: Delete file rule

Required permissions: ‘View files’, ‘Manage files’

Call syntax: bit9platform/v1/fileRule/{id}

GET Request for fileRule

Description: Returns object instance of this class

Required permissions: ‘View files’

Call syntax: bit9platform/v1/fileRule/{id}

GET Request for fileRule

Description: Returns objects that match given criteria

Required permissions: ‘View files’

Call syntax: bit9platform/v1/fileRule?q={q1}&q={q2}...&group={group}&sort={sort}&offset={offset}&limit={limit}

FileUpload

v1/fileUpload object exposes all uploaded files from the App Control Agents. It also allows requesting or canceling new uploads. Uploaded files can be accessed through the API.

All Object Properties for fileUpload

Properties modifiable Using PUT/POST Request for fileUpload

GET Request for fileUpload

Description: Returns fileUpload object

Required permissions: ‘View file uploads’

Call syntax: bit9platform/v1/fileUpload/{id}?downloadFile={downloadFile}

GET Request for fileUpload

Description: Returns object instance of this class

Required permissions: ‘View file uploads’

Call syntax: bit9platform/v1/fileUpload/{id}

GET Request for fileUpload

Description: Returns objects that match given criteria

Required permissions: ‘View file uploads’

Call syntax: bit9platform/v1/fileUpload?q={q1}&q={q2}...&group={group}&sort={sort}&offset={offset}&limit={limit}

POST Request for fileUpload

Description: Creates or updates file upload request

Required permissions: ‘View file uploads’, ‘Manage uploads of inventoried files’

Call syntax: bit9platform/v1/fileUpload

PUT Request for fileUpload

Description: Updates existing file upload request

Required permissions: ‘View file uploads’, ‘Manage uploads of inventoried files’

Call syntax: bit9platform/v1/fileUpload/{id}

GrantedUserPolicyPermission

v1/grantedUserPolicyPermission object exposes granted permissions for the user. This is a read-only object and can only be modified through the userGroup API.

All Object Properties for grantedUserPolicyPermission

grantedUserPolicyPermission is a read-only object and has no modifiable properties.

**GET Request for grantedUserPolicyPermission

Description: Returns object instance of this class

Required permissions: Unknown

Call syntax: bit9platform/v1/grantedUserPolicyPermission/{id}

GET Request for grantedUserPolicyPermission

Description: Returns objects that match given criteria

Required permissions: Unknown

Call syntax: bit9platform/v1/grantedUserPolicyPermission?q={q1}&q={q2}...&group={group}&groupType={groupType}&groupStep={groupStep}&sort={sort}&offset={offset}&limit={limit}&expand={expand1}&expand={expand2}...

InternalEvent

v1/internalEvent object exposes private events.

All Object Properties for internalEvent

internalEvent is a read-only object and has no modifiable properties.

GET Request for internalEvent

Description: Returns object instance of this class

Required permissions: ‘View events’

Call syntax: bit9platform/v1/internalEvent/{id}

GET Request for internalEvent

Description: Returns objects that match given criteria

Required permissions: ‘View events’

Call syntax: bit9platform/v1/internalEvent?q={q1}&q={q2}...&group={group}&sort={sort}&offset={offset}&limit={limit}

MeteredExecution

v1/meteredExecution object exposes metered executions. This is a read-only object and can only be configured from the App Control Console.

All Object Properties for meteredExecution

meteredExecution is a read-only object and has no modifiable properties.

GET Request for meteredExecution

Description: Returns object instance of this class

Required permissions: ‘View files’

Call syntax: bit9platform/v1/meteredExecution/{id}

GET Request for meteredExecution

Description: Returns objects that match given criteria

Required permissions: ‘View files’

Call syntax: bit9platform/v1/meteredExecution?q={q1}&q={q2}...&group={group}&sort={sort}&offset={offset}&limit={limit}

Notification

v1/notification object allows pushing notifications from the Network Connectors through POST request. These notifications can be based on previously requested file analysis, or can come directly from the network appliance, such as firewall.

Properties modifiable Using PUT/POST Request for notification

POST Request for notification

Description: This method posts a notification object. Notification should contain information about analyzed file If possible, App Control will match notification with known file and computer information

Required permissions: ‘Extend connectors through API’

Call syntax: bit9platform/v1/notification

Notifier

v1/notifier object exposes notifiers that are used in customRule and fileRule objects. Notifiers are displayed on the agents when file is blocked because of the rule. This is a read-only object and can only be modified from the App Control Console.

All Object Properties for notifier

notifier is a read-only object and has no modifiable properties.

GET Request for notifier

Description: Returns object instance of this class

Required permissions: ‘View notifiers’

Call syntax: bit9platform/v1/notifier/{id}

GET Request for notifier

Description: Returns objects that match given criteria

Required permissions: ‘View notifiers’

Call syntax: bit9platform/v1/notifier?q={q1}&q={q2}...&group={group}&sort={sort}&offset={offset}&limit={limit}

PendingAnalysis

v1/pendingAnalysis object exposes all pending analysis requests for a given connector. Only external connectors can be accessed. Analyized files can be accessed through the API.

All Object Properties for pendingAnalysis

Properties modifiable Using PUT/POST Request for pendingAnalysis

GET Request for pendingAnalysis

Description: Returns top N pending analysis requests for a given connector in a descending ordered of priority

Required permissions: ‘Extend connectors through API’

Call syntax: bit9platform/v1/pendingAnalysis?connectorId={connectorId}&maxCount={maxCount}

GET Request for pendingAnalysis

Description: Returns pending analysis requests for a given id

Required permissions: ‘Extend connectors through API’

Call syntax: bit9platform/v1/pendingAnalysis/{id}?downloadFile={downloadFile}

GET Request for pendingAnalysis

Description: Returns object instance of this class

Required permissions: ‘Extend connectors through API’

Call syntax: bit9platform/v1/pendingAnalysis/{id}

GET Request for pendingAnalysis

Description: Returns objects that match given criteria

Required permissions: ‘Extend connectors through API’

Call syntax: bit9platform/v1/pendingAnalysis?q={q1}&q={q2}...&group={group}&sort={sort}&offset={offset}&limit={limit}

PUT Request for pendingAnalysis

Description: Updates existing pending analysis requests

Required permissions: ‘Extend connectors through API’

Call syntax: bit9platform/v1/pendingAnalysis

Policy

v1/policy object exposes policy information. This is a read-only object and can only be modified from the App Control Console.

All Object Properties for policy