App Control REST API Reference

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'%*%'

Note: All string matching will be case-insensitive.

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

Name Type Property Description
id Int32 Unique approvalRequestId
fileCatalogId Int32 Id of fileCatalog entry associated with file for this request
installerFileCatalogId Int32 Id of fileCatalog entry associated with installer for this request
processFileCatalogId Int32 Id of fileCatalog entry associated with process for this request
computerId Int32 Id of computer where request originated
computerName String Name of computer where request originated
dateCreated DateTime Date/time when this request was created (UTC)
createdBy String User that created request on the agent
dateModified DateTime Date/time when this request was last modified (UTC)
modifiedBy Int32 User that last modified this request
enforcementLevel Int32 Enforcement level of agent at the time of request.
Can be one of:
20=High (Block Unapproved),
30=Medium (Prompt Unapproved),
40=Low (Monitor Unapproved),
60=None (Visibility),
80=None (Disabled)
resolution Int32 Resolution of request.
Can be one of:
0=Not Resolved,
1=Rejected,
2=Resolved - Approved,
3=Resolved - Rule Change,
4=Resolved - Installer,
5=Resolved - Updater,
6=Resolved - Publisher,
7=Resolved - Other
requestType Int32 Type of request. One if:
1=Approval,
2=Justification
requestorComments String Comments by user that created this request
requestorEmail String Email of user that created this request
priority Int32 Priority of this request. Can be one of:
0=High,
1=Medium,
2=Low
resolutionComments String Comments by request resolver
status Int32 Request status. Can be one of:
1=New,
2=Open,
3=Closed,
4=Escalated
policyId Int32 Id of policy for computer at the time when request arrived to the server
multipleBlocks Boolean True if file referenced by this request had multiple blocks
fileName String Name of file on the agent
pathName String Path of the file on the agent
process String Process that attempted to execute file on the agent. This is full process path
customRuleId Int32 Id of the customRule that caused the file block on the agent
duplicates Int32 Number of duplicates (if exist) of this approval request
related Int32 Number of related requests (if exist) of this approval request
platform String Platform of this approval request
publisherReputation String Reputation of this publisher. Can be one of:
0=Not trusted (Unknown),
1=Low,
2=Medium,
3=High
customRuleType String Custom rule type of the approval request. Can be one of: Memory Rule or Registry Rule
installer String Installer process that this file is part of. This is full installer path
processName String Process that attempted to execute file on the agent. This is file name part
processPath String Process that attempted to execute file on the agent. This is file path part
responseMailSent DateTime Date/time when response mail was sent from this approval request to requestor email
file String Full file path on the agent

Properties modifiable Using PUT/POST Request for approvalRequest

Name Type Property Description
resolution Int32 Resolution of request. Resolution can be changed for open requests or
closed requests only. It can be one of:
0=Not Resolved
1=Rejected
2=Resolved - Approved
3=Resolved - Rule Change
4=Resolved - Installer
5=Resolved - Updater
6=Resolved - Publisher
7=Resolved - Other
requestorEmail String Email of user that created this request
resolutionComments String Comments by request resolver
status Int32 Request status. Can be one of:
1=New,
2=Open,
3=Closed,
4=Escalated. Prohibited transitions are from any status back to 0 or 1.

POST Request for approvalRequest

Description: Updates approval request

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

Call syntax: bit9platform/v1/approvalRequest

Name Source Type Description
value FromBody approvalRequest Updated approval request object

PUT Request for approvalRequest

Description: Updates approval request

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

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

Name Source Type Description
id FromUri Int32 Id of file rule to create or update
value FromBody approvalRequest Updated approval request object

GET Request for approvalRequest

Description: Returns object instance of this class

Required permissions: ‘View approval requests’

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

Name Source Type Description
id FromUri Int64 id of a requested object

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}

Name Source Type Description
q FromUri List Query condition (Optional - multiple query conditions are supported)
group FromUri String Field name to group by (Optional)
sort FromUri String Field name to sort by (Optional)
offset FromUri Int32 Offset in query results (Optional)
limit FromUri Int32 Maximum number of results to return. When 0 or not present, all results will be returned. When -1, only count will be returned.
expand FromUri String[] Foreign key fields to expand (Optional)

AppTemplate

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

Properties modifiable Using PUT/POST Request for appTemplate

Name Type Property Description
id Int32 Unique updaterId
name String appTemplate name
description String appTemplate description
version String appTemplate version
enabled Boolean True if appTemplate is enabled
platformFlags Int32 Set of platform flags where this appTemplate is valid. combination of:
1 = Windows
2 = Mac
4 = Linux
dateCreated DateTime Date/time when this appTemplate was created (UTC)
createdBy String User that created this appTemplate
dateModified DateTime Date/time when this appTemplate was last modified (UTC)
modifiedBy String User that last modified this appTemplate
dateUpgraded DateTime Date/time when this appTemplate was upgraded from SRS (UTC)
clVersion Int64 CL version associated with this appTemplate
policyIds String List of IDs of policies where this appTemplate applies. Empty if this is a global appTemplate
autoDetectType Int32 Auto detection Type,
values :
0 - auto detection is not available,
1 - detection was based on Application,
2 - detection is based on file
autoDetectDesc String Description of Auto Detection process for this Application Configuration
computerCount Int32 Number of computers where this Application was detected
antibodyGroupId Int32 Antibody Group Id of the application
configured Boolean Already provided required parameters values for the Settings in this Application Template
autoDetection Boolean This application is detected on the computers
settingsList List Optional array of Settings objects with following fields:
• id appTemplateSettings Id
• name appTemplate name
• description appTemplateSettings description
• policyIds List of IDs of policies where this appTemplateSettings applies.
• paramList Optional array of Settings Parameters objects with following fields:
- • param_id_unique appTemplateSettingsParam unique Id(GUID)
- • type type of appTemplateSettingsParam
- • presentation presentation of appTemplateSettingsParam
- • label label of appTemplateSettingsParam
- • reg_exp reg_exp of appTemplateSettingsParam
- • param_desc description of appTemplateSettingsParam
- • required if appTemplateSettingsParam is required
- • value value of appTemplateSettingsParam
- • selectedOption selectedOption of appTemplateSettingsParam
- • paramOptionList list of options for appTemplateSettingsParam with following fields:
- - • option_id_unique appTemplateSettingsParamOption unique Id(GUID)
- - • label label of appTemplateSettingsParamOption
importFile appTemplateImportFile
• pwd file password
• xmlFile content of the encrypted xml file
autoDetectByPolcyList List Optional object to show Number of computers where this Application was detected by Policy
• policyId Policy Id
• computerNum Number of computers where this Application was detected in this Policy

POST Request for appTemplate

Description: Change appTemplate state

Required permissions: ‘View software rules pages’

Call syntax: bit9platform/v1/appTemplate

Name Source Type Description
value FromBody appTemplate appTemplate object with desired parameters.

PUT Request for appTemplate

Description: Change appTemplate state

Required permissions: ‘View software rules pages’

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

Name Source Type Description
id FromUri Int32 id of appTemplate to change
value FromBody appTemplate appTemplate object with desired parameters.

GET Request for appTemplate

Description: Returns object instance of this class

Required permissions: ‘View software rules pages’

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

Name Source Type Description
id FromUri Int64 id of a requested object

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}...

Name Source Type Description
q FromUri List Query condition (Optional - multiple query conditions are supported)
group FromUri String Field name to group by (Optional)
groupType FromUri String Type of windowed grouping (Optional, for time-based fields only)
groupStep FromUri Int32 Step for windowed grouping (Optional, for time-based fields only)
sort FromUri String Field name to sort by (Optional)
offset FromUri Int32 Offset in query results (Optional)
limit FromUri Int32 Maximum number of results to return. When 0 or not present, all results will be returned. When -1, only count will be returned.
expand FromUri String[] Foreign key fields to expand (Optional)

Certificate

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

All Object Properties for certificate

Name Type Property Description
id Int32 Unique certificate id
parentCertificateId Int32 Id of a parent certificate in a certificate chain
publisherId Int32 Id of publisher for this certificates
thumbprint String Thumbprint hash of the certificate
thumbprintAlgorithm String Algorithm used to calculate thumbprint of the certificate
subjectName String Certificate subject name
signatureAlgorithm String Certificate signature algorithm
serialNumber String Certificate serial number
validFrom DateTime Certificate valid from date (UTC)
validTo DateTime Certificate valid to date (UTC)
publicKeyAlgorithm String Certificate public key algorithm
publicKeySize Int32 Certificate public key size in bits
firstSeenComputerId Int32 Id of computer where this certificate was first seen
description String Description of certificate given by the user
sourceType Int32 Mechanism that changed publisher state. Can be one of:
1 = Manual
5 = External (API)
dateCreated DateTime Date/time certificate was first seen (UTC)
dateModified DateTime Date/time certificate state or description was modified (UTC)
modifiedByUser String User that last modified certificate state or description
intermediary Boolean True if certificate is intermediary certificate in the chain
valid Boolean True if certificate is valid
embedded Boolean True if certificate was seen as embedded signer of a file
detached Boolean True if certificate was seen as detached signer of a file
signer Boolean True if certificate was seen signing a file
cosigner Boolean True if certificate was seen counter-signing a file
certificateHash String Sha-256 hash of the certificate
uniqueSignedFiles Int32 Number of unique files that were found signed with this certificate
pathPositionId Int32 Certificate position in the certificate chain. Can be one of:
1=Leaf certificate
2=Intermediary certificate
3=Root certificate
lastValidation DateTime Last time this certificate was validated (UTC)
validationErrorCode Int32 Certificate validation error code (0 means no error)
validationError String Certificate validation error (in case error happened on last validation)
certificateState Int32 One of assigned states:
1=Unapproved
2=Approved
3=Banned
certificateEffectiveState Int32 One of effective states (taking into account other certificate in the chain):
1=Unapproved
2=Approved
3=Banned
4=Mixed (mix of approved and banned based on policy)
clVersion Int64 CL version associated with this certificate
certificateGlobalState String The default certificate state for all hosts
certificateGlobalStateDetails String The default certificate state details
certificateStateSource String How the certificate got into this state

Properties modifiable Using PUT/POST Request for certificate

Name Type Property Description
description String New certificate description
sourceType Int32 Mechanism that changed publisher state. Can be one of:
1 = Manual
5 = External (API)
certificateState Int32 New state of the certificate. Valid states are:
1=Unapproved
2=Approved
3=Banned

POST Request for certificate

Description: Change certificate state

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

Call syntax: bit9platform/v1/certificate

Name Source Type Description
value FromBody certificate Certificate object with desired parameters

PUT Request for certificate

Description: Change certificate state

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

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

Name Source Type Description
id FromUri Int32 id of certificate to change
value FromBody certificate Certificate object with desired parameters

DELETE Request for certificate

Description: Delete certificate approval

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

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

Name Source Type Description
id FromUri Int32 id of certificate for which to delete approval

GET Request for certificate

Description: Returns object instance of this class

Required permissions: ‘View software rules pages’

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

Name Source Type Description
id FromUri Int64 id of a requested object

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}

Name Source Type Description
q FromUri List Query condition (Optional - multiple query conditions are supported)
group FromUri String Field name to group by (Optional)
sort FromUri String Field name to sort by (Optional)
offset FromUri Int32 Offset in query results (Optional)
limit FromUri Int32 Maximum number of results to return. When 0 or not present, all results will be returned. When -1, only count will be returned.

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

Name Type Property Description
id Int32 Unique computer id
name String Computer name
computerTag String Custom computer tag
description String Description of this computer
policyId Int32 Id of policy this computer belongs to
policyName String Name of the policy this computer belongs to
automaticPolicy Boolean True if this computer’s policy is assigned automatically through AD
localApproval Boolean True if this computer is in local approval mode
users String List of last logged in users
ipAddress String Last known IP address of this computer
connected Boolean True if this computer is connected
enforcementLevel Int32 Current enforcement level.
Can be one of:
20=High (Block Unapproved)
30=Medium (Prompt Unapproved)
35=Local approval
40=Low (Monitor Unapproved)
60=None (Visibility)
80=None (Disabled)
disconnectedEnforcementLevel Int32 Current enforcement level for disconnected computers.
Can be one of:
20=High (Block Unapproved)
30=Medium (Prompt Unapproved)
35=Local approval
40=Low (Monitor Unapproved)
60=None (Visibility)
80=None (Disabled)
CLIPassword String CLI password for this computer. Viewing this field requires ‘Manage computers’ permission
lastRegisterDate DateTime Last date/time this computer registered to the server (UTC)
lastPollDate DateTime Last date/time this computer contacted the server (UTC)
osShortName String Short OS name
osName String Long OS name
platformId Int32 Platform Id. Can be one of:
1 = Windows
2 = Mac
4 = Linux
virtualized String True if computer is virtualized
virtualPlatform String If computer is virtualized, this is platform
dateCreated DateTime Date this computer was first registered
agentVersion String Version of App Control Platform agent
daysOffline Int32 Number of days this computer was offline
uninstalled Boolean True if this computer was uninstalled
deleted Boolean True if computer is disabled
processorCount Int32 Number of processor cores on this computer
processorSpeed Double Processor speed
processorModel String Processor model
machineModel String Machine model
memorySize Int32 Memory size in MB
upgradeStatus String Upgrade status
upgradeError String Last upgrade error
upgradeErrorTime DateTime Last time upgrade error changed
upgradeErrorCount Int32 Number of times last upgrade error happened so far
syncFlags Int32 Status of synchronization on this agent. Can be combination of:
0x01=Agent is going through initialization
0x02=Agent is going through full cache re-synch
0x08=Agent config list is out of date
0x10=Agent Enforcement is out of date
0x20=Kernel is not connected to the agent
0x40=Agent events timestamps indicate that system clock is out of synch
0x80=Agent has failed the health check
0x100=This is clone that is tracking only new files
0x200=This version of kernel is not supported by the agent (Linux only)
refreshFlags Int32 Refresh flags for this agent. Can be combination of:
0x01 = Complete resynch of agent NAB and installer table is requested
0x02 = Rescan of programs installed on the computer is requested
0x20 = Tell agent to refresh config list
0x40 = Force this agent to reregister with new cookie
0x200 = Trigger agent Reboot
0x1000 = Tell agent to refresh config list from the file
0x4000 = Boost the priority of this agent over all others permanently (until it is de-prioritized)
policyStatusDetails String Detailed status of policy on this agent
prioritized Boolean True if computer is prioritized
macAddress String MAC address of adapter used to connect to the App Control Server
debugLevel Int32 Current debug level of agent. Range is from 0 (none) to 8 (verbose)
kernelDebugLevel Int32 Current kernel debug level of agent. Range is from 0 (none) to 5 (verbose)
debugFlags Int32 Debug flags. Can be 0 or combination of:
0x01 = Upload debug files now
0x10 = Enable full memory dumps
0x20 = Copy agent cache
0x40 = Delete debug files
0x80 = Upload agent cache
0x200 = Save verbose debug info + counters to the cache when copied/uploaded
0x400 = Generate and upload an analysis.bt9 file that contains various constraint violation analysis information
0x800 = Run a health check and send results to server
debugDuration Int32 Debug duration in minutes
ccLevel Int32 Cache consistency check level set for agent. Can be one of:
0 = None1 = Quick verification
2 = Rescan known files
3 = Full scan for new files
ccFlags Int32 Cache consistency check flags set for agent. Can be 0 or combination of:
0x0001 = Whether this is just a test run or not
0x0002 = Should the state of invalid files be preserved
0x0004 = Should new files found be locally approved or not
0x0008 = Should we re-evaluate whether a file’s certificate information is still valid or not
0x0010 = Whether the check was scheduled or not
0x0020 = Whether the agent should run constraint checks to test for invalid results
0x0040 = Whether we are only searching for new script types as a result of a change to what ‘IsScript’ means
0x0080 = Whether we are doing a level 3 check for initialization
0x0100 = This cache check is to remediate CR# 18041
0x0200 = Force the re-evaluation of the IsCrawlable state and archive type
supportedKernel Boolean True if current computer kernel version is supported
forceUpgrade Boolean True if upgrade is forced for this computer
hasHealthCheckErrors Boolean True if computer has health check errors
clVersion Int32 Current CL version of this agent
agentMemoryDumps Int32 True if agent has memory dumps
systemMemoryDumps Int32 True if agent has system memory dumps
initializing Boolean True if agent is initializing
tamperProtectionActive Boolean True if agent’s tamper protection is active
agentCacheSize Int32 Number of files that agent is tracking
agentQueueSize Int32 Number of unsent file operations in agent’s queue
syncPercent Int32 Synchronization percentage for file operations on the agent
tdCount Int32 Count of Trusted Directories hosted by this agent
template Boolean True if computer is a template
templateComputerId Int32 Id of parent template computer if this is a clone
templateDate DateTime Date/time when this computer was templated (UTC)
templateCloneCleanupMode Int32 Mode of template cleanup.
Can be one of:
1=Manual (from console)
2=Automatic, by time (specified by templateCloneCleanupTime and templateCloneCleanupTimeScale)
3=Automatic, when new computer with the same name comes online
4=Automatic, as soon as computer goes offline
templateCloneCleanupTime Int32 If templateCloneCleanupMode is 2, this is time before clone is cleaned up. Time unit is specified in templateCloneCleanupTimeScale
templateCloneCleanupTimeScale Int32 Time unit of template cleanup. Can be one of:
1=Hours
2=Days
3=Weeks
templateTrackModsOnly Boolean If True, clones of this template will track only new and modified files
cbSensorId Int32 ID of Carbon Black sensor. If 0, sensor is not installed on this computer
cbSensorVersion String Version of Carbon Black sensor if installed
cbSensorFlags Int32 Carbon Black sensor flags. Can be combination of:
1 = User mode service is running
2 = Kernel driver is running
SCEPStatus Int32 Status of SCEP protection. Can be one of following values:
0 = Unknown
1 = Not Present
2 = Disabled
3 = Outdated
2 = Active

Properties modifiable Using PUT/POST Request for computer

Name Type Property Description
name String Computer name can be changed only if computer is a template
computerTag String Custom computer tag
description String Description of this computer
policyId Int32 New Id of policy for this computer. PolicyId is ignored if either automaticPolicy us True or localApproval is True
automaticPolicy Boolean True if this policy is assigned automatically through AD. Has to be False if localApproval is True
localApproval Boolean True if this computer is currently in local approval mode. Has to be False if automaticPolicy is True
refreshFlags Int32 Change refresh flags for this agent. Can be combination of:
0x01=Complete resynch of agent NAB and installer table is requested
0x02=Rescan of programs installed on the computer is requested
0x20=Tell agent to refresh config list
0x40=Force this agent to reregister with new cookie
0x200=Trigger agent Reboot.
0x1000=Tell agent to refresh config list from the file
0x4000 Boost the priority of this agent over all others permanently (until it is de-prioritized)
prioritized Boolean True to prioritize this computer
debugLevel Int32 Current debug level of agent. Range is from 0 (none) to 8 (verbose).
This value can be changed only if ‘changeDiagnostics’ request parameter is set to true.
kernelDebugLevel Int32 Current kernel debug level of agent. Range is from 0 (none) to 5 (verbose).
This value can be changed only if ‘changeDiagnostics’ request parameter is set to true.
debugFlags Int32 Debug flags. Can be 0 or combination of:
0x01 = Upload debug files now
0x10 = Enable full memory dumps
0x20 = Copy agent cache
0x40 = Delete debug files
0x80 = Upload agent cache
0x200 = Save verbose debug info + counters to the cache when copied/uploaded
0x400 = Generate and upload an analysis.bt9 file that contains various constraint violation analysis information
0x800 = Run a health check and send results to server
This value can be changed only if ‘changeDiagnostics’ request parameter is set to true.
debugDuration Int32 Debug duration in minutes. This value can be changed only if ‘changeDiagnostics’ request parameter is set to true.
ccLevel Int32 Cache consistency check level set for agent. Can be one of:
0 = None
1 = Quick verification
2 = Rescan known files
3 = Full scan for new files
This value can be changed only if ‘changeDiagnostics’ request parameter is set to true.
ccFlags Int32 Cache consistency check flags set for agent. Can be 0 or combination of:
0x0001 = Whether this is just a test run or not
0x0002 = Should the state of invalid files be preserved
0x0004 = Should new files found be locally approved or not
0x0008 = Should we re-evaluate whether a file’s certificate information is still valid or not
0x0010 = Whether the check was scheduled or not
0x0020 = Whether the agent should run constraint checks to test for invalid results
0x0040 = Whether we are only searching for new script types as a result of a change to what ‘IsScript’ means
0x0080 = Whether we are doing a level 3 check for initialization
0x0100 = This cache check is to remediate CR# 18041
0x0200 = Force the re-evaluation of the IsCrawlable state and archive type
This value can be changed only if ‘changeDiagnostics’ request parameter is set to true.
forceUpgrade Boolean True to force upgrade for this computer
template Boolean True if computer is a VDI template. This value can be changed only if ‘changeTemplate’ request parameter is set to true.
templateCloneCleanupMode Int32 Mode of template cleanup. Can be one of:
1=Manual (from console)
2=Automatic, by time (specified by templateCloneCleanupTime and templateCloneCleanupTimeScale)
3=Automatic, when new computer with the same name comes online
4=Automatic, as soon as computer goes offline
This value can be changed only if ‘changeTemplate’ request parameter is set to true.
templateCloneCleanupTime Int32 If templateCloneCleanupMode is 2, this is time before clone is cleaned up. Time unit is specified in templateCloneCleanupTimeScale.
This value can be changed only if ‘changeTemplate’ request parameter is set to true.
templateCloneCleanupTimeScale Int32 Time unit of template cleanup. Can be one of:
1=Hours
2=Days
3=Weeks
This value can be changed only if ‘changeTemplate’ request parameter is set to true.
templateTrackModsOnly Boolean If True, clones of this template will track only new and modified files. This value can be changed only if ‘changeTemplate’ request parameter is set to true.

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}

Name Source Type Description
value FromBody computer Updated computer object.
changeDiagnostics FromUri Boolean Optional flag, defaults to false. If set to true, debug and CC properties of computer will be updated from the object sent in the body the request. This action requires ‘Change advanced options’ permission.
changeTemplate FromUri Boolean Optional flag, defaults to false. If set to true, template settings will be updated from the object sent in the body the request. This action requires ‘Change advanced options’ permission.
delete FromUri Boolean Optional flag, deletes computer entry.
resetCLIPassword FromUri Boolean Optional flag to reset CLI password for this computer. This action requires ‘Change advanced options’ permission.
newTamperProtectionActive FromUri Nullable Optional boolean to set desired tamper protection. Note that tamper protection cannot be set through the object, and might not be reflected in the object immediately, but only after computer reports back its new tamper protection setting. This action requires ‘Change advanced options’ permission.

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}

Name Source Type Description
id FromUri Int32 Id of computer to change.
value FromBody computer Updated computer object.
changeDiagnostics FromUri Boolean Optional flag, defaults to false. If set to true, debug and CC properties of computer will be updated from the object sent in the body the request. This action requires ‘Change advanced options’ permission.
changeTemplate FromUri Boolean Optional flag, defaults to false. If set to true, template settings will be updated from the object sent in the body the request. This action requires ‘Change advanced options’ permission.
delete FromUri Boolean Optional flag, deletes computer entry.
resetCLIPassword FromUri Boolean Optional flag to reset CLI password for this computer. Command will clear the password, and it will re-populate with new value the next time computer registers. This action requires ‘Change advanced options’ permission.
newTamperProtectionActive FromUri Nullable Optional boolean to set desired tamper protection. Note that tamper protection cannot be set through the object, and might not be reflected in the object immediately, but only after computer reports back its new tamper protection setting. This action requires ‘Change advanced options’ permission.

DELETE Request for computer

Description: Delete computer

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

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

Name Source Type Description
id FromUri Int32 id of computer to delete

GET Request for computer

Description: Returns object instance of this class

Required permissions: ‘View computers’

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

Name Source Type Description
id FromUri Int64 id of a requested object

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}

Name Source Type Description
q FromUri List Query condition (Optional - multiple query conditions are supported)
group FromUri String Field name to group by (Optional)
sort FromUri String Field name to sort by (Optional)
offset FromUri Int32 Offset in query results (Optional)
limit FromUri Int32 Maximum number of results to return. When 0 or not present, all results will be returned. When -1, only count will be returned.

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

Name Type Property Description
id Int32 Unique connector Id
name String Name of the connector
analysisName String Name for analysis component of the connector (can be same as the name field)
connectorVersion String Version of this connector
canAnalyze Boolean True if this connector can analyze files
enabled Boolean True if connector is enabled
analysisEnabled Boolean True if analysis component of this connector is enabled
isInternal Boolean True if this is internal connector
analysisTargets String[] Array of possible analysis targets. Analysis targets are required when creating new fileAnalysis. They usualy represent different OS and configurations and are available only for some internal connectors.

Properties modifiable Using PUT/POST Request for connector

Name Type Property Description
name String Name of the connector. Note that only non-internal connectors can be renamed
analysisName String Name for analysis component of the connector (can be same as the name field)
connectorVersion String Version of this connector
canAnalyze Boolean True if this connector can analyze files
enabled Boolean True if connector is enabled
analysisEnabled Boolean True if analysis component of this connector is enabled

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}

Name Source Type Description
id FromUri Int32 Id of connector object to update
value FromBody connector Connector object to update
unregister FromUri Boolean Optional: whether to unregister this connector. Defaults to false
deleteData FromUri Boolean Optional: whether to delete all analysis results associated with this connector when unregistering. Defaults to true

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}

Name Source Type Description
connector FromBody connector Connector object to register
unregister FromUri Boolean Optional: whether to unregister this connector. Defaults to false
deleteData FromUri Boolean Optional: whether to delete all analysis results associated with this connector when unregistering. Defaults to true

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}

Name Source Type Description
id FromUri Int32 Connector id to unregister
deleteData FromUri Boolean Optional: whether to delete all analysis results associated with this connector. Defaults to true

GET Request for connector

Description: Returns object instance of this class

Required permissions: ‘View system configuration’

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

Name Source Type Description
id FromUri Int64 id of a requested object

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}

Name Source Type Description
q FromUri List Query condition (Optional - multiple query conditions are supported)
group FromUri String Field name to group by (Optional)
sort FromUri String Field name to sort by (Optional)
offset FromUri Int32 Offset in query results (Optional)
limit FromUri Int32 Maximum number of results to return. When 0 or not present, all results will be returned. When -1, only count will be returned.

DriftReport

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

All Object Properties for driftReport

Name Type Property Description
id Int32 Unique drift report ID
name String Name of drift report
description String Description of drift report
createDate DateTime Date drift report was created (UTC)
modifyDate DateTime Date drift report was last modified (UTC)
generateStartDate DateTime The last time this drift report started being generated (UTC)
generateEndDate DateTime The last time this drift report finished being generated (UTC)
lastGenerateStepDate DateTime The last time the last step in this drift report occurred (UTC)
durationSec Int32 Duration in seconds of last drift report generation
driftTimeInterval Int32 The number representing the interval between drift report generation
driftTimeIntervalType String The unit of time representing the interval between drift report generation (minutes, hours, days)
createUserId Int32 The user ID of the user that created this drift report
This is foreign key and can be expanded to expose fields from the related user object
modifyUserId Int32 The user ID of the user that last modified this drift report
This is foreign key and can be expanded to expose fields from the related user object
reportType Int32 0 = baseline
1 = historical
baselineType Int32 0 = computer
1 = policy
2 = advanced filter
3 = snapshot
4 = self
5 = none
6 = computer filter
targetType Int32 0 = computer
1 = policy
2 = advanced filter
3 = all computers
4 = computer filter
baselineId Int32 Depends on the baseline type (computer or policy)
snapshotId Int32 Implicit snaphot referenced by the report
targetId Int32 Depends on the baseline type (computer or policy)
baselineFilter String The primary filter applied to the baseline
finalBaselineFilter String The final filter applied to the baseline
targetFilter String The primary filter applied to the target
finalTargetFilter String The final filter applied to the target
generateFlags Int32 Flags representing how the reports are being generated:
0x0001 = include approved
0x0002 = include initialized
0x0004 = include bans
0x0008 = only applications
0x0010 = only executed files
0x1000 = track removals
0x2000 = match by hash (content)
0x4000 = generate details
0x8000 = hidden
enabled Boolean Whether this drift report has been enabled
deleted Boolean Whether this drift report has been deleted
regenerate Boolean Whether this drift report needs to be regenerated
rDrift Int64 A computed value representing raw drift from the last report
wDrift Double A computed value representing weighted drift from the last report
sDrift Double A computed value representing significant drift from the last report
percentageDone Int32 How much of the report generation is complete

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}

Name Source Type Description
id FromUri Int64 id of a requested object

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}...

Name Source Type Description
q FromUri List Query condition (Optional - multiple query conditions are supported)
group FromUri String Field name to group by (Optional)
groupType FromUri String Type of windowed grouping (Optional, for time-based fields only)
groupStep FromUri Int32 Step for windowed grouping (Optional, for time-based fields only)
sort FromUri String Field name to sort by (Optional)
offset FromUri Int32 Offset in query results (Optional)
limit FromUri Int32 Maximum number of results to return. When 0 or not present, all results will be returned. When -1, only count will be returned.
expand FromUri String[] Foreign key fields to expand (Optional)

DriftReportContents

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

All Object Properties for driftReportContents

Name Type Property Description
computerId Int32 The ID of the computer associated with this file drift. This is foreign key and can be expanded to expose fields from the related computer object
fileId Int32 The ID of the file associated with this file drift. This is foreign key and can be expanded to expose fields from the related fileInstance object
fileName String The file name associated with this file drift
localState Int32 Whether this drift was unapproved (1), approved (2) or banned (3)
date DateTime The date when this drift occurred
processName String The process file name associates with this file drift

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}

Name Source Type Description
q FromUri List Query parts
group FromUri String Group by field
groupType FromUri String For date groupings, unit of time to group by
sort FromUri String Sort by fields
offset FromUri Int32 Offset in query results
limit FromUri Int32 Maximum number of results to return. Omit to get only count of results.
driftReportId FromUri Int64 The drift report ID

Event

v1/event object exposes public events.

All Object Properties for event

Name Type Property Description
id Int64 Unique event Id
timestamp DateTime Date/Time when event was created (UTC)
receivedTimestamp DateTime Date/Time when event was received by the server (UTC)
description String Event description
type Int32 Event type. Can be one of:
0 = Server Management
1 = Session Management
2 = Computer Management
3 = Policy Management
4 = Policy Enforcement
5 = Discovery
6 = General Management
8 = Internal Events
subtype Int32 Event subtype. Can be one of event subtype IDs
subtypeName String Event subtype as string
ipAddress String IP address associated with this event
computerId Int32 Id of computer associated with this event
computerName String Name of computer associated with this event
policyId Int32 Id of policy where agent was at the time of the event
policyName String Name of policy where agent was at the time of the event
fileCatalogId Int32 Id of fileCatalog entry associated with file for this event
installerFileCatalogId Int32 Id of fileCatalog entry associated with installer for this event
processFileCatalogId Int32 Id of fileCatalog entry associated with process for this event
fileName String Name of the file associated with this event
pathName String Path of the file associated with this event
commandLine String Full command line associated with this event. Viewing this field requires ‘View process command lines’ permission
processPathName String Name of the process associated with this event
processFileName String Path of the process associated with this event
installerFileName String Name of the installer associated with this event
processKey String Process key associated with this event. This key uniquely identifies the process in both App Control Platform and Carbon Black product
severity Int32 Event severity. Can be one of:
2 = Critical
3 = Error
4 = Warning
5 = Notice
6 = Info
7 = Debug
userName String User name associated with this event
ruleName String Rule name associated with this event
banName String Ban name associated with this event
updaterName String Updater name associated with this event
indicatorName String Advanced threat indicator name associated with this event
param1 String Internal string parameter 1
param2 String Internal string parameter 2
param3 String Internal string parameter 3
stringId Int32 Internal string Id used for description
unifiedSource String Unified server name that created this 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}

Name Source Type Description
id FromUri Int64 id of a requested object

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}

Name Source Type Description
q FromUri List Query condition (Optional - multiple query conditions are supported)
group FromUri String Field name to group by (Optional)
sort FromUri String Field name to sort by (Optional)
offset FromUri Int32 Offset in query results (Optional)
limit FromUri Int32 Maximum number of results to return. When 0 or not present, all results will be returned. When -1, only count will be returned. When -2, a “quick count” will be returned.

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

Name Type Property Description
id Int64 Unique fileAnalysis id
computerId Int32 Id of computer entry associated with this analysis
fileCatalogId Int32 Id of fileCatalog entry associated with this analysis
connectorId Int32 Id of connector associated with this analysis
createdBy String User that requested this analysis
dateCreated DateTime Date/Time when fileAnalysis request was created (UTC)
dateModified DateTime Date/Time when fileAnalysis request was last modified (UTC)
fileName String Name of the file where file exists on the endpoint
pathName String Path of the file where file exists on the endpoint
priority Int32 File analysis priority in range [-2, 2], where 2 is highest priority. Default priority is 0
analysisStatus Int32 Status of analysis. Can be one of:
0 = scheduled
1 = submitted (file is sent for analysis)
2 = processed (file is processed but results are not available yet)
3 = analyzed (file is processed and results are available)
4 = error
5 = cancelled
analysisResult Int32 Result of the analysis. Can be one of:
0 = Not yet available
1 = File is clean
2 = File is a potential threat
3 = File is malicious
analysisTarget String Target of the analysis (Connector-dependent)

Properties modifiable Using PUT/POST Request for fileAnalysis

Name Type Property Description
computerId Int32 Id of computer from which to upload the file. If 0, system will find best computer to get the file from
fileCatalogId Int32 Id of fileCatalog entry for which analysis is requested
connectorId Int32 Id of target connector for the analysis
priority Int32 Analysis priority in range [-2, 2], where 2 is highest priority. Default priority is 0
analysisStatus Int32 Status of analysis. Status of analysis in progress can be changed to 5 (Cancelled)
analysisTarget String Target of the analysis (Optional). It has to be one of possible analysisTarget options defined for the given connector object, or empty for connectors without defined analysisTargets.

POST Request for fileAnalysis

Description: Creates or updates file analysis request

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

Call syntax: bit9platform/v1/fileAnalysis

Name Source Type Description
value FromBody fileAnalysis New fileAnalysis object

PUT Request for fileAnalysis

Description: Updates existing file analysis request

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

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

Name Source Type Description
id FromUri Int32 Id of file rule to create or update
value FromBody fileAnalysis New fileAnalysis object

GET Request for fileAnalysis

Description: Returns object instance of this class

Required permissions: ‘View files’

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

Name Source Type Description
id FromUri Int64 id of a requested object

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}

Name Source Type Description
q FromUri List Query condition (Optional - multiple query conditions are supported)
group FromUri String Field name to group by (Optional)
sort FromUri String Field name to sort by (Optional)
offset FromUri Int32 Offset in query results (Optional)
limit FromUri Int32 Maximum number of results to return. When 0 or not present, all results will be returned. When -1, only count will be returned.

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

Name Type Property Description
id Int32 Unique fileCatalog Id
dateCreated DateTime Date/Time when this unique hash was first seen (Database local time)
dateModified DateTime Date/Time when this unique hash was modified through the fileRule (Database local time)
pathName String Name of the path where this unique hash was first seen
fileName String Name of the file under which this unique hash was first seen
fileExtension String Extension of the file under which this unique hash was first seen
computerId Int32 Id of computer where this file was first seen
md5 String Md5 hash
sha1 String Sha-1 hash
sha256 String Sha-256 hash
sha256HashType Int32 Can be one of:
5:Regular hash
6:Fuzzy hash for MSI installers
fileType String Type of the file
fileSize Int64 Size of the file in bytes
productName String Name of the product associated with this file in the VERSIONINFO resource
description String Description of the product associated with this file in the VERSIONINFO resource
publisher String Subject name of the certificate that signed this file
company String Name of the company associated with this file in the VERSIONINFO resource
publisherOrCompany String Publisher name of the file if it exist. If file is not signed, this will be a company name from the VERSIONINFO resource
productVersion String Version of the file in the VERSIONINFO resource
installedProgramName String Name of the product associated with this file in the MSI package
reputationAvailable Boolean True if reputation information has arrived for this file
trust Int32 Trust of this file (0-10). Special value of -1 is reserved for unknown
trustMessages String More details about trust of this file
threat Int16 Threat of this file. Can be one of:
-1=Unknown
0=Clean
50=Potential risk
100=Malicious
category String Category of this file
fileState Int32 File state of this hash. Can be one of:
1=Unapproved
2=Approved
3=Banned
4=Approved by Policy
5=Banned by Policy
publisherState Int32 Publisher state of this hash. Can be one of:
1=Unapproved
2=Approved
3=Banned
4=Approved by Policy
5=Banned by Policy
certificateState Int32 Certificate state of this hash. Can be one of:
1=Unapproved
2=Approved
3=Banned
4=Approved by Policy
5=Banned by Policy
6=Mixed
effectiveState String Effective state of this hash, taking into account publisherState and fileState. Can be one of:
Unapproved
Approved
Banned
Approved by Policy
Banned by Policy
Mixed
approvedByReputation Boolean True if this file was approved by reputation
reputationEnabled Boolean True if reputation approvals are enabled for this file
acknowledged Boolean True if this file was acknowledged
clVersion Int64 CL version associated with this file
prevalence Int32 Number of endpoints that have this file
dirtyPrevalence Int32 Number of endpoints that have this file (unprocessed entries, can be null if all entries are processed)
fileFlags Int32 File flags.
0x00001 = File will report executions as ‘report bans’
0x00004 = File is manually marked as installer
0x00010 = File is detected as installer
0x00100 = File was seen as root of installation
0x00200 = File was seen as a child of of installation
0x01000 = File has all needed metadata
0x04000 = File was executed on endpoint
0x10000 = File is manually marked as ‘not installer’
0x20000 = State we are sending applies to all children if this is a root hash
0x40000 = File came from a Trusted Directory
0x80000 = File is an msi root file
0x200000 = File was seen blocking on at least one endpoint
0x400000 = File can be approved by reputation
0x2000000 = This is not an ‘interesting’ file
0x4000000 = The signature on this file is invalid
0x8000000 = We have all necessary metadata from Macintosh and Linux platforms
0x10000000 = The Server has gotten the data that comes with an ABItem on a ReportABList request
0x20000000 = File is excluded from inventory tracking and its prevalence count could be invalid.
publisherId Int32 Id of publisher that signed this file
certificateId Int32 Id of certificate that signed this file
verdict Int32 Combined File Analysis verdicts into one. Can be one of:
0 = Not available
1 = File is potentially clean
2 = File is clean
3 = File is a potential risk
4 = File is malicious
stateSource String If approved, how the file got that way
nodeType Int32 Can be one of:
0 = None (top level)
1 = Child
2 = Root
3 = Root + Child
transactionId Guid ID associated with file approval (if any)
globalStateDetails String How the file got into this state
initialized Boolean Whether the file has been initialized
unifiedSource String Unified server name that created this rule

POST Request for fileCatalog

Description: Change file catalog acknowledgement state

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

Call syntax: bit9platform/v1/fileCatalog

Name Source Type Description
value FromBody fileCatalog Value of new fileCatalog object

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}

Name Source Type Description
id FromUri Int32 id of file catalog object
acknowledge FromUri Boolean new acknowledge flag
changeLocalStateForComputerId FromUri Int32 change local approval state for this computer id
newApprovalState FromUri FileState the new approval state to change to. 1 = Unapproved, 2 = Approved

GET Request for fileCatalog

Description: Returns object instance of this class

Required permissions: ‘View files’

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

Name Source Type Description
id FromUri Int64 id of a requested object

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}

Name Source Type Description
q FromUri List Query condition (Optional - multiple query conditions are supported)
group FromUri String Field name to group by (Optional)
sort FromUri String Field name to sort by (Optional)
offset FromUri Int32 Offset in query results (Optional)
limit FromUri Int32 Maximum number of results to return. When 0 or not present, all results will be returned. When -1, only count will be returned. When -2, a “quick count” will be returned.

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

Name Type Property Description
id Int64 Unique id of this fileInstance
fileCatalogId Int32 Id of fileCatalog associated with this fileInstance
fileInstanceGroupId Int64 Id of fileInstanceGroup associated with this fileInstance
computerId Int32 Id of computer associated with this fileInstance
policyId Int32 Id of policy associated with this fileInstance. This is a foreign key and can be expanded to expose fields from the related policy object
dateCreated DateTime Date/Time when file was was created on agent (UTC)
fileName String Name of the file on the agent
pathName String Path of the file on the agent
executed Boolean True if file was ever executed on the agent
localState Int32 Local state of the file on the agent. Can be one of:
1=Unapproved
2=Approved
3=Banned
detailedLocalState Int32 Local state of the file on the agent. Can be one of:
1=Approved (Not Persisted)
2=Unapproved (Persisted)
3=Banned
4=Locally Approved
5=Banned by name (6.x agents only)
6=Banned by name (Report only, 6.x agents only)
7=Locally Approved (Auto)
8=Approved as Installer
11=Approved
12=Approved as Installer (Top Level)
13=Banned (Report only)
14=Unapproved
certificateId Int32 Id of certificate that signed this file through the catalog. This is a foreign key and can be expanded to expose fields from the related certificate object
detachedPublisherId Int32 Id of detached publisher that signed this file through the catalog
detachedCertificateId Int32 Id of detached certificate that signed this file through the catalog
initialized Boolean Whether fileInstance is initialized
topLevel Boolean Whether fileInstance is top level
unifiedSource String Unified server name that created the file rule

Properties modifiable Using PUT/POST Request for fileInstance

Name Type Property Description
localState Int32 Target local state for the file on the agent. Can be one of:
1=Unapproved
2=Approved.
Note that changed local state might not be reflected in the object immediately, but only after agent reports new state.

POST Request for fileInstance

Description: Change local file instance state

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

Call syntax: bit9platform/v1/fileInstance

Name Source Type Description
value FromBody fileInstance Value of new fileInstance object

PUT Request for fileInstance

Description: Change local file instance state

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

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

Name Source Type Description
id FromUri Int32 id of fileInstance to change
value FromBody fileInstance Value of new fileInstance object

GET Request for fileInstance

Description: Returns object instance of this class

Required permissions: ‘View files’

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

Name Source Type Description
id FromUri Int64 id of a requested object

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}

Name Source Type Description
q FromUri List Query condition (Optional - multiple query conditions are supported)
group FromUri String Field name to group by (Optional)
sort FromUri String Field name to sort by (Optional)
offset FromUri Int32 Offset in query results (Optional)
limit FromUri Int32 Maximum number of results to return. When 0 or not present, all results will be returned. When -1, only count will be returned.

FileInstanceDeleted

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

All Object Properties for fileInstanceDeleted

Name Type Property Description
id Int64 Unique id of this fileInstanceDeleted
fileInstanceGroupId Int64 Id of fileInstanceGroup associated with this fileInstanceDeleted
fileCatalogId Int32 Id of fileCatalog associated with this fileInstanceDeleted
computerId Int32 Id of computer associated with this fileInstanceDeleted
policyId Int32 Id of policy associated with this fileInstanceDeleted
dateCreated DateTime Date/Time when file was was created on agent (UTC)
dateDeleted DateTime Date/Time when file was was deleted on agent (UTC)
fileName String Name of the file on the agent
pathName String Path of the file on the agent
certificateId Int32 Id of certificate that signed this file through the catalog.
detachedPublisherId Int32 Id of detached publisher that signed this file through the catalog
detachedCertificateId Int32 Id of detached certificate that signed this file through the catalog
initialized Boolean Whether fileInstanceDeleted is initialized
topLevel Boolean Whether fileInstanceDeleted is top level
unifiedSource String Unified server name that created the file rule

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}

Name Source Type Description
id FromUri Int64 id of a requested object

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}

Name Source Type Description
q FromUri List Query condition (Optional - multiple query conditions are supported)
group FromUri String Field name to group by (Optional)
sort FromUri String Field name to sort by (Optional)
offset FromUri Int32 Offset in query results (Optional)
limit FromUri Int32 Maximum number of results to return. When 0 or not present, all results will be returned. When -1, only count will be returned. When -2, a “quick count” will be returned.

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

Name Type Property Description
id Int64 Unique id of this fileInstanceGroup
fileCatalogId Int32 Id of fileCatalog associated with this fileInstanceGroup
computerId Int32 Id of computer associated with this fileInstanceGroup
policyId Int32 Id of policy associated with this fileInstanceGroup
dateCreated DateTime Date/Time when file was was created on agent (UTC)
fileName String Name of the file on the agent
pathName String Path of the file on the agent
userName String User associated with this group creation on the agent
groupType Int32 Type of this group. It can be one of:
0=initialization group
1=top level group
2=process group
3=MSI group
installedProgramName String User associated with this group creation on the agent
fileGroupId Int32 ID of the overall file group
unifiedSource String Unified server name that created the file rule

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}

Name Source Type Description
id FromUri Int64 id of a requested object

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}

Name Source Type Description
q FromUri List Query condition (Optional - multiple query conditions are supported)
group FromUri String Field name to group by (Optional)
sort FromUri String Field name to sort by (Optional)
offset FromUri Int32 Offset in query results (Optional)
limit FromUri Int32 Maximum number of results to return. When 0 or not present, all results will be returned. When -1, only count will be returned.

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

Name Type Property Description
id Int64 Unique id of this fileRule
fileCatalogId Int32 Id of fileCatalog entry associated with this fileRule. Can be null if file hasn’t been seen on any endpoints yet
name String Name of this rule
description String Description of this rule
fileState Int32 File state for this rule. Can be one of:
1=Unapproved
2=Approved
3=Banned
sourceType Int32 >Mechanism that created this rule. Can be one of:
1 = Manual
2 = Trusted Directory
3 = Reputation
4 = Imported
5 = External (API)
6 = Event Rule
7 = Application Template
8 = Unified Management
sourceId Int32 Id of source of this rule. Can be event rule id or trusted directory id
reportOnly Boolean True if this has a report-only ban
reputationApprovalsEnabled Boolean True if reputation approvals are enabled for this file
forceInstaller Boolean True if this file is forced to act as installer, even if product detected it as ‘not installer’
forceNotInstaller Boolean True if this file is forced to act as ‘not installer’, even if product detected it as installer
policyIds String List of IDs of policies where this rule applies. 0 if this is a global rule
hash String Hash associated with this rule. Note that hash will be available only if rule was created through md5 or sha-1 hash. If rule was created through fileCatalogId or sha-256 hash that exists in the catalog, this field will be empty
fileName String File name associated with this rule. Note that file name will be available only if rule was created through file name. If rule was created through fileCatalogId or hash, this field will be empty.
lazyApproval Boolean This filed is valid only when creating approvals. When set to true, it will cause approval to be sent to agent only if file is marked as installer or if it blocked on any agent. This is useful when proactively creating lot of approvals that might or might not be required, since it is using less resources. Note that, as soon as lazy approval is sent to agents, this field will changed to ‘false’.
platformFlags Int32 Set of platform flags where this file rule will be valid. combination of:
1 = Windows
2 = Mac
4 = Linux
dateCreated DateTime Date/time when this rule was created (UTC)
createdBy String User that created this rule
dateModified DateTime Date/time when this rule was last modified (UTC)
modifiedBy String User that last modified this rule
modifiedByUserId Int32 Id of user that last modified this object
clVersion Int64 CL version associated with this file rule
idUnique Guid Unique GUID of this rule
origIdUnique Guid Unique GUID of the original rule
unifiedFlag Int32 Local override flag for unified rule (0 - if rule is not unified, 1 - no override allowed, 3 - local overrid
unifiedSource String Unified server name that created this rule
fileRuleType String Text description of file rule type
version Int64 Version of this file rule
visible Boolean If rule should be visible in the UI or not

Properties modifiable Using PUT/POST Request for fileRule

Name Type Property Description
fileCatalogId Int32 Id of fileCatalog entry associated with this fileRule. Can be 0 if creating/modifying rule based on hash or file name
name String Name of this rule
description String Description of this rule
fileState Int32 File state for this rule. Can be one of:
1=Unapproved
2=Approved
3=Banned
sourceType Int32 Mechanism that created this rule. Can be one of:
1 = Manual
2 = Trusted Directory
3 = Reputation
4 = Imported
5 = External (API)
6 = Event Rule
7 = Application Template
8 = Unified Management
reportOnly Boolean Set to true to create a report-only ban. Note: fileState has to be set to 1 (unapproved) before this flag can be set.
reputationApprovalsEnabled Boolean True if reputation approvals are enabled for this file
forceInstaller Boolean True if this file is forced to act as installer, even if product detected it as ‘not installer’
forceNotInstaller Boolean True if this file is forced to act as ‘not installer’, even if product detected it as installer
policyIds String List of IDs of policies where this rule applies. 0 if this is a global rule
hash String Hash associated with this rule. This parameter is ignored if fileCatalogId is supplied
fileName String File name associated with this rule. This parameter is ignored if fileCatalogId or hash is supplied
lazyApproval Boolean This filed is valid only when creating approvals. When set to true, it will cause approval to be sent to agent only if file is marked as installer or if it blocked on any agent. This is useful when proactively creating lot of approvals that might or might not be required, since it is using less resources
platformFlags Int32 Set of platform flags where this file rule will be valid. combination of:
1 = Windows
2 = Mac
4 = Linux
origIdUnique Guid Unique GUID of the original rule
unifiedFlag Int32 Local override flag for unified rule (0 if rule is not unified, 1
unifiedSource String Unified server name that created this rule

POST Request for fileRule

Description: Creates or updates file rule

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

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

Name Source Type Description
value FromBody fileRule New file rule object
delete FromUri Boolean If this is invoked from DELETE

PUT Request for fileRule

Description: Updates existing file rule

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

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

Name Source Type Description
id FromUri Int32 Id of file rule to create or update
value FromBody fileRule New file rule object

DELETE Request for fileRule

Description: Delete file rule

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

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

Name Source Type Description
id FromUri Int32 id of file rule for which to delete ban or approval. Note that, after deletion, rule will remain, but its fileState will be 1 (Unapproved). This means that rule is effectively inactive

GET Request for fileRule

Description: Returns object instance of this class

Required permissions: ‘View files’

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

Name Source Type Description
id FromUri Int64 id of a requested object

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}

Name Source Type Description
q FromUri List Query condition (Optional - multiple query conditions are supported)
group FromUri String Field name to group by (Optional)
sort FromUri String Field name to sort by (Optional)
offset FromUri Int32 Offset in query results (Optional)
limit FromUri Int32 Maximum number of results to return. When 0 or not present, all results will be returned. When -1, only count will be returned. When -2, a “quick count” will be returned.
expand FromUri String[] Foreign key fields to expand (Optional)

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

Name Type Property Description
id Int32 Unique id of this fileUpload
computerId Int32 Id of computer entry associated with this analysis
fileCatalogId Int32 Id of fileCatalog entry associated with this upload
createdBy String User that requested upload
dateCreated DateTime Date/time when upload was requested (UTC)
dateModified DateTime Date/time when upload was last modified by system (UTC)
fileName String Name of the file where file exists on the endpoint
pathName String Path of the file where file exists on the endpoint
priority Int32 Upload priority in range [-2, 2], where 2 is highest priority. Default priority is 0
uploadPath String Local upload path for this file on the server (can be a shared network path). Note that file is compressed in a ZIP archive
uploadedFileSize Int64 Size of uploaded file. This will be 0 unless uploadStatus is 3 (Completed)
uploadStatus Int32 Status of upload. Can be one of:
0 = Queued
1 = Initiated
2 = Uploading
3 = Completed
4 = Error
5 = Cancelled
6 = Deleted

Properties modifiable Using PUT/POST Request for fileUpload

Name Type Property Description
computerId Int32 Id of computer from which to upload the file. If 0, system will find best computer to get the file from
fileCatalogId Int32 Id of fileCatalog entry for file to upload
priority Int32 Upload priority in range [-2, 2], where 2 is highest priority. Default priority is 0
uploadStatus Int32 Status of upload. Status of upload in progress can be changed to 5 (Cancelled). Any upload can be changed to 6 (Deleted)

GET Request for fileUpload

Description: Returns fileUpload object

Required permissions: ‘View file uploads’

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

Name Source Type Description
id FromUri Int64 id of a requested fileUpload
downloadFile FromUri Boolean Set to true to get binary file back in the response of the message (valid only if uploadStatus is 3). Can return 503 in case when server is overloaded. In that case try again later.

GET Request for fileUpload

Description: Returns object instance of this class

Required permissions: ‘View file uploads’

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

Name Source Type Description
id FromUri Int64 id of a requested object

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}

Name Source Type Description
q FromUri List Query condition (Optional - multiple query conditions are supported)
group FromUri String Field name to group by (Optional)
sort FromUri String Field name to sort by (Optional)
offset FromUri Int32 Offset in query results (Optional)
limit FromUri Int32 Maximum number of results to return. When 0 or not present, all results will be returned. When -1, only count will be returned.

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

Name Source Type Description
value FromBody fileUpload New fileUpload object

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}

Name Source Type Description
id FromUri Int32 Id of file rule to create or update
value FromBody fileUpload New fileUpload object

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

Name Type Property Description
id String Unique id of granted permission
userId Int32 id of the user. This is foreign key and can be expanded to expose fields from the related user object
permissions String Permissions associated with users of this userGroup as a hexadecimal string. Can be combination of:
PERMISSION_COMPUTERS_VIEW = 0x0000000000000001
PERMISSION_COMPUTERS_ASSIGN = 0x0000000000000002
PERMISSION_COMPUTERS_TEMPORARY_ASSIGN = 0x0000000000000004
PERMISSION_COMPUTERS_ADVANCED = 0x0000000000000008
PERMISSION_FILES_VIEW = 0x0000000000000010
PERMISSION_FILES_MANAGE_STATE = 0x0000000000000020
PERMISSION_FILES_MANAGE_LOCAL_STATE = 0x0000000000000040
PERMISSION_POLICIES_VIEW = 0x0000000000000080
PERMISSION_POLICIES_MANAGE = 0x0000000000000100
PERMISSION_POLICIES_MAPPINGS = 0x0000000000000200
PERMISSION_RULES_VIEW = 0x0000000000000400
PERMISSION_RULES_MANAGE_DEVICE = 0x0000000000000800
PERMISSION_RULES_MANAGE_EVENT = 0x0000000000001000
PERMISSION_RULES_MANAGE_DIRECTORIES = 0x0000000000002000
PERMISSION_RULES_MANAGE_PUBLISHERS = 0x0000000000004000
PERMISSION_RULES_MANAGE_USERS = 0x0000000000008000
PERMISSION_RULES_MANAGE_CUSTOM = 0x0000000000010000
PERMISSION_REPORTS_VIEW_EVENTS = 0x0000000000020000
PERMISSION_REPORTS_MANAGE_DASHBOARDS = 0x0000000000040000
PERMISSION_REPORTS_VIEW_DRIFT = 0x0000000000080000
PERMISSION_REPORTS_MANAGE_DRIFT = 0x0000000000100000
PERMISSION_REPORTS_MANAGE_SNAPSHOTS = 0x0000000000200000
PERMISSION_REPORTS_SAVED_VIEWS = 0x0000000000400000
PERMISSION_TOOLS_VIEW_ALERTS = 0x0000000000800000
PERMISSION_TOOLS_MANAGE_ALERTS = 0x0000000001000000
PERMISSION_TOOLS_VIEW_METERS = 0x0000000002000000
PERMISSION_TOOLS_MANAGE_METERS = 0x0000000004000000
PERMISSION_ADMINISTRATION_VIEW_CONFIG = 0x0000000008000000
PERMISSION_ADMINISTRATION_VIEW_USERS = 0x0000000010000000
PERMISSION_ADMINISTRATION_MANAGE_CONFIG = 0x0000000020000000
PERMISSION_ADMINISTRATION_MANAGE_USERS = 0x0000000040000000
PERMISSION_ADMINISTRATION_MANAGE_USER_GROUPS = 0x0000000100000000
PERMISSION_DEVICES_VIEW = 0x0000000200000000
PERMISSION_RULES_MANAGE_UPDATERS = 0x0000000400000000
PERMISSION_MANAGE_APPROVAL_REQUESTS = 0x0000000800000000
PERMISSION_VIEW_APPROVAL_REQUESTS = 0x0000001000000000
PERMISSION_VIEW_UPLOADED_FILES = 0x0000002000000000
PERMISSION_ALLOW_UPLOAD_INVENTORY = 0x0000004000000000
PERMISSION_ALLOW_EXECUTE_COMMANDS = 0x0000008000000000
PERMISSION_RULES_MANAGE_SCRIPT = 0x0000010000000000
PERMISSION_NOTIFIERS_VIEW = 0x0000020000000000
PERMISSION_NOTIFIERS_MANAGE = 0x0000040000000000
PERMISSION_ACCESS_UPLOAD_FILES = 0x0000080000000000
PERMISSION_ALLOW_UPLOAD_FILES_BY_PATH = 0x0000100000000000
PERMISSION_ALLOW_ANALYZE_FILES = 0x0000200000000000
PERMISSION_RULES_MANAGE_ATI_SETS = 0x0000400000000000
PERMISSION_VIEW_EXTERNAL_ANALYTICS = 0x0000800000000000
PERMISSION_VIEW_PROCESS_COMMAND_LINES = 0x0001000000000000
PERMISSION_VIEW_SYSTEM_HEALTH = 0x0002000000000000
PERMISSION_EXTEND_CONNECTORS = 0x0004000000000000
PERMISSION_USE_UNIFIED_MANAGEMENT = 0x0800000000000000L
PERMISSION_CONFIGURE_UNIFIED_MANAGEMENT = 0x1000000000000000L
policyId Int32 Id of policy associated with this granted permission. It can be 0, indicating that permission is granted in all policies. This is foreign key and can be expanded to expose fields from the related policy object

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}

Name Source Type Description
id FromUri Int64 id of a requested object

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}...

Name Source Type Description
q FromUri List Query condition (Optional - multiple query conditions are supported)
group FromUri String Field name to group by (Optional)
groupType FromUri String Type of windowed grouping (Optional, for time-based fields only)
groupStep FromUri Int32 Step for windowed grouping (Optional, for time-based fields only)
sort FromUri String Field name to sort by (Optional)
offset FromUri Int32 Offset in query results (Optional)
limit FromUri Int32 Maximum number of results to return. When 0 or not present, all results will be returned. When -1, only count will be returned.
expand FromUri String[] Foreign key fields to expand (Optional)

InternalEvent

v1/internalEvent object exposes private events.

All Object Properties for internalEvent

Name Type Property Description
id Int64 Unique event Id
timestamp DateTime Date/Time when event was created (UTC)
receivedTimestamp DateTime Date/Time when event was received by the server (UTC)
description String Event description
type Int32 Event type. Can be one of:
0 = Server Management
1 = Session Management
2 = Computer Management
3 = Policy Management
4 = Policy Enforcement
5 = Discovery
6 = General Management
8 = Internal Events
subtype Int32 Event subtype. Can be one of event subtype IDs
subtypeName String Event subtype as string
ipAddress String IP address associated with this event
computerId Int32 Id of computer associated with this event
computerName String Name of computer associated with this event
policyId Int32 Id of policy where agent was at the time of the event
policyName String Name of policy where agent was at the time of the event
fileCatalogId Int32 Id of fileCatalog entry associated with file for this event
installerFileCatalogId Int32 Id of fileCatalog entry associated with installer for this event
processFileCatalogId Int32 Id of fileCatalog entry associated with process for this event
fileName String Name of the file associated with this event
pathName String Path of the file associated with this event
commandLine String Full command line associated with this event. Viewing this field requires ‘View process command lines’ permission
processPathName String Name of the process associated with this event
processFileName String Path of the process associated with this event
installerFileName String Name of the installer associated with this event
processKey String Process key associated with this event. This key uniquely identifies the process in both App Control Platform and Carbon Black product
severity Int32 Event severity. Can be one of:
2 = Critical
3 = Error
4 = Warning
5 = Notice
6 = Info
7 = Debug
userName String User name associated with this event
ruleName String Rule name associated with this event
banName String Ban name associated with this event
updaterName String Updater name associated with this event
indicatorName String Advanced threat indicator name associated with this event
param1 String Internal string parameter 1
param2 String Internal string parameter 2
param3 String Internal string parameter 3
stringId Int32 Internal string Id used for description

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}

Name Source Type Description
id FromUri Int64 id of a requested object

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}

Name Source Type Description
q FromUri List Query condition (Optional - multiple query conditions are supported)
group FromUri String Field name to group by (Optional)
sort FromUri String Field name to sort by (Optional)
offset FromUri Int32 Offset in query results (Optional)
limit FromUri Int32 Maximum number of results to return. When 0 or not present, all results will be returned. When -1, only count will be returned. When -2, a “quick count” will be returned.

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

Name Type Property Description
id Int32 Unique id of this meteredExecution
meterId Int32 Id of meter associated with this execution
name String Name of meter associated with this execution
description String Description of meter associated with this execution
type Int32 How the meter was defined. Can be one of:
1=md5 hash
2=sha1 hash
4=file name
5=sha-256 hash
6=fuzzy sha-256 hash
data String Data from definition of meter. Data depends on type, and can be file name or hash
eventId Int64 Id of event associated with this execution
computerId Int32 Id of computer associated with this execution
fileCatalogId Int32 Id of filecatalog entry associated with this execution
timestamp DateTime Date/time associated with this execution (UTC)
userName String User name associated with this execution

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}

Name Source Type Description
id FromUri Int64 id of a requested object

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}

Name Source Type Description
q FromUri List Query condition (Optional - multiple query conditions are supported)
group FromUri String Field name to group by (Optional)
sort FromUri String Field name to sort by (Optional)
offset FromUri Int32 Offset in query results (Optional)
limit FromUri Int32 Maximum number of results to return. When 0 or not present, all results will be returned. When -1, only count will be returned.

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

Name Type Property Description
connectorId Int64 Id of connector object that sent the notification
time DateTime Date/time of the notification (UTC)
analysisResult Int32 Analysis result. Can be one of:
0 = Unknown
1 = Not malicious
2 = Potential risk
3 = Malicious
fileAnalysisId Int64 Id of fileAnalysis object associated with the notification. This should be available if notification came as a result of the file analysis
fileName String File name (Optional)
md5 String Md5 hash of the file (Optional)
sha256 String Sha256 hash of the file (Optional)
sha1 String Sha-1 hash of the file (Optional)
malwareName String Name of malware (Optional)
malwareType String Type of malware (Optional)
externalUrl String External URL showing more details about the results (Optional)
externalId Int32 External Id (Optional)
severity String Severity of notification (Optional)
type String Type of notification (Optional)
appliance String Name of appliance (Optional)
product String Name of product (Optional)
version String Vesion of the product (Optional)
srcIp String Source IP address (Optional)
srcHost String Source computer name (Optional)
destIp String Destination IP address (Optional)
msgFormat String Message format (Optional)
anomaly String Anomaly detected by the appliance (Optional)
targetApp String Application associated with the notification(Optional)
targetOS String Target OS used when analyzing file (Optional)
httpHeader String Http header associated with the notification (Optional)
status Int32 Status associated with the notification (Optional)
srcUsername String Source user name associated with the network traffic (Optional)
destUsername String Destination user name associated with the network traffic (Optional)
flags Int32 Flags associated with the notification (Optional)
files NotificationFile[] Optional array of file objects with following fields:
• md5 Md5 hash of the file (Optional)
• sha1 Sha-1 hash of the file (Optional)
• sha256 Sha-256 hash of the file (Optional)
• fileSize Size of the file (Optional)
• fileName Name of the file (Optional)
• filePath Path of the file (Optional)
• processName Name of the process that created this directory (Optional)
• processPath Path of the process that created this directory (Optional)
• operation Operation associated with this directory (Optional)
• topLevel True if this is a top-level file (Optional)
regKeys NotificationRegKey[] Optional array of regkey objects with following fields:
• regKey Registry key path (Optional)
• regName Registry key name (Optional)
• regValue Registry key value (Optional)
• processMd5 Md5 hash of the process that created this directory (Optional)
• Operation Operation associated with this registry key (Optional)
directories NotificationDirectory[] Optional array of directory objects with following fields:
• dirPath Path of the created directory (Optional)

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

Name Source Type Description
value FromBody notification New notification object

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

Name Type Property Description
id Int32 Unique id of this notifier
name String Name of this notifier
title String Notifier dialog title
messageText String Full message text appearing in notifier dialog
eventLogText String Event log text
url String Url link appearing on notifier dialog
fgImageLocation String Foreground image of notifier dialog
bgImageLocation String Background image of notifier dialog
timeout Int32 Timeout of notifier in seconds
showLogo Boolean True to show logo on notifier dialog
logoUrl String Url to the logo image
flags Int32 Notifier flags. Can be 0 or combination of:
1 = Show approval request fields
2 = Show justification fields
systemNotifier Boolean True if this is system notifier
defaultRuleType Int32 Default customRule type for this notifier
defaultRuleGroupId Int32 Default customRule group Id for this notifier
createdBy String User that created this notifier
dateCreated DateTime Date/time when notifier was created (UTC)
modifiedBy String User that last modified this notifier
dateModified DateTime Date/time when notifier was last modified (UTC)
usageCount Int32 Number of customRule objects that reference this notifier
clVersion Int64 CL version associated with this 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}

Name Source Type Description
id FromUri Int64 id of a requested object

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}

Name Source Type Description
q FromUri List Query condition (Optional - multiple query conditions are supported)
group FromUri String Field name to group by (Optional)
sort FromUri String Field name to sort by (Optional)
offset FromUri Int32 Offset in query results (Optional)
limit FromUri Int32 Maximum number of results to return. When 0 or not present, all results will be returned. When -1, only count will be returned.

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

Name Type Property Description
id Int64 Unique fileAnalysis id
priority Int64 Priority of this file analysis
uploaded Boolean True if file is available
fileCatalogId Int32 Id of fileCatalog entry associated with this analysis
connectorId Int32 Id of connector associated with this analysis
createdBy String User that requested this analysis
dateCreated DateTime Date/Time when fileAnalysis request was created (UTC)
dateModified DateTime Date/Time when fileAnalysis request was last modified (UTC)
fileName String Name of the file where file exists on the endpoint
pathName String Path of the file where file exists on the endpoint
md5 String Md5 hash of file to be analyzed (if available)
sha1 String Sha-1 hash of file to be analyzed (if available)
sha256 String Sha-256 hash of file to be analyzed
uploadPath String Local upload path for this file on the server (can be a shared network path). Note that file is compressed in a ZIP archive
uploadedFileSize Int64 Size of uploaded file. This will be 0 if analysisStatus is 0 (Scheduled)
analysisStatus Int32 Status of analysis. Can be one of:
0 = scheduled
1 = submitted (file is sent for analysis)
2 = processed (file is processed but results are not available yet)
3 = analyzed (file is processed and results are available)
4 = error
5 = cancelled
analysisResult Int32 Result of the analysis. Can be one of:
0 = Not yet available
1 = File is clean
2 = File is a potential risk
3 = File is malicious
analysisTarget String Target of the analysis (Connector-dependent)
analysisError String Error that occurred during analysis

Properties modifiable Using PUT/POST Request for pendingAnalysis

Name Type Property Description
analysisStatus Int32 Status of analysis. Can be one of:
0 = scheduled
1 = submitted (file is sent for analysis)
2 = processed (file is processed but results are not available yet)
3 = analyzed (file is processed and results are available)
4 = error
5 = cancelled
analysisResult Int32 Result of the analysis. Can be set only if analysisStatus is set to 3. Possible values are:
0 = Not yet available
1 = File is clean
2 = File is a potential threat
3 = File is malicious
analysisError String Error that occurred during analysis (can be set only if analysisStatus is set to 4)

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}

Name Source Type Description
connectorId FromUri Int32 Id of connector for which to return results
maxCount FromUri Int32 (Optional) Max number of results to return. Defaults to 10

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}

Name Source Type Description
id FromUri Int64 Pending analysis id
downloadFile FromUri Boolean Set to true to get binary file back in the response of the message (valid only if uploaded is true). Can return 503 in case when server is overloaded. In that case try again later.

GET Request for pendingAnalysis

Description: Returns object instance of this class

Required permissions: ‘Extend connectors through API’

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

Name Source Type Description
id FromUri Int64 id of a requested object

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}

Name Source Type Description
q FromUri List Query condition (Optional - multiple query conditions are supported)
group FromUri String Field name to group by (Optional)
sort FromUri String Field name to sort by (Optional)
offset FromUri Int32 Offset in query results (Optional)
limit FromUri Int32 Maximum number of results to return. When 0 or not present, all results will be returned. When -1, only count will be returned.

PUT Request for pendingAnalysis

Description: Updates existing pending analysis requests

Required permissions: ‘Extend connectors through API’

Call syntax: bit9platform/v1/pendingAnalysis

Name Source Type Description
value FromBody pendingAnalysis Pending analysis object to update

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

Name Type Property Description
id Int32 Unique id of this policy
name String Name of this policy
description String Description of this policy
packageName String Name of installer package for this policy
enforcementLevel Int32 Target enforcement level. Can be one of:
20=High (Block Unapproved)
30=Medium (Prompt Unapproved)
40=Low (Monitor Unapproved)
60=None (Visibility)
80=None (Disabled)
disconnectedEnforcementLevel Int32 Target enforcement level for disconnected computers. Can be one of:
20=High (Block Unapproved)
30=Medium (Prompt Unapproved)
40=Low (Monitor Unapproved)
60=None (Visibility)
80=None (Disabled)
helpDeskUrl String Helpdesk URL for notifiers in this policy
imageUrl String Image logo URL for notifiers in this policy
dateCreated DateTime Date/time when policy was created (UTC)
dateModified DateTime Date/time when policy was last modified (UTC)
readOnly Boolean True if this policy is read-only
hidden Boolean True if this policy is hidden in the UI
automatic Boolean True if AD mapping is enabled for this policy
loadAgentInSafeMode Boolean True if agents in this policy will be loaded when machine is booted in “safe mode”
reputationEnabled Boolean True if reputation approvals are enabled in this policy
fileTrackingEnabled Boolean True if file tracking enabled in this policy
customLogo Boolean True if notifiers in this policy use custom logo
automaticApprovalsOnTransition Boolean True if agents in this policy will automatically locally approve files when transitioning into High Enforcement
allowAgentUpgrades Boolean True if agents can be upgraded for this policy
clVersionMax Int32 Max target CL version for agents in this policy

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

GET Request for policy

Description: Returns object instance of this class

Required permissions: ‘View policies’

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

Name Source Type Description
id FromUri Int64 id of a requested object

GET Request for policy

Description: Returns objects that match given criteria

Required permissions: ‘View policies’

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

Name Source Type Description
q FromUri List Query condition (Optional - multiple query conditions are supported)
group FromUri String Field name to group by (Optional)
sort FromUri String Field name to sort by (Optional)
offset FromUri Int32 Offset in query results (Optional)
limit FromUri Int32 Maximum number of results to return. When 0 or not present, all results will be returned. When -1, only count will be returned.

Publisher

v1/publisher object exposes publisher information and allows changing publisher state (Banning or Approving).

All Object Properties for publisher

Name Type Property Description
id Int32 Unique id of this publisher
name String Subject name of leaf certificate for this publisher
description String User-defined description for this publisher
modifiedBy String User that last modified this publisher
dateCreated DateTime Date/time when this publisher was first seen (UTC)
dateModified DateTime Date/time when this publisher was last modified (UTC)
publisherReputation Int32 Reputation of this publisher. Can be one of:
0=Not trusted (Unknown)
1=Low
2=Medium
3=High
publisherState Int32 State for this publisher. Can be one of:
1=Unapproved
2=Approved
3=Banned
4=Approved By Policy
5=Banned By Policy
firstSeenPlatformId Int32 ID of the platform where this publisher was first seen. It can be one of :
0 = Unknown
1 = Windows
2 = Mac
4 = Linux
acknowledged Boolean True if this publisher is acknowledged
acknowledgedByUserId Int32 Id of user that acknowledged this publisher. This is foreign key and can be expanded to expose fields from the related user object
dateAcknowledged DateTime Date/time when this object was acknowledged (UTC)
policyIds String List of IDs of policies where this rule applies. Empty if this is a global rule
reputationApprovalsEnabled Boolean True if publisher can be approved by reputation
sourceType Int32 Mechanism that changed publisher state. Can be one of:
1 = Manual
3 = Reputation
5 = External (API)
firstSeenComputerId Int32 Id of computer where this publisher was first seen
platformFlags Int32 Set of platform flags where this publisher will be approved/banned. Combination of:
1 = Windows
2 = Mac
4 = Linux
signedFilesCount Int32 Number of files this publisher has signed
signedCertificateCount Int32 Number of certificates associated with this publisher
hidden Boolean True if publisher is hidden from the UI (because it was not seen on endpoints or modified yet)
clVersion Int64 CL version associated with this publisher
stateSource String How this publisher got into this state

Properties modifiable Using PUT/POST Request for publisher

Name Type Property Description
description String User-defined description for this publisher
publisherState Int32 State for this publisher. Can be one of:
1=Unapproved
2=Approved
3=Banned
4=Approved By Policy
5=Banned By Policy
acknowledged Boolean Set to true to acknowledge this publisher
policyIds String List of IDs of policies where this rule applies. 0 if this is a global rule
reputationApprovalsEnabled Boolean True to enable reputation approvals for this publisher
sourceType Int32 Mechanism that changed publisher state. Can be one of:
1 = Manual
3 = Reputation
5 = External (API)
platformFlags Int32 Set of platform flags where this publisher will be appoved/banned. Combination of:
1 = Windows
2 = Mac
4 = Linux

POST Request for publisher

Description: Change publisher state

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

Call syntax: bit9platform/v1/publisher

Name Source Type Description
value FromBody publisher Publisher object with desired parameters.

PUT Request for publisher

Description: Change publisher state

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

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

Name Source Type Description
id FromUri Int32 id of publisher to change
value FromBody publisher Publisher object with desired parameters.

DELETE Request for publisher

Description: Delete publisher ban or approval

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

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

Name Source Type Description
id FromUri Int32 id of publisher for which to delete ban or approval

GET Request for publisher

Description: Returns object instance of this class

Required permissions: ‘View software rules pages’

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

Name Source Type Description
id FromUri Int64 id of a requested object

GET Request for publisher

Description: Returns objects that match given criteria

Required permissions: ‘View software rules pages’

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

Name Source Type Description
q FromUri List Query condition (Optional - multiple query conditions are supported)
group FromUri String Field name to group by (Optional)
sort FromUri String Field name to sort by (Optional)
offset FromUri Int32 Offset in query results (Optional)
limit FromUri Int32 Maximum number of results to return. When 0 or not present, all results will be returned. When -1, only count will be returned.

PublisherCertificate

v1/publisherCertificate object exposes all unique relationships between certificates and publishers.

All Object Properties for publisherCertificate

Name Type Property Description
id Int64 Unique id of this relationship
certificateId Int32 Id of certificate for this relationship. This is foreign key and can be expanded to expose fields from the related certificate object
publisherId Int32 Id of publisher for this relationship. This is foreign key and can be expanded to expose fields from the related publisher object
certificateStateForPublisher Int32 Certificate state in the context of a given publisher. Can be one of:
1=Unapproved
2=Approved
3=Banned

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

GET Request for publisherCertificate

Description: Returns object instance of this class

Required permissions: ‘View software rules pages’

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

Name Source Type Description
id FromUri Int64 id of a requested object

GET Request for publisherCertificate

Description: Returns objects that match given criteria

Required permissions: ‘View software rules pages’

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

Name Source Type Description
q FromUri List Query condition (Optional - multiple query conditions are supported)
group FromUri String Field name to group by (Optional)
groupType FromUri String Type of windowed grouping (Optional, for time-based fields only)
groupStep FromUri Int32 Step for windowed grouping (Optional, for time-based fields only)
sort FromUri String Field name to sort by (Optional)
offset FromUri Int32 Offset in query results (Optional)
limit FromUri Int32 Maximum number of results to return. When 0 or not present, all results will be returned. When -1, only count will be returned.
expand FromUri String[] Foreign key fields to expand (Optional)

ScriptRule

v1/scriptRule object exposes custom script rules. It allows creation and editing of rules that allow tracking of the script files.

All Object Properties for scriptRule

Name Type Property Description
id Int64 Unique id of this scriptRule
name String Name of this rule
description String Description of this rule
definitionType Int32 Type of script definition. It can be one of:
0 = File Association - Process is detected automatically through the file extension association on the system
1=Script Type And Process - Process is defined manually
platformId Int32 Platform where this file rule will be valid. It can be one of:
1 = Windows
2 = Mac
4 = Linux
pattern String File pattern that will be used to identify the script (e.g. *.rpm)
processName String Script files will be active only if file was launched by this process. Note that this field is used only when the definitionType is 1
hidden Boolean True if this script rule is hidden from the console
enabled Boolean True if this script rule is enabled
rescanComputers Boolean Setting this value to true will rescan all systems for existing files that match the definition and report them to the server. Note that enabling this field in a new or existing rule causes a delay during which existing local scripts might not be approved
dateCreated DateTime Date/time when this rule was created (UTC)
createdByUserId Int32 Id of user that created this object. This is foreign key and can be expanded to expose fields from the related user object
createdBy String User that created this object
dateModified DateTime Date/time when this object was last modified (UTC)
modifiedByUserId Int32 Id of user that last modified this object. This is foreign key and can be expanded to expose fields from the related user object
modifiedBy String User that last modified this object
clVersion Int64 CL version associated with this file rule

Properties modifiable Using PUT/POST Request for scriptRule

Name Type Property Description
name String Name of this rule
description String Description of this rule
definitionType Int32 Type of script definition. It can be one of:
0 = File Association - Process is detected automatically through the file extension association on the system
1=Script Type And Process - Process is defined manually
platformId Int32 Platform where this file rule will be valid. It can be one of:
1 = Windows
2 = Mac
4 = Linux
pattern String File pattern that will be used to identify the script (e.g. *.rpm)
processName String Script files will be active only if file was launched by this process. Note that this field is used only when the definitionType is 1
hidden Boolean True if this script rule is hidden from the console
enabled Boolean True if this script rule is enabled
rescanComputers Boolean Setting this value to true will rescan all systems for existing files that match the definition and report them to the server. Note that enabling this field in a new or existing rule causes a delay during which existing local scripts might not be approved

POST Request for scriptRule

Description: Creates or updates Script Rule

Required permissions: ‘View software rules pages’, ‘Manage custom scripts’

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

Name Source Type Description
value FromBody scriptRule New scriptRule object
delete FromUri Boolean Set to true to delete existing scriptRule object

PUT Request for scriptRule

Description: Changes Script Rule

Required permissions: ‘View software rules pages’, ‘Manage custom scripts’

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

Name Source Type Description
id FromUri Int32 id of scriptRule to change
value FromBody scriptRule scriptRule object with desired parameters.

DELETE Request for scriptRule

Description: Deletes Script Rule

Required permissions: ‘View software rules pages’, ‘Manage custom scripts’

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

Name Source Type Description
id FromUri Int32 id of scriptRule to delete.

GET Request for scriptRule

Description: Returns object instance of this class

Required permissions: ‘View software rules pages’

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

Name Source Type Description
id FromUri Int64 id of a requested object

GET Request for scriptRule

Description: Returns objects that match given criteria

Required permissions: ‘View software rules pages’

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

Name Source Type Description
q FromUri List Query condition (Optional - multiple query conditions are supported)
group FromUri String Field name to group by (Optional)
groupType FromUri String Type of windowed grouping (Optional, for time-based fields only)
groupStep FromUri Int32 Step for windowed grouping (Optional, for time-based fields only)
sort FromUri String Field name to sort by (Optional)
offset FromUri Int32 Offset in query results (Optional)
limit FromUri Int32 Maximum number of results to return. When 0 or not present, all results will be returned. When -1, only count will be returned.
expand FromUri String[] Foreign key fields to expand (Optional)

ServerConfig

v1/serverConfig object exposes configuration properties for the server. This is a read-only object. Some of more interesting configuration properties are:

  • API_Version: Version of this API
  • ParityServerVersion: Version of this server installation
  • WebServerAddress: URL of this server
  • BinaryPort: Port used for agent connections
  • CBServerUrl: URL of CarbonBlack server if installed
  • ParityServerOSDescription: OS of this system

All Object Properties for serverConfig

Name Type Property Description
id Int32 Unique id of this serverConfig
name String Name of property
value String Value of property
dateModified DateTime Date/time when this property was last modified (UTC)
modifiedBy String User that last modified this property

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

GET Request for serverConfig

Description: Returns object instance of this class

Required permissions: ‘View system configuration’

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

Name Source Type Description
id FromUri Int64 id of a requested object

GET Request for serverConfig

Description: Returns objects that match given criteria

Required permissions: ‘View system configuration’

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

Name Source Type Description
q FromUri List Query condition (Optional - multiple query conditions are supported)
group FromUri String Field name to group by (Optional)
sort FromUri String Field name to sort by (Optional)
offset FromUri Int32 Offset in query results (Optional)
limit FromUri Int32 Maximum number of results to return. When 0 or not present, all results will be returned. When -1, only count will be returned.

ServerPerformance

v1/serverPerformance object exposes server performance statistics. This is a read-only object.

All Object Properties for serverPerformance

Name Type Property Description
id Int64 Id of entry. Note: id is ordinal in the result set and cannot be persisted/cached.
dateCreated DateTime Date/Time of the performance entry (UTC)
connectedAgents Int32 Average number of connected agents
agentFileBacklog Int64 Size of all agent file change queues
agentProcessingRate Int64 Daily processing rate from the agent queue
serverFileBacklog Int64 Size of server file backlog
serverProcessingRate Int64 Daily processing rate of agent file changes
serverFiles Int64 Total number of inventory files server is tracking
diskDataWrite Int64 Disk data file write rate in B/second
diskDataRead Int64 Disk data file read rate in B/second
diskIndexWrite Int64 Disk index file write rate in B/second
diskIndexRead Int64 Disk index file read rate in B/second
diskLogWrite Int64 Disk log file write rate in B/second
diskDataIOPS Decimal Disk data file IOPS
diskIndexIOPS Decimal Disk index file IOPS
diskLogIOPS Decimal Disk log file IOPS
avgDiskLogWriteStallMs Decimal Average disk log file write stall in Ms
avgDiskDataWriteStallMs Decimal Average disk data file write stall in Ms
avgDiskIndexWriteStallMs Decimal Average disk index file write stall in Ms
avgDiskDataReadStallMs Decimal Average disk data file read stall in Ms
avgDiskIndexReadStallMs Decimal Average disk index file read stall in Ms
sqlMemoryPressure Decimal Memory pressure of SQL server in % of maximum recommended value
sqlLatencyMs Decimal Average network latency between App Control Server and SQL server in Ms
sqlInsertLatencyMs Decimal Average network latency between App Control Server and SQL server when inserting data into database in Ms

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

GET Request for serverPerformance

Description: Returns serverPerformance object

Required permissions: ‘View system configuration’

Call syntax: bit9platform/v1/serverPerformance/{id}?period={period}

Name Source Type Description
id FromUri Int64 id of a requested policy
period FromUri Int32 Period for statistics in hours. If omitted, it defaults to 24.

GET Request for serverPerformance

Description: Returns serverPerformance objects that match given criteria

Required permissions: ‘View system configuration’

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

Name Source Type Description
q FromUri List Query parts
group FromUri String Group by field
sort FromUri String Sort by fields
offset FromUri Int32 Offset in query results
limit FromUri Int32 Maximum number of results to return. Omit to get only count of results.
period FromUri Int32 Period for statistics in hours. If omitted, it defaults to 24.

TrustedDirectory

v1/trustedDirectory object exposes trusted directory rules. It allows creation and editing of trusted directories.

All Object Properties for trustedDirectory

Name Type Property Description
id Int64 Unique id of this trustedDirectory
name String Name of the trusted directory as it will appear on the console. This is not the name of the directory that will be sent to the endpoint
description String Description of this trusted directory
computerId Int32 Id of computer that is hosting this trusted directory. This is foreign key and can be expanded to expose fields from the related computer object
directoryPath String Path to the directory in which agent will globally approve files. This needs to be directory on the agent that is hosting trustedDirectory
enabled Boolean True if this trusted directory is currently enabled
accessible Int32 Accessibility of this trustedDirectory. Can be one of:
-1 = Unknown (Agent did not report the accessibility yet)
0 = Inaccessible (Agent cannot find the directoryPath or it is not accessible)
1 = Accesible (Agent can find and access the directoryPath)
totalItems Int32 Number of work items scheduled for processing by the trustedDirectory. Work item is typically a directory
completedItems Int32 Number of work items that have been processed by the agent so far. completedItems*100/totalItems gives Trusted Directory analysis progress in %.
dateCreated DateTime Date/time when this object was created (UTC)
createdByUserId Int32 Id of user that created this object. This is foreign key and can be expanded to expose fields from the related user object
createdBy String User that created this object
dateModified DateTime Date/time when this object was last modified (UTC)
modifiedByUserId Int32 Id of user that last modified this object. This is foreign key and can be expanded to expose fields from the related user object
modifiedBy String User that last modified this object
clVersion Int64 CL version associated with this trustedDirectory

Properties modifiable Using PUT/POST Request for trustedDirectory

Name Type Property Description
name String Name of the trusted directory as it will appear on the console. This is not the name of the directory that will be sent to the endpoint
description String Description of this trusted directory
computerId Int32 Id of computer that is hosting this trusted directory
directoryPath String Path to the directory in which agent will globally approve files. This needs to be directory on the agent that is hosting trustedDirectory
enabled Boolean True if this trusted directory is currently enabled

POST Request for trustedDirectory

Description: Creates or updates trustedDirectory

Required permissions: ‘View software rules pages’, ‘Manage trusted directories’

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

Name Source Type Description
value FromBody trustedDirectory New trustedDirectory object
delete FromUri Boolean Set to true to delete existing trustedDirectory object

PUT Request for trustedDirectory

Description: Change Trusted directory

Required permissions: ‘View software rules pages’, ‘Manage trusted directories’

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

Name Source Type Description
id FromUri Int32 id of trustedDirectory to change
value FromBody trustedDirectory trustedDirectory object with desired parameters.

DELETE Request for trustedDirectory

Description: Delete Trusted directory

Required permissions: ‘View software rules pages’, ‘Manage trusted directories’

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

Name Source Type Description
id FromUri Int32 id of trustedDirectory to delete.

GET Request for trustedDirectory

Description: Returns object instance of this class

Required permissions: ‘View software rules pages’

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

Name Source Type Description
id FromUri Int64 id of a requested object

GET Request for trustedDirectory

Description: Returns objects that match given criteria

Required permissions: ‘View software rules pages’

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

Name Source Type Description
q FromUri List Query condition (Optional - multiple query conditions are supported)
group FromUri String Field name to group by (Optional)
groupType FromUri String Type of windowed grouping (Optional, for time-based fields only)
groupStep FromUri Int32 Step for windowed grouping (Optional, for time-based fields only)
sort FromUri String Field name to sort by (Optional)
offset FromUri Int32 Offset in query results (Optional)
limit FromUri Int32 Maximum number of results to return. When 0 or not present, all results will be returned. When -1, only count will be returned.
expand FromUri String[] Foreign key fields to expand (Optional)

TrustedUser

v1/trustedUser object exposes trusted user rules. It allows creation and editing of trusted users.

All Object Properties for trustedUser

Name Type Property Description
id Int64 Unique id of this trustedUser
name String Name of the user as it will appear on the console. This is not the name that will be enforced on the endpoint.
userSid String Id of the user that will be trusted on the endpoint. This field can be user name, user SID (Security identifier) on Windows platforms or user’s ID on Linux and Mac platforms
description String Description of this rule
platformId Int32 Platform where this trustedUser will be valid. it is one of:
1 = Windows
2 = Mac
4 = Linux
dateCreated DateTime Date/time when this object was created (UTC)
createdByUserId Int32 Id of user that created this object. This is foreign key and can be expanded to expose fields from the related user object
createdBy String User that created this object
dateModified DateTime Date/time when this object was last modified (UTC)
modifiedByUserId Int32 Id of user that last modified this object. This is foreign key and can be expanded to expose fields from the related user object
modifiedBy String User that last modified this object
clVersion Int64 CL version associated with this trustedUser

Properties modifiable Using PUT/POST Request for trustedUser

Name Type Property Description
name String Name of the user as it will appear on the console. This is not the name that will be enforced on the endpoint. Trusted user names need to be unique - creation of trustedUser will fail if user with the same name already exists.
userSid String Id of the user that will be trusted on the endpoint. This field can be user name, user SID (Security identifier) on Windows platforms or user’s ID on Linux and Mac platforms
description String Description of this rule
platformId Int32 Platform where this rule will be valid. it is one of:
1 = Windows
2 = Mac
4 = Linux

POST Request for trustedUser

Description: Creates or updates trustedUser

Required permissions: ‘View software rules pages’, ‘Manage trusted users’

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

Name Source Type Description
value FromBody trustedUser New trusted user object
delete FromUri Boolean Set to true to delete existing trusted user object

DELETE Request for trustedUser

Description: Delete trusted user

Required permissions: ‘View software rules pages’, ‘Manage trusted users’

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

Name Source Type Description
id FromUri Int32 id of trustedUser to delete.

GET Request for trustedUser

Description: Returns object instance of this class

Required permissions: ‘View software rules pages’

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

Name Source Type Description
id FromUri Int64 id of a requested object

GET Request for trustedUser

Description: Returns objects that match given criteria

Required permissions: ‘View software rules pages’

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

Name Source Type Description
q FromUri List Query condition (Optional - multiple query conditions are supported)
group FromUri String Field name to group by (Optional)
groupType FromUri String Type of windowed grouping (Optional, for time-based fields only)
groupStep FromUri Int32 Step for windowed grouping (Optional, for time-based fields only)
sort FromUri String Field name to sort by (Optional)
offset FromUri Int32 Offset in query results (Optional)
limit FromUri Int32 Maximum number of results to return. When 0 or not present, all results will be returned. When -1, only count will be returned.
expand FromUri String[] Foreign key fields to expand (Optional)

Updater

v1/updater object exposes updater information and allows enabling/disabling of updaters.

All Object Properties for updater

Name Type Property Description
id Int32 Unique updaterId
name String Updater name
version String Updater version
enabled Boolean True if updater is enabled
dateCreated DateTime Date/time when this updater was created (UTC)
createdBy String User that created this updater
dateModified DateTime Date/time when this updater was last modified (UTC)
modifiedBy String User that last modified this updater
clVersion Int64 CL version associated with this updater
platformFlags Int32 Set of platform flags where this updater is valid. combination of:
1 = Windows
2 = Mac
4 = Linux

Properties modifiable Using PUT/POST Request for updater

Name Type Property Description
enabled Boolean True if updater is enabled

POST Request for updater

Description: Change updater state

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

Call syntax: bit9platform/v1/updater

Name Source Type Description
value FromBody updater updater object with desired parameters.

PUT Request for updater

Description: Change updater state

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

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

Name Source Type Description
id FromUri Int32 id of updater to change
value FromBody updater updater object with desired parameters.

GET Request for updater

Description: Returns object instance of this class

Required permissions: ‘View software rules pages’

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

Name Source Type Description
id FromUri Int64 id of a requested object

GET Request for updater

Description: Returns objects that match given criteria

Required permissions: ‘View software rules pages’

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

Name Source Type Description
q FromUri List Query condition (Optional - multiple query conditions are supported)
group FromUri String Field name to group by (Optional)
sort FromUri String Field name to sort by (Optional)
offset FromUri Int32 Offset in query results (Optional)
limit FromUri Int32 Maximum number of results to return. When 0 or not present, all results will be returned. When -1, only count will be returned.

User

v1/user object exposes console users.

All Object Properties for user

Name Type Property Description
id Int32 Unique id of this user
name String Name of this user
userGroupIds String Comma-separated list of IDs of corresponding userGroup objects
eMailAddress String EMail address of this user
firstName String First name of this user
lastName String Last name of this user
title String Title of this user
salutation String Salutation of this user
department String Department this user belongs to
homePhone String User’s home phone
cellPhone String User’s cell phone
backupCellPhone String User’s secondary cell phone
pager String User’s pager number
backupPager String User’s secondary pager number
comments String Comments for this user
adminComments String Administrator’s comments for this user
registrationDate DateTime Date this user was first registered (UTC)
readOnly Boolean True if this user is one of internal system users or AD user. These users cannot be modified through the API
external Boolean True if this is externally generated user (e.g. from AD).
automatic Boolean True if this user’s roles are assigned automatically through mappings (valid only for external users).
unified Boolean True if this user’s token is already connected to a remote unified environment (token should not be changed).
enabled Boolean True if this user is enabled.
passwordHash String Hash of user password
passwordSalt String Salt used to generate password hash
apiToken String API token for this user

Properties modifiable Using PUT/POST Request for user

Name Type Property Description
name String Name of this user
userGroupIds String Comma-separated list of IDs of corresponding userGroup objects
eMailAddress String EMail address of this user
firstName String First name of this user
lastName String Last name of this user
title String Title of this user
salutation String Salutation of this user
department String Department this user belongs to
homePhone String User’s home phone
cellPhone String User’s cell phone
backupCellPhone String User’s secondary cell phone
pager String User’s pager number
backupPager String User’s secondary pager number
comments String Comments for this user
adminComments String Administrator’s comments for this user
automatic Boolean True if this user’s roles are assigned automatically through mappings (valid only for external users).
unified Boolean True if this user’s token is already connected to a remote unified environment (token should not be changed).
enabled Boolean True if this user is enabled.
passwordHash String Hash of user password
passwordSalt String Salt used to generate password hash
apiToken String API token for this user

POST Request for user

Description: Creates or updates user

Required permissions: ‘View login accounts and user roles’, ‘Manage login accounts’

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

Name Source Type Description
value FromBody user New user object
delete FromUri Boolean Set to true to delete existing user object

PUT Request for user

Description: Change user

Required permissions: ‘View login accounts and user roles’, ‘Manage login accounts’

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

Name Source Type Description
id FromUri Int32 id of use object to change
value FromBody user user object with desired parameters.

DELETE Request for user

Description: Delete user

Required permissions: ‘View login accounts and user roles’

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

Name Source Type Description
id FromUri Int32 id of user to delete.

GET Request for user

Description: Returns object instance of this class

Required permissions: ‘View login accounts and user roles’

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

Name Source Type Description
id FromUri Int64 id of a requested object

GET Request for user

Description: Returns objects that match given criteria

Required permissions: ‘View login accounts and user roles’

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

Name Source Type Description
q FromUri List Query condition (Optional - multiple query conditions are supported)
group FromUri String Field name to group by (Optional)
groupType FromUri String Type of windowed grouping (Optional, for time-based fields only)
groupStep FromUri Int32 Step for windowed grouping (Optional, for time-based fields only)
sort FromUri String Field name to sort by (Optional)
offset FromUri Int32 Offset in query results (Optional)
limit FromUri Int32 Maximum number of results to return. When 0 or not present, all results will be returned. When -1, only count will be returned.
expand FromUri String[] Foreign key fields to expand (Optional)

UserGroup

v1/userGroup object exposes user groups and associated permissions.

All Object Properties for userGroup

Name Type Property Description
id Int32 Unique id of this userGroup
name String Name of this userGroup
description String Description of this userGroup
permissions String Permissions associated with users of this userGroup as a hexadecimal string. Can be combination of:
PERMISSION_COMPUTERS_VIEW = 0x0000000000000001
PERMISSION_COMPUTERS_ASSIGN = 0x0000000000000002
PERMISSION_COMPUTERS_TEMPORARY_ASSIGN = 0x0000000000000004
PERMISSION_COMPUTERS_ADVANCED = 0x0000000000000008
PERMISSION_FILES_VIEW = 0x0000000000000010
PERMISSION_FILES_MANAGE_STATE = 0x0000000000000020
PERMISSION_FILES_MANAGE_LOCAL_STATE = 0x0000000000000040
PERMISSION_POLICIES_VIEW = 0x0000000000000080
PERMISSION_POLICIES_MANAGE = 0x0000000000000100
PERMISSION_POLICIES_MAPPINGS = 0x0000000000000200
PERMISSION_RULES_VIEW = 0x0000000000000400
PERMISSION_RULES_MANAGE_DEVICE = 0x0000000000000800
PERMISSION_RULES_MANAGE_EVENT = 0x0000000000001000
PERMISSION_RULES_MANAGE_DIRECTORIES = 0x0000000000002000
PERMISSION_RULES_MANAGE_PUBLISHERS = 0x0000000000004000
PERMISSION_RULES_MANAGE_USERS = 0x0000000000008000
PERMISSION_RULES_MANAGE_CUSTOM = 0x0000000000010000
PERMISSION_REPORTS_VIEW_EVENTS = 0x0000000000020000
PERMISSION_REPORTS_MANAGE_DASHBOARDS = 0x0000000000040000
PERMISSION_REPORTS_VIEW_DRIFT = 0x0000000000080000
PERMISSION_REPORTS_MANAGE_DRIFT = 0x0000000000100000
PERMISSION_REPORTS_MANAGE_SNAPSHOTS = 0x0000000000200000
PERMISSION_REPORTS_SAVED_VIEWS = 0x0000000000400000
PERMISSION_TOOLS_VIEW_ALERTS = 0x0000000000800000
PERMISSION_TOOLS_MANAGE_ALERTS = 0x0000000001000000
PERMISSION_TOOLS_VIEW_METERS = 0x0000000002000000
PERMISSION_TOOLS_MANAGE_METERS = 0x0000000004000000
PERMISSION_ADMINISTRATION_VIEW_CONFIG = 0x0000000008000000
PERMISSION_ADMINISTRATION_VIEW_USERS = 0x0000000010000000
PERMISSION_ADMINISTRATION_MANAGE_CONFIG = 0x0000000020000000
PERMISSION_ADMINISTRATION_MANAGE_USERS = 0x0000000040000000
PERMISSION_ADMINISTRATION_MANAGE_USER_GROUPS = 0x0000000100000000
PERMISSION_DEVICES_VIEW = 0x0000000200000000
PERMISSION_RULES_MANAGE_UPDATERS = 0x0000000400000000
PERMISSION_MANAGE_APPROVAL_REQUESTS = 0x0000000800000000
PERMISSION_VIEW_APPROVAL_REQUESTS = 0x0000001000000000
PERMISSION_VIEW_UPLOADED_FILES = 0x0000002000000000
PERMISSION_ALLOW_UPLOAD_INVENTORY = 0x0000004000000000
PERMISSION_ALLOW_EXECUTE_COMMANDS = 0x0000008000000000
PERMISSION_RULES_MANAGE_SCRIPT = 0x0000010000000000
PERMISSION_NOTIFIERS_VIEW = 0x0000020000000000
PERMISSION_NOTIFIERS_MANAGE = 0x0000040000000000
PERMISSION_ACCESS_UPLOAD_FILES = 0x0000080000000000
PERMISSION_ALLOW_UPLOAD_FILES_BY_PATH = 0x0000100000000000
PERMISSION_ALLOW_ANALYZE_FILES = 0x0000200000000000
PERMISSION_RULES_MANAGE_ATI_SETS = 0x0000400000000000
PERMISSION_VIEW_EXTERNAL_ANALYTICS = 0x0000800000000000
PERMISSION_VIEW_PROCESS_COMMAND_LINES = 0x0001000000000000
PERMISSION_VIEW_SYSTEM_HEALTH = 0x0002000000000000
PERMISSION_EXTEND_CONNECTORS = 0x0004000000000000
PERMISSION_USE_UNIFIED_MANAGEMENT = 0x0800000000000000L
PERMISSION_CONFIGURE_UNIFIED_MANAGEMENT = 0x1000000000000000L
policyIds String List of IDs of policies where this user group applies. Value will be empty if this is a global user group
enabled Boolean True if this userGroup is enabled
editable Boolean True if this userGroup is editable
dateCreated DateTime Date/time when this rule was created (UTC)
createdByUserId Int32 Id of user that created this object. This is foreign key and can be expanded to expose fields from the related user object
createdBy String User that created this object
dateModified DateTime Date/time when this object was last modified (UTC)
modifiedByUserId Int32 Id of user that last modified this object. This is foreign key and can be expanded to expose fields from the related user object
modifiedBy String User that last modified this object
automaticCount Int32 Number of users that belong to this group and have been assigned through AD rule (doesn’t include internal users)
manualCount Int32 Number of users that belong to this group and have been assigned manually (doesn’t include internal users)

Properties modifiable Using PUT/POST Request for userGroup

Name Type Property Description
name String Name of this userGroup
description String Description of this userGroup
permissions String Permissions associated with users of this userGroup as a hexadecimal string. Can be combination of:
PERMISSION_COMPUTERS_VIEW = 0x0000000000000001
PERMISSION_COMPUTERS_ASSIGN = 0x0000000000000002
PERMISSION_COMPUTERS_TEMPORARY_ASSIGN = 0x0000000000000004
PERMISSION_COMPUTERS_ADVANCED = 0x0000000000000008
PERMISSION_FILES_VIEW = 0x0000000000000010
PERMISSION_FILES_MANAGE_STATE = 0x0000000000000020
PERMISSION_FILES_MANAGE_LOCAL_STATE = 0x0000000000000040
PERMISSION_POLICIES_VIEW = 0x0000000000000080
PERMISSION_POLICIES_MANAGE = 0x0000000000000100
PERMISSION_POLICIES_MAPPINGS = 0x0000000000000200
PERMISSION_RULES_VIEW = 0x0000000000000400
PERMISSION_RULES_MANAGE_DEVICE = 0x0000000000000800
PERMISSION_RULES_MANAGE_EVENT = 0x0000000000001000
PERMISSION_RULES_MANAGE_DIRECTORIES = 0x0000000000002000
PERMISSION_RULES_MANAGE_PUBLISHERS = 0x0000000000004000
PERMISSION_RULES_MANAGE_USERS = 0x0000000000008000
PERMISSION_RULES_MANAGE_CUSTOM = 0x0000000000010000
PERMISSION_REPORTS_VIEW_EVENTS = 0x0000000000020000
PERMISSION_REPORTS_MANAGE_DASHBOARDS = 0x0000000000040000
PERMISSION_REPORTS_VIEW_DRIFT = 0x0000000000080000
PERMISSION_REPORTS_MANAGE_DRIFT = 0x0000000000100000
PERMISSION_REPORTS_MANAGE_SNAPSHOTS = 0x0000000000200000
PERMISSION_REPORTS_SAVED_VIEWS = 0x0000000000400000
PERMISSION_TOOLS_VIEW_ALERTS = 0x0000000000800000
PERMISSION_TOOLS_MANAGE_ALERTS = 0x0000000001000000
PERMISSION_TOOLS_VIEW_METERS = 0x0000000002000000
PERMISSION_TOOLS_MANAGE_METERS = 0x0000000004000000
PERMISSION_ADMINISTRATION_VIEW_CONFIG = 0x0000000008000000
PERMISSION_ADMINISTRATION_VIEW_USERS = 0x0000000010000000
PERMISSION_ADMINISTRATION_MANAGE_CONFIG = 0x0000000020000000
PERMISSION_ADMINISTRATION_MANAGE_USERS = 0x0000000040000000
PERMISSION_ADMINISTRATION_MANAGE_USER_GROUPS = 0x0000000100000000
PERMISSION_DEVICES_VIEW = 0x0000000200000000
PERMISSION_RULES_MANAGE_UPDATERS = 0x0000000400000000
PERMISSION_MANAGE_APPROVAL_REQUESTS = 0x0000000800000000
PERMISSION_VIEW_APPROVAL_REQUESTS = 0x0000001000000000
PERMISSION_VIEW_UPLOADED_FILES = 0x0000002000000000
PERMISSION_ALLOW_UPLOAD_INVENTORY = 0x0000004000000000
PERMISSION_ALLOW_EXECUTE_COMMANDS = 0x0000008000000000
PERMISSION_RULES_MANAGE_SCRIPT = 0x0000010000000000
PERMISSION_NOTIFIERS_VIEW = 0x0000020000000000
PERMISSION_NOTIFIERS_MANAGE = 0x0000040000000000
PERMISSION_ACCESS_UPLOAD_FILES = 0x0000080000000000
PERMISSION_ALLOW_UPLOAD_FILES_BY_PATH = 0x0000100000000000
PERMISSION_ALLOW_ANALYZE_FILES = 0x0000200000000000
PERMISSION_RULES_MANAGE_ATI_SETS = 0x0000400000000000
PERMISSION_VIEW_EXTERNAL_ANALYTICS = 0x0000800000000000
PERMISSION_VIEW_PROCESS_COMMAND_LINES = 0x0001000000000000
PERMISSION_VIEW_SYSTEM_HEALTH = 0x0002000000000000
PERMISSION_EXTEND_CONNECTORS = 0x0004000000000000
PERMISSION_USE_UNIFIED_MANAGEMENT = 0x0800000000000000L
PERMISSION_CONFIGURE_UNIFIED_MANAGEMENT = 0x1000000000000000L
policyIds String List of IDs of policies where this user group applies. Value will be empty if this is a global user group
enabled Boolean True if this userGroup is enabled

POST Request for userGroup

Description: Creates or updates userGroup

Required permissions: ‘View login accounts and user roles’, ‘Manage user roles and mappings’

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

Name Source Type Description
value FromBody userGroup New userGroup object
delete FromUri Boolean Set to true to delete existing userGroup object

PUT Request for userGroup

Description: Change userGroup

Required permissions: ‘View login accounts and user roles’, ‘Manage user roles and mappings’

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

Name Source Type Description
id FromUri Int32 id of use object to change
value FromBody userGroup userGroup object with desired parameters.

DELETE Request for userGroup

Description: Delete userGroup

Required permissions: ‘View login accounts and user roles’, ‘Manage user roles and mappings’

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

Name Source Type Description
id FromUri Int32 id of user to delete.

GET Request for userGroup

Description: Returns object instance of this class

Required permissions: ‘View login accounts and user roles’

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

Name Source Type Description
id FromUri Int64 id of a requested object

GET Request for userGroup

Description: Returns objects that match given criteria

Required permissions: ‘View login accounts and user roles’

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

Name Source Type Description
q FromUri List Query condition (Optional - multiple query conditions are supported)
group FromUri String Field name to group by (Optional)
groupType FromUri String Type of windowed grouping (Optional, for time-based fields only)
groupStep FromUri Int32 Step for windowed grouping (Optional, for time-based fields only)
sort FromUri String Field name to sort by (Optional)
offset FromUri Int32 Offset in query results (Optional)
limit FromUri Int32 Maximum number of results to return. When 0 or not present, all results will be returned. When -1, only count will be returned.
expand FromUri String[] Foreign key fields to expand (Optional)

Give Feedback

New survey coming soon!


Last modified on February 15, 2023