Deep Security API

Deep Security includes a REST (REpresentational State Transfer) Web Services API to allow Deep Security functionality to be integrated with other applications. This allows for an easy, programming language-neutral method to externally access data and programming configurations. The REST API uses standard HTTP methods such as GET, POST, PUT, and DELETE and encodes data using JSON.

Using the REST API

Basic API access

All access to the REST API is through the Deep Security Manager URL https://<hostname>:<port>/rest. For example, if the Deep Security Manager is installed on a host named dsm.example.com and is listening on port 4119, the URL would be https://dsm.example.com:4119/rest.

Most API method require you to provide a session identifier. You can get a session identifier through the login API or the assume role with SAML API.

Response codes

The REST API uses standard HTTP status code to return the status of requests. The documentation for each API method lists the codes you should expect to see when making requests to that method.

AWS Marketplace Billing

Applies to Deep Security as a Service only

List AWS Marketplace Billing Records

Applies to Deep Security as a Service only

Retrieve AWS billing records

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Query Parameters

endDate
integer
End of the date range (timestamp in milliseconds). Default is "now" if not specified.
startDate
integer
Start of the date range (timestamp in milliseconds). Default is one day before endDate if not specified.

Response Codes

200
if the request is successful
403
if the user is not authorized to view billing records
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ListSummaryBillingRecordsResponse
The metering records between dates specified, including endDate, category, quantity, isProcessed, meteringRecordID, status and dateBilled.
Properties
summaryBillingRecords
SummaryBillingRecord
the list of summary billing records.
Properties
endDate
number
the end date of the billing record.
category
Category
the variant billed.
Values
aws-large
aws-medium-or-smaller
aws-xlarge-or-bigger
aws-workspace
other-large
other-medium-or-smaller
other-xlarge-or-bigger
not-cloud
instanceCount
number
the quantity of variant billed.
status
string
the status from the API.
dateBilled
number
the date the record was added.
processed
boolean
the indicator that the billing is success or failure.
meteringRecordID
string
the meteringRecordID.

Example Request

GET /aws-billing/meteringRecords?endDate={endDate}&startDate={startDate}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ListSummaryBillingRecordsResponse": {
    "summaryBillingRecords": [ {
      "endDate": 12345,
      "category": "aws-medium-or-smaller",
      "instanceCount": 12345,
      "status": "...",
      "dateBilled": 12345,
      "processed": true,
      "meteringRecordID": "..."
    }, {
      "endDate": 12345,
      "category": "other-medium-or-smaller",
      "instanceCount": 12345,
      "status": "...",
      "dateBilled": 12345,
      "processed": true,
      "meteringRecordID": "..."
    } ]
  }
}
                    
                  

Administrator roles

Interface to the Administrator Role API.

Deep Security uses role-based access control (RBAC) to restrict user permissions to parts of Deep Security. Once you have installed Deep Security Manager, you should create individual accounts for each user and assign each user a role that will restrict their activities to all but those necessary for the completion of their duties. Learn more.

Rules for administrator roles:

  • Administrators are not permitted to escalate their own privileges by adding rights, hosts, host groups, policies, or access types.
  • Administrators are not permitted to create a new role that has more privileges than their current role has.
  • Administrators who downgrade their privileges by removing rights, hosts, host groups, policies, or access types will not be able to re-escalate to the original state.
  • Administrators with the delegate flag set to true are only allowed to see roles that have equal or lesser privileges to their current role.

List administrator roles

List administrator roles.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Query Parameters

administratorRoleID
integer
(optional) used to define the starting point for the query. Combine with administratorRoleIDOp to page through results.
administratorRoleIDOp
string
(optional, required if administratorRoleID is specified) Currently supported operations are:
  • gt (greater than)
  • ge (greater than or equal to)
  • eq (equal to)
  • lt (less than)
  • le (less than or equal to)
maxItems
integer
(optional) the number of items to retrieve. The maximum value for this parameter is controlled by the "Maximum number of items to retrieve from database" setting on the administrator account, which defaults to 5000.

Response Codes

200
if the request is successful
403
if the user is not authorized to view administrator roles
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ListAdministratorRolesResponse
a ListAdministratorRolesResponse with the administrator roles.
Properties
roles
AdministratorRole
the list of role details.
Properties
roleID
number
the administrator role ID.
URN
string
the administrator role URN.
allHosts
boolean
the value of the "all hosts" flag.

When the "all hosts" flag is true, rights assigned to the role will apply to all hosts.

allPolicies
boolean
the value of the "all policies" flag.

When the "all policies" flag is true, rights assigned to the role will apply to all policies.

allowGUI
boolean
the value of the "allow GUI access" flag.

When the "allow GUI access" flag is true, administrators with this role will be allowed to access the Deep Security Manager console.

allowWebService
boolean
the value of the "allow Web Service access" flag.

When the "allow Web Service access" flag is true, administrators with this role will be allowed to access the Deep Security Manager Web Services (SOAP) API.

delegate
boolean
the value of the "delegate" flag.

When the "delegate" flag is true, administrators with this role will have limited access to view and / or modify other administrator roles. The only roles that they will be able to view / modify are roles with equal or lesser access than their own.

name
string
the role's name.
description
string
the role's description.
readOnly
boolean
the value of the "read-only" flag.

The Deep Security Manager comes with a default "Full Access" role that is read-only and cannot be deleted or changed. It is not possible to create other read-only roles.

rights
string
the list of rights assigned to the role.
hosts
number
the list of hosts (IDs) associated with the role.

You can limit the scope of permissions for rights that apply to hosts using this attribute in combination with the hostGroups attribute and the allHosts flag. If the allHosts flag is set to true, rights that are assigned to the role will apply to all hosts. When the allHosts flag is set to false, rights that are assigned to the role will apply only to hosts and host groups set using the hosts and hostGroups attributes.

hostGroups
number
the list of host groups (IDs) associated with the role.

You can limit the scope of permissions for rights that apply to hosts using this attribute in combination with the hosts attribute and the allHosts flag. If the allHosts flag is set to true, rights that are assigned to the role will apply to all hosts. When the allHosts flag is set to false, rights that are assigned to the role will apply only to hosts and host groups set using the hosts and hostGroups attributes.

policies
number
the list of policies (IDs) associated with the role.

You can limit the scope of permissions for rights that apply to policies using this attribute in combination with the allPolicies flag. If the allPolicies flag is set to true, rights that are assigned to the role will apply to all policies. When the allPolicies flag is set to false, rights that are assigned to the role will apply only to policies set using the policies attribute.

Example Request

GET /administrator-roles?administratorRoleID={administratorRoleID}&administratorRoleIDOp={administratorRoleIDOp}&maxItems={maxItems}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ListAdministratorRolesResponse": {
    "roles": [ {
      "roleID": 12345,
      "URN": "...",
      "allHosts": true,
      "allPolicies": true,
      "allowGUI": true,
      "allowWebService": true,
      "delegate": true,
      "name": "...",
      "description": "...",
      "readOnly": true,
      "rights": [ "...", "..." ],
      "hosts": [ 12345, 12345 ],
      "hostGroups": [ 12345, 12345 ],
      "policies": [ 12345, 12345 ]
    }, {
      "roleID": 12345,
      "URN": "...",
      "allHosts": true,
      "allPolicies": true,
      "allowGUI": true,
      "allowWebService": true,
      "delegate": true,
      "name": "...",
      "description": "...",
      "readOnly": true,
      "rights": [ "...", "..." ],
      "hosts": [ 12345, 12345 ],
      "hostGroups": [ 12345, 12345 ],
      "policies": [ 12345, 12345 ]
    } ]
  }
}
                    
                  

Create an administrator role

Create a new administrator role.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Request Body

CreateAdministratorRoleRequest
a CreateAdministratorRoleRequest with the details of the administrator role.
Properties
the role details.

Response Codes

200
if the request is successful
403
if the user is not authorized to create administrator roles
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

CreateAdministratorRoleResponse
a CreateAdministratorRoleResponse with the details of the administrator role.
Properties
the role details.

Example Request

POST /administrator-roles
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "CreateAdministratorRoleRequest": {
    "role": {
      "roleID": 12345,
      "URN": "...",
      "allHosts": true,
      "allPolicies": true,
      "allowGUI": true,
      "allowWebService": true,
      "delegate": true,
      "name": "...",
      "description": "...",
      "readOnly": true,
      "rights": [ "...", "..." ],
      "hosts": [ 12345, 12345 ],
      "hostGroups": [ 12345, 12345 ],
      "policies": [ 12345, 12345 ]
    }
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "CreateAdministratorRoleResponse": {
    "role": {
      "roleID": 12345,
      "URN": "...",
      "allHosts": true,
      "allPolicies": true,
      "allowGUI": true,
      "allowWebService": true,
      "delegate": true,
      "name": "...",
      "description": "...",
      "readOnly": true,
      "rights": [ "...", "..." ],
      "hosts": [ 12345, 12345 ],
      "hostGroups": [ 12345, 12345 ],
      "policies": [ 12345, 12345 ]
    }
  }
}
                    
                  

Delete an administrator role

Delete an administrator role.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

roleID
integer
the role ID.

Response Codes

200
if the request is successful
403
if the user is not authorized to delete administrator roles
404
if the user is authorized to delete administrator roles but the administrator role does not exist or if the user is not authorized to delete the requested administrator role
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Example Request

DELETE /administrator-roles/{roleID}
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
                  

Describe an administrator role

Describe an administrator role.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

roleID
integer
the role ID.

Response Codes

200
if the request is successful
403
if the user is not authorized to view administrator roles
404
if the user is authorized to view administrator roles but the administrator role does not exist or if the user is not authorized to view the requested administrator role
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

DescribeAdministratorRoleResponse
a DescribeAdministratorRoleResponse with the details of the administrator role.
Properties
the role details.

Example Request

GET /administrator-roles/{roleID}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "DescribeAdministratorRoleResponse": {
    "role": {
      "roleID": 12345,
      "URN": "...",
      "allHosts": true,
      "allPolicies": true,
      "allowGUI": true,
      "allowWebService": true,
      "delegate": true,
      "name": "...",
      "description": "...",
      "readOnly": true,
      "rights": [ "...", "..." ],
      "hosts": [ 12345, 12345 ],
      "hostGroups": [ 12345, 12345 ],
      "policies": [ 12345, 12345 ]
    }
  }
}
                    
                  

Modify an administrator role

Modify an administrator role.

Any unset elements in the request object will be left unchanged by the modify request.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

roleID
integer
the role ID.

Request Body

ModifyAdministratorRoleRequest
a ModifyAdministratorRoleRequest with the details of the administrator role.
Properties
the role details.

Response Codes

200
if the request is successful
403
if the user is not authorized to modify administrator roles
404
if the user is authorized to modify administrator roles but the administrator role does not exist or if the user is not authorized to modify the requested administrator role
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ModifyAdministratorRoleResponse
a ModifyAdministratorRoleResponse with the modified details of the administrator role.
Properties
the role details.

Example Request

POST /administrator-roles/{roleID}
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "ModifyAdministratorRoleRequest": {
    "role": {
      "roleID": 12345,
      "URN": "...",
      "allHosts": true,
      "allPolicies": true,
      "allowGUI": true,
      "allowWebService": true,
      "delegate": true,
      "name": "...",
      "description": "...",
      "readOnly": true,
      "rights": [ "...", "..." ],
      "hosts": [ 12345, 12345 ],
      "hostGroups": [ 12345, 12345 ],
      "policies": [ 12345, 12345 ]
    }
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ModifyAdministratorRoleResponse": {
    "role": {
      "roleID": 12345,
      "URN": "...",
      "allHosts": true,
      "allPolicies": true,
      "allowGUI": true,
      "allowWebService": true,
      "delegate": true,
      "name": "...",
      "description": "...",
      "readOnly": true,
      "rights": [ "...", "..." ],
      "hosts": [ 12345, 12345 ],
      "hostGroups": [ 12345, 12345 ],
      "policies": [ 12345, 12345 ]
    }
  }
}
                    
                  

Add administrator role host group access

Update an administrator role with an additional set of host groups.

Administrator roles can have access to all host groups or can be restricted to a set of listed host groups (and any child host groups of the listed host groups). Administrators will have access to any host in the set of allowed host groups (and any child host group of the listed host groups).

Any pre-existing host groups for the role will be retained and augmented by the host groups specified by the request.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

roleID
integer
the role ID.

Request Body

AddAdministratorRoleHostGroupsRequest
an AddAdministratorRoleHostGroupsRequest with the new host groups to add to the administrator role.
Properties
hostGroups
number
the list of host group IDs to add to the administrator role.

Response Codes

200
if the request is successful
403
if the user is not authorized to modify administrator roles
404
if the user is authorized to modify administrator roles but the administrator role does not exist or if the user is not authorized to modify the requested administrator role
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

a ModifyAdministratorRoleResponse with the modified details of the administrator role.

Example Request

POST /administrator-roles/{roleID}/host-groups
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "AddAdministratorRoleHostGroupsRequest": {
    "hostGroups": [ 12345, 12345 ]
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ModifyAdministratorRoleResponse": {
    "role": {
      "roleID": 12345,
      "URN": "...",
      "allHosts": true,
      "allPolicies": true,
      "allowGUI": true,
      "allowWebService": true,
      "delegate": true,
      "name": "...",
      "description": "...",
      "readOnly": true,
      "rights": [ "...", "..." ],
      "hosts": [ 12345, 12345 ],
      "hostGroups": [ 12345, 12345 ],
      "policies": [ 12345, 12345 ]
    }
  }
}
                    
                  

Modify administrator role host group access

Update an administrator role with a new (complete) set of host groups.

Administrator roles can have access to all host groups or can be restricted to a set of listed host groups (and any child host groups of the listed host groups). Administrators will have access to any host in the set of allowed host groups (and any child host group of the listed host groups).

Any pre-existing host groups for the role will be replaced by the host groups specified in the request.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

roleID
integer
the role ID.

Request Body

ModifyAdministratorRoleHostGroupsRequest
an ModifyAdministratorRoleHostGroupsRequest with the new host groups for the administrator role.
Properties
hostGroups
number
the list of host group IDs to add to the administrator role.

Response Codes

200
if the request is successful
403
if the user is not authorized to modify administrator roles
404
if the user is authorized to modify administrator roles but the administrator role does not exist or if the user is not authorized to modify the requested administrator role
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

a ModifyAdministratorRoleResponse with the modified details of the administrator role.

Example Request

PUT /administrator-roles/{roleID}/host-groups
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "ModifyAdministratorRoleHostGroupsRequest": {
    "hostGroups": [ 12345, 12345 ]
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ModifyAdministratorRoleResponse": {
    "role": {
      "roleID": 12345,
      "URN": "...",
      "allHosts": true,
      "allPolicies": true,
      "allowGUI": true,
      "allowWebService": true,
      "delegate": true,
      "name": "...",
      "description": "...",
      "readOnly": true,
      "rights": [ "...", "..." ],
      "hosts": [ 12345, 12345 ],
      "hostGroups": [ 12345, 12345 ],
      "policies": [ 12345, 12345 ]
    }
  }
}
                    
                  

Add administrator role host access

Update an administrator role with an additional set of hosts.

Administrator roles can have access to all hosts or can be restricted to a set of listed hosts. Access to a host may also be granted if the host is in a host group that the administrator has access to.

Any pre-existing hosts for the role will be retained and augmented by the hosts specified by the request.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

roleID
integer
the role ID.

Request Body

AddAdministratorRoleHostsRequest
an AddAdministratorRoleHostsRequest with the new hosts to add to the administrator role.
Properties
hosts
number
the list of host IDs to add to the administrator role.

Response Codes

200
if the request is successful
403
if the user is not authorized to modify administrator roles
404
if the user is authorized to modify administrator roles but the administrator role does not exist or if the user is not authorized to modify the requested administrator role
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

a ModifyAdministratorRoleResponse with the modified details of the administrator role.

Example Request

POST /administrator-roles/{roleID}/hosts
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "AddAdministratorRoleHostsRequest": {
    "hosts": [ 12345, 12345 ]
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ModifyAdministratorRoleResponse": {
    "role": {
      "roleID": 12345,
      "URN": "...",
      "allHosts": true,
      "allPolicies": true,
      "allowGUI": true,
      "allowWebService": true,
      "delegate": true,
      "name": "...",
      "description": "...",
      "readOnly": true,
      "rights": [ "...", "..." ],
      "hosts": [ 12345, 12345 ],
      "hostGroups": [ 12345, 12345 ],
      "policies": [ 12345, 12345 ]
    }
  }
}
                    
                  

Modify administrator role host access

Update an administrator role with a new (complete) set of hosts.

Administrator roles can have access to all hosts or can be restricted to a set of listed hosts. Access to a host may also be granted if the host is in a host group that the administrator has access to.

Any pre-existing hosts for the role will be replaced by the hosts specified in the request.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

roleID
integer
the role ID.

Request Body

ModifyAdministratorRoleHostsRequest
an ModifyAdministratorRoleHostsRequest with the new hosts for the administrator role.
Properties
hosts
number
the list of host IDs to add to the administrator role.

Response Codes

200
if the request is successful
403
if the user is not authorized to modify administrator roles
404
if the user is authorized to modify administrator roles but the administrator role does not exist or if the user is not authorized to modify the requested administrator role
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

a ModifyAdministratorRoleResponse with the modified details of the administrator role.

Example Request

PUT /administrator-roles/{roleID}/hosts
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "ModifyAdministratorRoleHostsRequest": {
    "hosts": [ 12345, 12345 ]
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ModifyAdministratorRoleResponse": {
    "role": {
      "roleID": 12345,
      "URN": "...",
      "allHosts": true,
      "allPolicies": true,
      "allowGUI": true,
      "allowWebService": true,
      "delegate": true,
      "name": "...",
      "description": "...",
      "readOnly": true,
      "rights": [ "...", "..." ],
      "hosts": [ 12345, 12345 ],
      "hostGroups": [ 12345, 12345 ],
      "policies": [ 12345, 12345 ]
    }
  }
}
                    
                  

Add administrator role policy access

Update an administrator role with an additional set of policies.

Administrator roles can have access to all policies or can be restricted to a set of listed policies.

Any pre-existing policies for the role will be retained and augmented by the policies specified by the request.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

roleID
integer
the role ID.

Request Body

AddAdministratorRolePoliciesRequest
an AddAdministratorRolePoliciesRequest with the new policies to add to the administrator role.
Properties
policies
number
the list of policy IDs to add to the administrator role.

Response Codes

200
if the request is successful
403
if the user is not authorized to modify administrator roles
404
if the user is authorized to modify administrator roles but the administrator role does not exist or if the user is not authorized to modify the requested administrator role
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

a ModifyAdministratorRoleResponse with the modified details of the administrator role.

Example Request

POST /administrator-roles/{roleID}/policies
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "AddAdministratorRolePoliciesRequest": {
    "policies": [ 12345, 12345 ]
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ModifyAdministratorRoleResponse": {
    "role": {
      "roleID": 12345,
      "URN": "...",
      "allHosts": true,
      "allPolicies": true,
      "allowGUI": true,
      "allowWebService": true,
      "delegate": true,
      "name": "...",
      "description": "...",
      "readOnly": true,
      "rights": [ "...", "..." ],
      "hosts": [ 12345, 12345 ],
      "hostGroups": [ 12345, 12345 ],
      "policies": [ 12345, 12345 ]
    }
  }
}
                    
                  

Modify administrator role policy access

Update an administrator role with a new (complete) set of policies.

Administrator roles can have access to all policies or can be restricted to a set of listed policies.

Any pre-existing policies for the role will be replaced by the policies specified in the request.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

roleID
integer
the role ID.

Request Body

ModifyAdministratorRolePoliciesRequest
an ModifyAdministratorRolePoliciesRequest with the new policies for the administrator role.
Properties
policies
number
the list of policy IDs to add to the administrator role.

Response Codes

200
if the request is successful
403
if the user is not authorized to modify administrator roles
404
if the user is authorized to modify administrator roles but the administrator role does not exist or if the user is not authorized to modify the requested administrator role
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

a ModifyAdministratorRoleResponse with the modified details of the administrator role.

Example Request

PUT /administrator-roles/{roleID}/policies
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "ModifyAdministratorRolePoliciesRequest": {
    "policies": [ 12345, 12345 ]
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ModifyAdministratorRoleResponse": {
    "role": {
      "roleID": 12345,
      "URN": "...",
      "allHosts": true,
      "allPolicies": true,
      "allowGUI": true,
      "allowWebService": true,
      "delegate": true,
      "name": "...",
      "description": "...",
      "readOnly": true,
      "rights": [ "...", "..." ],
      "hosts": [ 12345, 12345 ],
      "hostGroups": [ 12345, 12345 ],
      "policies": [ 12345, 12345 ]
    }
  }
}
                    
                  

Add administrator role rights

Update an administrator role with an additional set of rights.

Any pre-existing rights for the role will be retained and augmented by the rights specified by the request.

You can use the #listRoles(String) and #describeRole(String, Integer) APIs to find the "Full Access" role and retrieve a full list of supported right IDs.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

roleID
integer
the role ID.

Request Body

AddAdministratorRoleRightsRequest
an AddAdministratorRoleRightsRequest with the new rights to add to the administrator role.
Properties
rights
string
the list of right IDs to add to the administrator role.

Response Codes

200
if the request is successful
403
if the user is not authorized to modify administrator roles
404
if the user is authorized to modify administrator roles but the administrator role does not exist or if the user is not authorized to modify the requested administrator role
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

a ModifyAdministratorRoleResponse with the modified details of the administrator role.

Example Request

POST /administrator-roles/{roleID}/rights
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "AddAdministratorRoleRightsRequest": {
    "rights": [ "...", "..." ]
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ModifyAdministratorRoleResponse": {
    "role": {
      "roleID": 12345,
      "URN": "...",
      "allHosts": true,
      "allPolicies": true,
      "allowGUI": true,
      "allowWebService": true,
      "delegate": true,
      "name": "...",
      "description": "...",
      "readOnly": true,
      "rights": [ "...", "..." ],
      "hosts": [ 12345, 12345 ],
      "hostGroups": [ 12345, 12345 ],
      "policies": [ 12345, 12345 ]
    }
  }
}
                    
                  

Modify administrator role rights

Update an administrator role with a new (complete) set of rights.

Any pre-existing rights for the role will be replaced by the rights specified in the request.

You can use the #listRoles(String) and #describeRole(String, Integer) APIs to find the "Full Access" role and retrieve a full list of supported right IDs.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

roleID
integer
the role ID.

Request Body

ModifyAdministratorRoleRightsRequest
an ModifyAdministratorRoleRightsRequest with the new rights for the administrator role.
Properties
rights
string
the list of right IDs to add to the administrator role.

Response Codes

200
if the request is successful
403
if the user is not authorized to modify administrator roles
404
if the user is authorized to modify administrator roles but the administrator role does not exist or if the user is not authorized to modify the requested administrator role
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

a ModifyAdministratorRoleResponse with the modified details of the administrator role.

Example Request

PUT /administrator-roles/{roleID}/rights
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "ModifyAdministratorRoleRightsRequest": {
    "rights": [ "...", "..." ]
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ModifyAdministratorRoleResponse": {
    "role": {
      "roleID": 12345,
      "URN": "...",
      "allHosts": true,
      "allPolicies": true,
      "allowGUI": true,
      "allowWebService": true,
      "delegate": true,
      "name": "...",
      "description": "...",
      "readOnly": true,
      "rights": [ "...", "..." ],
      "hosts": [ 12345, 12345 ],
      "hostGroups": [ 12345, 12345 ],
      "policies": [ 12345, 12345 ]
    }
  }
}
                    
                  

Delete administrator role host group access

Remove a host group from an administrator role.

Administrator roles can have access to all host groups or can be restricted to a set of listed host groups (and any child host groups of the listed host groups). Administrators will have access to any host in the set of allowed host groups (and any child host group of the listed host groups).

You can use the #describeRole(String, Integer) API to retrieve the existing set of host groups assigned to the role.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

hostGroupID
integer
the host group ID.
roleID
integer
the role ID.

Response Codes

200
if the request is successful
403
if the user is not authorized to modify administrator roles
404
if the user is authorized to modify administrator roles but the administrator role does not exist or if the user is not authorized to modify the requested administrator role
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

a ModifyAdministratorRoleResponse with the modified details of the administrator role.

Example Request

DELETE /administrator-roles/{roleID}/host-groups/{hostGroupID}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ModifyAdministratorRoleResponse": {
    "role": {
      "roleID": 12345,
      "URN": "...",
      "allHosts": true,
      "allPolicies": true,
      "allowGUI": true,
      "allowWebService": true,
      "delegate": true,
      "name": "...",
      "description": "...",
      "readOnly": true,
      "rights": [ "...", "..." ],
      "hosts": [ 12345, 12345 ],
      "hostGroups": [ 12345, 12345 ],
      "policies": [ 12345, 12345 ]
    }
  }
}
                    
                  

Delete administrator role host access

Remove a host from an administrator role.

Administrator roles can have access to all hosts or can be restricted to a set of listed hosts. Access to a host may also be granted if the host is in a host group that the administrator has access to.

You can use the #describeRole(String, Integer) API to retrieve the existing set of hosts assigned to the role.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

hostID
integer
the host ID.
roleID
integer
the role ID.

Response Codes

200
if the request is successful
403
if the user is not authorized to modify administrator roles
404
if the user is authorized to modify administrator roles but the administrator role does not exist or if the user is not authorized to modify the requested administrator role
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

a ModifyAdministratorRoleResponse with the modified details of the administrator role.

Example Request

DELETE /administrator-roles/{roleID}/hosts/{hostID}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ModifyAdministratorRoleResponse": {
    "role": {
      "roleID": 12345,
      "URN": "...",
      "allHosts": true,
      "allPolicies": true,
      "allowGUI": true,
      "allowWebService": true,
      "delegate": true,
      "name": "...",
      "description": "...",
      "readOnly": true,
      "rights": [ "...", "..." ],
      "hosts": [ 12345, 12345 ],
      "hostGroups": [ 12345, 12345 ],
      "policies": [ 12345, 12345 ]
    }
  }
}
                    
                  

Delete administrator role policy access

Remove a policy from an administrator role.

Administrator roles can have access to all policies or can be restricted to a set of listed policies.

You can use the #describeRole(String, Integer) API to retrieve the existing set of policies assigned to the role.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

policyID
integer
the policy ID.
roleID
integer
the role ID.

Response Codes

200
if the request is successful
403
if the user is not authorized to modify administrator roles
404
if the user is authorized to modify administrator roles but the administrator role does not exist or if the user is not authorized to modify the requested administrator role
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

a ModifyAdministratorRoleResponse with the modified details of the administrator role.

Example Request

DELETE /administrator-roles/{roleID}/policies/{policyID}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ModifyAdministratorRoleResponse": {
    "role": {
      "roleID": 12345,
      "URN": "...",
      "allHosts": true,
      "allPolicies": true,
      "allowGUI": true,
      "allowWebService": true,
      "delegate": true,
      "name": "...",
      "description": "...",
      "readOnly": true,
      "rights": [ "...", "..." ],
      "hosts": [ 12345, 12345 ],
      "hostGroups": [ 12345, 12345 ],
      "policies": [ 12345, 12345 ]
    }
  }
}
                    
                  

Delete an administrator role right

Remove a right from an administrator role.

You can use the #describeRole(String, Integer) API to retrieve the existing set of rights assigned to the role.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

rightID
string
the right ID.
roleID
integer
the role ID.

Response Codes

200
if the request is successful
403
if the user is not authorized to modify administrator roles
404
if the user is authorized to modify administrator roles but the administrator role does not exist or if the user is not authorized to modify the requested administrator role
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

a ModifyAdministratorRoleResponse with the modified details of the administrator role.

Example Request

DELETE /administrator-roles/{roleID}/rights/{rightID}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ModifyAdministratorRoleResponse": {
    "role": {
      "roleID": 12345,
      "URN": "...",
      "allHosts": true,
      "allPolicies": true,
      "allowGUI": true,
      "allowWebService": true,
      "delegate": true,
      "name": "...",
      "description": "...",
      "readOnly": true,
      "rights": [ "...", "..." ],
      "hosts": [ 12345, 12345 ],
      "hostGroups": [ 12345, 12345 ],
      "policies": [ 12345, 12345 ]
    }
  }
}
                    
                  

Administrators

Interface to the Administrator API.

Deep Security administrators can sign in to the Deep Security Manager or use the Deep Security Manager APIs with a unique username and password. Learn more

List administrators

List administrators.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Query Parameters

administratorID
integer
(optional) used to define the starting point for the query. Combine with administratorIDOp to page through results.
administratorIDOp
string
(optional, required if administratorID is specified) Currently supported operations are:
  • gt (greater than)
  • ge (greater than or equal to)
  • eq (equal to)
  • lt (less than)
  • le (less than or equal to)
maxItems
integer
(optional) the number of items to retrieve. The maximum value for this parameter is controlled by the "Maximum number of items to retrieve from database" setting on the administrator account, which defaults to 5000.

Response Codes

200
if the request is successful
403
if the user is not authorized to view administrators
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ListAdministratorsResponse
a ListAdministratorsResponse with the administrator details.
Properties
administrators
Administrator
the list of administrator details.
Properties
ID
number
the administrator ID.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

username
string
the administrator username.
password
string
the administrator password.

To prevent accidental disclosure of the administrator password, the Deep Security Manager will not return this value; it can only be used to set the administrator password.

fullName
string
the administrator full name.
description
string
the administrator description.
roleID
number
the administrator role ID.
locale
string
the administrator locale.

The locale is specified in IETF BCP 47 format, for example en-US. Deep Security supports three locales for administrators:

  • en-US - US English
  • ja-JP - Japanese
  • zh-CN - Simplified Chinese
timeZone
string
the administrator time zone.

Deep Security will attempt to parse the time zone identifier you provide and translate it into an internal identifier. When you retrieve the time zone from Deep Security, you will get one of the IANA Time Zone Database identifiers.

If you don't provide a time zone, the system will set the administrator time zone to the system local timezone. If you provide a time zone that Deep Security can't parse, the administrator time zone will be set to GMT.

timeFormat
TimeFormat
the administrator time format.

The administrator time format determines whether times are shown in 12-hour or 24-hour format in the Deep Security Manager console.

Values
12
Use 12-hour time format when displaying times in the Deep Security Manager console.
24
Use 24-hour time format when displaying times in the Deep Security Manager console.
passwordNeverExpires
boolean
the state of the "password never expires" flag.

If the "password never expires" flag is set to true, then the Deep Security Manager password expiry settings will not apply to this administrator.

active
boolean
the state of the "active" flag.

If the "active" flag is false, the user will be locked out and will not be permitted to log in. When the "active" flag is changed from true to false, any existing sessions for the administrator are terminated.

mfaType
MFAType
the type of multi-factor authentication enabled for the administrator.
Values
none
Multi-factor authentication is not enabled for this administrator.
local-totp
RFC 6238 Local time-based one-time password (TOTP) is enabled as an authentication factor for this administrator.
phoneNumber
string
the administrator phone number.
mobileNumber
string
the administrator mobile number.
pagerNumber
string
the administrator pager number.
emailAddress
string
the administrator email address.
primaryContact
boolean
the value of the "primary contact" flag for the administrator.
receiveNotifications
boolean
the value of the "receive notifications" flag for the administrator.
reportPDFPasswordEnabled
boolean
the value of the "report PDF password enabled" flag for the administrator.

If you enable the report PDF password, any reports sent to the administrator will be protected using the report PDF password.

reportPDFPassword
string
the report PDF password for the administrator.

This value is required if the reportPDFPasswordEnabled flag is true and is automatically reset to blank if the reportPDFPasswordEnabled flag is set to false.

To prevent accidental disclosure of the administrator report PDF password, the Deep Security Manager will not return this value; it can only be used to set the administrator report PDF password.

created
number
the time when the administrator was created, as the number of milliseconds since January 1, 1970, 00:00:00 GMT.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

lastPasswordChange
number
the time when the administrator password was changed, as the number of milliseconds since January 1, 1970, 00:00:00 GMT.

If the administrator password has never been changed, this value will be null.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

lastSignIn
number
the time when the administrator last signed in, as the number of milliseconds since January 1, 1970, 00:00:00 GMT.

If the administrator has never signed in, this value will be null.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

unlockTime
number
the time when the locked administrator account will automatically unlock, as the number of milliseconds since January 1, 1970, 00:00:00 GMT.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

unsuccessfulSignInAttempts
number
the number of unsuccessful sign-in attempts since the administrator last successfully signed in.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

directoryName
string
the directory name for the administrator.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

directoryInfo
string
the directory information for the administrator.

This is the Base64-encoded value of the administrator's unique identifier in the directory.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

external
boolean
the "external" flag value for the administrator.

This flag is set to true when the administrator has been synchronized from an external source.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

externalUserID
string
the external user identifier for the administrator.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

temporary
boolean
the "temporary user" flag value for the administrator.

The "temporary user" flag is set to true for administrators in tenant accounts which are created by the primary tenant for support purposes.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

readOnly
boolean
the "read-only user" flag value for the administrator.

The read-only user account is created by the system and cannot be removed.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

Example Request

GET /administrators?administratorID={administratorID}&administratorIDOp={administratorIDOp}&maxItems={maxItems}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ListAdministratorsResponse": {
    "administrators": [ {
      "ID": 12345,
      "username": "...",
      "password": "...",
      "fullName": "...",
      "description": "...",
      "roleID": 12345,
      "locale": "...",
      "timeZone": "...",
      "timeFormat": "12",
      "passwordNeverExpires": true,
      "active": true,
      "mfaType": "local-totp",
      "phoneNumber": "...",
      "mobileNumber": "...",
      "pagerNumber": "...",
      "emailAddress": "...",
      "primaryContact": true,
      "receiveNotifications": true,
      "reportPDFPasswordEnabled": true,
      "reportPDFPassword": "...",
      "created": 12345,
      "lastPasswordChange": 12345,
      "lastSignIn": 12345,
      "unlockTime": 12345,
      "unsuccessfulSignInAttempts": 12345,
      "directoryName": "...",
      "directoryInfo": "...",
      "external": true,
      "externalUserID": "...",
      "temporary": true,
      "readOnly": true
    }, {
      "ID": 12345,
      "username": "...",
      "password": "...",
      "fullName": "...",
      "description": "...",
      "roleID": 12345,
      "locale": "...",
      "timeZone": "...",
      "timeFormat": "24",
      "passwordNeverExpires": true,
      "active": true,
      "mfaType": "none",
      "phoneNumber": "...",
      "mobileNumber": "...",
      "pagerNumber": "...",
      "emailAddress": "...",
      "primaryContact": true,
      "receiveNotifications": true,
      "reportPDFPasswordEnabled": true,
      "reportPDFPassword": "...",
      "created": 12345,
      "lastPasswordChange": 12345,
      "lastSignIn": 12345,
      "unlockTime": 12345,
      "unsuccessfulSignInAttempts": 12345,
      "directoryName": "...",
      "directoryInfo": "...",
      "external": true,
      "externalUserID": "...",
      "temporary": true,
      "readOnly": true
    } ]
  }
}
                    
                  

Create an administrator

Create a new administrator.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Request Body

CreateAdministratorRequest
a CreateAdministratorRequest with the administrator details.
Properties
administrator
the administrator details.

Response Codes

200
if the request is successful
403
if the user is not authorized to create administrators
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

CreateAdministratorResponse
a CreateAdministratorResponse with the administrator details.
Properties
administrator
the administrator details.

Example Request

POST /administrators
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "CreateAdministratorRequest": {
    "administrator": {
      "ID": 12345,
      "username": "...",
      "password": "...",
      "fullName": "...",
      "description": "...",
      "roleID": 12345,
      "locale": "...",
      "timeZone": "...",
      "timeFormat": "24",
      "passwordNeverExpires": true,
      "active": true,
      "mfaType": "none",
      "phoneNumber": "...",
      "mobileNumber": "...",
      "pagerNumber": "...",
      "emailAddress": "...",
      "primaryContact": true,
      "receiveNotifications": true,
      "reportPDFPasswordEnabled": true,
      "reportPDFPassword": "...",
      "created": 12345,
      "lastPasswordChange": 12345,
      "lastSignIn": 12345,
      "unlockTime": 12345,
      "unsuccessfulSignInAttempts": 12345,
      "directoryName": "...",
      "directoryInfo": "...",
      "external": true,
      "externalUserID": "...",
      "temporary": true,
      "readOnly": true
    }
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "CreateAdministratorResponse": {
    "administrator": {
      "ID": 12345,
      "username": "...",
      "password": "...",
      "fullName": "...",
      "description": "...",
      "roleID": 12345,
      "locale": "...",
      "timeZone": "...",
      "timeFormat": "24",
      "passwordNeverExpires": true,
      "active": true,
      "mfaType": "local-totp",
      "phoneNumber": "...",
      "mobileNumber": "...",
      "pagerNumber": "...",
      "emailAddress": "...",
      "primaryContact": true,
      "receiveNotifications": true,
      "reportPDFPasswordEnabled": true,
      "reportPDFPassword": "...",
      "created": 12345,
      "lastPasswordChange": 12345,
      "lastSignIn": 12345,
      "unlockTime": 12345,
      "unsuccessfulSignInAttempts": 12345,
      "directoryName": "...",
      "directoryInfo": "...",
      "external": true,
      "externalUserID": "...",
      "temporary": true,
      "readOnly": true
    }
  }
}
                    
                  

Delete an administrator

Delete an administrator.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

administratorID
integer
the administrator ID.

Response Codes

200
if the request is successful
403
if the user is not authorized to delete administrators
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Example Request

DELETE /administrators/{administratorID}
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
                  

Describe an administrator

Describe an administrator.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

administratorID
integer
the administrator ID.

Response Codes

200
if the request is successful
403
if the user is not authorized to view administrators
404
if the user is authorized to view administrators but the administrator does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

DescribeAdministratorResponse
a DescribeAdministratorResponse with the administrator details.
Properties
administrator
the administrator details.

Example Request

GET /administrators/{administratorID}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "DescribeAdministratorResponse": {
    "administrator": {
      "ID": 12345,
      "username": "...",
      "password": "...",
      "fullName": "...",
      "description": "...",
      "roleID": 12345,
      "locale": "...",
      "timeZone": "...",
      "timeFormat": "24",
      "passwordNeverExpires": true,
      "active": true,
      "mfaType": "none",
      "phoneNumber": "...",
      "mobileNumber": "...",
      "pagerNumber": "...",
      "emailAddress": "...",
      "primaryContact": true,
      "receiveNotifications": true,
      "reportPDFPasswordEnabled": true,
      "reportPDFPassword": "...",
      "created": 12345,
      "lastPasswordChange": 12345,
      "lastSignIn": 12345,
      "unlockTime": 12345,
      "unsuccessfulSignInAttempts": 12345,
      "directoryName": "...",
      "directoryInfo": "...",
      "external": true,
      "externalUserID": "...",
      "temporary": true,
      "readOnly": true
    }
  }
}
                    
                  

Modify an administrator

Modify an administrator.

Any unset elements in the request object will be left unchanged by the modify request.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

administratorID
integer
the administrator ID.

Request Body

ModifyAdministratorRequest
a ModifyAdministratorRequest with the details of the administrator .
Properties
administrator
the administrator details.

Response Codes

200
if the request is successful
403
if the user is not authorized to modify administrators or if the requested modification is not permitted
404
if the user is authorized to modify administrators but the administrator does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ModifyAdministratorResponse
an ModifyAdministratorResponse with the updated administrator details.
Properties
administrator
the administrator details.

Example Request

POST /administrators/{administratorID}
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "ModifyAdministratorRequest": {
    "administrator": {
      "ID": 12345,
      "username": "...",
      "password": "...",
      "fullName": "...",
      "description": "...",
      "roleID": 12345,
      "locale": "...",
      "timeZone": "...",
      "timeFormat": "12",
      "passwordNeverExpires": true,
      "active": true,
      "mfaType": "local-totp",
      "phoneNumber": "...",
      "mobileNumber": "...",
      "pagerNumber": "...",
      "emailAddress": "...",
      "primaryContact": true,
      "receiveNotifications": true,
      "reportPDFPasswordEnabled": true,
      "reportPDFPassword": "...",
      "created": 12345,
      "lastPasswordChange": 12345,
      "lastSignIn": 12345,
      "unlockTime": 12345,
      "unsuccessfulSignInAttempts": 12345,
      "directoryName": "...",
      "directoryInfo": "...",
      "external": true,
      "externalUserID": "...",
      "temporary": true,
      "readOnly": true
    }
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "UpdateAdministratorResponse": {
    "administrator": {
      "ID": 12345,
      "username": "...",
      "password": "...",
      "fullName": "...",
      "description": "...",
      "roleID": 12345,
      "locale": "...",
      "timeZone": "...",
      "timeFormat": "12",
      "passwordNeverExpires": true,
      "active": true,
      "mfaType": "none",
      "phoneNumber": "...",
      "mobileNumber": "...",
      "pagerNumber": "...",
      "emailAddress": "...",
      "primaryContact": true,
      "receiveNotifications": true,
      "reportPDFPasswordEnabled": true,
      "reportPDFPassword": "...",
      "created": 12345,
      "lastPasswordChange": 12345,
      "lastSignIn": 12345,
      "unlockTime": 12345,
      "unsuccessfulSignInAttempts": 12345,
      "directoryName": "...",
      "directoryInfo": "...",
      "external": true,
      "externalUserID": "...",
      "temporary": true,
      "readOnly": true
    }
  }
}
                    
                  

List UI preferences

List UI preferences.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

administratorID
integer
the administrator ID
pageName
string
the page name. For now, the only available page name is "relay-management".

Response Codes

200
if the request is successful
403
if the user is not authorized to view UI preferences
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ListUIPreferencesResponse
a ListUIPreferencesResponse with the UI preferences details.
Properties
uiPreferences
UIPreference
the list of UI preference details.
Properties
key
string
the UI preference key.
value
string
the UI preference value.

Example Request

GET /administrators/{administratorID}/ui-preferences/{pageName}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ListUIPreferencesResponse": {
    "uiPreferences": [ {
      "key": "...",
      "value": "..."
    }, {
      "key": "...",
      "value": "..."
    } ]
  }
}
                    
                  

Modify UI preferences

Modify UI preferences.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

administratorID
integer
the administrator ID
pageName
string
the page name. For now, the only available page name is "relay-management".

Request Body

ModifyUIPreferencesRequest
a ModifyUIPreferencesRequest with the UI preferences details.
Properties
uiPreferences
the list of UI preference details.

Response Codes

200
if the request is successful
403
if the user is not authorized to modify UI preferences
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ModifyUIPreferencesResponse
a ModifyUIPreferencesResponse with the modified UI preferences details.
Properties
uiPreferences
the list of UI preference details.

Example Request

POST /administrators/{administratorID}/ui-preferences/{pageName}
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "ModifyUIPreferencesRequest": {
    "uiPreferences": [ {
      "key": "...",
      "value": "..."
    }, {
      "key": "...",
      "value": "..."
    } ]
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ModifyUIPreferencesResponse": {
    "uiPreferences": [ {
      "key": "...",
      "value": "..."
    }, {
      "key": "...",
      "value": "..."
    } ]
  }
}
                    
                  

Alert types

Interface to the Alert Type API.

The alert types are defined by the Deep Security system. It is not possible to add or remove alert types but some details of an alert type can be modified. Actions available through the API are described below.

List alert types

List alert types.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Query Parameters

alertTypeID
integer
(optional) used to define the starting point for the query. Combine with op to page through results.
maxItems
integer
(optional) the number of items to retrieve. The maximum value for this parameter is controlled by the "Maximum number of items to retrieve from database" setting on the administrator account, which defaults to 5000.
op
string
(optional, required if alertTypeID is specified) Currently supported operations are:
  • gt (greater than)
  • ge (greater than or equal to)
  • eq (equal to)
  • lt (less than)
  • le (less than or equal to)
overrides
boolean
(optional) include only alert types with overrides

Response Codes

200
if the request is successful
403
if the user is not authorized to view alert types
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ListAlertTypesResponse
a ListAlertTypesResponse with the alert type details.
Properties
alertTypes
AlertType
the list of alert type details.
Properties
id
number
the alert type identifier.

This value is assigned by the Deep Security Manager to uniquely identify each alert type.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

name
string
the alert type name.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

description
string
the alert type description.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

dismissible
boolean
the alert type dismissible flag.

This flag indicates whether or not alerts of this type can be dismissed by the end user.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

enabled
boolean
the alert type enabled flag.

When disabled no alerts of this type will be raised by the Deep Security Manager.

severity
Severity
the alert type severity.

Either warning or critical.

Values
warning
Warning.
critical
Critical.
notifyStart
boolean
the alert type notify start flag.

When set this flag indicates that an email notification should be sent each time the conditions change for an alert of this type.

notifyChange
boolean
the alert type notify change flag.

When set this flag indicates that an email notification should be sent each time the conditions change for an alert of this type.

notifyEnd
boolean
the alert type notify end flag.

When set this flag indicates that an email notification should be sent each time an alert of this type is resolved.

alertAlways
boolean
the alert type alert always flag.

Some alerts can be enabled/disabled based on rules (e.g. firewall rules or integrity monitoring rules). This flag overrides these rule-by-rule settings so alerts of this type will always be raised, regardless of the rule configuration.

Note that this flag is not available for all alert types.

Example Request

GET /alert-types?alertTypeID={alertTypeID}&maxItems={maxItems}&op={op}&overrides={overrides}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ListAlertTypesResponse": {
    "alertTypes": [ {
      "id": 12345,
      "name": "...",
      "description": "...",
      "dismissible": true,
      "enabled": true,
      "severity": "warning",
      "notifyStart": true,
      "notifyChange": true,
      "notifyEnd": true,
      "alertAlways": true
    }, {
      "id": 12345,
      "name": "...",
      "description": "...",
      "dismissible": true,
      "enabled": true,
      "severity": "warning",
      "notifyStart": true,
      "notifyChange": true,
      "notifyEnd": true,
      "alertAlways": true
    } ]
  }
}
                    
                  

Reset an alert type

Reset an alert type to default values.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

alertTypeID
integer
the alert type identifier.

Response Codes

200
if the request is successful
403
if the user is not authorized to modify alert types
404
if the user is authorized to modify alert types but the alert type does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Example Request

DELETE /alert-types/{alertTypeID}
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
                  

Describe an alert type

Describe an alert type.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

alertTypeID
integer
the alert type identifier.

Query Parameters

overrides
boolean
(optional) include only fields with non-default values

Response Codes

200
if the request is successful
403
if the user is not authorized to view alert types
404
if the user is authorized to view alert types but the alert type does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

DescribeAlertTypeResponse
a DescribeAlertTypeResponse with the alert type details.
Properties
alertType
the alert type details.

Example Request

GET /alert-types/{alertTypeID}?overrides={overrides}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "DescribeAlertTypeResponse": {
    "alertType": {
      "id": 12345,
      "name": "...",
      "description": "...",
      "dismissible": true,
      "enabled": true,
      "severity": "warning",
      "notifyStart": true,
      "notifyChange": true,
      "notifyEnd": true,
      "alertAlways": true
    }
  }
}
                    
                  

Modify an alert type

Modify an alert type.

Any unset elements in the request object will be left unchanged by the modify request.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

alertTypeID
integer
the alert type identifier.

Request Body

ModifyAlertTypeRequest
a ModifyAlertTypeRequest with the details of the alert type.
Properties
alertType
the alert type details.

Response Codes

200
if the request is successful
400
if the request contains invalid information
403
if the user is not authorized to modify alert types
404
if the user is authorized to modify alert types but the alert type does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ModifyAlertTypeResponse
an ModifyAlertTypeResponse with the updated alert type details.
Properties
alertType
the alert type details.

Example Request

POST /alert-types/{alertTypeID}
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "ModifyAlertTypeRequest": {
    "alertType": {
      "id": 12345,
      "name": "...",
      "description": "...",
      "dismissible": true,
      "enabled": true,
      "severity": "critical",
      "notifyStart": true,
      "notifyChange": true,
      "notifyEnd": true,
      "alertAlways": true
    }
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ModifyAlertTypeResponse": {
    "alertType": {
      "id": 12345,
      "name": "...",
      "description": "...",
      "dismissible": true,
      "enabled": true,
      "severity": "critical",
      "notifyStart": true,
      "notifyChange": true,
      "notifyEnd": true,
      "alertAlways": true
    }
  }
}
                    
                  

Alerts

Interface to the Alert API.

Alerts are generated by the Deep Security system. It is not possible to add or remove alerts but some alerts can be dismissed. Actions available through the API are described below.

List alerts

List alerts.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Query Parameters

alertID
integer
(optional) used to define the starting point for the query. Combine with op to page through results.
dismissed
boolean
(optional) include alerts that have been dismissed.
maxItems
integer
(optional) the number of items to retrieve. The maximum value for this parameter is controlled by the "Maximum number of items to retrieve from database" setting on the administrator account, which defaults to 5000.
op
string
(optional, required if alertID is specified) Currently supported operations are:
  • gt (greater than)
  • ge (greater than or equal to)
  • eq (equal to)
  • lt (less than)
  • le (less than or equal to)

Response Codes

200
if the request is successful
403
if the user is not authorized to view alerts
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ListAlertsResponse
a ListAlertsResponse with the alert details sorted by date raised (newest first).
Properties
alerts
Alert
the list of alert details.
Properties
id
number
the alert identifier.

This value is assigned by the Deep Security Manager to uniquely identify each alert.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

typeID
number
the alert type identifier.

This value is assigned by the Deep Security Manager to uniquely identify each alert type.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

name
string
the alert name.

This information is copied from the Alert Type and all alerts of the same type will have the same name.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

description
string
the alert description.

This information is copied from the Alert Type and all alerts of the same type will have the same description.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

dismissible
boolean
the alert dismissible flag.

This flag indicates whether or not alerts of this type can be dismissed by the end user. This information is copied from the Alert Type and all alerts of the same type will be dismissible or not dismissible.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

severity
the alert severity.

Either warning or critical.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

Values
warning
Warning.
critical
Critical.
managerNodeID
number
the manager node identifier.

This value is assigned by the Deep Security Manager to uniquely identify each manager node.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

timeRaised
number
the time when the alert was first raised, as the number of milliseconds since January 1, 1970, 00:00:00 GMT.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

timeChanged
number
the time the alert was last changed, as the number of milliseconds since January 1, 1970, 00:00:00 GMT.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

timeDismissed
number
the time the alert was dismissed, as the number of milliseconds since January 1, 1970, 00:00:00 GMT.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

dismissedByID
number
the identifier of the administrator who dismissed the alert.

The value will be one of:

  • the unique identifier of an administrator (for manually dismissed alerts).
  • 0 for alerts automatically dismissed by the system.
  • null for alerts that are still active.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

targets
Target
the target objects associated with this alert.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

Properties
id
number
the target identifier.

This value is assigned by the Deep Security Manager to uniquely identify each target within an alert.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

timeRaised
number
the time when the alert was first raised for this target, as the number of milliseconds since January 1, 1970, 00:00:00 GMT.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

timeDismissed
number
the time the alert was dismissed for this target, as the number of milliseconds since January 1, 1970, 00:00:00 GMT.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

dismissedByID
number
the identifier of the administrator who dismissed the alert for this target.

The value will be one of:

  • the unique identifier of an administrator (for manually dismissed alerts).
  • 0 for alerts automatically dismissed by the system.
  • null for alerts that are still active.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

urn
string
the object associated with this target, expressed as a Uniform Resource Name.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

Example Request

GET /alerts?alertID={alertID}&dismissed={dismissed}&maxItems={maxItems}&op={op}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ListAlertsResponse": {
    "alerts": [ {
      "id": 12345,
      "typeID": 12345,
      "name": "...",
      "description": "...",
      "dismissible": true,
      "severity": "critical",
      "managerNodeID": 12345,
      "timeRaised": 12345,
      "timeChanged": 12345,
      "timeDismissed": 12345,
      "dismissedByID": 12345,
      "targets": [ {
        "id": 12345,
        "timeRaised": 12345,
        "timeDismissed": 12345,
        "dismissedByID": 12345,
        "urn": "..."
      }, {
        "id": 12345,
        "timeRaised": 12345,
        "timeDismissed": 12345,
        "dismissedByID": 12345,
        "urn": "..."
      } ]
    }, {
      "id": 12345,
      "typeID": 12345,
      "name": "...",
      "description": "...",
      "dismissible": true,
      "severity": "critical",
      "managerNodeID": 12345,
      "timeRaised": 12345,
      "timeChanged": 12345,
      "timeDismissed": 12345,
      "dismissedByID": 12345,
      "targets": [ {
        "id": 12345,
        "timeRaised": 12345,
        "timeDismissed": 12345,
        "dismissedByID": 12345,
        "urn": "..."
      }, {
        "id": 12345,
        "timeRaised": 12345,
        "timeDismissed": 12345,
        "dismissedByID": 12345,
        "urn": "..."
      } ]
    } ]
  }
}
                    
                  

Dismiss an alert

Dismiss an alert.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

alertID
integer
the alert identifier.

Response Codes

200
if the request is successful
403
if the user is not authorized to dismiss alerts
404
if the user is authorized to dismiss alerts but the alert does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Example Request

DELETE /alerts/{alertID}
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
                  

Describe an alert

Describe an alert.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

alertID
integer
the alert identifier.

Query Parameters

dismissed
boolean
(optional) include targets within the alert that have been dismissed.

Response Codes

200
if the request is successful
403
if the user is not authorized to view alerts
404
if the user is authorized to view alerts but the alert does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

DescribeAlertResponse
a DescribeAlertResponse with the alert details.
Properties
alert
the alert details.

Example Request

GET /alerts/{alertID}?dismissed={dismissed}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "DescribeAlertResponse": {
    "alert": {
      "id": 12345,
      "typeID": 12345,
      "name": "...",
      "description": "...",
      "dismissible": true,
      "severity": "critical",
      "managerNodeID": 12345,
      "timeRaised": 12345,
      "timeChanged": 12345,
      "timeDismissed": 12345,
      "dismissedByID": 12345,
      "targets": [ {
        "id": 12345,
        "timeRaised": 12345,
        "timeDismissed": 12345,
        "dismissedByID": 12345,
        "urn": "..."
      }, {
        "id": 12345,
        "timeRaised": 12345,
        "timeDismissed": 12345,
        "dismissedByID": 12345,
        "urn": "..."
      } ]
    }
  }
}
                    
                  

Dismiss an alert on a single target

Dismiss an alert for one target.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

alertID
integer
the alert identifier.
targetID
integer
the target identifier within the alert

Response Codes

200
if the request is successful
403
if the user is not authorized to dismiss alerts
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Example Request

DELETE /alerts/{alertID}/target/{targetID}
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
                  

Anti-malware events

Interface for event retrieval

List anti-malware events

Get anti-malware events.

Query Parameters

eventId
integer
the event id to query for events. Combined with eventIdOp, the returning events can be filtered according to the id.
eventIdOp
string
defined the events to return. Currently supported operations include gt(greater than), ge(greater than or equal to), eq(eqaul to), lt(less than), and le(less than or equal to). If an unsupported operator is provided, the default is 'eq'.
eventTime
integer
the event time to query for events. It is represented by a long integer, which is the milliseconds since January 1, 1970, 00:00:00 GMT. Combined with eventTimeOp, the returning events can be filtered by the specific milliseconds.
eventTimeOp
string
defined the events to return. Currently supported operations include gt(greater than), ge(greater than or equal to), eq(eqaul to), lt(less than), and le(less than or equal to). If an unsupported operator is provided, the default is 'eq'.
maxItems
integer
the maximum events to return
sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Response Codes

200
if the request is successful
400
if the request is invalid
403
if the user is not authorized to view anti-malware events
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ListAntiMalwareEventsResponse
a AntiMalwareEventListing, a collection of the events meet the given criteria.
Properties
lastEventID
number
the last event ID.

This will be 0 if no events are retrieved.

events
AntiMalwareEvent
the list of events.
Properties
antiMalwareConfigID
number
The primary key of AntiMalwareID.
antiMalwareEventID
number
The primary key of the event entry.
antiMalwareEventGUID
string
The AmEvent GUID
errorCode
number
The VSAPI error code indicates the reason of the actions of failure.
hostID
number
The id of the host the event was recorded on
hostName
string
The host name of the event was recorded on
infectedFilePath
string
The infected file full path
infectionSource
string
The source computer of the infection
malwareName
string
The name of the malware
malwareType
EnumMalwareType
The Malware Type of Event
Values
GENERAL
SPYWARE
SUSPICIOUS_FILE
SUSPICIOUS_ACTIVITY
UNAUTHORIZED_CHANGE
protocol
number
The protocols: Local Files(0), Network shared folder(1), etc. However, currently Agent only support local files.
quarantineRecordID
number
The Record ID referring to the record in QuarantineFile Table
scanResultAction1
number
The result of the first scan action: represent whether the action is successful (0) or failed (Error Code)
scanResultAction2
number
The result of the second scan action: represent whether the action is successful (0) or failed (Error Code)
scanAction1
number
The actual first scan action being taken: e.g. Pass, Delete, Quarantined...etc
scanAction2
number
The actual second scan action being taken: e.g. Pass, Delete, Quarantined...etc
scanType
EnumAntiMalwareScanType
The scan types include Real time, Manual, Scheduled, Quick etc.
Values
REALTIME
MANUAL
SCHEDULED
QUICK
spywareItems
AntiMalwareSpywareItem
Lists of spyware items if this is a spyware event.
Properties
antiMalwareSpywareItemID
number
The primary key of the spyware item
antiMalwareQuarantinedFileID
number
The key that refers to the spyware backup file. It does not enforce referential integrity, i.e. cascade delete when record removing takes place
hostID
number
The key refers to the host. It does not enforce referential integrity, i.e. cascade delete when record removing takes place.
objectInfo
string
File-path, registry key, process name...etc (aka: resource)
objectType
number
Type identifier for Process, Cookies, File System, System Registry, Shortcut Link, Host File, Other (aka: resource type)
riskLevel
number
Risk level gauge Very Low (0), Low (25), Medium(50), High(75), Very High(100)
scanAction
number
Scan Action: The action taken upon each spyware items: Pass (1), Delete (2), Quarantined (3), Clean (4), Deny Access (5)
scanResultAction
number
Represent whether the action is successful (0) or failed (Error Code)
spywareType
number
Type identifier for Adware, Cookie, Diale, Keylogger, Trojan, Worm, Downloader..etc
summaryScanResult
string
Scan result description.
target
string
The infected target, useful in behavior monitor
targetType
number
The infected target type, useful in behavior monitor

Supported the following target type:
- 0 maps to Unknown
- 1 maps to Process
- 2 maps to Registry
- 3 maps to File
- 4 maps to API
- 5 maps to Exploit

majorVirusType
number
The Major Virus Type of malware

Possible values are the following integer
- 0 maps to Joke
- 1 maps to Trojan
- 2 maps to Virus
- 3 maps to Test
- 4 maps to SPYWARE
- 5 maps to Packer
- 6 maps to Generic
- 7 maps to Other
- 8 maps to Active Content
- 9 maps to Blocked File Type
- 10 maps to Heuristic CVE Exploit
- 11 maps to Heuristic Detection
- 12 maps to Suspicious Object
- 13 maps to User Defined Suspicious Object
- 14 maps to Suspicious Activity
- 15 maps to Unauthorized Change

policyId
string
The detection rule, used in behavior monitor
sectionId
string
The detection method, used in behavior monitor
md5
string
The md5 value of the file when hash value calculation enabled
sha1
string
The sha1 value of the file when hash value calculation enabled
sha256
string
The sha256 value of the file when hash value calculation enabled
containerID
string
The ID of the Docker container where the malware was found
containerImageName
string
The image name of the Docker container where the malware was found
containerName
string
The name of the Docker container where the malware was found
relevantDetectionNames
string
The similar threat names with this predictive machine learning detection
detectionConfidence
number
The possibility percentage of this predictive machine learning detection
moreEvents
boolean
the indicator that there are more events available.

Example Request

GET /events/antimalware?eventId={eventId}&eventIdOp={eventIdOp}&eventTime={eventTime}&eventTimeOp={eventTimeOp}&maxItems={maxItems}&sID={sID}
Accept: application/json
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "antiMalwareEventListing": {
    "lastEventID": 12345,
    "events": [ {
      "antiMalwareConfigID": 12345,
      "antiMalwareEventID": 12345,
      "antiMalwareEventGUID": "...",
      "errorCode": 12345,
      "hostID": 12345,
      "hostName": "...",
      "infectedFilePath": "...",
      "infectionSource": "...",
      "malwareName": "...",
      "malwareType": "GENERAL",
      "protocol": 12345,
      "quarantineRecordID": 12345,
      "scanResultAction1": 12345,
      "scanResultAction2": 12345,
      "scanAction1": 12345,
      "scanAction2": 12345,
      "scanType": "REALTIME",
      "spywareItems": [ {
        "antiMalwareSpywareItemID": 12345,
        "antiMalwareQuarantinedFileID": 12345,
        "hostID": 12345,
        "objectInfo": "...",
        "objectType": 12345,
        "riskLevel": 12345,
        "scanAction": 12345,
        "scanResultAction": 12345,
        "spywareType": 12345
      }, {
        "antiMalwareSpywareItemID": 12345,
        "antiMalwareQuarantinedFileID": 12345,
        "hostID": 12345,
        "objectInfo": "...",
        "objectType": 12345,
        "riskLevel": 12345,
        "scanAction": 12345,
        "scanResultAction": 12345,
        "spywareType": 12345
      } ],
      "summaryScanResult": "...",
      "target": "...",
      "targetType": 12345,
      "majorVirusType": 12345,
      "policyId": "...",
      "sectionId": "...",
      "md5": "...",
      "sha1": "...",
      "sha256": "...",
      "containerID": "...",
      "containerImageName": "...",
      "containerName": "...",
      "relevantDetectionNames": "...",
      "detectionConfidence": 12345,
      "logTime": 12345,
      "origin": "GUESTAGENT",
      "tags": "..."
    }, {
      "antiMalwareConfigID": 12345,
      "antiMalwareEventID": 12345,
      "antiMalwareEventGUID": "...",
      "errorCode": 12345,
      "hostID": 12345,
      "hostName": "...",
      "infectedFilePath": "...",
      "infectionSource": "...",
      "malwareName": "...",
      "malwareType": "SUSPICIOUS_ACTIVITY",
      "protocol": 12345,
      "quarantineRecordID": 12345,
      "scanResultAction1": 12345,
      "scanResultAction2": 12345,
      "scanAction1": 12345,
      "scanAction2": 12345,
      "scanType": "SCHEDULED",
      "spywareItems": [ {
        "antiMalwareSpywareItemID": 12345,
        "antiMalwareQuarantinedFileID": 12345,
        "hostID": 12345,
        "objectInfo": "...",
        "objectType": 12345,
        "riskLevel": 12345,
        "scanAction": 12345,
        "scanResultAction": 12345,
        "spywareType": 12345
      }, {
        "antiMalwareSpywareItemID": 12345,
        "antiMalwareQuarantinedFileID": 12345,
        "hostID": 12345,
        "objectInfo": "...",
        "objectType": 12345,
        "riskLevel": 12345,
        "scanAction": 12345,
        "scanResultAction": 12345,
        "spywareType": 12345
      } ],
      "summaryScanResult": "...",
      "target": "...",
      "targetType": 12345,
      "majorVirusType": 12345,
      "policyId": "...",
      "sectionId": "...",
      "md5": "...",
      "sha1": "...",
      "sha256": "...",
      "containerID": "...",
      "containerImageName": "...",
      "containerName": "...",
      "relevantDetectionNames": "...",
      "detectionConfidence": 12345,
      "logTime": 12345,
      "origin": "APPLIANCEAGENT",
      "tags": "..."
    } ],
    "moreEvents": true
  }
}
                    
                  

Describe an anti-malware event

Get an anti-malware event.

Path Parameters

eventId
integer
the event id to fetch

Query Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Response Codes

200
if the request is successful
400
if the request is invalid
403
if the user is not authorized to view anti-malware events
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

the event with the specific id

Example Request

GET /events/antimalware/{eventId}?sID={sID}
Accept: application/json
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "antiMalwareEvent": {
    "antiMalwareConfigID": 12345,
    "antiMalwareEventID": 12345,
    "antiMalwareEventGUID": "...",
    "errorCode": 12345,
    "hostID": 12345,
    "hostName": "...",
    "infectedFilePath": "...",
    "infectionSource": "...",
    "malwareName": "...",
    "malwareType": "UNAUTHORIZED_CHANGE",
    "protocol": 12345,
    "quarantineRecordID": 12345,
    "scanResultAction1": 12345,
    "scanResultAction2": 12345,
    "scanAction1": 12345,
    "scanAction2": 12345,
    "scanType": "QUICK",
    "spywareItems": [ {
      "antiMalwareSpywareItemID": 12345,
      "antiMalwareQuarantinedFileID": 12345,
      "hostID": 12345,
      "objectInfo": "...",
      "objectType": 12345,
      "riskLevel": 12345,
      "scanAction": 12345,
      "scanResultAction": 12345,
      "spywareType": 12345
    }, {
      "antiMalwareSpywareItemID": 12345,
      "antiMalwareQuarantinedFileID": 12345,
      "hostID": 12345,
      "objectInfo": "...",
      "objectType": 12345,
      "riskLevel": 12345,
      "scanAction": 12345,
      "scanResultAction": 12345,
      "spywareType": 12345
    } ],
    "summaryScanResult": "...",
    "target": "...",
    "targetType": 12345,
    "majorVirusType": 12345,
    "policyId": "...",
    "sectionId": "...",
    "md5": "...",
    "sha1": "...",
    "sha256": "...",
    "containerID": "...",
    "containerImageName": "...",
    "containerName": "...",
    "relevantDetectionNames": "...",
    "detectionConfidence": 12345,
    "logTime": 12345,
    "origin": "GUESTAGENT",
    "tags": "..."
  }
}
                    
                  

Application control events

Interface for retrieving Application Control events.

List application control events

Get Application Control events.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Query Parameters

eventID
integer
the event ID to query for events. Combined with eventIDOp, the returning events can be filtered according to the id.
eventIDOp
string
defined the events to return. Currently supported operations include gt(greater than), ge(greater than or equal to), eq(equal to), lt(less than), and le(less than or equal to). If an unsupported operator is provided, the default is 'eq'.
eventTime
integer
the event time to query for events. It is represented by a long integer, which is the milliseconds since January 1, 1970, 00:00:00 GMT. Combined with eventTimeOp, the returning events can be filtered by the specific milliseconds. Please be aware that for Application Control events, the accuracy of event time is millisecond. In other words, if you want to exactly filter events by event time, the eventTime value must be millisecond accuracy.
eventTimeOp
string
defined the events to return. Currently supported operations include gt(greater than), ge(greater than or equal to), eq(eqaul to), lt(less than), and le(less than or equal to). If an unsupported operator is provided, the default is 'eq'.
maxItems
integer
the maximum number of events to return

Response Codes

200
if the request is successful
403
if the user is not authorized to view application control events
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ListEventsResponse
a ListEventsResponse containing a collection of the events that meet the given criteria.
Properties
lastEventID
number
the last event ID.

This will be 0 if no events are retrieved.

events
Event
the list of events.
Properties
eventID
number
the event ID.
sha1
string
the SHA-1 hash of the application that was blocked.
sha256
string
the SHA-256 hash of the application that was blocked.
md5
string
the MD5 hash of the application that was blocked.
hostID
number
the ID of the host where the application was blocked.
hostName
string
the hostname of the host where the application was blocked.
tags
string
the tags associated with the event.

The tags will be returned in a comma-and-whitespace-separated list. For example, if an event has been tagged with tag1 and tag2, then the returned string will be tag1, tag2.

blockReason
BlockReason
the reason the application launch was blocked.
Values
unknown
Used if the application launch was blocked for an unknown reason.
blacklisted
Used if the application launch was blocked because the application was blacklisted.
not-whitelisted
Used if the application launch was blocked because the application was not on the whitelist.
fileName
string
the filename of the application that was blocked.
rulesetID
number
the ruleset that is assigned to the host where the application was blocked.
groupID
string
the primary group ID of the user that launched the application that was blocked.
groupName
string
the primary group name of the user that launched the application that was blocked.
action
Action
the action that was taken when the application was launched.
Values
unknown
Used if the action that triggered this event is unknown.
detect-only
Used if the application launch would have been blocked, but Application Control is in detect-only mode.
blocked
Used if the application launch was blocked.
path
string
the path to the application that was launched.
processID
number
the process ID of the process that attempted to launch the application.
processName
string
the process name of the process that attempted to launch the application.
userID
string
the user ID of the user that attempted to launch the application.
userName
string
the user name of the user that attempted to launch the application.

NOTE: This is the system username, not necessarily a person's actual name. This ID will likely need to be mapped to an actual person through your identity management system.

logTime
number
the time at which the event was recorded.
repeatCount
number
the number of individual security events that were aggregated into this event. For aggregationType = 0, repeatCount is always 1 For aggregationType = 1 or aggregationType = 2, the repeatCount is greater than / equal to 1.
aggregationType
number
the event aggregation type.
- 0 indicates that the event is not aggregated
- 1 indicates that the event is aggregated based on file name, path and event type
- 2 indicates that the event is aggregated based on event type

Event types is one of the following:
- Execution of Unrecognized Software Allowed
- Execution of Unrecognized Software Blocked
- Execution of Software Blocked by Rule

moreEvents
boolean
the indicator that there are more events available.

Example Request

GET /events/appcontrol?eventID={eventID}&eventIDOp={eventIDOp}&eventTime={eventTime}&eventTimeOp={eventTimeOp}&maxItems={maxItems}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ListEventsResponse": {
    "lastEventID": 12345,
    "events": [ {
      "eventID": 12345,
      "sha1": "...",
      "sha256": "...",
      "md5": "...",
      "hostID": 12345,
      "hostName": "...",
      "tags": "...",
      "blockReason": "not-whitelisted",
      "fileName": "...",
      "rulesetID": 12345,
      "groupID": "...",
      "groupName": "...",
      "action": "detect-only",
      "path": "...",
      "processID": 12345,
      "processName": "...",
      "userID": "...",
      "userName": "...",
      "logTime": 12345,
      "repeatCount": 12345,
      "aggregationType": 12345
    }, {
      "eventID": 12345,
      "sha1": "...",
      "sha256": "...",
      "md5": "...",
      "hostID": 12345,
      "hostName": "...",
      "tags": "...",
      "blockReason": "unknown",
      "fileName": "...",
      "rulesetID": 12345,
      "groupID": "...",
      "groupName": "...",
      "action": "detect-only",
      "path": "...",
      "processID": 12345,
      "processName": "...",
      "userID": "...",
      "userName": "...",
      "logTime": 12345,
      "repeatCount": 12345,
      "aggregationType": 12345
    } ],
    "moreEvents": true
  }
}
                    
                  

Describe an application control event

Get the Application Control event with the specified event ID.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

eventID
integer
the ID of the event to fetch.

Response Codes

200
if the request is successful
403
if the user is not authorized to view application control events
404
if the application control event does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

DescribeEventResponse
a DescribeEventResponse containing the event with the specific ID
Properties
event
the event details.

Example Request

GET /events/appcontrol/{eventID}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "DescribeEventResponse": {
    "event": {
      "eventID": 12345,
      "sha1": "...",
      "sha256": "...",
      "md5": "...",
      "hostID": 12345,
      "hostName": "...",
      "tags": "...",
      "blockReason": "blacklisted",
      "fileName": "...",
      "rulesetID": 12345,
      "groupID": "...",
      "groupName": "...",
      "action": "blocked",
      "path": "...",
      "processID": 12345,
      "processName": "...",
      "userID": "...",
      "userName": "...",
      "logTime": 12345,
      "repeatCount": 12345,
      "aggregationType": 12345
    }
  }
}
                    
                  

Authentication

Interface for the authentication API.

Log in

Authenticate a user, and return a session ID (sID) to use in subsequent calls to other APIs.

Note: if your application uses both the SOAP web services API and the REST API, the same session ID can be used in both APIs; you do not need to log in separately to each API.

Request Body

DSCredentials
The credentials to use to authenticate.
Properties
tenantName
string
Tenant account name; required when logging in to a tenant account.
userName
string
User name to use for authentication
password
string
Password used for authentication
applicationInfos
ApplicationInfos
Application information provided by calling application, optional
Properties
applicationName
string
Integrated application name; required if applicationInfos is provided. Accepts maximum length of 254 characters
applicationVersion
string
Integrated application version; (Optional) Not blank if application version is provided. Accepts maximum length of 254 characters
serverName
string
Integrated server hostname; required if applicationInfos is provided. The format of hostname should follow RFC 1123 or a valid IP format.
requestID
string
Integrated application request ID; (Optional) Not blank if request ID is provided. Accepts maximum length of 254 characters
mfaCode
string
Multi-factor authentication code for authentication with accounts which have MFA enabled.

Response Codes

200
if the request is successful
403
if the user is not successfully authenticated
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

string
session ID the session ID value to pass to subsequent API methods that look for a session ID.
String
session ID the session ID value to pass to subsequent API methods that look for a session ID.

Example Request

POST /authentication/login
Content-Type: application/json
Accept: application/json
                    
{
  "dsCredentials": {
    "tenantName": "...",
    "userName": "...",
    "password": "...",
    "applicationInfos": {
      "applicationName": "...",
      "applicationVersion": "...",
      "serverName": "...",
      "requestID": "..."
    },
    "mfaCode": "..."
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
...
                    
                  

Log out

Ends the client session. The given session ID will not be usable after this call.

Query Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Response Codes

200
if the session is ended
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

string
a response with status 200 OK when the logout succeeds. The returned string is purely informational and can be ignored.
String
a response with status 200 OK when the logout succeeds. The returned string is purely informational and can be ignored.

Example Request

DELETE /authentication/logout?sID={sID}
Accept: application/json
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
...
                    
                  

Log in to a tenant account

Does not apply to Deep Security as a Service

Multi-tenant environment only

Primary tenant only

Sign in as a tenant, and return a session ID (sID) to use in subsequent calls to other APIs.

Note:

  • Sign in as a tenant will not log out the original session
  • if your application uses both the SOAP web services API and the REST API, the same session ID can be used in both APIs; you do not need to log in separately to each API.

Path Parameters

tenantName
string
the tenant's name

Query Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API for the primary tenant user session.

Response Codes

200
if the request is successful
403
if the user is not authorized to sign in as a tenant
404
if the user is authorized to sign in as a tenant but the tenant does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

string
the tenant session ID value to pass to subsequent API methods that look for a session ID.
String
the tenant session ID value to pass to subsequent API methods that look for a session ID.

Example Request

GET /authentication/signinastenant/name/{tenantName}?sID={sID}
Accept: application/json
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
...
                    
                  

Billing

Applies to AWS Marketplace only

Primary tenant only

Interface for AWS MMS usage retrieval

List AWS MMS usage details

Applies to AWS Marketplace only

Primary tenant only

Get AWS MMS Usage data - detailed view

Query Parameters

endDate
string
End of the date range. Default is "now" if not specified.
sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.
startDate
string
Start of the date range. Default is one hour before endDate if not specified.

Response Codes

200
if the request is successful
400
if the request is invalid
403
if the user is not authorized to view AWS MMS usage data
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

MMSDetailsListing
an MMSUsageDetailsListing, a collection of detailed information about AWS MMS Usage
Properties
details
MMSDetails
-
Properties
usageDate
number
-
category
string
-
instanceCount
number
-
computerListing
MMSComputerListing
-
Properties
computer
MMSComputer
-
Properties
hostID
number
-
computerName
string
-
instanceType
string
-
status
string
-

Example Request

GET /mms/details?endDate={endDate}&sID={sID}&startDate={startDate}
Accept: application/json
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "##default": {
    "details": [ {
      "usageDate": 12345,
      "category": "...",
      "instanceCount": 12345,
      "computerListing": {
        "computer": [ { }, { } ]
      },
      "status": "..."
    }, {
      "usageDate": 12345,
      "category": "...",
      "instanceCount": 12345,
      "computerListing": {
        "computer": [ { }, { } ]
      },
      "status": "..."
    } ]
  }
}
                    
                  

List AWS MMS usage summary

Applies to AWS Marketplace only

Primary tenant only

Get AWS MMS Usage data - summary view

Query Parameters

endDate
string
End of the date range. Default is "now" if not specified.
sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.
startDate
string
Start of the date range. Default is one hour before endDate if not specified.

Response Codes

200
if the request is successful
400
if the request is invalid
403
if the user is not authorized to view AWS MMS usage data
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

MMSSummaryListing
an MMSUsageSummaryListing, a collection of summary information about AWS MMS Usage
Properties
summary
MMSSummary
-
Properties
usageDate
number
-
category
string
-
instanceCount
number
-
status
string
-

Example Request

GET /mms/summary?endDate={endDate}&sID={sID}&startDate={startDate}
Accept: application/json
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "##default": {
    "summary": [ {
      "usageDate": 12345,
      "category": "...",
      "instanceCount": 12345,
      "status": "..."
    }, {
      "usageDate": 12345,
      "category": "...",
      "instanceCount": 12345,
      "status": "..."
    } ]
  }
}
                    
                  

Cloud accounts

Interface for the Cloud Account API. For AWS Cloud Accounts, see 'Cloud Accounts - AWS'

List all cloud accounts

Lists all of the cloud accounts that are in Deep Security

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Response Body

ListCloudAccountsResponse
A response with status 200 OK and a body containing GetCloudAccountsResponse object if the get was successful If there is an authentication issue with the session cookie it will return a 403 Forbidden If there is an error getting the account list it will return a 500 Internal Server Error
Properties
cloudAccount
CloudAccount
The list of cloud accounts.
Properties
id
number
the internal Id of the cloud account.
cloudType
string
the type of cloud provider for the account.
name
string
the name of the cloud account.
lastTimeSynchronized
number
the last time the account was synchronized.

Example Request

GET /cloudaccounts
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ListCloudAccountsResponse": {
    "cloudAccount": [ {
      "id": 12345,
      "cloudType": "...",
      "name": "...",
      "lastTimeSynchronized": 12345
    }, {
      "id": 12345,
      "cloudType": "...",
      "name": "...",
      "lastTimeSynchronized": 12345
    } ]
  }
}
                    
                  

Create a cloud account

Add a new cloud account.

The following fields of the CloudAccountElement are mandatory:

For VCLOUD

  • userId
  • userPassword
  • endpoint
  • cloudType where the value is VCLOUD_PRIVATE_CLOUD
  • name

For AZURE

  • subscriptionId
  • subscriptionName
  • cloudType where the value is AZURE_ARM
  • name
  • azureAdTenantId
  • azureAdTenantName
  • azureAdApplicationId
  • azureAdApplicationName
  • azureAdApplicationPassword

Request Body

CreateCloudAccountRequest
The request parameters.
Properties
cloudAccountElement
CloudAccountElement
Contains cloud account related information. The class is a superset of attributes coming from our supported cloud providers.
Properties
cloudType
string
The cloud type; supported types are AMAZON, VCLOUD_PRIVATE_CLOUD, AZURE and AZURE_ARM.

Note: Deep Security can now connect to Azure using the Resource Manager interface:
Update the Azure cloud account with the cloud type AZURE_ARM, and the necessary parameters: subscriptionId, azureTenantId, azureApplicationId, azureApplicationPassword.
cloudRegion
string
Represents a cloud partition/region, current mapping is the following:
- amazon.cloud.region.key.1 maps to us-east-1
- amazon.cloud.region.key.2 maps to us-west-2
- amazon.cloud.region.key.3 maps to us-west-1
- amazon.cloud.region.key.4 maps to eu-west-1
- amazon.cloud.region.key.5 maps to ap-southeast-1
- amazon.cloud.region.key.6 maps to ap-northeast-1
- amazon.cloud.region.key.7 maps to sa-east-1
name
string
User-friendly name to be given to the cloud account.
description
string
Description to be associated to the cloud account.
userId
string
Used by VCLOUD_PRIVATE_CLOUD to uniquely identify an user; the format is usually <userid>@<organization>
userPassword
string
Used by VCLOUD_PRIVATE_CLOUD as the user's password.
accessKey
string
Used by AMAZON, the user access key.
secretKey
string
Used by AMAZON, the user secret key.
realTimeSynchronization
boolean
-
lastTimeSynchronized
number
Last time synchronized; provided by the server.
endpoint
string
IP Address of the vCloud cloud.
cloudAccountId
number
Internal identifier uniquely identifying a cloud provider account.
subscriptionId
string
Subscription ID of the Azure cloud.
azureCertificate
string
Key Pair file for the Azure cloud. A PEM-encoded X509 file includes private/public key. The allowed format is base64 string of key pair file.
azureCertPassword
string
Password of Key Pair file for the Azure cloud. Leave blank if key pair is not encrypted.
subscriptionName
string
Subscription name of the Azure cloud.
azureAdTenantId
string
Tenant ID of the Azure Active Directory.
azureAdTenantName
string
Tenant name of the Azure Active Directory.
azureAdApplicationId
string
Application ID in the Azure Active Directory.
azureAdApplicationName
string
Application name in the Azure Active Directory.
azureAdApplicationPassword
string
Application password in the Azure Active Directory.
azureEntryPoint
string
IP Address of the Azure cloud.

Response Body

CreateCloudAccountResponse
A response with status 200 OK and a body containing response information when adding a cloud account succeeds. It will return a response with status 400 Bad Request and a body containing an ErrorMessage when mandatory parameters are missing or validation fails.
Properties
cloudAccountId
number
Return the ID of the newly created cloud account

Example Request

POST /cloudaccounts
Content-Type: application/json
Accept: application/json
                    
{
  "createCloudAccountRequest": {
    "cloudAccountElement": {
      "cloudType": "...",
      "cloudRegion": "...",
      "name": "...",
      "description": "...",
      "userId": "...",
      "userPassword": "...",
      "accessKey": "...",
      "secretKey": "...",
      "realTimeSynchronization": true,
      "lastTimeSynchronized": 12345,
      "endpoint": "...",
      "cloudAccountId": 12345,
      "subscriptionId": "...",
      "azureCertificate": "...",
      "azureCertPassword": "...",
      "subscriptionName": "...",
      "azureAdTenantId": "...",
      "azureAdTenantName": "...",
      "azureAdApplicationId": "...",
      "azureAdApplicationName": "...",
      "azureAdApplicationPassword": "...",
      "azureEntryPoint": "..."
    },
    "sessionId": "..."
  }
}
                    
                  

Example Response

HTTP/1.1 201 Created
Content-Type: application/json
                    
{
  "createCloudAccountResponse": {
    "cloudAccountId": 12345
  }
}
                    
                  

Delete a cloud account

Delete a cloud account.

Path Parameters

cloudAccountID
integer
Identifier uniquely identifying the cloud account to delete.

Query Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Response Body

DeleteCloudAccountResponse
A response with status 200 OK and a body containing response information when deletion was successful. If the id is null or empty, it will return a response with status 400 Bad Request and a body containing an ErrorMessage.

Example Request

DELETE /cloudaccounts/{cloudAccountID}?sID={sID}
Accept: application/json
                  

Example Response

HTTP/1.1 204 No Content
Content-Type: application/json
                    
{
  "deleteCloudAccountResponse": { }
}
                    
                  

Describe a cloud account

Get a specific cloud account.

Path Parameters

cloudAccountID
integer
Identifier uniquely identifying a cloud account.

Query Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Response Body

The requested cloud account. It will return response code 404 Not Found when trying to retrieve a non-existent cloud account.

Example Request

GET /cloudaccounts/{cloudAccountID}?sID={sID}
Accept: application/json
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "cloudAccount": {
    "cloudType": "...",
    "cloudRegion": "...",
    "name": "...",
    "description": "...",
    "userId": "...",
    "userPassword": "...",
    "accessKey": "...",
    "secretKey": "...",
    "realTimeSynchronization": true,
    "lastTimeSynchronized": 12345,
    "endpoint": "...",
    "cloudAccountId": 12345,
    "subscriptionId": "...",
    "azureCertificate": "...",
    "azureCertPassword": "...",
    "subscriptionName": "...",
    "azureAdTenantId": "...",
    "azureAdTenantName": "...",
    "azureAdApplicationId": "...",
    "azureAdApplicationName": "...",
    "azureAdApplicationPassword": "...",
    "azureEntryPoint": "..."
  }
}
                    
                  

Modify a cloud account

Update cloud account information.

Path Parameters

cloudAccountID
integer
Identifier uniquely identifying the cloud account to update.

Request Body

UpdateCloudAccountRequest
The request parameters
Properties
cloudAccountElement
Contains cloud account related information. The class is a superset of attributes coming from our supported cloud providers.

Response Body

UpdateCloudAccountResponse
A response with status 200 OK and a body containing response information when updating a cloud account succeeds. It will return a response with status 400 Bad Request and a body containing an ErrorMessage when trying to modify an unsupported attribute or when trying to modify a non-existent cloud account.

Example Request

PUT /cloudaccounts/{cloudAccountID}
Content-Type: application/json
Accept: application/json
                    
{
  "updateCloudAccountRequest": {
    "cloudAccountElement": {
      "cloudType": "...",
      "cloudRegion": "...",
      "name": "...",
      "description": "...",
      "userId": "...",
      "userPassword": "...",
      "accessKey": "...",
      "secretKey": "...",
      "realTimeSynchronization": true,
      "lastTimeSynchronized": 12345,
      "endpoint": "...",
      "cloudAccountId": 12345,
      "subscriptionId": "...",
      "azureCertificate": "...",
      "azureCertPassword": "...",
      "subscriptionName": "...",
      "azureAdTenantId": "...",
      "azureAdTenantName": "...",
      "azureAdApplicationId": "...",
      "azureAdApplicationName": "...",
      "azureAdApplicationPassword": "...",
      "azureEntryPoint": "..."
    },
    "sessionId": "..."
  }
}
                    
                  

Example Response

HTTP/1.1 204 No Content
Content-Type: application/json
                    
{
  "updateCloudAccountResponse": { }
}
                    
                  

Sync a cloud account

Synchronize a cloud account by ID.

Path Parameters

cloudAccountID
integer
Identifier uniquely identifying the cloud account to synchronize.

Query Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Response Body

SynchronizeCloudAccountResponse
A response with status 200 OK and a body containing response information when synchronization was successful. If the id is null or empty, it will return a response with status 400 Bad Request and a body containing an ErrorMessage.
Properties
startTime
number
Return the time at which synchronization began
endTime
number
Return the time at which the synchronization process completed.

Example Request

PUT /cloudaccounts/{cloudAccountID}/synchronize?sID={sID}
Accept: application/json
                  

Example Response

HTTP/1.1 204 No Content
Content-Type: application/json
                    
{
  "synchronizeCloudAccountResponse": {
    "startTime": 12345,
    "endTime": 12345
  }
}
                    
                  

Test a cloud account connection

Test a cloud account connection against its supporting cloud provider.

Path Parameters

cloudAccountID
integer
Identifier uniquely identifying the cloud account to test.

Query Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Response Body

TestCloudAccountResponse
A response with status 200 OK and a body containing response information when the connection to the supporting cloud provider was successful. If the cloudAccountId is null or empty, it will return a response with status 400 Bad Request and a body containing an ErrorMessage.

Example Request

PUT /cloudaccounts/{cloudAccountID}/testconnection?sID={sID}
Accept: application/json
                  

Example Response

HTTP/1.1 204 No Content
Content-Type: application/json
                    
{
  "testCloudAccountResponse": { }
}
                    
                  

Cloud accounts - AWS

Interface for the AWS Account API.

Create an AWS account cloud connector

Create a new AWS account cloud connector.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Request Body

AddAwsAccountRequest
AddAwsAccountRequest object describing the Amazon account.
Properties
useInstanceRole
boolean
if the instance role is used to add the AWS account.
awsCredentials
AwsCredentials
the AWS credentials (Access Key, Secret Key) used to add the AWS account.
Properties
accessKeyId
string
-
secretKey
string
-
seedRegion
string
the region to initialize the EC2 client in. This is an advanced option used if you want to access special region.
crossAccountRole
CrossAccountRole
the The Cross Account Role (ARN, External ID) used to add the AWS account.
Properties
roleArn
string
the ARN (Amazon Resource Name) of the Cross Account Role.
externalId
string
the external Id of the Cross Account Role if it exists.
workspacesEnabled
boolean
the flag indicating whether or not Amazon Workspaces are enabled for this account.

Response Codes

200
if the request is successful
403
if the user is not authorized to create AWS account cloud connectors
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

AddAwsAccountResponse
A response with status 200 OK and a body containing AddAwsAccountResponse object when addition was successful If there is an authentication issue with the session cookie it will return a 403 Forbidden If there is a permission issue with the give AWS credentials, or the account has already been imported it will return a 400 Bad Request If there is an error adding the account it will return a 500 Internal Server Error
Properties
awsAccountId
string
-
internalId
number
-
awsAccountAlias
string
-

Example Request

POST /cloudaccounts/aws
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "AddAwsAccountRequest": {
    "useInstanceRole": true,
    "awsCredentials": {
      "accessKeyId": "...",
      "secretKey": "..."
    },
    "seedRegion": "...",
    "crossAccountRole": {
      "roleArn": "...",
      "externalId": "..."
    },
    "workspacesEnabled": true
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "AddAwsAccountResponse": {
    "awsAccountId": "...",
    "internalId": 12345,
    "awsAccountAlias": "..."
  }
}
                    
                  

Delete an AWS account cloud connector

Delete an existing AWS account cloud connector.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

internalID
integer
the internal account ID

Response Codes

200
if the request is successful
403
if the user is not authorized to delete AWS account cloud connectors
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Example Request

DELETE /cloudaccounts/aws/{internalID}
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
                  

Describe an AWS account cloud connector

Describe an existing AWS account cloud connector.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

internalID
integer
the internal account ID

Response Codes

200
if the request is successful
403
if the user is not authorized to view AWS account cloud connectors
404
if the AWS cloud connector does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

GetAwsAccountResponse
A response with status 200 OK and a body containing GetAwsAccountResponse object if the object exists If there is an authentication issue with the session cookie it will return a 403 Forbidden If the account ID does not exist it will return a 404 Not Found
Properties
internalId
number
the Deep Security internal Id of the AWS cloud account.
accountID
string
the AWS account Id.
accountAlias
string
the AWS account alias.
accessKey
string
the AWS Access Key ID.
seedRegion
string
the region to initialize the EC2 client in. This is an advanced option used if you want to access special region.
useInstanceRole
boolean
whether or not to use the instance role for permissions to add the AWS account.
crossAccountRoleArn
string
the Cross Account Role (ARN, External ID) used to add the AWS account.
lastSyncTime
number
the last time this AWS account was synchronized.
syncedRegions
AwsRegion
the list of AWS regions that have been synced for this account.
Properties
region
string
the Amazon region name.
computersSynced
number
The number of instances in the region during the last sync.
workspacesSynced
number
The number of workspaces in the region during the last sync.
workspacesEnabled
boolean
the flag indicating whether or not Amazon Workspaces are enabled for this account.

Example Request

GET /cloudaccounts/aws/{internalID}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "GetAwsAccountResponse": {
    "internalId": 12345,
    "accountID": "...",
    "accountAlias": "...",
    "accessKey": "...",
    "seedRegion": "...",
    "useInstanceRole": true,
    "crossAccountRoleArn": "...",
    "lastSyncTime": 12345,
    "syncedRegions": [ {
      "region": "...",
      "computersSynced": 12345,
      "workspacesSynced": 12345
    }, {
      "region": "...",
      "computersSynced": 12345,
      "workspacesSynced": 12345
    } ],
    "workspacesEnabled": true
  }
}
                    
                  

Synchronize an AWS account cloud connector

Trigger a sync of the specified AWS account cloud connector.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

internalID
integer
the internal account ID

Response Codes

200
if the request is successful
403
if the user is not authorized to synchronize AWS account cloud connectors
404
if the AWS cloud connector does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Example Request

POST /cloudaccounts/aws/{internalID}/sync
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
                  

Modify an AWS account cloud connector

Update the specified AWS cloud account

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

internalID
integer
the internal account ID

Request Body

UpdateAwsAccountRequest
-
Properties
useInstanceRole
boolean
Whether or not to use the instance role for permissions to add the AWS account.
awsCredentials
the AWS credentials (Access Key, Secret Key) used to add the AWS account.
seedRegion
string
the region to initialize the EC2 client in. This is an advanced option used if you want to access special region.
crossAccountRole
the Cross Account Role (ARN, External ID) used to add the AWS account.
workspacesEnabled
boolean
the flag indicating whether or not Amazon Workspaces are enabled for this account.

Response Codes

200
if the request is successful
403
if the user is not authorized to modify AWS account cloud connectors
404
if the AWS cloud connector does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Example Request

POST /cloudaccounts/aws/{internalID}/update
Content-Type: application/json
Cookie: sID=12345;
                    
{
  "UpdateAwsAccountRequest": {
    "useInstanceRole": true,
    "awsCredentials": {
      "accessKeyId": "...",
      "secretKey": "..."
    },
    "seedRegion": "...",
    "crossAccountRole": {
      "roleArn": "...",
      "externalId": "..."
    },
    "workspacesEnabled": true
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
                  

Diagnostics

Support interface for retrieving diagnostic information from the system.

Get manager diagnostic package

Retrieve the manager diagnostics package.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Query Parameters

verbose
boolean

Response Codes

200
if the request is successful
403
if the user is not authorized to create a manager diagnostics package
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

object
a ZIP file containing the manager diagnostics package.

Example Request

GET /support/manager/diagnostics-package?verbose={verbose}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
...
                    
                  

Get agent diagnostic package

Retrieve the agent diagnostics package for a specific host.

If the agent is not reachable, then only the manager diagnostics will be included.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

hostID
integer

Response Codes

200
if the request is successful
403
if the user is not authorized to create an agent diagnostics package for the host
404
if the host does not exist or the user is not authorized to view the host
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

object
a ZIP file containing the diagnostics package.

Example Request

GET /support/hosts/{hostID}/diagnostics-package
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
...
                    
                  

Event-based tasks

Interface to the Event-Based Task API.

List event-based tasks

List event-based tasks.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Response Codes

200
if the request is successful
403
if the user is not authorized to view event-based tasks
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ListEventBasedTasksResponse
a ListEventBasedTasksResponse with the event-based task details.
Properties
tasks
EventBasedTask
the list of tasks.
Properties
id
number
the task's identifier.
name
string
the name to use when displaying this task.
type
EventType
the event type that will trigger this task.
Values
computer-created-by-system
Trigger the task when a computer object is created by the system.
computer-moved-by-system
Trigger the task when a computer object is moved by the system.
agent-initiated-activation
Trigger the task when a computer object is activated by the agent on that computer.
agent-ip-changed
Trigger the task when the agent IP changes.
nsx-protection-changed
Trigger the task when the NSX protection for the computer changes.
computer-powered-on-by-system
Trigger the task when a computer is powered on by the system.
enabled
boolean
the enabled state for this task.
conditions
Condition
the conditions that must be true for this task to start.
Properties
field
Field
the event field to match against when evaluating this condition.
Values
hostname
Match against the name of the host that the event occurred on. Regular expressions are supported for the match value.
vcenter
Match against the vCenter of the host that the event occurred on. Regular expressions are supported for the match value.
cloudProvider
Match against the cloud provider of the host that the event occurred on. Regular expressions are supported for the match value.
securityGroup
Match against the security group name of the host that the event occurred on. Regular expressions are supported for the match value.
imageId
Match against the image identifier of the host that the event occurred on. Regular expressions are supported for the match value.
esx
Match against the ESX host of the host that the event occurred on. Regular expressions are supported for the match value.
folder
Match against the folder of the host that the event occurred on. Regular expressions are supported for the match value.
platform
Match against the platform name of the host that the event occurred on. Regular expressions are supported for the match value.
applianceProtectionAvailable
Match against the state of appliance protection of the host that the event occurred on. Valid values are true and false.
applianceProtectionActivated
Match against the state of appliance protection of the host that the event occurred on. Valid values are true and false.
lastUsedIP
Match against the IP address of the host that the event occurred on. The value may be an IP list.
tag
Match against a tag on the host that the event occurred on. This is a key / value condition: set the key to the name of the tag and the value to the tag value. Regular expressions are supported for the tag value.
nsxSecurityGroup
Match against the NSX security group of the host that the event occurred on. Regular expressions are supported for the match value.
key
string
the key to match when evaluating this condition if the condition is matching against a key/value field.
value
string
the value to match when evaluating this condition.
actions
Action
the actions that will be performed by this task.
Properties
type
Type
the type of action that will be taken by the task.
Values
activate
Activate the Deep Security Agent on the computer that triggered the task.
assign-policy
Assign a policy to the computer that triggered the task.

This action requires a parameter. The parameter value is the policy identifier for the policy that will be assigned to the computer.

assign-relay
Assign a Deep Security Relay to the computer that triggered the task.

This action requires a parameter. The parameter value is the relay identifier for the relay that will be assigned to the computer.

assign-group
Assign the computer that triggered the task to a host group.

This action requires a parameter. The parameter value is the host group identifier for the host group that the computer will be assigned to.

deactivate
Deactivate the Deep Security Agent on the computer that triggered the task.
parameterValue
number
the parameter value for actions that require a parameter.

Example Request

GET /tasks/event-based
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ListEventBasedTasksResponse": {
    "tasks": [ {
      "id": 12345,
      "name": "...",
      "type": "computer-powered-on-by-system",
      "enabled": true,
      "conditions": [ {
        "field": "lastUsedIP",
        "key": "...",
        "value": "..."
      }, {
        "field": "lastUsedIP",
        "key": "...",
        "value": "..."
      } ],
      "actions": [ {
        "type": "assign-group",
        "parameterValue": 12345
      }, {
        "type": "assign-relay",
        "parameterValue": 12345
      } ]
    }, {
      "id": 12345,
      "name": "...",
      "type": "computer-created-by-system",
      "enabled": true,
      "conditions": [ {
        "field": "lastUsedIP",
        "key": "...",
        "value": "..."
      }, {
        "field": "tag",
        "key": "...",
        "value": "..."
      } ],
      "actions": [ {
        "type": "assign-policy",
        "parameterValue": 12345
      }, {
        "type": "assign-relay",
        "parameterValue": 12345
      } ]
    } ]
  }
}
                    
                  

Create an event-based task

Create a new event-based task.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Request Body

CreateEventBasedTaskRequest
a CreateEventBasedTaskRequest describing the details of the event-based task.
Properties
the task details.

Response Codes

200
if the request is successful
403
if the user is not authorized to create event-based tasks
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

CreateEventBasedTaskResponse
a CreateEventBasedTaskResponse carrying the ID of the created task.
Properties
taskID
number
the task identifier for the created task.

Example Request

POST /tasks/event-based
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "CreateEventBasedTaskRequest": {
    "task": {
      "id": 12345,
      "name": "...",
      "type": "agent-initiated-activation",
      "enabled": true,
      "conditions": [ {
        "field": "tag",
        "key": "...",
        "value": "..."
      }, {
        "field": "applianceProtectionAvailable",
        "key": "...",
        "value": "..."
      } ],
      "actions": [ {
        "type": "assign-policy",
        "parameterValue": 12345
      }, {
        "type": "deactivate",
        "parameterValue": 12345
      } ]
    }
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "CreateEventBasedTaskResponse": {
    "taskID": 12345
  }
}
                    
                  

Delete an event-based task

Delete an event-based task.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

id
integer
the task ID.

Response Codes

200
if the request is successful
403
if the user is not authorized to delete event-based tasks
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Example Request

DELETE /tasks/event-based/{id}
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
                  

Host groups

Interface for the Host Group API.

List entire tree

List the entire host group tree

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Response Codes

200
if the request is successful
403
if the user is not authorized to view host groups
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ListHostGroupsResponse
a ListHostGroupsResponse with the host group details.
Properties
hostGroups
HostGroup
the list of host group details.
Properties
children
the host group's children
id
number
the host group ID.
name
string
the host group name.
type
string
the host group type.

Example Request

GET /host-groups
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ListHostGroupsResponse": {
    "hostGroups": [ {
      "children": [ { }, { } ],
      "id": 12345,
      "name": "...",
      "type": "..."
    }, {
      "children": [ { }, { } ],
      "id": 12345,
      "name": "...",
      "type": "..."
    } ]
  }
}
                    
                  

Host settings - scanner

Interface for host scanner settings.

Reset host settings - scanner

Delete any host-level scanner setting overrides on a host.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

hostID
integer
the host ID.

Response Codes

204
if the request is successful
403
if the user is authorized to view the host but is not authorized to modify settings
404
if the host does not exist or the user is not authorized to access the host
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Example Request

DELETE /hosts/{hostID}/scanner/settings
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 204 No Content
                  

Describe host settings - scanner

Describe the scanner settings on a host.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

hostID
integer
the host ID.

Query Parameters

overrides
boolean
the flag to see overrides attributes.

Response Codes

200
if the request is successful
403
if the user is authorized to view the host but is not authorized to view settings
404
if the host does not exist or the user is not authorized to view the host
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

DescribeHostScannerSettingsResponse
a DescribeHostScannerSettingsResponse with the setting details.
Properties
sap
SAP
the SAP details.
Properties
state
State
the SAP status ID.

If this value is set to on, then get the SAP function "On" on the host. If this value is set to off, then get the SAP function "Off" on the host. If this value is set to inherited, then get the SAP function "Inherited" on the host.

Values
inherited
Scanner SAP state inherited from policy or as default value.
on
Scanner SAP state on
off
Scanner SAP state off
description
string
the description

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

Example Request

GET /hosts/{hostID}/scanner/settings?overrides={overrides}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "DescribeHostScannerSettingsResponse": {
    "sap": {
      "state": "inherited",
      "description": "..."
    }
  }
}
                    
                  

Modify host settings - scanner

Modify the scanner settings on a host.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

hostID
integer
the host ID.

Request Body

ModifyHostScannerSettingsRequest
the updated scanner settings for the host. If a setting value is unspecified or null, the current setting value is not changed.
Properties
sap
the SAP details.

Response Codes

200
if the request is successful
400
if the request parameter is invalid
403
if the user is authorized to view the host but is not authorized to modify settings
404
if the host does not exist or the user is not authorized to access the host
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ModifyHostScannerSettingsResponse
a ModifyHostScannerSettingsResponse with the new setting details.
Properties
sap
the SAP details.

Example Request

POST /hosts/{hostID}/scanner/settings
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "ModifyHostScannerSettingsRequest": {
    "sap": {
      "state": "on",
      "description": "..."
    }
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ModifyHostScannerSettingsResponse": {
    "sap": {
      "state": "off",
      "description": "..."
    }
  }
}
                    
                  

IHostSettingsAPI

DELETE /hosts/{hostID}/antimalware/settings

Delete host-level antimalware setting already defined in antimalware settings overrides on a host.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

hostID
integer
the host ID.

Response Codes

204
if the request is successful
403
if the user is authorized to view the host but is not authorized to modify settings
404
if the host does not exist or the user is not authorized to access the host
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Example Request

DELETE /hosts/{hostID}/antimalware/settings
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 204 No Content
                  

GET /hosts/{hostID}/antimalware/settings

Describe the antimalware settings on a host.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

hostID
integer
the host ID.

Query Parameters

overrides
boolean
the flag to see overrides attributes.

Response Codes

200
if the request is successful
403
if the user is authorized to view the host but is not authorized to view settings
404
if the host does not exist or the user is not authorized to view the host
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

DescribeAntiMalwareSettingsResponse
a DescribeAntiMalwareSettingsResponse with the setting details.
Properties
settings
AntiMalwareSettings
-
Properties
predictiveMachineLearningExceptions
string
-

Example Request

GET /hosts/{hostID}/antimalware/settings?overrides={overrides}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "DescribeAntimalwareSettingsResponse": {
    "settings": {
      "predictiveMachineLearningExceptions": [ "...", "..." ]
    }
  }
}
                    
                  

POST /hosts/{hostID}/antimalware/settings

Modify the antimalware settings on a host.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

hostID
integer
the host ID.

Request Body

ModifyAntiMalwareSettingsRequest
the updated antimalware settings for the host. If a setting value is unspecified or null, the current setting value is not changed.
Properties

Response Codes

200
if the request is successful
400
if the request parameter is invalid
403
if the user is authorized to view the host but is not authorized to modify settings
404
if the host does not exist or the user is not authorized to access the host
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ModifyAntiMalwareSettingsResponse
a ModifyAntiMalwareSettingsResponse with the new setting details.
Properties

Example Request

POST /hosts/{hostID}/antimalware/settings
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "ModifyAntiMalwareSettingsRequest": {
    "settings": {
      "predictiveMachineLearningExceptions": [ "...", "..." ]
    }
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ModifyAntiMalwareSettingsResponse": {
    "settings": {
      "predictiveMachineLearningExceptions": [ "...", "..." ]
    }
  }
}
                    
                  

IPolicySettingsAPI

DELETE /policies/{policyID}/antimalware/settings

Delete any policy-level antimalware setting: AntiMalwareSettings overrides on a policy.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

policyID
integer
the policy ID.

Response Codes

204
if the request is successful
403
if the user is authorized to view the policy but is not authorized to modify settings
404
if the policy does not exist or the user is not authorized to access the policy
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Example Request

DELETE /policies/{policyID}/antimalware/settings
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 204 No Content
                  

GET /policies/{policyID}/antimalware/settings

Describe the antimalware settings on a policy.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

policyID
integer
the policy ID.

Query Parameters

overrides
boolean
the flag to see overrides attributes.

Response Codes

200
if the request is successful
403
if the user is authorized to view the policy but is not authorized to view settings
404
if the policy does not exist or the user is not authorized to view the policy
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

a DescribeAntiMalwareSettingsResponse with the setting details.

Example Request

GET /policies/{policyID}/antimalware/settings?overrides={overrides}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "DescribeAntimalwareSettingsResponse": {
    "settings": {
      "predictiveMachineLearningExceptions": [ "...", "..." ]
    }
  }
}
                    
                  

POST /policies/{policyID}/antimalware/settings

Modify the antimalware settings on a policy.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

policyID
integer
the policy ID.

Request Body

the updated antimalware settings for the policy. If a setting value is unspecified or null, the current setting value is not changed.

Response Codes

200
if the request is successful
400
if the request parameter is invalid
403
if the user is authorized to view the policy but is not authorized to modify settings
404
if the policy does not exist or the user is not authorized to access the policy
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

a ModifyAntiMalwareSettingsResponse with the new setting details.

Example Request

POST /policies/{policyID}/antimalware/settings
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "ModifyAntiMalwareSettingsRequest": {
    "settings": {
      "predictiveMachineLearningExceptions": [ "...", "..." ]
    }
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ModifyAntiMalwareSettingsResponse": {
    "settings": {
      "predictiveMachineLearningExceptions": [ "...", "..." ]
    }
  }
}
                    
                  

Instance rates

Applies to Deep Security as a Service only

List instance rates

Applies to Deep Security as a Service only

Retrieve a list of instance rate data

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Response Codes

200
if the request is successful
403
if the user is not authorized to view instance rate data
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ListInstanceRatesResponse
a list of instance rate data
Properties
instanceRates
InstanceRateData
-
Properties
instanceName
string
-
rate
number
-

Example Request

GET /monitoring/usages/hosts/instancerates
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ListInstanceRatesResponse": {
    "instanceRates": [ {
      "instanceName": "...",
      "rate": 12345.0
    }, {
      "instanceName": "...",
      "rate": 12345.0
    } ]
  }
}
                    
                  

Integrity monitoring events

Interface for integrity monitoring events.

List integrity monitoring events

Get Integrity events. Users can assign filters when querying events from DSM. The following are some notable behaviors that how DSM reacts:

DSM only accepts proper operator/operand pairs.
When only both an operator and an operand are properly assigned, DSM accepts the filter -- otherwise DSM ignores these improper parameters. Examples:

     eventID=100&eventIDOp='gt' -> a valid filter
     eventID=100 -> an invalid filter. DSM ignores it.
     eventIDOp='le' -> an invalid filter. DSM ignores it.
 

The output events are always sorted by ID in ascending.
DSM outputs results by counting the events from the smallest ID to the larger ID until the number of output events meets the maxItems; for instance, if DSM receives a request with either 'lt' or 'le' operator, firstly the API filter events by the filter, secondly it sorts the results by ID in ascending, and finally the API outputs events from the smallest ID until the number of output events meets the maxItems

In the database, the ordering of ID is not equal to the ordering of LogDate.
Sometimes DSM receives older events (e.g. yesterday's events), however, these older events' IDs are larger than newer events' IDs. When querying events by only time filter with 'ge' operator, DSM returns desired events and the corresponding lastEventID. However, it doesn't mean that in the database, all events whose ID larger than the lastEventID are older than the time filter in the query.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Query Parameters

eventID
integer
the event ID to query for events. Combined with eventIDOp, the returning events can be filtered according to the ID.
eventIDOp
string
defined the events to return. Currently supported operations include gt(greater than), ge(greater than or equal to), eq(eqaul to), lt(less than), and le(less than or equal to). If an unsupported operator is provided, the default is 'eq'.
eventTime
integer
the event time to query for events. It is represented by a long integer, which is the milliseconds since January 1, 1970, 00:00:00 GMT. Combined with eventTimeOp, the returning events can be filtered by the specific milliseconds. Please be aware that for integrity events, the accuracy of event time is millisecond. In other words, if you want to exactly filter events by event time, the eventTime value must be millisecond accuracy.
eventTimeOp
string
defined the events to return. Currently supported operations include gt(greater than), ge(greater than or equal to), eq(eqaul to), lt(less than), and le(less than or equal to). If an unsupported operator is provided, the default is 'eq'.
extendedDesc
boolean
provide more information about the affected entities and related attributes (default is "false")
maxItems
integer
the maximum events to response. The minimum valid value is 1.

Response Codes

200
if the request is successful
400
if the request is invalid
403
if the user is not authorized to view integrity events
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ListEventsResponse
ListEventsResponse, a collection of the events meet the given criteria.
Properties
lastEventID
number
the last event ID.

This will be 0 if no events are retrieved.

events
Event
the list of events.
Properties
eventID
number
the integrityEventID value for this IntegrityEvent
change
string
the change value from this IntegrityEvent.
description
string
the description value from this IntegrityEvent.
hostID
number
the hostID value from this IntegrityEvent.
hostName
string
the hostName value from this IntegrityEvent.
isEntity
Entity
the Entity value from this IntegrityEvent. The isEntity stores an entity's attributes after the integrity scan.
Properties
key
string
the key value from this Entity
type
string
the type value from this Entity
attribute
Attribute
the type value from this Entity
Properties
friendlyValue
string
the friendlyValue value from this Attribute.
name
string
the name value from this Attribute.
value
string
the value from this Attribute.
wasEntity
the Entity value from this IntegrityEvent. The wasEntity stores an entity's attributes before the integrity scan.
key
string
the key value from this IntegrityEvent.
process
string
the process value from this IntegrityEvent.
rank
number
the rank value from this IntegrityEvent.
reason
string
the reason value from this IntegrityEvent.
severity
IntegrityRuleSeverity
the Severity value from this IntegrityEvent.
Values
critical
high
medium
low
default
integrityRuleID
number
the integrityRuleID value from this IntegrityEvent.
type
string
the type value from this IntegrityEvent.
user
string
the user value from this IntegrityEvent.
tags
string
the tags associated with the event.

The tags will be returned in a comma-and-whitespace-separated list. For example, if an event has been tagged with tag1 and tag2, then the returned string will be tag1, tag2.

logTime
number
the time at which the event was recorded.
moreEvents
boolean
the indicator that there are more events available.

Example Request

GET /events/integrity?eventID={eventID}&eventIDOp={eventIDOp}&eventTime={eventTime}&eventTimeOp={eventTimeOp}&extendedDesc={extendedDesc}&maxItems={maxItems}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "##default": {
    "lastEventID": 12345,
    "events": [ {
      "eventID": 12345,
      "change": "...",
      "description": "...",
      "hostID": 12345,
      "hostName": "...",
      "isEntity": {
        "key": "...",
        "type": "...",
        "attribute": [ { }, { } ]
      },
      "wasEntity": {
        "key": "...",
        "type": "...",
        "attribute": [ { }, { } ]
      },
      "key": "...",
      "process": "...",
      "rank": 12345,
      "reason": "...",
      "severity": "medium",
      "integrityRuleID": 12345,
      "type": "...",
      "user": "...",
      "tags": "...",
      "logTime": 12345
    }, {
      "eventID": 12345,
      "change": "...",
      "description": "...",
      "hostID": 12345,
      "hostName": "...",
      "isEntity": {
        "key": "...",
        "type": "...",
        "attribute": [ { }, { } ]
      },
      "wasEntity": {
        "key": "...",
        "type": "...",
        "attribute": [ { }, { } ]
      },
      "key": "...",
      "process": "...",
      "rank": 12345,
      "reason": "...",
      "severity": "medium",
      "integrityRuleID": 12345,
      "type": "...",
      "user": "...",
      "tags": "...",
      "logTime": 12345
    } ],
    "moreEvents": true
  }
}
                    
                  

Describe an integrity monitoring event

Get the Integrity event with the specified event ID.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

eventID
integer
the ID of the event to fetch.

Query Parameters

extendedDesc
boolean
provide more information about the affected entities and related attributes (default is "false")

Response Codes

200
if the request is successful
403
if the user is not authorized to view integrity events
404
if the integrity event does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

DescribeEventResponse
a DescribeEventResponse containing the event with the specific ID
Properties
event
the event details.

Example Request

GET /events/integrity/{eventID}?extendedDesc={extendedDesc}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "##default": {
    "event": {
      "eventID": 12345,
      "change": "...",
      "description": "...",
      "hostID": 12345,
      "hostName": "...",
      "isEntity": {
        "key": "...",
        "type": "...",
        "attribute": [ { }, { } ]
      },
      "wasEntity": {
        "key": "...",
        "type": "...",
        "attribute": [ { }, { } ]
      },
      "key": "...",
      "process": "...",
      "rank": 12345,
      "reason": "...",
      "severity": "low",
      "integrityRuleID": 12345,
      "type": "...",
      "user": "...",
      "tags": "...",
      "logTime": 12345
    }
  }
}
                    
                  

Licenses

Interface for the licensing API.

Describe license status

Describe the license status of DSM modules. The level of detail depends on user permissions.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Response Codes

200
if the request is successful
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

DescribeLicenseStatusResponse
a DescribeLicenseStatusResponse with license status information for all protection modules
Properties
modules
LicenseInfo
map of all modules to their license status.
Properties
licensed
boolean
the license status.
licenseStatus
string
the detailed license status.
licenseType
string
the license type.
activationCode
string
the activation code.
expiryDate
number
the expiration date in milliseconds since epoch
graceDate
number
the grace date in milliseconds since epoch

Example Request

GET /license
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "DescribeLicenseStatusResponse": {
    "modules": {
      "property1": {
        "licensed": true,
        "licenseStatus": "...",
        "licenseType": "...",
        "activationCode": "...",
        "expiryDate": 12345,
        "graceDate": 12345
      },
      "property2": {
        "licensed": true,
        "licenseStatus": "...",
        "licenseType": "...",
        "activationCode": "...",
        "expiryDate": 12345,
        "graceDate": 12345
      }
    }
  }
}
                    
                  

Update license activation codes

Add license activation codes for DSM protection modules and optionally update license information for all stored activation codes. If any activation code is invalid or cannot be added due to error, no code is added. Does not accept multi-tenant activation codes - please use the /multitenantconfiguration API

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Query Parameters

update
boolean
(optional) true to update license information for all stored activation codes.

Request Body

UpdateLicenseActivationCodesRequest
an UpdateLicenseActivationCodesRequest containing zero or more Deep Security Manager license activation codes
Properties
activationCodes
string
the list of activation codes.

Response Codes

200
if the request is successful
403
if the user is not authorized to change license information
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

a DescribeLicenseStatusResponse with DSM module license status

Example Request

POST /license?update={update}
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "UpdateLicenseActivationCodesRequest": {
    "activationCodes": [ "...", "..." ]
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "DescribeLicenseStatusResponse": {
    "modules": {
      "property1": {
        "licensed": true,
        "licenseStatus": "...",
        "licenseType": "...",
        "activationCode": "...",
        "expiryDate": 12345,
        "graceDate": 12345
      },
      "property2": {
        "licensed": true,
        "licenseStatus": "...",
        "licenseType": "...",
        "activationCode": "...",
        "expiryDate": 12345,
        "graceDate": 12345
      }
    }
  }
}
                    
                  

Log inspection events

Log inspection events API.

List log inspection events

Get log inspection events. Users can assign filters when querying events from DSM. The following are some notable behaviors that how DSM reacts:

DSM only accepts proper operator/operand pairs.
When only both an operator and an operand are properly assigned, DSM accepts the filter -- otherwise DSM ignores these improper parameters. Examples:

     eventID=100&eventIDOp='gt' -> a valid filter
     eventID=100 -> an invalid filter. DSM ignores it.
     eventIDOp='le' -> an invalid filter. DSM ignores it.
 

The output events are always sorted by ID in ascending.
DSM outputs results by counting the events from the smallest ID to the larger ID until the number of output events meets the maxItems; for instance, if DSM receives a request with either 'lt' or 'le' operator, firstly the API filter events by the filter, secondly it sorts the results by ID in ascending, and finally the API outputs events from the smallest ID until the number of output events meets the maxItems

In the database, the ordering of ID is not equal to the ordering of LogDate.
Sometimes DSM receives older events (e.g. yesterday's events), however, these older events' IDs are larger than newer events' IDs. When querying events by only time filter with 'ge' operator, DSM returns desired events and the corresponding lastEventID. However, it doesn't mean that in the database, all events whose ID larger than the lastEventID are older than the time filter in the query.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Query Parameters

eventID
integer
the event ID to query for events. Combined with eventIDOp, the returning events can be filtered according to the ID.
eventIDOp
string
defined the events to return. Currently supported operations include gt(greater than), ge(greater than or equal to), eq(eqaul to), lt(less than), and le(less than or equal to). If an unsupported operator is provided, the default is 'eq'.
eventTime
integer
the event time to query for events. It is represented by a long integer, which is the milliseconds since January 1, 1970, 00:00:00 GMT. Combined with eventTimeOp, the returning events can be filtered by the specific milliseconds. Please be aware that for log inspection events, the accuracy of event time is second, which means that the millisecond part of events' time in the database are always 000.
eventTimeOp
string
defined the events to return. Currently supported operations include gt(greater than), ge(greater than or equal to), eq(eqaul to), lt(less than), and le(less than or equal to). If an unsupported operator is provided, the default is 'eq'.
maxItems
integer
the maximum events to response. The valid minimum value is 1.

Response Codes

200
if the request is successful
403
if the user is not authorized to view log inspection events
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ListEventsResponse
an ListEventsResponse, a collection of the events meet the given criteria.
Properties
lastEventID
number
the last event ID.

This will be 0 if no events are retrieved.

events
Event
the list of events.
Properties
eventID
number
the LogInspectionEventID (unique key)
hostID
number
the hostID value from this LogInspectionEvent.
hostName
string
the hostName value from this LogInspectionEvent.
logTime
number
the time at which the event was recorded.
rank
number
the rank value from this LogInspectionEvent.
reason
string
the reason value from this LogInspectionEvent.
description
string
the description value from this LogInspectionEvent.
logInspectionRuleID
number
the logInspectionRuleID value from this LogInspectionEvent.
ruleID
number
the ruleID value from this LogInspectionEvent.
severity
string
the severity value from this LogInspectionEvent.
groups
string
the groups value from this LogInspectionEvent.
sourceHostName
string
the sourceHostName value from this LogInspectionEvent.
programName
string
the programName value from this LogInspectionEvent.
message
string
the message value from this LogInspectionEvent.
location
string
the location value from this LogInspectionEvent.
sourceIP
string
the sourceIP value from this LogInspectionEvent.
sourcePort
string
the sourceUser value from this LogInspectionEvent.
destinationIP
string
the destinationIP value from this LogInspectionEvent.
destinationPort
string
the destinationPort value from this LogInspectionEvent.
protocol
string
the protocol value from this LogInspectionEvent.
action
string
the action value from this LogInspectionEvent.
sourceUser
string
the sourceUser value from this LogInspectionEvent.
destinationUser
string
the destinationUser value from this LogInspectionEvent.
sourceID
string
the sourceID value from this LogInspectionEvent.
status
string
the status value from this LogInspectionEvent.
command
string
the command value from this LogInspectionEvent.
url
string
the url value from this LogInspectionEvent.
data
string
the data value from this LogInspectionEvent.
systemName
string
the systemName value from this LogInspectionEvent.
fullEvent
string
the fullEvent value from this LogInspectionEvent.
tags
string
the tags associated with the event.

The tags will be returned in a comma-and-whitespace-separated list. For example, if an event has been tagged with tag1 and tag2, then the returned string will be tag1, tag2.

moreEvents
boolean
the indicator that there are more events available.

Example Request

GET /events/logInspection?eventID={eventID}&eventIDOp={eventIDOp}&eventTime={eventTime}&eventTimeOp={eventTimeOp}&maxItems={maxItems}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "##default": {
    "lastEventID": 12345,
    "events": [ {
      "eventID": 12345,
      "hostID": 12345,
      "hostName": "...",
      "logTime": 12345,
      "rank": 12345,
      "reason": "...",
      "description": "...",
      "logInspectionRuleID": 12345,
      "ruleID": 12345,
      "severity": "...",
      "groups": "...",
      "sourceHostName": "...",
      "programName": "...",
      "message": "...",
      "location": "...",
      "sourceIP": "...",
      "sourcePort": "...",
      "destinationIP": "...",
      "destinationPort": "...",
      "protocol": "...",
      "action": "...",
      "sourceUser": "...",
      "destinationUser": "...",
      "sourceID": "...",
      "status": "...",
      "command": "...",
      "url": "...",
      "data": "...",
      "systemName": "...",
      "fullEvent": "...",
      "tags": "..."
    }, {
      "eventID": 12345,
      "hostID": 12345,
      "hostName": "...",
      "logTime": 12345,
      "rank": 12345,
      "reason": "...",
      "description": "...",
      "logInspectionRuleID": 12345,
      "ruleID": 12345,
      "severity": "...",
      "groups": "...",
      "sourceHostName": "...",
      "programName": "...",
      "message": "...",
      "location": "...",
      "sourceIP": "...",
      "sourcePort": "...",
      "destinationIP": "...",
      "destinationPort": "...",
      "protocol": "...",
      "action": "...",
      "sourceUser": "...",
      "destinationUser": "...",
      "sourceID": "...",
      "status": "...",
      "command": "...",
      "url": "...",
      "data": "...",
      "systemName": "...",
      "fullEvent": "...",
      "tags": "..."
    } ],
    "moreEvents": true
  }
}
                    
                  

Describe a log inspection event

Get the Log Inspection event with the specified event ID.

Cookie Parameters

sID
string
a session ID returned by the {@linkplain IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

eventID
integer
the ID of the event to fetch.

Response Codes

200
if the request is successful
403
if the user is not authorized to view log inspection events
404
if the log inspection event does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

DescribeEventResponse
a DescribeEventResponse containing the event with the specific ID
Properties
event
the event details.

Example Request

GET /events/logInspection/{eventID}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "##default": {
    "event": {
      "eventID": 12345,
      "hostID": 12345,
      "hostName": "...",
      "logTime": 12345,
      "rank": 12345,
      "reason": "...",
      "description": "...",
      "logInspectionRuleID": 12345,
      "ruleID": 12345,
      "severity": "...",
      "groups": "...",
      "sourceHostName": "...",
      "programName": "...",
      "message": "...",
      "location": "...",
      "sourceIP": "...",
      "sourcePort": "...",
      "destinationIP": "...",
      "destinationPort": "...",
      "protocol": "...",
      "action": "...",
      "sourceUser": "...",
      "destinationUser": "...",
      "sourceID": "...",
      "status": "...",
      "command": "...",
      "url": "...",
      "data": "...",
      "systemName": "...",
      "fullEvent": "...",
      "tags": "..."
    }
  }
}
                    
                  

Manager nodes

Does not apply to Deep Security as a Service

Primary tenant only

Interface to the manager node API.

List manager nodes

Does not apply to Deep Security as a Service

Primary tenant only

List manager nodes.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Query Parameters

id
integer
(optional) used to define the starting point for the query. Combine with op to page through results.
maxItems
integer
(optional) the number of items to retrieve. The maximum value for this parameter is controlled by the "Maximum number of items to retrieve from database" setting on the administrator account, which defaults to 5000.
op
string
(optional, required if id is specified) Currently supported operations are:
  • gt (greater than)
  • ge (greater than or equal to)
  • eq (equal to)
  • lt (less than)
  • le (less than or equal to)

Response Codes

200
if the request is successful
403
if the user is not authorized to view manager nodes
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ListManagerNodesResponse
a ListManagerNodesResponse with the manager node details.
Properties
managerNodes
ManagerNode
the list of manager node details.
Properties
id
number
the manager node ID.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

name
string
the manager node name.
description
string
the manager node description.
guid
string
the manager node GUID.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

sslThumbprint
string
the manager node SSL thumbprint.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

default
boolean
the flag indicating whether this manager node should be treated as the default manager node for contact.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

location
Location
the manager node location information.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

Properties
hostname
string
the manager node hostname.

This may not be the actual machine hostname on the manager node; it is the name used for the manager node in the database.

lastIPUsed
string
the last IP address used for the manager node.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

alternateURL
string
the alternate URL for accessing the manager node, if any.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

managerPort
number
the TCP (HTTPS) port where the manager node is listening for console requests.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

heartbeatPort
number
the TCP port where the manager node is listening for heartbeat requests.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

jobs
Jobs
the manager node job assignment information.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

Properties
assignTenants
boolean
the flag indicating whether tenant jobs should be allowed to run on this manager node.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

exclude
string
the list of job types to exclude from this manager node.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

include
string
the list of job types to include on this manager node.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

systemInformation
SystemInformation
the manager node system information.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

Properties
javaVersion
string
the version of the Java runtime environment that is in use on this manager node.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

installDirectory
string
the directory in which the Deep Security Manager software has been installed on this manager node.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

systemArchitecture
string
the system architecture of this manager node.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

platform
string
the operating system name and version for this manager node.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

processors
number
the number of processors reported by the system for this manager node.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

databaseTimeSkew
number
the time skew between this manager node and the database, in milliseconds.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

memory
Memory
information about the memory used by the manager node.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

Properties
free
number
the amount of free memory reported by this manager node, in bytes.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

used
number
the amount of used memory reported by this manager node, in bytes.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

max
number
the amount of memory allocated to this manager node process, in bytes.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

disks
Disk
information about the disks used by the manager node.

At this time, the information reported is only for the device where the manager node software is installed.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

Properties
free
number
the amount of free disk space reported for this device, in kilobytes.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

percentFree
number
the percentage of free disk space reported for this device.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

device
string
the disk identifier as reported by the system.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

timestamps
Timestamps
the manager node lifecycle timestamps information.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

Properties
created
number
the time when this manager node was created, as the number of milliseconds since January 1, 1970, 00:00:00 GMT.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

started
number
the time when this manager node was started, as the number of milliseconds since January 1, 1970, 00:00:00 GMT.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

lastActivity
number
the time when this manager node last reported activity, as the number of milliseconds since January 1, 1970, 00:00:00 GMT.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

shutdown
number
the time when this manager node was shut down, as the number of milliseconds since January 1, 1970, 00:00:00 GMT.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

shutdownBy
number
the manager node ID that initiated the shutdown of this node.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

status
Status
the manager node status information.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

Properties
requiresRestart
boolean
the flag indicating whether this manager node needs to be restarted.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

heartbeatServiceAlert
boolean
the flag indicating whether the heartbeat service on this manager node has failed.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

gridConnectionAlert
boolean
the flag indicating whether this manager node has encountered problems connecting to the Trend Micro GRID service.

The Trend Micro GRID (Goodware Resource and Information Database) is a database of known-good files and binaries.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

databaseQueryBenchmark
number
the database round-trip time, in nanoseconds.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

online
boolean
the flag indicating whether the manager node is online.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

performanceProfileID
number
the manager node's performance profile ID.
version
string
the version of Deep Security Manager software running on the manager node.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

onlineHelpVersion
string
the version of Deep Security Manager online help available on the manager node.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

Example Request

GET /manager-nodes?id={id}&maxItems={maxItems}&op={op}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ListManagerNodesResponse": {
    "managerNodes": [ {
      "id": 12345,
      "name": "...",
      "description": "...",
      "guid": "...",
      "sslThumbprint": "...",
      "default": true,
      "location": {
        "hostname": "...",
        "lastIPUsed": "...",
        "alternateURL": "...",
        "managerPort": 12345,
        "heartbeatPort": 12345
      },
      "jobs": {
        "assignTenants": true,
        "exclude": [ "...", "..." ],
        "include": [ "...", "..." ]
      },
      "systemInformation": {
        "javaVersion": "...",
        "installDirectory": "...",
        "systemArchitecture": "...",
        "platform": "...",
        "processors": 12345,
        "databaseTimeSkew": 12345,
        "memory": { },
        "disks": [ { }, { } ]
      },
      "timestamps": {
        "created": 12345,
        "started": 12345,
        "lastActivity": 12345,
        "shutdown": 12345,
        "shutdownBy": 12345
      },
      "status": {
        "requiresRestart": true,
        "heartbeatServiceAlert": true,
        "gridConnectionAlert": true,
        "databaseQueryBenchmark": 12345,
        "online": true
      },
      "performanceProfileID": 12345,
      "version": "...",
      "onlineHelpVersion": "..."
    }, {
      "id": 12345,
      "name": "...",
      "description": "...",
      "guid": "...",
      "sslThumbprint": "...",
      "default": true,
      "location": {
        "hostname": "...",
        "lastIPUsed": "...",
        "alternateURL": "...",
        "managerPort": 12345,
        "heartbeatPort": 12345
      },
      "jobs": {
        "assignTenants": true,
        "exclude": [ "...", "..." ],
        "include": [ "...", "..." ]
      },
      "systemInformation": {
        "javaVersion": "...",
        "installDirectory": "...",
        "systemArchitecture": "...",
        "platform": "...",
        "processors": 12345,
        "databaseTimeSkew": 12345,
        "memory": { },
        "disks": [ { }, { } ]
      },
      "timestamps": {
        "created": 12345,
        "started": 12345,
        "lastActivity": 12345,
        "shutdown": 12345,
        "shutdownBy": 12345
      },
      "status": {
        "requiresRestart": true,
        "heartbeatServiceAlert": true,
        "gridConnectionAlert": true,
        "databaseQueryBenchmark": 12345,
        "online": true
      },
      "performanceProfileID": 12345,
      "version": "...",
      "onlineHelpVersion": "..."
    } ]
  }
}
                    
                  

Delete a manager node

Does not apply to Deep Security as a Service

Primary tenant only

Delete a manager node.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

managerNodeID
integer
the manager node ID.

Response Codes

200
if the request is successful
403
if the user is not authorized to delete manager nodes
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Example Request

DELETE /manager-nodes/{managerNodeID}
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
                  

Describe a manager node

Does not apply to Deep Security as a Service

Primary tenant only

Describe a manager node.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

managerNodeID
integer
the manager node ID.

Response Codes

200
if the request is successful
403
if the user is not authorized to view manager nodes
404
if the user is authorized to view manager nodes but the manager node does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

DescribeManagerNodeResponse
a DescribeManagerNodeResponse with the manager node details.
Properties
managerNode
the manager node details.

Example Request

GET /manager-nodes/{managerNodeID}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "DescribeManagerNodeResponse": {
    "managerNode": {
      "id": 12345,
      "name": "...",
      "description": "...",
      "guid": "...",
      "sslThumbprint": "...",
      "default": true,
      "location": {
        "hostname": "...",
        "lastIPUsed": "...",
        "alternateURL": "...",
        "managerPort": 12345,
        "heartbeatPort": 12345
      },
      "jobs": {
        "assignTenants": true,
        "exclude": [ "...", "..." ],
        "include": [ "...", "..." ]
      },
      "systemInformation": {
        "javaVersion": "...",
        "installDirectory": "...",
        "systemArchitecture": "...",
        "platform": "...",
        "processors": 12345,
        "databaseTimeSkew": 12345,
        "memory": { },
        "disks": [ { }, { } ]
      },
      "timestamps": {
        "created": 12345,
        "started": 12345,
        "lastActivity": 12345,
        "shutdown": 12345,
        "shutdownBy": 12345
      },
      "status": {
        "requiresRestart": true,
        "heartbeatServiceAlert": true,
        "gridConnectionAlert": true,
        "databaseQueryBenchmark": 12345,
        "online": true
      },
      "performanceProfileID": 12345,
      "version": "...",
      "onlineHelpVersion": "..."
    }
  }
}
                    
                  

Modify a manager node

Does not apply to Deep Security as a Service

Primary tenant only

Modify a manager node.

Any unset elements in the request object will be left unchanged by the modify request.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

managerNodeID
integer
the manager node ID.

Request Body

ModifyManagerNodeRequest
a ModifyManagerNodeRequest with the details of the manager node.
Properties
managerNode
the manager node details.

Response Codes

200
if the request is successful
403
if the user is not authorized to modify manager nodes or if the requested modification is not permitted
404
if the user is authorized to modify manager nodes but the manager node does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ModifyManagerNodeResponse
an ModifyManagerNodeResponse with the updated manager node details.
Properties
managerNode
the manager node details.

Example Request

POST /manager-nodes/{managerNodeID}
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "ModifyManagerNodeRequest": {
    "managerNode": {
      "id": 12345,
      "name": "...",
      "description": "...",
      "guid": "...",
      "sslThumbprint": "...",
      "default": true,
      "location": {
        "hostname": "...",
        "lastIPUsed": "...",
        "alternateURL": "...",
        "managerPort": 12345,
        "heartbeatPort": 12345
      },
      "jobs": {
        "assignTenants": true,
        "exclude": [ "...", "..." ],
        "include": [ "...", "..." ]
      },
      "systemInformation": {
        "javaVersion": "...",
        "installDirectory": "...",
        "systemArchitecture": "...",
        "platform": "...",
        "processors": 12345,
        "databaseTimeSkew": 12345,
        "memory": { },
        "disks": [ { }, { } ]
      },
      "timestamps": {
        "created": 12345,
        "started": 12345,
        "lastActivity": 12345,
        "shutdown": 12345,
        "shutdownBy": 12345
      },
      "status": {
        "requiresRestart": true,
        "heartbeatServiceAlert": true,
        "gridConnectionAlert": true,
        "databaseQueryBenchmark": 12345,
        "online": true
      },
      "performanceProfileID": 12345,
      "version": "...",
      "onlineHelpVersion": "..."
    }
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ModifyManagerNodeResponse": {
    "managerNode": {
      "id": 12345,
      "name": "...",
      "description": "...",
      "guid": "...",
      "sslThumbprint": "...",
      "default": true,
      "location": {
        "hostname": "...",
        "lastIPUsed": "...",
        "alternateURL": "...",
        "managerPort": 12345,
        "heartbeatPort": 12345
      },
      "jobs": {
        "assignTenants": true,
        "exclude": [ "...", "..." ],
        "include": [ "...", "..." ]
      },
      "systemInformation": {
        "javaVersion": "...",
        "installDirectory": "...",
        "systemArchitecture": "...",
        "platform": "...",
        "processors": 12345,
        "databaseTimeSkew": 12345,
        "memory": { },
        "disks": [ { }, { } ]
      },
      "timestamps": {
        "created": 12345,
        "started": 12345,
        "lastActivity": 12345,
        "shutdown": 12345,
        "shutdownBy": 12345
      },
      "status": {
        "requiresRestart": true,
        "heartbeatServiceAlert": true,
        "gridConnectionAlert": true,
        "databaseQueryBenchmark": 12345,
        "online": true
      },
      "performanceProfileID": 12345,
      "version": "...",
      "onlineHelpVersion": "..."
    }
  }
}
                    
                  

Multi-tenant configuration

Does not apply to Deep Security as a Service

Primary tenant only

Interface for the Multi Tenant Configuration API.

Configure settings

Does not apply to Deep Security as a Service

Primary tenant only

Configuration of DSM Multi Tenant settings.

Query Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Response Body

MultiTenantConfigurationElement
The information about the multi tenant configuration.
Properties
activationCode
string
Activation code to be used to enable multi-tenancy; only used when enabling multi-tenancy for the first time.
configurationType
string
The multi-tenancy configuration type; supported types are: ENTERPRISE, NONE (only as a returned value before multi-tenancy is configured)
licenseModeType
string
License mode; supported choices are: PER_TENANT, PRIMARY_TENANT_INHERITANCE, NONE (only as a returned value before multi-tenancy is configured)

Example Request

GET /multitenantconfiguration?sID={sID}
Accept: application/json
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "multiTenantConfiguration": {
    "activationCode": "...",
    "configurationType": "...",
    "licenseModeType": "..."
  }
}
                    
                  

Modify configuration

Does not apply to Deep Security as a Service

Primary tenant only

Set the multi-tenant configuration.

Request Body

UpdateMultiTenantConfigurationRequest
The request parameters
Properties
multiTenantConfigurationElement
The multi-tenant configuration.

Response Body

UpdateMultiTenantConfigurationResponse
a response with status 200 OK and a body containing response information when the configuration was successful. It will return a response with status 400 Bad Request and a body containing an ErrorMessage when mandatory parameters are missing and/or validation fails.

Example Request

PUT /multitenantconfiguration
Content-Type: application/json
Accept: application/json
                    
{
  "updateMultiTenantConfigurationRequest": {
    "multiTenantConfigurationElement": {
      "activationCode": "...",
      "configurationType": "...",
      "licenseModeType": "..."
    },
    "sessionId": "..."
  }
}
                    
                  

Example Response

HTTP/1.1 204 No Content
Content-Type: application/json
                    
{
  "updateMultiTenantConfigurationResponse": { }
}
                    
                  

News feed

Management API for News Feed.

Describe the news feed

Get metadata about the news feed.

Cookie Parameters

sID
string
A session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API

Query Parameters

background
boolean
(optional) If true, does not extends the session. Default false.

Response Codes

200
if the request is successful
403
if the user is not authenticated
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

DescribeNewsFeedResponse
a DescribeNewsFeedResponse containing metadata from the news feed
Properties
hasCriticalEntry
boolean
if the news feed have a critical entry.
hasCommunicationError
boolean
the flag saying there is an error communicating with the news feed.
newEntries
number
the number of new (not viewed) news entries.

Example Request

GET /newsfeed?background={background}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "DescribeNewsFeedResponse": {
    "hasCriticalEntry": true,
    "hasCommunicationError": true,
    "newEntries": 12345
  }
}
                    
                  

List news feed entries

List news feed entries.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API

Query Parameters

all
boolean
true to get all news entries, false to get only non-dismissed entries.
entryID
integer
(optional) used to define the starting point for the query. Combine with entryIDOp to page through results.
entryIDOp
string
(optional), required if entryID is specified) Currently supported operations are:
  • gt(greater than)
  • ge(greater than or equal to)
  • eq(equal to)
  • lt(less than)
  • le(less than or equal to)
maxItems
integer
(optional) the number of items to retrieve. The maximum value for this parameter is controlled by the "Maximum number of items to retrieve from database" setting on the administrator account, which defaults to 5000.

Response Codes

200
if the request is successful
403
if the user is not authenticated
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ListNewsEntriesResponse
a ListNewsEntriesResponse containing the list of News Entries
Properties
newsEntries
NewsEntry
the list of news entries.
Properties
entryID
number
the id of the news feed entry.
title
string
the title of the news feed entry.
content
string
the content of the news feed entry.
link
string
the link of the news feed entry.
linkText
string
the text to be displayed with the link.
viewed
boolean
the indication if the current user has seen the news entry.
dismissed
boolean
the indication if the current user has dismissed the news entry.
pinned
boolean
the indication if the news entry should be pinned.
publishedDate
number
the published date of the news entry.
category
Category
the category of the news entry.
Values
critical
service
whats-new
threat-news-and-tips
unknown
hasCommunicationError
boolean
the flag saying there is an error communicating with the news feed.

Example Request

GET /newsfeed/entries?all={all}&entryID={entryID}&entryIDOp={entryIDOp}&maxItems={maxItems}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ListNewsEntriesResponse": {
    "newsEntries": [ {
      "entryID": 12345,
      "title": "...",
      "content": "...",
      "link": "...",
      "linkText": "...",
      "viewed": true,
      "dismissed": true,
      "pinned": true,
      "publishedDate": 12345,
      "category": "threat-news-and-tips"
    }, {
      "entryID": 12345,
      "title": "...",
      "content": "...",
      "link": "...",
      "linkText": "...",
      "viewed": true,
      "dismissed": true,
      "pinned": true,
      "publishedDate": 12345,
      "category": "service"
    } ],
    "hasCommunicationError": true
  }
}
                    
                  

Dismiss news feed entry

Dismiss a news feed entry.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API

Path Parameters

entryID
integer
the ID of the New Entry to be dismissed

Response Codes

204
if the request is successful
403
if the user is not authenticated
404
if the news feed entry is not found
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Example Request

DELETE /newsfeed/entries/{entryID}
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 204 No Content
                  

Performance profiles

Does not apply to Deep Security as a Service

Primary tenant only

Interface to the PerformanceProfile API.

Deep Security Manager uses an optimized concurrent job scheduler that considers the impacts of each job on CPU, database and agents or appliances. Performance profiles can be used to fine tune the job scheduler in environments where Deep Security Manager hardware resources are limited. Learn more

List performance profiles

Does not apply to Deep Security as a Service

Primary tenant only

List performance profiles.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Query Parameters

maxItems
integer
(optional) the number of items to retrieve. The maximum value for this parameter is controlled by the "Maximum number of items to retrieve from database" setting on the administrator account, which defaults to 5000.
op
string
(optional, required if performanceProfileID is specified) Currently supported operations are:
  • gt (greater than)
  • ge (greater than or equal to)
  • eq (equal to)
  • lt (less than)
  • le (less than or equal to)
performanceProfileID
integer
(optional) used to define the starting point for the query. Combine with op to page through results.

Response Codes

200
if the request is successful
403
if the user is not authorized to view performance profiles
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ListPerformanceProfilesResponse
a ListPerformanceProfilesResponse with the performance profile details.
Properties
performanceProfiles
PerformanceProfile
the list of performance profile details.
Properties
ID
number
the performance profile identifier.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

name
string
the performance profile name.

This read-only value is provided for reference only. The actual name is found in the performance profile content, identified with the key: .

The name must be unique. Adding a new performance profile with a duplicate name will fail, and trying to change the name of an existing performance profile will fail if there is an existing profile with the new name.

preferred
boolean
the performance profile preferred value.

This read-only value is provided for reference only. The actual preferred flag is found in the performance profile content, identified with the key: .

The performance profile with the preferred flag set will automatically be assigned to each new Deep Security Manager during installation. If no performance profile has the preferred flag set then no performance profile will be assigned. If more than one performance profile has the preferred flag set then the results are non-deterministic.

content
string
the performance profile content.

The content is a Base64-encoded properties file (each line contains a assignment). Maximum content size is 16 kilobytes (encoded).

For more information about the performance profiles see this article.

Example Request

GET /performance-profiles?maxItems={maxItems}&op={op}&performanceProfileID={performanceProfileID}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ListPerformanceProfilesResponse": {
    "performanceProfiles": [ {
      "ID": 12345,
      "name": "...",
      "preferred": true,
      "content": "..."
    }, {
      "ID": 12345,
      "name": "...",
      "preferred": true,
      "content": "..."
    } ]
  }
}
                    
                  

Create a performance profile

Does not apply to Deep Security as a Service

Primary tenant only

Create a performance profile.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Request Body

CreatePerformanceProfileRequest
a CreatePerformanceProfileRequest with the performance profile details.
Properties
performanceProfile
the performance profile details.

Response Codes

200
if the request is successful
403
if the user is not authorized to create performance profiles
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

CreatePerformanceProfileResponse
a CreatePerformanceProfileResponse with the performance profile details.
Properties
performanceProfile
the performance profile details.

Example Request

PUT /performance-profiles
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "CreatePerformanceProfileRequest": {
    "performanceProfile": {
      "ID": 12345,
      "name": "...",
      "preferred": true,
      "content": "..."
    }
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "CreatePerformanceProfileResponse": {
    "performanceProfile": {
      "ID": 12345,
      "name": "...",
      "preferred": true,
      "content": "..."
    }
  }
}
                    
                  

Delete a performance profile

Does not apply to Deep Security as a Service

Primary tenant only

Delete a performance profile.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

performanceProfileID
integer
the performance profile ID.

Response Codes

200
if the request is successful
403
if the user is not authorized to delete performance profiles
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Example Request

DELETE /performance-profiles/{performanceProfileID}
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
                  

Describe a performance profile

Does not apply to Deep Security as a Service

Primary tenant only

Describe a performance profile.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

performanceProfileID
integer
the performance profile identifier.

Response Codes

200
if the request is successful
403
if the user is not authorized to view performance profiles
404
if the user is authorized to view performance profiles but the performance profile does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

DescribePerformanceProfileResponse
a DescribePerformanceProfileResponse with the performance profile details.
Properties
performanceProfile
the performance profile details.

Example Request

GET /performance-profiles/{performanceProfileID}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "DescribePerformanceProfileResponse": {
    "performanceProfile": {
      "ID": 12345,
      "name": "...",
      "preferred": true,
      "content": "..."
    }
  }
}
                    
                  

Modify a performance profile

Does not apply to Deep Security as a Service

Primary tenant only

Modify a performance profile.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

performanceProfileID
integer
the performance profile identifier.

Request Body

ModifyPerformanceProfileRequest
a ModifyPerformanceProfileRequest with the details of the performance profile.
Properties
performanceProfile
the performance profile details.

Response Codes

200
if the request is successful.
403
if the user is not authorized to modify performance profiles
404
if the user is authorized to modify performance profiles but the performance profile does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ModifyPerformanceProfileResponse
an ModifyPerformanceProfileResponse with the updated performance profile details.
Properties
performanceProfile
the performance profile details.

Example Request

POST /performance-profiles/{performanceProfileID}
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "ModifyPerformanceProfileRequest": {
    "performanceProfile": {
      "ID": 12345,
      "name": "...",
      "preferred": true,
      "content": "..."
    }
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ModifyPerformanceProfileResponse": {
    "performanceProfile": {
      "ID": 12345,
      "name": "...",
      "preferred": true,
      "content": "..."
    }
  }
}
                    
                  

Policy settings - application control

Interface to the Application Control Policy API.

Describe an application control policy

Retrieve the application control settings for a policy.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

policyID
integer
the policy ID.

Response Codes

200
if the request was successful
403
if the user is not authorized to view the policy
404
if the policy does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

DescribeApplicationControlPolicyResponse
a DescribeApplicationControlPolicyResponse containing the application control settings for the policy.
Properties
appControlPolicyParameters
AppControlPolicyParameters
the application control policy parameters for the policy.
Properties
state
ActivationState
the activation state for application control.
Values
on
Application control is enabled.
off
Application control is disabled.
inherit
Application control state is inherited from the parent policy.
lockdown
boolean
the lockdown state for application control.
whitelistMode
WhitelistMode
the whitelist mode for application control.
Values
inherit
Inherit whitelist mode from parent policy.
local-inventory
Use local inventory as whitelist.
shared
Use a shared whitelist.
rulesetID
number
the ID for the ruleset to use when application control is enabled and set to block or notify when applications not in the ruleset are launched.

Example Request

GET /policies/{policyID}/application-control
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "DescribeApplicationControlPolicyResponse": {
    "appControlPolicyParameters": {
      "state": "off",
      "lockdown": true,
      "whitelistMode": "shared",
      "rulesetID": 12345
    }
  }
}
                    
                  

Modify an application control policy

Modify the application control portion of a policy.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

policyID
integer

Request Body

ModifyApplicationControlPolicyRequest
a ModifyApplicationControlPolicyRequest describing the details of the policy.
Properties
appControlPolicyParameters
the application control policy parameters for the policy.

Response Codes

200
if the request was successful
400
if the request is invalid
403
if the user is not authorized to update the policy
404
if the policy does not exist or the user is not authorized to view the policy
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Example Request

POST /policies/{policyID}/application-control
Content-Type: application/json
Cookie: sID=12345;
                    
{
  "ModifyApplicationControlPolicyRequest": {
    "appControlPolicyParameters": {
      "state": "on",
      "lockdown": true,
      "whitelistMode": "inherit",
      "rulesetID": 12345
    }
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
                  

Policy settings - scanner

Interface for scanner settings in the security policy.

Reset policy settings - scanner

Delete any policy-level scanner setting overrides on a policy.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

policyID
integer
the policy ID.

Response Codes

204
if the request is successful
403
if the user is authorized to view the policy but is not authorized to modify settings
404
if the policy does not exist or the user is not authorized to access the policy
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Example Request

DELETE /policies/{policyID}/scanner/settings
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 204 No Content
                  

Describe policy settings - scanner

Describe the scanner settings on a policy.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

policyID
integer
the policy ID.

Query Parameters

overrides
boolean
the flag to see overrides attributes.

Response Codes

200
if the request is successful
403
if the user is authorized to view the policy but is not authorized to view settings
404
if the policy does not exist or the user is not authorized to view the policy
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

DescribePolicyScannerSettingsResponse
a DescribePolicyScannerSettingsResponse with the setting details.
Properties
sap
the SAP details.

Example Request

GET /policies/{policyID}/scanner/settings?overrides={overrides}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "DescribePolicyScannerSettingsResponse": {
    "sap": {
      "state": "inherited",
      "description": "..."
    }
  }
}
                    
                  

Modify policy settings - scanner

Modify the scanner settings on a policy.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

policyID
integer
the policy ID.

Request Body

ModifyPolicyScannerSettingsRequest
the updated scanner settings for the policy. If a setting value is unspecified or null, the current setting value is not changed.
Properties
sap
the SAP details.

Response Codes

200
if the request is successful
400
if the request parameter is invalid
403
if the user is authorized to view the policy but is not authorized to modify settings
404
if the policy does not exist or the user is not authorized to access the policy
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ModifyPolicyScannerSettingsResponse
a ModifyPolicyScannerSettingsResponse with the new setting details.
Properties
sap
the SAP details.

Example Request

POST /policies/{policyID}/scanner/settings
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "ModifyPolicyScannerSettingsRequest": {
    "sap": {
      "state": "on",
      "description": "..."
    }
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ModifyPolicyScannerSettingsResponse": {
    "sap": {
      "state": "inherited",
      "description": "..."
    }
  }
}
                    
                  

Proxies

Interface to the Proxy API.

List proxies

List proxies.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Query Parameters

defaultType
string
used to get the default proxy which is set. Currently supported types are:
  • host Primary Security Update Proxy used by Agents, Appliances, and Relays
  • manager Deep Security Manager (Software Updates, CSSS, News Updates, Product Registration and Licensing)
  • manager-cloud Deep Security Manager (Cloud Accounts - HTTP Protocol Only)
id
integer
(optional) used to define the starting point for the query. Combine with op to page through results.
maxItems
integer
(optional) the number of items to retrieve. The maximum value for this parameter is controlled by the "Maximum number of items to retrieve from database" setting on the administrator account, which defaults to 5000.
op
string
(optional, required if id is specified) Currently supported operations are:
  • gt (greater than)
  • ge (greater than or equal to)
  • eq (equal to)
  • lt (less than)
  • le (less than or equal to)

Response Codes

200
if the request is successful
403
if the user is not authorized to view proxies
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ListProxiesResponse
a ListProxiesResponse with the proxy details.
Properties
proxies
Proxy
the list of proxy details.
Properties
ID
number
the proxy ID.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

name
string
the proxy name.
description
string
the proxy description.
address
string
the proxy address.
port
number
the proxy port.
protocol
Protocol
the proxy protocol.
Values
http
This proxy will be accessed using HTTP / HTTPS.
socks4
This proxy will be accessed using SOCKS4.
socks5
This proxy will be accessed using SOCKS5.
authenticated
boolean
the flag indicating whether access to the proxy is authenticated.
username
string
the proxy username for use if the proxy requires authentication.
password
string
the proxy password for use if the proxy requires authentication.

To prevent accidental disclosure of the proxy password, the Deep Security Manager will not return this value; it can only be used to set the proxy password.

Example Request

GET /proxies?defaultType={defaultType}&id={id}&maxItems={maxItems}&op={op}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ListProxiesResponse": {
    "proxies": [ {
      "ID": 12345,
      "name": "...",
      "description": "...",
      "address": "...",
      "port": 12345,
      "protocol": "http",
      "authenticated": true,
      "username": "...",
      "password": "..."
    }, {
      "ID": 12345,
      "name": "...",
      "description": "...",
      "address": "...",
      "port": 12345,
      "protocol": "socks4",
      "authenticated": true,
      "username": "...",
      "password": "..."
    } ]
  }
}
                    
                  

Create a proxy

Create a new proxy.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Request Body

CreateProxyRequest
a CreateProxyRequest with the proxy details.
Properties
proxy
the proxy details.

Response Codes

200
if the request is successful
403
if the user is not authorized to create proxies
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

CreateProxyResponse
a CreateProxyResponse with the proxy details.
Properties
proxy
the proxy details.

Example Request

POST /proxies
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "CreateProxyRequest": {
    "proxy": {
      "ID": 12345,
      "name": "...",
      "description": "...",
      "address": "...",
      "port": 12345,
      "protocol": "socks4",
      "authenticated": true,
      "username": "...",
      "password": "..."
    }
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "CreateProxyResponse": {
    "proxy": {
      "ID": 12345,
      "name": "...",
      "description": "...",
      "address": "...",
      "port": 12345,
      "protocol": "http",
      "authenticated": true,
      "username": "...",
      "password": "..."
    }
  }
}
                    
                  

Delete a proxy

Delete a proxy.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

proxyID
integer
the proxy ID.

Response Codes

200
if the request is successful
403
if the user is not authorized to delete proxies
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Example Request

DELETE /proxies/{proxyID}
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
                  

Describe a proxy

Describe a proxy.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

proxyID
integer
the proxy ID.

Response Codes

200
if the request is successful
403
if the user is not authorized to view proxies
404
if the user is authorized to view proxies but the proxy does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

DescribeProxyResponse
a DescribeProxyResponse with the proxy details.
Properties
proxy
the proxy details.

Example Request

GET /proxies/{proxyID}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "DescribeProxyResponse": {
    "proxy": {
      "ID": 12345,
      "name": "...",
      "description": "...",
      "address": "...",
      "port": 12345,
      "protocol": "socks5",
      "authenticated": true,
      "username": "...",
      "password": "..."
    }
  }
}
                    
                  

Modify a proxy

Modify a proxy.

Any unset elements in the request object will be left unchanged by the modify request.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

proxyID
integer
the proxy ID.

Request Body

ModifyProxyRequest
a ModifyProxyRequest with the details of the proxy.
Properties
proxy
the proxy details.

Response Codes

200
if the request is successful
403
if the user is not authorized to modify proxies or if the requested modification is not permitted
404
if the user is authorized to modify proxies but the proxy does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ModifyProxyResponse
an ModifyProxyResponse with the updated proxy details.
Properties
proxy
the proxy details.

Example Request

POST /proxies/{proxyID}
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "ModifyProxyRequest": {
    "proxy": {
      "ID": 12345,
      "name": "...",
      "description": "...",
      "address": "...",
      "port": 12345,
      "protocol": "socks4",
      "authenticated": true,
      "username": "...",
      "password": "..."
    }
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "UpdateProxyResponse": {
    "proxy": {
      "ID": 12345,
      "name": "...",
      "description": "...",
      "address": "...",
      "port": 12345,
      "protocol": "http",
      "authenticated": true,
      "username": "...",
      "password": "..."
    }
  }
}
                    
                  

Relay groups

Interface to the Relay Group API.

List relay groups

List relay groups

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Query Parameters

ascending
boolean
(optional) If true, indicate ascending. Default is true. This parameter only works with sortBy.
background
boolean
(optional) If true, does not extends the session. Default is false.
expanded
boolean
(optional) If true, the response includes relays in each group. Default is false.
maxItems
integer
(optional) the number of items to retrieve. The maximum value for this parameter is controlled by the "Maximum number of items to retrieve from database" setting on the administrator account, which defaults to 5000.
offset
integer
(optional) used to define the starting point for the query. This parameter only works with sortBy.
sortBy
string
(optional) used to define the sorting field. For now, the only available sorting column is "name". This parameter can work with maxItems, ascending and offset. In other words, relayGroupID and relayGroupIDOp will be ignore if sortBy is specified.

Response Codes

200
if the request is successful
403
if the user is not authorized to view relay groups
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ListRelayGroupsResponse
a ListRelayGroupsResponse with the relay group details.
Properties
relayGroups
RelayGroup
the list of relay group details.
Properties
id
number
the relay group ID.
name
string
the relay group name.
description
string
the relay group description.
updateSourceID
number
the update source ID of the relay group.
updateSourceName
string
the update source name of the relay group.
updateSourceProxyID
number
the update source proxy ID of the relay group.
updateSourceProxyName
string
the update source proxy name of the relay group.
status
RelayGroupStatus
the status of the relay group.

GREY: Empty
GREEN: All online
ORANGE: One or more offline
RED: All offline
Properties
status
Status
the status light of the relay group.
Values
none
critical
warning
okay
value
string
the status string of the relay group.
onlyUpdatePatterns
boolean
the value of the "Only Update Patterns" flag.
relays
Relay
the list of relay details.
Properties
id
number
the relay ID.
name
string
the relay name.
platform
string
the platform of the relay.
relayStatus
RelayStatus
the status of the relay.
Properties
status
Status
the status light of the relay. This is the same as the host status light.
Values
none
critical
warning
okay
not-supported
blank
value
string
the status string of the relay. This is the same as the host status string.
relayGroupID
number
the relay group ID.
relayGroupName
string
the relay group name.
operationStatus
RelayOperationStatus
the operation status of the relay.
Properties
relayGroupID
number
the target relay group ID.
progressStatus
ProgressStatus
the progress status.
Values
neutral
enabling-in-progress
disabling-in-progress
enabling-failed
disabling-failed
online
boolean
the state of the "online" flag.
version
string
the relay version.
hostCount
number
the host count of the relay group.
hasMore
boolean
the indicator that there are more relay groups available.

Example Request

GET /relay-groups?ascending={ascending}&background={background}&expanded={expanded}&maxItems={maxItems}&offset={offset}&sortBy={sortBy}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ListRelayGroupsResponse": {
    "relayGroups": [ {
      "id": 12345,
      "name": "...",
      "description": "...",
      "updateSourceID": 12345,
      "updateSourceName": "...",
      "updateSourceProxyID": 12345,
      "updateSourceProxyName": "...",
      "status": {
        "status": "critical",
        "value": "..."
      },
      "onlyUpdatePatterns": true,
      "relays": [ {
        "id": 12345,
        "name": "...",
        "platform": "...",
        "relayStatus": { },
        "relayGroupID": 12345,
        "relayGroupName": "...",
        "operationStatus": { },
        "online": true,
        "version": "..."
      }, {
        "id": 12345,
        "name": "...",
        "platform": "...",
        "relayStatus": { },
        "relayGroupID": 12345,
        "relayGroupName": "...",
        "operationStatus": { },
        "online": true,
        "version": "..."
      } ],
      "hostCount": 12345
    }, {
      "id": 12345,
      "name": "...",
      "description": "...",
      "updateSourceID": 12345,
      "updateSourceName": "...",
      "updateSourceProxyID": 12345,
      "updateSourceProxyName": "...",
      "status": {
        "status": "none",
        "value": "..."
      },
      "onlyUpdatePatterns": true,
      "relays": [ {
        "id": 12345,
        "name": "...",
        "platform": "...",
        "relayStatus": { },
        "relayGroupID": 12345,
        "relayGroupName": "...",
        "operationStatus": { },
        "online": true,
        "version": "..."
      }, {
        "id": 12345,
        "name": "...",
        "platform": "...",
        "relayStatus": { },
        "relayGroupID": 12345,
        "relayGroupName": "...",
        "operationStatus": { },
        "online": true,
        "version": "..."
      } ],
      "hostCount": 12345
    } ],
    "hasMore": true
  }
}
                    
                  

Create a relay group

Create a relay group.

If the request doens't contain a specified group, then a group with default values will be created.
If the relayGroup's updateSourceID is null, or 0, or not specified, then the group's update source will be "Primary Security Update Source"

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Request Body

CreateRelayGroupRequest
a CreateRelayGroupRequest with the details of the relay group.
Properties
relayGroup
the relay group details.

Response Codes

200
if the request is successful
403
if the user is not authorized to create a relay group
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

CreateRelayGroupResponse
a CreateRelayGroupResponse with the details of the new created relay group.
Properties
relayGroup
the relay group details.

Example Request

POST /relay-groups
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "CreateRelayGroupRequest": {
    "relayGroup": {
      "id": 12345,
      "name": "...",
      "description": "...",
      "updateSourceID": 12345,
      "updateSourceName": "...",
      "updateSourceProxyID": 12345,
      "updateSourceProxyName": "...",
      "status": {
        "status": "critical",
        "value": "..."
      },
      "onlyUpdatePatterns": true,
      "relays": [ {
        "id": 12345,
        "name": "...",
        "platform": "...",
        "relayStatus": { },
        "relayGroupID": 12345,
        "relayGroupName": "...",
        "operationStatus": { },
        "online": true,
        "version": "..."
      }, {
        "id": 12345,
        "name": "...",
        "platform": "...",
        "relayStatus": { },
        "relayGroupID": 12345,
        "relayGroupName": "...",
        "operationStatus": { },
        "online": true,
        "version": "..."
      } ],
      "hostCount": 12345
    }
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "CreateRelayGroupResponse": {
    "relayGroup": {
      "id": 12345,
      "name": "...",
      "description": "...",
      "updateSourceID": 12345,
      "updateSourceName": "...",
      "updateSourceProxyID": 12345,
      "updateSourceProxyName": "...",
      "status": {
        "status": "okay",
        "value": "..."
      },
      "onlyUpdatePatterns": true,
      "relays": [ {
        "id": 12345,
        "name": "...",
        "platform": "...",
        "relayStatus": { },
        "relayGroupID": 12345,
        "relayGroupName": "...",
        "operationStatus": { },
        "online": true,
        "version": "..."
      }, {
        "id": 12345,
        "name": "...",
        "platform": "...",
        "relayStatus": { },
        "relayGroupID": 12345,
        "relayGroupName": "...",
        "operationStatus": { },
        "online": true,
        "version": "..."
      } ],
      "hostCount": 12345
    }
  }
}
                    
                  

Delete a relay group

Remove a relay group.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

relayGroupID
integer
the relay group ID. (0 for Default Relay Group)

Response Codes

200
if the request is successful
403
if the user is not authorized to delete the requested relay group
404
if the user is authorized to delete the requested relay group but the relay group does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Example Request

DELETE /relay-groups/{relayGroupID}
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
                  

Describe a relay group

Describe a relay group.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

relayGroupID
integer
the relay group ID (0 for Default Relay Group).

Query Parameters

expanded
boolean
(optional) If true, the response includes relays in each group. Default is false.

Response Codes

200
if the request is successful
403
if the user is not authorized to view relay groups
404
if the user is authorized to view relay groups but the requested relay group does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

DescribeRelayGroupResponse
a DescribeRelayGroupResponse with the relay group details.
Properties
relayGroup
the relay group details.

Example Request

GET /relay-groups/{relayGroupID}?expanded={expanded}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "DescribeRelayGroupResponse": {
    "relayGroup": {
      "id": 12345,
      "name": "...",
      "description": "...",
      "updateSourceID": 12345,
      "updateSourceName": "...",
      "updateSourceProxyID": 12345,
      "updateSourceProxyName": "...",
      "status": {
        "status": "warning",
        "value": "..."
      },
      "onlyUpdatePatterns": true,
      "relays": [ {
        "id": 12345,
        "name": "...",
        "platform": "...",
        "relayStatus": { },
        "relayGroupID": 12345,
        "relayGroupName": "...",
        "operationStatus": { },
        "online": true,
        "version": "..."
      }, {
        "id": 12345,
        "name": "...",
        "platform": "...",
        "relayStatus": { },
        "relayGroupID": 12345,
        "relayGroupName": "...",
        "operationStatus": { },
        "online": true,
        "version": "..."
      } ],
      "hostCount": 12345
    }
  }
}
                    
                  

Modify a relay group

Modify a relay group.

Any unset element in the request object will be left unchanged by the modify request.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

relayGroupID
integer
the relay group ID. (0 for Default Relay Group)

Request Body

ModifyRelayGroupRequest
a ModifyRelayGroupRequest with the details of the relay group. In addition, By adding hosts to a relay group, the relay feature will be enabled on those hosts. In this scenario, please assign hosts' IDs in the relays array. An example: move 2 hosts (with ID 15 and 21) to a relay group
 {
 		"ModifyRelayGroupRequest": {
 			"relayGroup": {
 				"relays": [{"id": 15}, {"id": 21}]
 			}
 		}
 }
 
Properties
relayGroup
the relay group details.

Response Codes

200
if the request is successful
403
if the user is not authorized to modify the requested relay group
404
if the user is authorized to modify the requested relay group but the requested relay group does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ModifyRelayGroupResponse
a ModifyRelayGroupResponse with the details of the relay group after modified.
Properties
relayGroup
the relay group details.

Example Request

POST /relay-groups/{relayGroupID}
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "ModifyRelayGroupRequest": {
    "relayGroup": {
      "id": 12345,
      "name": "...",
      "description": "...",
      "updateSourceID": 12345,
      "updateSourceName": "...",
      "updateSourceProxyID": 12345,
      "updateSourceProxyName": "...",
      "status": {
        "status": "critical",
        "value": "..."
      },
      "onlyUpdatePatterns": true,
      "relays": [ {
        "id": 12345,
        "name": "...",
        "platform": "...",
        "relayStatus": { },
        "relayGroupID": 12345,
        "relayGroupName": "...",
        "operationStatus": { },
        "online": true,
        "version": "..."
      }, {
        "id": 12345,
        "name": "...",
        "platform": "...",
        "relayStatus": { },
        "relayGroupID": 12345,
        "relayGroupName": "...",
        "operationStatus": { },
        "online": true,
        "version": "..."
      } ],
      "hostCount": 12345
    }
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ModifyRelayGroupResponse": {
    "relayGroup": {
      "id": 12345,
      "name": "...",
      "description": "...",
      "updateSourceID": 12345,
      "updateSourceName": "...",
      "updateSourceProxyID": 12345,
      "updateSourceProxyName": "...",
      "status": {
        "status": "okay",
        "value": "..."
      },
      "onlyUpdatePatterns": true,
      "relays": [ {
        "id": 12345,
        "name": "...",
        "platform": "...",
        "relayStatus": { },
        "relayGroupID": 12345,
        "relayGroupName": "...",
        "operationStatus": { },
        "online": true,
        "version": "..."
      }, {
        "id": 12345,
        "name": "...",
        "platform": "...",
        "relayStatus": { },
        "relayGroupID": 12345,
        "relayGroupName": "...",
        "operationStatus": { },
        "online": true,
        "version": "..."
      } ],
      "hostCount": 12345
    }
  }
}
                    
                  

List available update sources

List available update sources in a specific relay group.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

relayGroupID
integer
the relay group ID. (0 for Default Relay Group)

Query Parameters

maxItems
integer
(optional) the number of items to retrieve. The maximum value for this parameter is controlled by the "Maximum number of items to retrieve from database" setting on the administrator account, which defaults to 5000.

Response Codes

200
if the request is successful
403
if the user is not authorized to view update sources
404
if the user is authorized to view update sources but the requested relay group does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ListAvailableUpdateSourcesResponse
a ListAvailableUpdateSourcesResponse with the update source details.
Properties
availableUpdateSources
UpdateSource
the list of available update source details.
Properties
id
number
the update source ID.
name
string
the update source name.

Example Request

GET /relay-groups/{relayGroupID}/available-update-sources?maxItems={maxItems}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ListAvailableUpdateSourcesResponse": {
    "availableUpdateSources": [ {
      "id": 12345,
      "name": "..."
    }, {
      "id": 12345,
      "name": "..."
    } ]
  }
}
                    
                  

List relay group hosts

List hosts assigned to a specific relay group.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

relayGroupID
integer
the relay group ID. (0 for Default Relay Group)

Query Parameters

ascending
boolean
(optional) If true, indicate ascending. Default is true. This parameter only works with sortBy.
maxItems
integer
(optional) the number of items to retrieve. The maximum value for this parameter is controlled by the "Maximum number of items to retrieve from database" setting on the administrator account, which defaults to 5000.
offset
integer
(optional) used to define the starting point for the query. This parameter only works with sortBy.
sortBy
string
(optional) used to define the sorting field. For now, the only available sorting column is "name". This parameter can work with maxItems, ascending and offset. In other words, relayGroupID and relayGroupIDOp will be ignore if sortBy is specified.

Response Codes

200
if the request is successful
403
if the user is not authorized to view hosts
404
if the user is authorized to view hosts but the requested relay group does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ListRelayGroupHostsResponse
a ListRelayGroupHostsResponse with the host details.
Properties
relayGroupHosts
HostTransport
the list of host assigned to the relay group details.
Properties
id
number
The Host ID assigned by the DSM.
hostname
string
The hostname used to connect to the host.
displayname
string
The display name set for the host.
description
string
A description of the host.
created
number
The time in milliseconds since Unix epoch when the host was created.
lastModified
number
The time in milliseconds since Unix epoch when the host was last modified.
lastUpdateAttempt
string
The last date and time an update was attempted on the host.
agentReportedVersion
string
The version of the agent.
externalId
string
The identifier assigned by the DSM administrator, if any.
instanceId
string
The identifier assigned by the cloud provider, if any.
lastIpUsed
string
The last IP used to communicate with the host.
platform
string
The platform on which the host is running.
hostGroupId
number
The primary key ID of the host's host group.
policy
PolicySummaryInfo
Summary information about the policy assigned to this host.
Properties
id
number
-
name
string
-
hostStatus
HostStatus
The host status on which the host is running.
Properties
status
Status
the status light of the host.
Values
none
critical
warning
okay
not-supported
blank
value
string
the status string of the host.
hasMore
boolean
the indicator that there are more hosts available.

Example Request

GET /relay-groups/{relayGroupID}/hosts?ascending={ascending}&maxItems={maxItems}&offset={offset}&sortBy={sortBy}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ListRelayGroupHostsResponse": {
    "relayGroupHosts": [ {
      "id": 12345,
      "hostname": "...",
      "displayname": "...",
      "description": "...",
      "created": 12345,
      "lastModified": 12345,
      "lastUpdateAttempt": "...",
      "agentReportedVersion": "...",
      "externalId": "...",
      "instanceId": "...",
      "lastIpUsed": "...",
      "platform": "...",
      "hostGroupId": 12345,
      "policy": {
        "id": 12345,
        "name": "..."
      },
      "hostStatus": {
        "status": "blank",
        "value": "..."
      }
    }, {
      "id": 12345,
      "hostname": "...",
      "displayname": "...",
      "description": "...",
      "created": 12345,
      "lastModified": 12345,
      "lastUpdateAttempt": "...",
      "agentReportedVersion": "...",
      "externalId": "...",
      "instanceId": "...",
      "lastIpUsed": "...",
      "platform": "...",
      "hostGroupId": 12345,
      "policy": {
        "id": 12345,
        "name": "..."
      },
      "hostStatus": {
        "status": "critical",
        "value": "..."
      }
    } ],
    "hasMore": true
  }
}
                    
                  

Relays

The APIs to return information about the Relays.

List relays

List relays

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Query Parameters

ascending
boolean
(optional) set true indicate ascending. Default is true. This parameter only works with sortBy.
background
boolean
(optional) If true, does not extends the session. Default false.
failed
boolean
(optional) set true, indicate that the API only returns the failure records of enabling/disabling. If false, the API returns valid relays according to the specified criteria. Default is false.
maxItems
integer
(optional) the number of items to retrieve. The maximum value for this parameter is controlled by the "Maximum number of items to retrieve from database" setting on the administrator account, which defaults to 5000.
offset
integer
(optional) used to define the starting point for the query. This parameter only works with sortBy.
sortBy
string
(optional) used to define the sorting field. The only available sorting column is Name. However, if sortBy is not specified, the default sorting column is id. This parameter can work with maxItems, ascending and offset.

Response Codes

200
if the request is successful
403
if the user is not authorized to list relays
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ListRelaysResponse
a ListRelaysResponse with the host details.
Properties
relays
the list of relay details.

Example Request

GET /relays?ascending={ascending}&background={background}&failed={failed}&maxItems={maxItems}&offset={offset}&sortBy={sortBy}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "##default": {
    "relays": [ {
      "id": 12345,
      "name": "...",
      "platform": "...",
      "relayStatus": {
        "status": "blank",
        "value": "..."
      },
      "relayGroupID": 12345,
      "relayGroupName": "...",
      "operationStatus": {
        "relayGroupID": 12345,
        "progressStatus": "disabling-in-progress"
      },
      "online": true,
      "version": "..."
    }, {
      "id": 12345,
      "name": "...",
      "platform": "...",
      "relayStatus": {
        "status": "not-supported",
        "value": "..."
      },
      "relayGroupID": 12345,
      "relayGroupName": "...",
      "operationStatus": {
        "relayGroupID": 12345,
        "progressStatus": "disabling-failed"
      },
      "online": true,
      "version": "..."
    } ]
  }
}
                    
                  

Disable a relay

Disable a relay.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

hostID
integer
the host ID.

Query Parameters

dryrun
boolean
test host ability to disable relay.

Response Codes

204
if the relay is successfully disabled
403
if the user is not able to disable the relay
404
if the hostID is not valid
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

DisableRelayResponse
dryrun = true: return a DisableRelayResponse with the ability to disable of the host
dryrun = false: return null if disable the relay successfully
Properties
isAbleToDisableRelay
boolean
the ability to disable relay.
message
string
the message for disabling relay.

Example Request

DELETE /relays/{hostID}?dryrun={dryrun}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 204 No Content
Content-Type: application/json
                    
{
  "##default": {
    "isAbleToDisableRelay": true,
    "message": "..."
  }
}
                    
                  

Describe a relay

Describe a relay.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

hostID
integer
the host ID.

Response Codes

200
if the request is successful
403
if the user is not authorized to describe the relay
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

DescribeRelayResponse
a DescribeRelayResponse with the relay details.
Properties
relay
the relay details.

Example Request

GET /relays/{hostID}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "DescribeRelayResponse": {
    "relay": {
      "id": 12345,
      "name": "...",
      "platform": "...",
      "relayStatus": {
        "status": "okay",
        "value": "..."
      },
      "relayGroupID": 12345,
      "relayGroupName": "...",
      "operationStatus": {
        "relayGroupID": 12345,
        "progressStatus": "enabling-in-progress"
      },
      "online": true,
      "version": "..."
    }
  }
}
                    
                  

Modify a relay

Modify a relay.

Any unset element in the request object will be left unchanged after the request executed.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

hostID
integer
the host ID.

Request Body

ModifyRelayRequest
a ModifyRelayRequest with the details of the relay.
Properties
relay
the relay details.

Response Codes

200
if the request is successful
403
if the user is not authorized to modify relays
404
if the user is authorized to modify relays but the relay does not exist or if the user is not authorized to modify the requested relay
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ModifyRelayResponse
a ModifyRelayResponse with the the detail information of the relay after modified.
Properties
relay
the relay details.

Example Request

POST /relays/{hostID}
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "ModifyRelayRequest": {
    "relay": {
      "id": 12345,
      "name": "...",
      "platform": "...",
      "relayStatus": {
        "status": "blank",
        "value": "..."
      },
      "relayGroupID": 12345,
      "relayGroupName": "...",
      "operationStatus": {
        "relayGroupID": 12345,
        "progressStatus": "disabling-in-progress"
      },
      "online": true,
      "version": "..."
    }
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ModifyRelayResponse": {
    "relay": {
      "id": 12345,
      "name": "...",
      "platform": "...",
      "relayStatus": {
        "status": "critical",
        "value": "..."
      },
      "relayGroupID": 12345,
      "relayGroupName": "...",
      "operationStatus": {
        "relayGroupID": 12345,
        "progressStatus": "enabling-failed"
      },
      "online": true,
      "version": "..."
    }
  }
}
                    
                  

Dismiss a relay failure record

Dismiss the alert for enabling/disabling failure.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

hostID
integer
the host ID.

Response Codes

200
if the request is successful
403
if the user is not authorized to delete the failure record of relays
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Example Request

DELETE /relays/{hostID}/failure-record
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
                  

Report templates

Interface to the Report API.

List report templates

List report templates.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Query Parameters

id
integer
(optional) used to define the starting point for the query. Combine with op to page through results.
maxItems
integer
(optional) the number of items to retrieve. The maximum value for this parameter is controlled by the "Maximum number of items to retrieve from database" setting on the administrator account, which defaults to 5000.
op
string
(optional, required if id is specified) Currently supported operations are:
  • gt (greater than)
  • ge (greater than or equal to)
  • eq (equal to)
  • lt (less than)
  • le (less than or equal to)

Response Codes

200
if the request is successful
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ListReportTemplatesResponse
a ListReportTemplatesResponse with the report template details.
Properties
reportTemplates
ReportTemplate
the list of report templates.
Properties
ID
number
the report template identifier.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

name
string
the report template name.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

timeFilterSupported
boolean
Is a time filter supported for this report type?

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

hostFilterSupported
boolean
Is a host filter supported for this report type?

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

tagFilterSupported
boolean
Is a tag filter supported for this report type?

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

supportedFormats
Format
the supported formats for this report type.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

Values
pdf
csv
html
plaintext
rtf
xls
xml

Example Request

GET /reports?id={id}&maxItems={maxItems}&op={op}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ListReportTemplatesResponse": {
    "reportTemplates": [ {
      "ID": 12345,
      "name": "...",
      "timeFilterSupported": true,
      "hostFilterSupported": true,
      "tagFilterSupported": true,
      "supportedFormats": [ "html", "csv" ]
    }, {
      "ID": 12345,
      "name": "...",
      "timeFilterSupported": true,
      "hostFilterSupported": true,
      "tagFilterSupported": true,
      "supportedFormats": [ "pdf", "rtf" ]
    } ]
  }
}
                    
                  

Rulesets

Interface to the Ruleset API.

List rulesets

Retrieve a list of rulesets.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Query Parameters

maxItems
integer
(optional) the number of items to retrieve. The maximum value for this parameter is controlled by the "Maximum number of items to retrieve from database" setting on the administrator account, which defaults to 5000.
rulesetID
integer
(optional) used to define the starting point for the query. Combine with rulesetIDOp to page through results.
rulesetIDOp
string
(optional, required if rulesetID is specified) Currently supported operations include gt(greater than), ge(greater than or equal to), eq(eqaul to), lt(less than), and le(less than or equal to).

Response Codes

200
if the request is successful
400
if the request is invalid
403
if the user is not authorized to view rulesets
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ListRulesetsResponse
a list of rulesets.
Properties
rulesets
RulesetSummary
the list of rulesets.
Properties
rulesetID
number
the ruleset ID.
name
string
the ruleset name.
description
string
the ruleset description.
version
number
the ruleset version.

Example Request

GET /rulesets?maxItems={maxItems}&rulesetID={rulesetID}&rulesetIDOp={rulesetIDOp}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ListRulesetsResponse": {
    "rulesets": [ {
      "rulesetID": 12345,
      "name": "...",
      "description": "...",
      "version": 12345
    }, {
      "rulesetID": 12345,
      "name": "...",
      "description": "...",
      "version": 12345
    } ]
  }
}
                    
                  

Create a ruleset

Create a new ruleset.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Request Body

CreateRulesetRequest
a CreateRulesetRequest object describing the ruleset.
Properties
ruleset
Ruleset
The ruleset details.

Optional. One of ruleset or inventoryId must be specified.

Properties
rules
Rule
the list of rules in the ruleset.
Properties
sha256
string
the SHA-256 hash of the executable named in the rule.
size
number
the size of the executable named in the rule.
path
string
the full path (excluding filename) of the executable named in the rule.
fileName
string
the filename (excluding path) of the executable named in the rule.
action
Action
the action to take when a user attempts to launch the executable named in the rule.

IMPORTANT: The actual behavior of application control is controlled by policy. To block applications from being launched, application control must be enabled.

Values
allow
Allow the application to launch.
block
Block the application from launching.

IMPORTANT: The actual behavior of application control is controlled by policy. To block applications from being launched, application control must be enabled.

ruleID
number
The rule ID.
inventoryId
number
The inventory ID of the inventory to base the new ruleset on.

Optional. One of ruleset or inventoryId must be specified. If an inventory is specified, all items in the inventory will be added to the ruleset with action=ALLOW.

Response Codes

200
if the request is successful
400
if the request is invalid
403
if the user is not authorized to create a ruleset
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

CreateRulesetResponse
a CreateRulesetResponse containing the ID of the created ruleset.
Properties
rulesetID
number
-

Example Request

POST /rulesets
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "CreateRulesetRequest": {
    "ruleset": {
      "rules": [ {
        "sha256": "...",
        "size": 12345,
        "path": "...",
        "fileName": "...",
        "action": "block",
        "ruleID": 12345
      }, {
        "sha256": "...",
        "size": 12345,
        "path": "...",
        "fileName": "...",
        "action": "allow",
        "ruleID": 12345
      } ],
      "rulesetID": 12345,
      "name": "...",
      "description": "...",
      "version": 12345
    },
    "inventoryId": 12345
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "CreateRulesetResponse": {
    "rulesetID": 12345
  }
}
                    
                  

Delete a ruleset

Deletes a ruleset from the Deep Security Manager.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

rulesetID
integer
the ruleset ID.

Response Codes

204
if the request is successful
403
if the user is not authorized to delete rulesets
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Example Request

DELETE /rulesets/{rulesetID}
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 204 No Content
                  

Describe a ruleset

Gets the contents of one ruleset.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

rulesetID
integer
the ruleset ID.

Query Parameters

maxItems
integer
(optional) the number of items to retrieve. The maximum value for this parameter is controlled by the "Maximum number of items to retrieve from database" setting on the administrator account, which defaults to 5000.
ruleID
integer
(optional) used to define the starting point for the query. Combine with ruleIDOp to page through results.
ruleIDOp
string
(optional, required if ruleID is specified) Currently supported operations include gt(greater than), ge(greater than or equal to), eq(eqaul to), lt(less than), and le(less than or equal to).

Response Codes

200
if the request is successful
400
if the request is invalid
403
if the user is not authorized to view rulesets
404
if the ruleset does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

DescribeRulesetResponse
the ruleset contents
Properties
ruleset
-

Example Request

GET /rulesets/{rulesetID}?maxItems={maxItems}&ruleID={ruleID}&ruleIDOp={ruleIDOp}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "DescribeRulesetResponse": {
    "ruleset": {
      "rules": [ {
        "sha256": "...",
        "size": 12345,
        "path": "...",
        "fileName": "...",
        "action": "block",
        "ruleID": 12345
      }, {
        "sha256": "...",
        "size": 12345,
        "path": "...",
        "fileName": "...",
        "action": "block",
        "ruleID": 12345
      } ],
      "rulesetID": 12345,
      "name": "...",
      "description": "...",
      "version": 12345
    }
  }
}
                    
                  

Rulesets - Global

Interface to the Global Ruleset API.

Describe global ruleset

Gets the contents of global ruleset.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Query Parameters

maxItems
integer
(optional) the number of items to retrieve. The maximum value for this parameter is controlled by the "Maximum number of items to retrieve from database" setting on the administrator account, which defaults to 5000.
ruleID
integer
(optional) used to define the starting point for the query. Combine with ruleIDOp to page through results.
ruleIDOp
string
(optional, required if ruleID is specified) Currently supported operations include gt(greater than), ge(greater than or equal to), eq(eqaul to), lt(less than), and le(less than or equal to).

Response Codes

200
if the request is successful
400
if the request is invalid
403
if the user is not authorized to view rulesets
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

DescribeGlobalRulesetResponse
the ruleset contents
Properties
ruleset
GlobalRuleset
-
Properties
rules
BlockHashRule
the list of rules in the ruleset.
Properties
sha256
string
the SHA-256 hash of the executable named in the rule.
description
string
The description for block by hash rule.

Optional.

action
Action
the action to take when a user attempts to launch the executable named in the rule.

IMPORTANT: The actual behavior of application control is controlled by policy. To block applications from being launched, application control must be enabled.

Values
block
Block the application from launching.

IMPORTANT: The actual behavior of application control is controlled by policy. To block applications from being launched, application control must be enabled.

ruleID
number
The rule ID.

Example Request

GET /rulesets/global?maxItems={maxItems}&ruleID={ruleID}&ruleIDOp={ruleIDOp}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "DescribeGlobalRulesetResponse": {
    "ruleset": {
      "rules": [ {
        "sha256": "...",
        "description": "...",
        "action": "block",
        "ruleID": 12345
      }, {
        "sha256": "...",
        "description": "...",
        "action": "block",
        "ruleID": 12345
      } ],
      "rulesetID": 12345,
      "name": "...",
      "description": "...",
      "version": 12345
    }
  }
}
                    
                  

Add global ruleset rules

Add rules to the global ruleset.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Request Body

AddGlobalRulesetRulesRequest
a AddGlobalRulesetRulesRequest object describing the request to add rules to the global ruleset. The maximum number of rules that can be added in a single request is 5000.
Properties
the list of rules in the request.

Response Codes

200
if the request is successful
400
if the request is invalid
403
if the user is not authorized to modify ruleset
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

AddGlobalRulesetRulesResponse
a AddGlobalRulesetRulesResponse containing the added rules.
Properties
the list of rules in the response.

Example Request

POST /rulesets/global/rules
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "AddGlobalRulesetRulesRequest": {
    "rules": [ {
      "sha256": "...",
      "description": "...",
      "action": "block",
      "ruleID": 12345
    }, {
      "sha256": "...",
      "description": "...",
      "action": "block",
      "ruleID": 12345
    } ]
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "AddGlobalRulesetRulesResponse": {
    "rules": [ {
      "sha256": "...",
      "description": "...",
      "action": "block",
      "ruleID": 12345
    }, {
      "sha256": "...",
      "description": "...",
      "action": "block",
      "ruleID": 12345
    } ]
  }
}
                    
                  

Delete global ruleset rules

Delete a rule from the global ruleset.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

ruleID
integer
the rule ID to delete.

Response Codes

204
if the request is successful
400
if the request is invalid
403
if the user is not authorized to modify ruleset
404
if the rule with given ruleID does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Example Request

DELETE /rulesets/global/rules/{ruleID}
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 204 No Content
                  

SAML identity providers

Interface to the SAML Identity Provider API.

List SAML identity providers

List SAML identity providers.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Query Parameters

id
integer
(optional) used to define the starting point for the query. Combine with op to page through results.
maxItems
integer
(optional) the number of items to retrieve. The maximum value for this parameter is controlled by the "Maximum number of items to retrieve from database" setting on the SAMLIdentityProvider account, which defaults to 5000.
op
string
(optional, required if id is specified) Currently-supported operations are:
  • gt (greater than)
  • ge (greater than or equal to)
  • eq (equal to)
  • lt (less than)
  • le (less than or equal to)

Response Codes

200
if the request is successful
403
if the user is not authorized to view SAML identity providers
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ListSAMLIdentityProvidersResponse
a ListSAMLIdentityProvidersResponse with the SAML identity provider details.
Properties
SAMLIdentityProviders
SAMLIdentityProvider
the list of SAML identity providers.
Properties
id
number
the ID for this SAML identity provider.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

urn
string
the URN for this SAML identity provider.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

name
string
the name for this SAML identity provider.

The name may be between 1-254 characters long and may use alphanumeric characters plus =, ., @, and -.

description
string
the description for this SAML identity provider.

The description may be between 0-2000 characters long.

metadataXML
string
the Base64-encoded metadata XML for this SAML identity provider.

The decoded metadata XML must be at least 1000 characters and may be at most 1 000 000 characters.

created
number
the time when this SAML identity provider was created, as the number of milliseconds since January 1, 1970, 00:00:00 GMT.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

updated
number
the time when this SAML identity provider was updated, as the number of milliseconds since January 1, 1970, 00:00:00 GMT.

If the SAML identity provider has never been updated, this value will be null.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

validUntil
number
the time when this SAML identity provider's certificate will expire, as the number of milliseconds since January 1, 1970, 00:00:00 GMT.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

Example Request

GET /identity-providers/saml?id={id}&maxItems={maxItems}&op={op}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ListSAMLIdentityProvidersResponse": {
    "SAMLIdentityProviders": [ {
      "id": 12345,
      "urn": "...",
      "name": "...",
      "description": "...",
      "metadataXML": "...",
      "created": 12345,
      "updated": 12345,
      "validUntil": 12345
    }, {
      "id": 12345,
      "urn": "...",
      "name": "...",
      "description": "...",
      "metadataXML": "...",
      "created": 12345,
      "updated": 12345,
      "validUntil": 12345
    } ]
  }
}
                    
                  

Create a SAML identity provider

Create a SAML identity provider.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Request Body

CreateSAMLIdentityProviderRequest
a CreateSAMLIdentityProviderRequest with the SAML identity provider details.
Properties
SAMLIdentityProvider
the SAML identity provider.

Response Codes

200
if the request is successful
400
if the request is invalid
403
if the user is not authorized to create SAML identity providers
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

CreateSAMLIdentityProviderResponse
a CreateSAMLIdentityProviderResponse with the SAML identity provider details.
Properties
SAMLIdentityProvider
the SAML identity provider.

Example Request

POST /identity-providers/saml
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "CreateSAMLIdentityProviderRequest": {
    "SAMLIdentityProvider": {
      "id": 12345,
      "urn": "...",
      "name": "...",
      "description": "...",
      "metadataXML": "...",
      "created": 12345,
      "updated": 12345,
      "validUntil": 12345
    }
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "CreateSAMLIdentityProviderResponse": {
    "SAMLIdentityProvider": {
      "id": 12345,
      "urn": "...",
      "name": "...",
      "description": "...",
      "metadataXML": "...",
      "created": 12345,
      "updated": 12345,
      "validUntil": 12345
    }
  }
}
                    
                  

Delete a SAML identity provider

Delete a SAML identity provider.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

samlIdentityProviderID
integer
the SAML identity provider ID.

Response Codes

200
if the request is successful
403
if the user is not authorized to delete SAML identity providers
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Example Request

DELETE /identity-providers/saml/{samlIdentityProviderID}
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
                  

Describe a SAML identity provider

Describe a SAML identity provider.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

samlIdentityProviderID
integer
the SAML identity provider ID.

Response Codes

200
if the request is successful
403
if the user is not authorized to view SAML identity providers
404
if the user is authorized to view SAML identity providers but the SAML identity provider does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

DescribeSAMLIdentityProviderResponse
a DescribeSAMLIdentityProviderResponse with the SAML identity provider details.
Properties
SAMLIdentityProvider
the SAML identity provider.

Example Request

GET /identity-providers/saml/{samlIdentityProviderID}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "DescribeSAMLIdentityProviderResponse": {
    "SAMLIdentityProvider": {
      "id": 12345,
      "urn": "...",
      "name": "...",
      "description": "...",
      "metadataXML": "...",
      "created": 12345,
      "updated": 12345,
      "validUntil": 12345
    }
  }
}
                    
                  

Modify a SAML identity provider

Modify a SAML identity provider.

Any unset elements in the request object will be left unchanged by the modify request.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

samlIdentityProviderID
integer
the SAML identity provider ID.

Request Body

ModifySAMLIdentityProviderRequest
a ModifySAMLIdentityProviderRequest with the details of the SAML identity provider.
Properties
SAMLIdentityProvider
the SAML identity provider.

Response Codes

200
if the request is successful
400
if the requested change is invalid
403
if the user is not authorized to modify SAML identity providers or if the requested modification is not permitted
404
if the user is authorized to modify SAML identity providers but the SAML identity provider does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ModifySAMLIdentityProviderResponse
a ModifySAMLIdentityProviderResponse with the updated SAMLIdentityProvider details.
Properties
SAMLIdentityProvider
the SAML identity provider.

Example Request

POST /identity-providers/saml/{samlIdentityProviderID}
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "ModifySAMLIdentityProviderRequest": {
    "SAMLIdentityProvider": {
      "id": 12345,
      "urn": "...",
      "name": "...",
      "description": "...",
      "metadataXML": "...",
      "created": 12345,
      "updated": 12345,
      "validUntil": 12345
    }
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ModifySAMLIdentityProviderResponse": {
    "SAMLIdentityProvider": {
      "id": 12345,
      "urn": "...",
      "name": "...",
      "description": "...",
      "metadataXML": "...",
      "created": 12345,
      "updated": 12345,
      "validUntil": 12345
    }
  }
}
                    
                  

SAML service provider

Interface to the SAML Service Provider API.

Describe the SAML service provider

Describe the SAML service provider.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Response Codes

200
if the request is successful
403
if the user is not authorized to view the SAML service provider
404
if the user is authorized to view the SAML service provider but the SAML service provider is not configured or SAML is disabled
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

DescribeSAMLServiceProviderResponse
a DescribeSAMLServiceProviderResponse with the SAML service provider details.
Properties
SAMLServiceProvider
SAMLServiceProvider
the SAML service provider details.
Properties
entityID
string
the SAML service provider's entity ID.
serviceName
string
the SAML service provider's service name.
privateKey
string
the base64-encoded SAML service provider's private key.

The private key must be an RSA key; other key types are not supported.

Note: To prevent accidental disclosure of the private key, the Deep Security Manager will not return this value; it can only be used to set the private key.

certificate
string
the base64-encoded SAML service provider's signing certificate.
passphrase
string
the SAML service provider's private key passphrase.

Note: To prevent accidental disclosure of the private key passphrase, the Deep Security Manager will not return this value; it can only be used to set the private key passphrase.

validUntil
number
the time when this SAML service provider's certificate will expire, as the number of milliseconds since January 1, 1970, 00:00:00 GMT.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

Example Request

GET /service-provider/saml
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "DescribeSAMLServiceProviderResponse": {
    "SAMLServiceProvider": {
      "entityID": "...",
      "serviceName": "...",
      "privateKey": "...",
      "certificate": "...",
      "passphrase": "...",
      "validUntil": 12345
    }
  }
}
                    
                  

Modify the SAML service provider

Does not apply to Deep Security as a Service

Primary tenant only

Modify the SAML service provider.

Any unset elements in the request object will be left unchanged by the modify request.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Request Body

ModifySAMLServiceProviderRequest
-
Properties
SAMLServiceProvider
the SAML service provider details.

Response Codes

200
if the request is successful
400
if the requested change is invalid
403
if the user is not authorized to modify SAML service providers or if the requested modification is not permitted
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ModifySAMLServiceProviderResponse
a ModifySAMLServiceProviderResponse with the updated SAMLServiceProvider details.
Properties
SAMLServiceProvider
the SAML service provider details.

Example Request

POST /service-provider/saml
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "ModifySAMLServiceProviderRequest": {
    "SAMLServiceProvider": {
      "entityID": "...",
      "serviceName": "...",
      "privateKey": "...",
      "certificate": "...",
      "passphrase": "...",
      "validUntil": 12345
    }
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ModifySAMLServiceProviderResponse": {
    "SAMLServiceProvider": {
      "entityID": "...",
      "serviceName": "...",
      "privateKey": "...",
      "certificate": "...",
      "passphrase": "...",
      "validUntil": 12345
    }
  }
}
                    
                  

SSL configurations

Management API for host SSL configurations.

List SSL configurations

List SSL configurations.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API

Path Parameters

hostID
integer
the ID of the host for which the SSL configurations are being listed

Query Parameters

maxItems
integer
(optional) the maximum number of items to retrieve. The maximum value for this parameter is controlled by the "Maximum number of items to retrieve from database" setting on the administrator account, which defaults to 5000.
sslConfigurationID
integer
(optional) used to define the starting point for the query. Combine with sslConfigurationIDOp to page through results.
sslConfigurationIDOp
string
(optional, required if sslConfigurationID is specified) Currently supported operations are:
  • gt (greater than)
  • ge (greater than or equal to)
  • eq (equal to)
  • lt (less than)
  • le (less than or equal to)

Response Codes

200
if the request is successful
404
if the host is not found or the user is not authorized to view the host information
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ListSSLConfigurationsResponse
a ListSSLConfigurationResponse containing a list of SSL configurations
Properties
sslConfigurations
SSLConfiguration
the list of SSL configuration details
Properties
id
number
the SSL configuration ID.
enabled
boolean
the SSL configuration state.
name
string
the SSL configuration name.
description
string
the SSL configuration description.
ports
number
the list of port numbers for the SSL configuration.
portListID
number
the port list ID for the SSL configuration.
sslCredential
SSLCredential
the SSL configuration's SSL credential.
Properties
id
number
the SSL credential ID.
type
Type
the SSL credential type.
Values
pkcs12
pem
capi
name
string
the SSL credential name.
identifier
string
the SSL credential identifier. For a file, it's the file path. For type = CAPI, it's the name of the certificate.

Null if the credential is stored in the DSM's database

passphrase
string
the SSL credential passphrase.

Note: To prevent accidental disclosure of the passphrase, the Deep Security Manager will not return this value; it can only be used to set the passphrase.

details
string
the SSL credential details.
privateKey
string
the SSL credential private key.

The Base64-encoded contents of either a PKCS#12 file containing a single private key or a PEM (PKCS#1) file. Use the #getType() Type parameter to tell the Deep Security Manager which you are using.

To prevent accidental disclosure of the private key, the Deep Security Manager will not return this value; it can only be used to set the private key.

Note: the private key is only used if the credential is stored in the DSM's database. For credentials that are stored on the host, use the identifier instead. If both an identifier and private key are provided, the identifier will be ignored.

allInterfaces
boolean
whether or not the SSL configuration applies to all interfaces.
allIPs
boolean
whether or not the SSL configuration applies to all IP addresses.
specificIP
string
the IP address for which the SSL configuration applies.

Example Request

GET /hosts/{hostID}/intrusion-prevention/ssl-configurations?maxItems={maxItems}&sslConfigurationID={sslConfigurationID}&sslConfigurationIDOp={sslConfigurationIDOp}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ListSSLConfigurationsResponse": {
    "sslConfigurations": [ {
      "id": 12345,
      "enabled": true,
      "name": "Example Configuration",
      "description": "...",
      "ports": [ 12345, 12345 ],
      "portListID": 99999,
      "sslCredential": {
        "id": 12345,
        "type": "pem",
        "name": "Example Credential",
        "identifier": "EMPTY_STRING",
        "passphrase": "null",
        "details": "...",
        "privateKey": "WW91IHdlcmVuJ3QgZXhwZWN0aW5nIGEgcmVhbCBwcml2YXRlIGtleSwgd2VyZSB5b3U/Cg=="
      },
      "allInterfaces": true,
      "allIPs": true,
      "specificIP": "EMPTY_STRING"
    }, {
      "id": 12345,
      "enabled": true,
      "name": "Example Configuration",
      "description": "...",
      "ports": [ 12345, 12345 ],
      "portListID": 99999,
      "sslCredential": {
        "id": 12345,
        "type": "pem",
        "name": "Example Credential",
        "identifier": "EMPTY_STRING",
        "passphrase": "null",
        "details": "...",
        "privateKey": "WW91IHdlcmVuJ3QgZXhwZWN0aW5nIGEgcmVhbCBwcml2YXRlIGtleSwgd2VyZSB5b3U/Cg=="
      },
      "allInterfaces": true,
      "allIPs": true,
      "specificIP": "EMPTY_STRING"
    } ]
  }
}
                    
                  

Create an SSL configuration

Create a new SSL configuration.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API

Path Parameters

hostID
integer
the ID of the host for which the new SSL configuration is being created

Request Body

CreateSSLConfigurationRequest
a CreateSSLConfigurationRequest describing the SSL configuration details
Properties
sslConfiguration
the SSL configuration details

Response Codes

200
if the request is successful
400
if the request object is not provided
403
if the user is authorized to view but not update the host information
404
if the host is not found or the user is not authorized to view the host information
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

CreateSSLConfigurationResponse
a CreateSSLConfigurationResponse containing the created SSL configuration details
Properties
sslConfiguration
the SSL configuration details

Example Request

POST /hosts/{hostID}/intrusion-prevention/ssl-configurations
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "CreateSSLConfigurationRequest": {
    "sslConfiguration": {
      "id": 12345,
      "enabled": true,
      "name": "Example Configuration",
      "description": "...",
      "ports": [ 12345, 12345 ],
      "portListID": 99999,
      "sslCredential": {
        "id": 12345,
        "type": "pem",
        "name": "Example Credential",
        "identifier": "EMPTY_STRING",
        "passphrase": "null",
        "details": "...",
        "privateKey": "WW91IHdlcmVuJ3QgZXhwZWN0aW5nIGEgcmVhbCBwcml2YXRlIGtleSwgd2VyZSB5b3U/Cg=="
      },
      "allInterfaces": true,
      "allIPs": true,
      "specificIP": "EMPTY_STRING"
    }
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "CreateSSLConfigurationResponse": {
    "sslConfiguration": {
      "id": 12345,
      "enabled": true,
      "name": "Example Configuration",
      "description": "...",
      "ports": [ 12345, 12345 ],
      "portListID": 99999,
      "sslCredential": {
        "id": 12345,
        "type": "pem",
        "name": "Example Credential",
        "identifier": "EMPTY_STRING",
        "passphrase": "null",
        "details": "...",
        "privateKey": "WW91IHdlcmVuJ3QgZXhwZWN0aW5nIGEgcmVhbCBwcml2YXRlIGtleSwgd2VyZSB5b3U/Cg=="
      },
      "allInterfaces": true,
      "allIPs": true,
      "specificIP": "EMPTY_STRING"
    }
  }
}
                    
                  

Delete an SSL configuration

Delete an SSL configuration.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API

Path Parameters

hostID
integer
the ID of the host to which the SSL configuration belongs
id
integer

Response Codes

204
if the request is successful
403
if the user is authorized to view but not update the host information
404
if the host is not found or the user is not authorized to view the host information
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Example Request

DELETE /hosts/{hostID}/intrusion-prevention/ssl-configurations/{id}
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 204 No Content
                  

Describe an SSL configuration

Get details of an SSL configuration.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API

Path Parameters

hostID
integer
the ID of the host to which the SSL configuration belongs
id
integer
the SSL configuration ID

Response Codes

200
if the request is successful
404
if the host is not found or the user is not authorized to view the host information
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

DescribeSSLConfigurationResponse
an SSLConfiguration object with the SSL configuration details
Properties
sslConfiguration
the SSL configuration details

Example Request

GET /hosts/{hostID}/intrusion-prevention/ssl-configurations/{id}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "DescribeSSLConfigurationResponse": {
    "sslConfiguration": {
      "id": 12345,
      "enabled": true,
      "name": "Example Configuration",
      "description": "...",
      "ports": [ 12345, 12345 ],
      "portListID": 99999,
      "sslCredential": {
        "id": 12345,
        "type": "pem",
        "name": "Example Credential",
        "identifier": "EMPTY_STRING",
        "passphrase": "null",
        "details": "...",
        "privateKey": "WW91IHdlcmVuJ3QgZXhwZWN0aW5nIGEgcmVhbCBwcml2YXRlIGtleSwgd2VyZSB5b3U/Cg=="
      },
      "allInterfaces": true,
      "allIPs": true,
      "specificIP": "EMPTY_STRING"
    }
  }
}
                    
                  

Modify an SSL configuration

Modify an SSL configuration.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API

Path Parameters

hostID
integer
the ID of the host to which the SSL configuration belongs
id
integer
the SSL configuration ID

Request Body

ModifySSLConfigurationRequest
the ModifySSLConfigurationRequest containing the updated SSL configuration details
Properties
sslConfiguration
the SSL configuration details

Response Codes

200
if the request is successful
400
if the request object is not provided
403
if the user is authorized to view but not update the host information
404
if the host is not found or the user is not authorized to view the host information
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ModifySSLConfigurationResponse
a ModifySSLConfigurationResponse containing the updated SSL configuration
Properties
sslConfiguration
the SSL configuration details

Example Request

POST /hosts/{hostID}/intrusion-prevention/ssl-configurations/{id}
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "ModifySSLConfigurationRequest": {
    "sslConfiguration": {
      "id": 12345,
      "enabled": true,
      "name": "Example Configuration",
      "description": "...",
      "ports": [ 12345, 12345 ],
      "portListID": 99999,
      "sslCredential": {
        "id": 12345,
        "type": "pem",
        "name": "Example Credential",
        "identifier": "EMPTY_STRING",
        "passphrase": "null",
        "details": "...",
        "privateKey": "WW91IHdlcmVuJ3QgZXhwZWN0aW5nIGEgcmVhbCBwcml2YXRlIGtleSwgd2VyZSB5b3U/Cg=="
      },
      "allInterfaces": true,
      "allIPs": true,
      "specificIP": "EMPTY_STRING"
    }
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ModifySSLConfigurationResponse": {
    "sslConfiguration": {
      "id": 12345,
      "enabled": true,
      "name": "Example Configuration",
      "description": "...",
      "ports": [ 12345, 12345 ],
      "portListID": 99999,
      "sslCredential": {
        "id": 12345,
        "type": "pem",
        "name": "Example Credential",
        "identifier": "EMPTY_STRING",
        "passphrase": "null",
        "details": "...",
        "privateKey": "WW91IHdlcmVuJ3QgZXhwZWN0aW5nIGEgcmVhbCBwcml2YXRlIGtleSwgd2VyZSB5b3U/Cg=="
      },
      "allInterfaces": true,
      "allIPs": true,
      "specificIP": "EMPTY_STRING"
    }
  }
}
                    
                  

Scheduled tasks

Interface to the Scheduled Task API.

List scheduled tasks

List scheduled tasks.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Query Parameters

id
integer
(optional) used to define the starting point for the query. Combine with op to page through results.
maxItems
integer
(optional) the number of items to retrieve. The maximum value for this parameter is controlled by the "Maximum number of items to retrieve from database" setting on the administrator account, which defaults to 5000.
op
string
(optional, required if id is specified) Currently supported operations are:
  • gt (greater than)
  • ge (greater than or equal to)
  • eq (equal to)
  • lt (less than)
  • le (less than or equal to)

Response Codes

200
if the request is successful
403
if the user is not authorized to view scheduled tasks
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ListScheduledTasksResponse
a ListScheduledTaskResponse with the task details.
Properties
scheduledTasks
ScheduledTask
the list of scheduled tasks.
Properties
ID
number
the task's identifier.
name
string
the name to use when displaying this task.
type
Type
the task's type.
Values
scan-for-open-ports
send-alert-summary
discover-computers
run-script
send-policy
generate-report
synchronize-directory
synchronize-users
scan-for-recommendations
synchronize-vcenter
scan-for-integrity-changes
scan-for-malware
check-for-security-updates
synchronize-cloud-account
check-for-software-updates
update-suspicious-objects-list
schedule
Schedule
the schedule details for this task.
Properties
startTime
number
the start time for the task.
recurrenceType
RecurrenceType
the recurrence type for the task.
Values
none
The task runs once but does not recur.
hourly
The task runs at the same time every hour. The startTime parameter controls the time.
daily
The task runs daily. See DailyScheduleParameters for details.
weekly
The task runs weekly. See WeeklyScheduleParameters for details.
monthly
The task runs monthly. See MonthlyScheduleParameters for details.
recurrenceCount
number
the recurrence count for the task.

A recurrence count of zero implies that the task will continue to recur forever. A value greater than zero is a count which is decremented every time the task runs, and when the defined number of task executions is reached the task is automatically deleted.

dailyScheduleParameters
DailyScheduleParameters
the daily schedule parameters for the task.

A DailyScheduleParameters object is required whenever the RecurrenceType is Daily. The DailyScheduleParameters is not valid with any other {@code RecurrenceType.

Properties
frequencyType
FrequencyType
the frequency type.
Values
everyday
Run the task every day.
weekdays
Run the task Monday to Friday, but not on Saturday or Sunday.
custom
Define a custom frequency.
customInterval
number
the custom interval.
weeklyScheduleParameters
WeeklyScheduleParameters
the weekly schedule parameters for the task.

A WeeklyScheduleParameters object is required whenever the RecurrenceType is Weekly. The WeeklyScheduleParameters is not valid with any other {@code RecurrenceType.

Properties
interval
number
the interval (weeks between runs).
days
Day
the days of the week when the task will run.
Values
sunday
monday
tuesday
wednesday
thursday
friday
saturday
monthlyScheduleParameters
MonthlyScheduleParameters
the monthly schedule parameters for the task.

A MonthlyScheduleParameters object is required whenever the RecurrenceType is Monthly. The MonthlyScheduleParameters is not valid with any other {@code RecurrenceType.

Properties
frequencyType
FrequencyType
the frequency type.
Values
day-of-month
A specific day each month (e.g. the 3rd).
last-day-of-month
The last day of the month, regardless of how many days are in each month.
custom
A custom schedule to run on a specific day within a specific week each month (e.g. second Tuesday of the month).
dayOfMonth
number
the day of month.
weekOfMonth
Week
the week of month.
Values
first
second
third
fourth
last
dayOfWeek
Day
the day of week.
Values
sunday
monday
tuesday
wednesday
thursday
friday
saturday
months
Month
the months.
Values
january
feburary
march
april
may
june
july
august
september
october
november
december
enabled
boolean
the enabled state for this task.
timeZone
string
the task time zone.

Deep Security will attempt to parse the time zone identifier you provide and translate it into an internal identifier. When you retrieve the time zone from Deep Security, you will get one of the IANA Time Zone Database identifiers.

If you don't provide a time zone, the system will set the task time zone to the system local time zone. If you provide a time zone that Deep Security can't parse, the task time zone will be set to GMT.

lastRunTime
number
the last run time for this task.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

nextRunTime
number
the next run time for this task.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

scanForOpenPortsTaskParameters
ScanForOpenPortsTaskParameters
the scan for open ports task parameters.
Properties
hostFilter
HostFilter
the host filter.
Properties
type
Type
the host filter type.
Values
host
Include only a specific host. This option requires the hostID value to identify the host.
all-hosts
Include all hosts.
hosts-in-hostgroup
Include all hosts in a specific host group. This option requires the hostGroupID value to identify the host group.
hosts-in-group-or-subgroup
Include all hosts in a specific host group or sub-groups. This option requires the hostGroupID. value to identify the top-level host group.
hosts-using-policy
Include all hosts using a specific security policy. This option requires the policyID value to identify the policy.
hosts-using-policy-or-descendant
Include all hosts using a specific security policy or descendant policies. This option requires the policyID value to identify the top-level policy.
hosts-in-smart-folder
Include all hosts in a smart folder. This option requires the smartFolderID value to identify the smart folder.
hostID
number
the host identifier.
hostGroupID
number
the host group identifier.
policyID
number
the policy identifier.
smartFolderID
number
the smart folder identifier.
sendAlertSummaryTaskParameters
SendAlertSummaryTaskParameters
the send alert summary task parameters.
Properties
recipients
Recipients
the recipients.
Properties
allAdministrators
boolean
the all administrators flag.

When set to true this flag overrides any specific administrators or contacts associated with the scheduled task. When set to false then at least one administrator or contact must be specified.

administratorIDs
number
the list of administrator identifiers.

You can also use ScheduledTaskAPI.modifyAdministratorsList, ScheduledTaskAPI.addAdministrators, and ScheduledTaskAPI.deleteAdministrator to define the administrators associated with a scheduled task.

The list of administrators is ignored if the AllAdministrators value is set to true.

contactIDs
number
the list of contact identifiers.

You can also use ScheduledTaskAPI.modifyContactsList, ScheduledTaskAPI.addContacts, and ScheduledTaskAPI.deleteContact to define the contacts associated with a scheduled task.

The list of contacts is ignored if the AllAdministrators value is set to true.

discoverComputersTaskParameters
DiscoverComputersTaskParameters
the discover computers task parameters.
Properties
type
SearchType
the search type.
Values
range
Discover computers within a range of addresses. This type requires the ipRangeLow and ipRangeHigh values to define the search criteria.

Note that only IPv4 addresses are supported at this time.

masked-ip
Discover computers based on an IP Address and a Mask. This type requires the ip and ipMask values to define the search criteria.

Note that only IPv4 addresses are supported at this time.

IP
string
the IP Address for a Masked IP search.

Note that only IPv4 addresses are supported at this time.

IPMask
string
the Mask for a Masked IP search.

Note that only IPv4 addresses are supported at this time.

IPRangeLow
string
the low IP Address for a Range search.

Note that only IPv4 addresses are supported at this time.

IPRangeHigh
string
the high IP Address for a Range search.

Note that only IPv4 addresses are supported at this time.

scanDiscoveredComputers
boolean
Automatically scan discovered computers for open ports?
resolveIPs
boolean
Automatically resolve IP Addresses of discovered computers?

If set true then the IP address will be used to obtain an InetAddress, and from that the host name will be obtained. If set false then the IP address will be used as the host name.

hostGroupID
number
the host group identifier that will be assigned to discovered computers.
runScriptTaskParameters
RunScriptTaskParameters
the run script task parameters.
Properties
filename
string
the script filename.
sendPolicyTaskParameters
SendPolicyTaskParameters
the send policy task parameters.
Properties
hostFilter
the host filter.
generateReportTaskParameters
GenerateReportTaskParameters
the generate report task parameters.
Properties
reportID
number
the report identifier.
format
the report format.
Values
pdf
csv
html
plaintext
rtf
xls
xml
classification
Classification
the report classification.
Values
blank
topsecret
secret
confidential
official
les
limited
unclassified
internal
recipients
the report recipients.
timeRange
TimeRange
the time range.
Properties
unit
Unit
the unit.
Values
hour
day
week
month
value
number
the value.
tagFilter
TagFilter
the tag filter.
Properties
type
Type
the type.
Values
all
Include both tagged and untagged objects.
untagged
Include only untagged objects.
tags
Include only tagged objects. The value defines the specific tag(s) to include.
value
string
the value.
hostFilter
the host filter.
synchronizeDirectoryTaskParameters
SynchronizeDirectoryTaskParameters
the synchronize directory task parameters.
Properties
hostGroupID
number
the host group identifier.
scanForRecommendationsTaskParameters
ScanForRecommendationsTaskParameters
the scan for recommendations task parameters.
Properties
hostFilter
the host filter.
synchronizeVCenterTaskParameters
SynchronizeVCenterTaskParameters
the synchronize vcenter task parameters.
Properties
hostGroupID
number
the host group identifier.
scanForIntegrityChangesTaskParameters
ScanForIntegrityChangesTaskParameters
the scan for integrity changes task parameters.
Properties
hostFilter
the host filter.
trustedComputers
TrustedComputers
the trusted computers filter.
Values
all-computers
Scan all computers.
trusted-computers-only
Scan only trusted computers.
exclude-trusted-computers
Scan only untrusted computers.
scanForMalwareTaskParameters
ScanForMalwareTaskParameters
the scan for malware task parameters.
Properties
hostFilter
the host filter.
timeoutMinutes
number
the timeout minutes.
checkForSecurityUpdatesTaskParameters
CheckForSecurityUpdatesTaskParameters
the check for security updates task parameters.
Properties
hostFilter
the host filter.
synchronizeCloudAccountTaskParameters
SynchronizeCloudAccountTaskParameters
the synchronize cloud account task parameters.
Properties
hostGroupID
number
the host group identifier.
updateSuspiciousObjectsListTaskParameters
UpdateSuspiciousObjectsListTaskParameters
the update suspicious objects list task parameters.
Properties
hostFilter
the host filter.

Example Request

GET /tasks/scheduled?id={id}&maxItems={maxItems}&op={op}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ListScheduledTasksResponse": {
    "scheduledTasks": [ {
      "ID": 12345,
      "name": "...",
      "type": "scan-for-recommendations",
      "schedule": {
        "startTime": 12345,
        "recurrenceType": "monthly",
        "recurrenceCount": 12345,
        "dailyScheduleParameters": { },
        "weeklyScheduleParameters": { },
        "monthlyScheduleParameters": { }
      },
      "enabled": true,
      "timeZone": "...",
      "lastRunTime": 12345,
      "nextRunTime": 12345,
      "scanForOpenPortsTaskParameters": {
        "hostFilter": { }
      },
      "sendAlertSummaryTaskParameters": {
        "recipients": { }
      },
      "discoverComputersTaskParameters": {
        "type": "masked-ip",
        "IP": "...",
        "IPMask": "...",
        "IPRangeLow": "...",
        "IPRangeHigh": "...",
        "scanDiscoveredComputers": true,
        "resolveIPs": true,
        "hostGroupID": 12345
      },
      "runScriptTaskParameters": {
        "filename": "..."
      },
      "sendPolicyTaskParameters": {
        "hostFilter": { }
      },
      "generateReportTaskParameters": {
        "reportID": 12345,
        "format": "pdf",
        "classification": "internal",
        "recipients": { },
        "timeRange": { },
        "tagFilter": { },
        "hostFilter": { }
      },
      "synchronizeDirectoryTaskParameters": {
        "hostGroupID": 12345
      },
      "scanForRecommendationsTaskParameters": {
        "hostFilter": { }
      },
      "synchronizeVCenterTaskParameters": {
        "hostGroupID": 12345
      },
      "scanForIntegrityChangesTaskParameters": {
        "hostFilter": { },
        "trustedComputers": "trusted-computers-only"
      },
      "scanForMalwareTaskParameters": {
        "hostFilter": { },
        "timeoutMinutes": 12345
      },
      "checkForSecurityUpdatesTaskParameters": {
        "hostFilter": { }
      },
      "synchronizeCloudAccountTaskParameters": {
        "hostGroupID": 12345
      },
      "updateSuspiciousObjectsListTaskParameters": {
        "hostFilter": { }
      }
    }, {
      "ID": 12345,
      "name": "...",
      "type": "synchronize-vcenter",
      "schedule": {
        "startTime": 12345,
        "recurrenceType": "daily",
        "recurrenceCount": 12345,
        "dailyScheduleParameters": { },
        "weeklyScheduleParameters": { },
        "monthlyScheduleParameters": { }
      },
      "enabled": true,
      "timeZone": "...",
      "lastRunTime": 12345,
      "nextRunTime": 12345,
      "scanForOpenPortsTaskParameters": {
        "hostFilter": { }
      },
      "sendAlertSummaryTaskParameters": {
        "recipients": { }
      },
      "discoverComputersTaskParameters": {
        "type": "range",
        "IP": "...",
        "IPMask": "...",
        "IPRangeLow": "...",
        "IPRangeHigh": "...",
        "scanDiscoveredComputers": true,
        "resolveIPs": true,
        "hostGroupID": 12345
      },
      "runScriptTaskParameters": {
        "filename": "..."
      },
      "sendPolicyTaskParameters": {
        "hostFilter": { }
      },
      "generateReportTaskParameters": {
        "reportID": 12345,
        "format": "plaintext",
        "classification": "unclassified",
        "recipients": { },
        "timeRange": { },
        "tagFilter": { },
        "hostFilter": { }
      },
      "synchronizeDirectoryTaskParameters": {
        "hostGroupID": 12345
      },
      "scanForRecommendationsTaskParameters": {
        "hostFilter": { }
      },
      "synchronizeVCenterTaskParameters": {
        "hostGroupID": 12345
      },
      "scanForIntegrityChangesTaskParameters": {
        "hostFilter": { },
        "trustedComputers": "all-computers"
      },
      "scanForMalwareTaskParameters": {
        "hostFilter": { },
        "timeoutMinutes": 12345
      },
      "checkForSecurityUpdatesTaskParameters": {
        "hostFilter": { }
      },
      "synchronizeCloudAccountTaskParameters": {
        "hostGroupID": 12345
      },
      "updateSuspiciousObjectsListTaskParameters": {
        "hostFilter": { }
      }
    } ]
  }
}
                    
                  

Create a scheduled task

Create a new scheduled task.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Query Parameters

runNow
boolean

Request Body

CreateScheduledTaskRequest
a CreateScheduledTaskRequest with the scheduled task details.
Properties
scheduledTask
the scheduled task.

Response Codes

200
if the request is successful
403
if the user is not authorized to create scheduled tasks
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

CreateScheduledTaskResponse
a CreateScheduledTaskResponse with the scheduled task details.
Properties
scheduledTask
the scheduled task.

Example Request

POST /tasks/scheduled?runNow={runNow}
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "CreateScheduledTaskRequest": {
    "scheduledTask": {
      "ID": 12345,
      "name": "...",
      "type": "run-script",
      "schedule": {
        "startTime": 12345,
        "recurrenceType": "none",
        "recurrenceCount": 12345,
        "dailyScheduleParameters": { },
        "weeklyScheduleParameters": { },
        "monthlyScheduleParameters": { }
      },
      "enabled": true,
      "timeZone": "...",
      "lastRunTime": 12345,
      "nextRunTime": 12345,
      "scanForOpenPortsTaskParameters": {
        "hostFilter": { }
      },
      "sendAlertSummaryTaskParameters": {
        "recipients": { }
      },
      "discoverComputersTaskParameters": {
        "type": "masked-ip",
        "IP": "...",
        "IPMask": "...",
        "IPRangeLow": "...",
        "IPRangeHigh": "...",
        "scanDiscoveredComputers": true,
        "resolveIPs": true,
        "hostGroupID": 12345
      },
      "runScriptTaskParameters": {
        "filename": "..."
      },
      "sendPolicyTaskParameters": {
        "hostFilter": { }
      },
      "generateReportTaskParameters": {
        "reportID": 12345,
        "format": "html",
        "classification": "confidential",
        "recipients": { },
        "timeRange": { },
        "tagFilter": { },
        "hostFilter": { }
      },
      "synchronizeDirectoryTaskParameters": {
        "hostGroupID": 12345
      },
      "scanForRecommendationsTaskParameters": {
        "hostFilter": { }
      },
      "synchronizeVCenterTaskParameters": {
        "hostGroupID": 12345
      },
      "scanForIntegrityChangesTaskParameters": {
        "hostFilter": { },
        "trustedComputers": "trusted-computers-only"
      },
      "scanForMalwareTaskParameters": {
        "hostFilter": { },
        "timeoutMinutes": 12345
      },
      "checkForSecurityUpdatesTaskParameters": {
        "hostFilter": { }
      },
      "synchronizeCloudAccountTaskParameters": {
        "hostGroupID": 12345
      },
      "updateSuspiciousObjectsListTaskParameters": {
        "hostFilter": { }
      }
    }
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "CreateScheduledTaskResponse": {
    "scheduledTask": {
      "ID": 12345,
      "name": "...",
      "type": "synchronize-users",
      "schedule": {
        "startTime": 12345,
        "recurrenceType": "hourly",
        "recurrenceCount": 12345,
        "dailyScheduleParameters": { },
        "weeklyScheduleParameters": { },
        "monthlyScheduleParameters": { }
      },
      "enabled": true,
      "timeZone": "...",
      "lastRunTime": 12345,
      "nextRunTime": 12345,
      "scanForOpenPortsTaskParameters": {
        "hostFilter": { }
      },
      "sendAlertSummaryTaskParameters": {
        "recipients": { }
      },
      "discoverComputersTaskParameters": {
        "type": "masked-ip",
        "IP": "...",
        "IPMask": "...",
        "IPRangeLow": "...",
        "IPRangeHigh": "...",
        "scanDiscoveredComputers": true,
        "resolveIPs": true,
        "hostGroupID": 12345
      },
      "runScriptTaskParameters": {
        "filename": "..."
      },
      "sendPolicyTaskParameters": {
        "hostFilter": { }
      },
      "generateReportTaskParameters": {
        "reportID": 12345,
        "format": "rtf",
        "classification": "topsecret",
        "recipients": { },
        "timeRange": { },
        "tagFilter": { },
        "hostFilter": { }
      },
      "synchronizeDirectoryTaskParameters": {
        "hostGroupID": 12345
      },
      "scanForRecommendationsTaskParameters": {
        "hostFilter": { }
      },
      "synchronizeVCenterTaskParameters": {
        "hostGroupID": 12345
      },
      "scanForIntegrityChangesTaskParameters": {
        "hostFilter": { },
        "trustedComputers": "all-computers"
      },
      "scanForMalwareTaskParameters": {
        "hostFilter": { },
        "timeoutMinutes": 12345
      },
      "checkForSecurityUpdatesTaskParameters": {
        "hostFilter": { }
      },
      "synchronizeCloudAccountTaskParameters": {
        "hostGroupID": 12345
      },
      "updateSuspiciousObjectsListTaskParameters": {
        "hostFilter": { }
      }
    }
  }
}
                    
                  

Delete a scheduled task

Delete a scheduled task.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

scheduledTaskID
integer
the scheduled task identifier.

Response Codes

200
if the request is successful
403
if the user is not authorized to delete scheduled tasks
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Example Request

DELETE /tasks/scheduled/{scheduledTaskID}
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
                  

Describe a scheduled task

Describe a scheduled task.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

scheduledTaskID
integer
the scheduled task identifier.

Response Codes

200
if the request is successful
403
if the user is not authorized to view scheduled tasks
404
if the user is authorized to view scheduled tasks but the scheduled task does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

DescribeScheduledTaskResponse
a DescribeScheduledTaskResponse with the scheduled task details.
Properties
scheduledTask
the scheduled task.

Example Request

GET /tasks/scheduled/{scheduledTaskID}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "DescribeScheduledTaskResponse": {
    "scheduledTask": {
      "ID": 12345,
      "name": "...",
      "type": "synchronize-vcenter",
      "schedule": {
        "startTime": 12345,
        "recurrenceType": "monthly",
        "recurrenceCount": 12345,
        "dailyScheduleParameters": { },
        "weeklyScheduleParameters": { },
        "monthlyScheduleParameters": { }
      },
      "enabled": true,
      "timeZone": "...",
      "lastRunTime": 12345,
      "nextRunTime": 12345,
      "scanForOpenPortsTaskParameters": {
        "hostFilter": { }
      },
      "sendAlertSummaryTaskParameters": {
        "recipients": { }
      },
      "discoverComputersTaskParameters": {
        "type": "masked-ip",
        "IP": "...",
        "IPMask": "...",
        "IPRangeLow": "...",
        "IPRangeHigh": "...",
        "scanDiscoveredComputers": true,
        "resolveIPs": true,
        "hostGroupID": 12345
      },
      "runScriptTaskParameters": {
        "filename": "..."
      },
      "sendPolicyTaskParameters": {
        "hostFilter": { }
      },
      "generateReportTaskParameters": {
        "reportID": 12345,
        "format": "xml",
        "classification": "confidential",
        "recipients": { },
        "timeRange": { },
        "tagFilter": { },
        "hostFilter": { }
      },
      "synchronizeDirectoryTaskParameters": {
        "hostGroupID": 12345
      },
      "scanForRecommendationsTaskParameters": {
        "hostFilter": { }
      },
      "synchronizeVCenterTaskParameters": {
        "hostGroupID": 12345
      },
      "scanForIntegrityChangesTaskParameters": {
        "hostFilter": { },
        "trustedComputers": "exclude-trusted-computers"
      },
      "scanForMalwareTaskParameters": {
        "hostFilter": { },
        "timeoutMinutes": 12345
      },
      "checkForSecurityUpdatesTaskParameters": {
        "hostFilter": { }
      },
      "synchronizeCloudAccountTaskParameters": {
        "hostGroupID": 12345
      },
      "updateSuspiciousObjectsListTaskParameters": {
        "hostFilter": { }
      }
    }
  }
}
                    
                  

Modify a scheduled task

Modify a scheduled task.

Any unset elements in the request object will be left unchanged by the modify request.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

scheduledTaskID
integer
the scheduled task identifier.

Query Parameters

runNow
boolean

Request Body

ModifyScheduledTaskRequest
a ModifyScheduledTaskRequest with the details of the scheduled task.
Properties
scheduledTask
the task.

Response Codes

200
if the request is successful
403
if the user is not authorized to modify scheduled tasks or if the requested modification is not permitted
404
if the user is authorized to modify scheduled tasks but the scheduled task does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ModifyScheduledTaskResponse
a ModifyScheduledTaskResponse with the updated scheduled task details.
Properties
scheduledTask
the scheduled task.

Example Request

POST /tasks/scheduled/{scheduledTaskID}?runNow={runNow}
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "ModifyScheduledTaskRequest": {
    "scheduledTask": {
      "ID": 12345,
      "name": "...",
      "type": "update-suspicious-objects-list",
      "schedule": {
        "startTime": 12345,
        "recurrenceType": "weekly",
        "recurrenceCount": 12345,
        "dailyScheduleParameters": { },
        "weeklyScheduleParameters": { },
        "monthlyScheduleParameters": { }
      },
      "enabled": true,
      "timeZone": "...",
      "lastRunTime": 12345,
      "nextRunTime": 12345,
      "scanForOpenPortsTaskParameters": {
        "hostFilter": { }
      },
      "sendAlertSummaryTaskParameters": {
        "recipients": { }
      },
      "discoverComputersTaskParameters": {
        "type": "masked-ip",
        "IP": "...",
        "IPMask": "...",
        "IPRangeLow": "...",
        "IPRangeHigh": "...",
        "scanDiscoveredComputers": true,
        "resolveIPs": true,
        "hostGroupID": 12345
      },
      "runScriptTaskParameters": {
        "filename": "..."
      },
      "sendPolicyTaskParameters": {
        "hostFilter": { }
      },
      "generateReportTaskParameters": {
        "reportID": 12345,
        "format": "plaintext",
        "classification": "unclassified",
        "recipients": { },
        "timeRange": { },
        "tagFilter": { },
        "hostFilter": { }
      },
      "synchronizeDirectoryTaskParameters": {
        "hostGroupID": 12345
      },
      "scanForRecommendationsTaskParameters": {
        "hostFilter": { }
      },
      "synchronizeVCenterTaskParameters": {
        "hostGroupID": 12345
      },
      "scanForIntegrityChangesTaskParameters": {
        "hostFilter": { },
        "trustedComputers": "all-computers"
      },
      "scanForMalwareTaskParameters": {
        "hostFilter": { },
        "timeoutMinutes": 12345
      },
      "checkForSecurityUpdatesTaskParameters": {
        "hostFilter": { }
      },
      "synchronizeCloudAccountTaskParameters": {
        "hostGroupID": 12345
      },
      "updateSuspiciousObjectsListTaskParameters": {
        "hostFilter": { }
      }
    }
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ModifyScheduledTaskResponse": {
    "scheduledTask": {
      "ID": 12345,
      "name": "...",
      "type": "send-policy",
      "schedule": {
        "startTime": 12345,
        "recurrenceType": "monthly",
        "recurrenceCount": 12345,
        "dailyScheduleParameters": { },
        "weeklyScheduleParameters": { },
        "monthlyScheduleParameters": { }
      },
      "enabled": true,
      "timeZone": "...",
      "lastRunTime": 12345,
      "nextRunTime": 12345,
      "scanForOpenPortsTaskParameters": {
        "hostFilter": { }
      },
      "sendAlertSummaryTaskParameters": {
        "recipients": { }
      },
      "discoverComputersTaskParameters": {
        "type": "range",
        "IP": "...",
        "IPMask": "...",
        "IPRangeLow": "...",
        "IPRangeHigh": "...",
        "scanDiscoveredComputers": true,
        "resolveIPs": true,
        "hostGroupID": 12345
      },
      "runScriptTaskParameters": {
        "filename": "..."
      },
      "sendPolicyTaskParameters": {
        "hostFilter": { }
      },
      "generateReportTaskParameters": {
        "reportID": 12345,
        "format": "xls",
        "classification": "les",
        "recipients": { },
        "timeRange": { },
        "tagFilter": { },
        "hostFilter": { }
      },
      "synchronizeDirectoryTaskParameters": {
        "hostGroupID": 12345
      },
      "scanForRecommendationsTaskParameters": {
        "hostFilter": { }
      },
      "synchronizeVCenterTaskParameters": {
        "hostGroupID": 12345
      },
      "scanForIntegrityChangesTaskParameters": {
        "hostFilter": { },
        "trustedComputers": "all-computers"
      },
      "scanForMalwareTaskParameters": {
        "hostFilter": { },
        "timeoutMinutes": 12345
      },
      "checkForSecurityUpdatesTaskParameters": {
        "hostFilter": { }
      },
      "synchronizeCloudAccountTaskParameters": {
        "hostGroupID": 12345
      },
      "updateSuspiciousObjectsListTaskParameters": {
        "hostFilter": { }
      }
    }
  }
}
                    
                  

Modify recipients list - add administrators

Modify a scheduled task's recipients list to add administrators.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

scheduledTaskID
integer
the scheduled task identifier.

Request Body

ModifyAdministratorsListRequest
a ModifyAdministratorsListRequest with the details of the administrators list.
Properties
administrators
number
the administrators list.

Response Codes

200
if the request is successful
400
if the task does not support a recipients list
403
if the user is not authorized to modify scheduled tasks or if the requested modification is not permitted
404
if the user is authorized to modify scheduled tasks but the scheduled task does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ModifyAdministratorsListResponse
a ModifyAdministratorsListResponse with the updated administrators list details.
Properties
administrators
number
the administrators list.

Example Request

POST /tasks/scheduled/{scheduledTaskID}/recipients/administrators
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "ModifyAdministratorsListRequest": {
    "administrators": [ 12345, 12345 ]
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ModifyAdministratorsListResponse": {
    "administrators": [ 12345, 12345 ]
  }
}
                    
                  

Modify recipients list - replace administrators

Modify a scheduled task's recipients list with a new (complete) list of administrators.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

scheduledTaskID
integer
the scheduled task identifier.

Request Body

a ModifyAdministratorsListRequest with the details of the administrators list.

Response Codes

200
if the request is successful
400
if the task does not support a recipients list
403
if the user is not authorized to modify scheduled tasks or if the requested modification is not permitted
404
if the user is authorized to modify scheduled tasks but the scheduled task does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

a ModifyAdministratorsListResponse with the updated administrators list details.

Example Request

PUT /tasks/scheduled/{scheduledTaskID}/recipients/administrators
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "ModifyAdministratorsListRequest": {
    "administrators": [ 12345, 12345 ]
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ModifyAdministratorsListResponse": {
    "administrators": [ 12345, 12345 ]
  }
}
                    
                  

Modify recipients list - add contacts

Modify a scheduled task's recipients list with additional contacts.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

scheduledTaskID
integer
the scheduled task identifier.

Request Body

ModifyContactsListRequest
a ModifyContactsListRequest with the details of the contacts list.
Properties
contacts
number
the contacts list.

Response Codes

200
if the request is successful
400
if the task does not support a recipients list
403
if the user is not authorized to modify scheduled tasks or if the requested modification is not permitted
404
if the user is authorized to modify scheduled tasks but the scheduled task does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ModifyContactsListResponse
a ModifyContactsListResponse with the updated contacts list details.
Properties
contacts
number
the contacts list.

Example Request

POST /tasks/scheduled/{scheduledTaskID}/recipients/contacts
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "ModifyContactsListRequest": {
    "contacts": [ 12345, 12345 ]
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ModifyContactsListResponse": {
    "contacts": [ 12345, 12345 ]
  }
}
                    
                  

Modify recipients list - replace contacts

Modify a scheduled task's recipients list with a new (complete) list of contacts.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

scheduledTaskID
integer
the scheduled task identifier.

Request Body

a ModifyContactsListRequest with the details of the contacts list.

Response Codes

200
if the request is successful
400
if the task does not support a recipients list
403
if the user is not authorized to modify scheduled tasks or if the requested modification is not permitted
404
if the user is authorized to modify scheduled tasks but the scheduled task does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

a ModifyContactsListResponse with the updated contacts list details.

Example Request

PUT /tasks/scheduled/{scheduledTaskID}/recipients/contacts
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "ModifyContactsListRequest": {
    "contacts": [ 12345, 12345 ]
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ModifyContactsListResponse": {
    "contacts": [ 12345, 12345 ]
  }
}
                    
                  

Modify recipients list - remove administrator

Remove an administrator from a scheduled task's recipients list.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

administratorID
integer
the administrator identifier.
scheduledTaskID
integer
the scheduled task identifier.

Response Codes

200
if the request is successful
400
if the task does not support a recipients list
403
if the user is not authorized to edit scheduled tasks
404
if the user is authorized to edit scheduled tasks but the scheduled task does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

Example Request

DELETE /tasks/scheduled/{scheduledTaskID}/recipients/administrators/{administratorID}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ModifyAdministratorsListResponse": {
    "administrators": [ 12345, 12345 ]
  }
}
                    
                  

Modify recipients list - remove contact

Remove a contact from a scheduled task's recipients list

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

contactID
integer
the contact identifier
scheduledTaskID
integer
the scheduled task identifier

Response Codes

200
if the request is successful
400
if the task does not support a recipients list
403
if the user is not authorized to edit scheduled tasks
404
if the user is authorized to edit scheduled tasks but the scheduled task does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

Example Request

DELETE /tasks/scheduled/{scheduledTaskID}/recipients/contacts/{contactID}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ModifyContactsListResponse": {
    "contacts": [ 12345, 12345 ]
  }
}
                    
                  

Scripts

Interface to the Scripts API.

List scripts

List scripts.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Query Parameters

id
integer
(optional) used to define the starting point for the query. Combine with op to page through results.
maxItems
integer
(optional) the number of items to retrieve. The maximum value for this parameter is controlled by the "Maximum number of items to retrieve from database" setting on the administrator account, which defaults to 5000.
op
string
(optional, required if id is specified) Currently supported operations are:
  • gt (greater than)
  • ge (greater than or equal to)
  • eq (equal to)
  • lt (less than)
  • le (less than or equal to)

Response Codes

200
if the request is successful
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ListScriptsResponse
a ListScriptsResponse with the list of scripts.
Properties
scripts
Script
the list of scripts.
Properties
ID
number
the script identifier.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

name
string
the script name.

This system value is provided for information purposes and cannot be set through the API. Attempts to set or change this read-only value through the API will be ignored.

Example Request

GET /scripts?id={id}&maxItems={maxItems}&op={op}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ListScriptsResponse": {
    "scripts": [ {
      "ID": 12345,
      "name": "..."
    }, {
      "ID": 12345,
      "name": "..."
    } ]
  }
}
                    
                  

Sessions

Interface to the Session API.

End a session

End a session.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API or the ISessionAPI#assumeRoleWithSAML(AssumeRoleWithSAMLRequest) session API.

Response Codes

204
if the request is successful or if the session ID does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Example Request

DELETE /session
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 204 No Content
                  

Describe a session

Describe a session.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API or the ISessionAPI#assumeRoleWithSAML(AssumeRoleWithSAMLRequest) session API.

Response Codes

200
if the request is successful
403
if the session ID is invalid
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

DescribeSessionResponse
a DescribeSessionResponse with the session details.
Properties
session
Session
the session details.
Properties
administrator
the administrator details.
created
number
the time when the session was created, as the number of milliseconds since January 1, 1970, 00:00:00 GMT.
rights
string
the list of rights assigned to the current user.

Example Request

GET /session
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "DescribeSessionResponse": {
    "session": {
      "administrator": {
        "ID": 12345,
        "username": "...",
        "password": "...",
        "fullName": "...",
        "description": "...",
        "roleID": 12345,
        "locale": "...",
        "timeZone": "...",
        "timeFormat": "24",
        "passwordNeverExpires": true,
        "active": true,
        "mfaType": "none",
        "phoneNumber": "...",
        "mobileNumber": "...",
        "pagerNumber": "...",
        "emailAddress": "...",
        "primaryContact": true,
        "receiveNotifications": true,
        "reportPDFPasswordEnabled": true,
        "reportPDFPassword": "...",
        "created": 12345,
        "lastPasswordChange": 12345,
        "lastSignIn": 12345,
        "unlockTime": 12345,
        "unsuccessfulSignInAttempts": 12345,
        "directoryName": "...",
        "directoryInfo": "...",
        "external": true,
        "externalUserID": "...",
        "temporary": true,
        "readOnly": true
      },
      "created": 12345,
      "rights": [ "...", "..." ]
    }
  }
}
                    
                  

Assume a role using SAML

Assume a role using a SAML response from an authorized identity provider.

Request Body

AssumeRoleWithSAMLRequest
an AssumeRoleWithSAMLRequest containing the SAML document, the URN for the requested identity provider, and the URN for the requested role.
Properties
saml
string
the Base64-encoded SAML 2.0 response from the identity provider.
identityProvider
string
the identity provider URN on the Deep Security Manager.
role
string
the role URN on the Deep Security Manager.

Response Codes

200
if the request is successful
400
if the request is invalid
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

AssumeRoleWithSAMLResponse
an AssumeRoleWithSAMLResponse containing a session ID that can be used in future requests.
Properties
sessionID
string
the session ID.

Example Request

POST /session
Content-Type: application/json
Accept: application/json
                    
{
  "AssumeRoleWithSAMLRequest": {
    "saml": "...",
    "identityProvider": "...",
    "role": "..."
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "AssumeRoleWithSAMLResponse": {
    "sessionID": "..."
  }
}
                    
                  

Smart folders

List smart folders

Returns a list of all smart folders.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Response Codes

200
if the request was successful
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ListSmartFoldersResponse
Properties
smartFolders
SmartFolderSummary
the list of smart folders.
Properties
smartFolderId
number
the smart folder identifier.
name
string
the smart folder name.
parentSmartFolderId
number
the parent smart folder identifier.
type
number
the smart folder type: 1 - A standard query based smart folder 2 - A smart folder with an AWS tag hierarchy 3 - A child smart folder of a smart folder with AWS tag hierarchy (i.e. A smart folder representing an AWS tag value)
childSmartFolders
the list of child smart folders.

Example Request

GET /smart-folders
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ListSmartFoldersResponse": {
    "smartFolders": [ {
      "smartFolderId": 12345,
      "name": "...",
      "parentSmartFolderId": 12345,
      "type": 12345,
      "childSmartFolders": [ { }, { } ]
    }, {
      "smartFolderId": 12345,
      "name": "...",
      "parentSmartFolderId": 12345,
      "type": 12345,
      "childSmartFolders": [ { }, { } ]
    } ]
  }
}
                    
                  

Create a smart folder

Create a smart folder.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Request Body

CreateSmartFolderRequest
a CreateSmartFolderRequest object describing the smart folder.
Properties
name
string
the smart folder name.
comparison
Comparison
the comparator used to combine the Query Groups.
Values
AND
OR
queryGroups
QueryGroup
the list of Query Groups that make up the Smart Folder.
Properties
query
Query
the list of Queries in the group.
Properties
key
Key
the key that specifies the type of Query.
Values
GENERAL_HOST_NAME
GENERAL_DISPLAY_NAME
GENERAL_GROUP_NAME
GENERAL_OS
GENERAL_IP
GENERAL_POLICY
GENERAL_AGENT_ACTIVATED
GENERAL_DOCKER_RUNNING
GENERAL_COMPUTER_TYPE
GENERAL_LAST_RECOMMENDATION_RUN_TIME
GENERAL_LAST_AGENT_COMMUNICATION
GENERAL_AGENT_OFFLINE
GENERAL_HOST_CREATION_TIME
AWS_TAG
AWS_SECURITY_GROUP
AWS_SECURITY_GROUP_ID
AWS_AMI_ID
AWS_ACCOUNT_ID
AWS_ACCOUNT_ALIAS
AWS_REGION_ID
AWS_REGION_NAME
AWS_VPC_ID
AWS_SUBNET_ID
AWS_DIRECTORY_ID
AZURE_SUBSCRIPTION_NAME
AZURE_RESOURCE_GROUP
AZURE_LOCATION
VCENTER_NAME
VCENTER_DATACENTER
VCENTER_FOLDER
VCENTER_ESX_HOST
VCENTER_CUSTOM_ATTRIBUTE
VCLOUD_NAME
VCLOUD_DATACENTER
VCLOUD_APPLICATION
DIRECTORY_NAME
DIRECTORY_FOLDER
operator
Operator
the operator of the Query.
Values
EQUALS
NOT_EQUALS
CONTAINS
DOES_NOT_CONTAIN
ANY_VALUE
IN_RANGE
NOT_IN_RANGE
OLDER_THAN
MORE_RECENTLY_THAN
NEVER
BEFORE
AFTER
value
string
the value of the Query.
secondaryOperator
the secondary operator of the Query.
Values
EQUALS
NOT_EQUALS
CONTAINS
DOES_NOT_CONTAIN
ANY_VALUE
IN_RANGE
NOT_IN_RANGE
OLDER_THAN
MORE_RECENTLY_THAN
NEVER
BEFORE
AFTER
secondaryValue
string
the secondary value of the Query.
comparison
the comparator for combining the queries.
Values
AND
OR
awsTagFoldersNameKey
string
the Key of the AWS tag used to create an auto generated.
parent
number
the Id of the parent smart folder.
duplicateOf
number
the Id of the Smart Folder to duplicate.
operator
the operator of the Query.
Values
EQUALS
NOT_EQUALS
CONTAINS
DOES_NOT_CONTAIN
ANY_VALUE
IN_RANGE
NOT_IN_RANGE
OLDER_THAN
MORE_RECENTLY_THAN
NEVER
BEFORE
AFTER

Response Codes

200
if the request was successful
400
if the request is invalid
403
if the user is not authorized to create a smart folder
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

CreateSmartFolderResponse
a CreateSmartFolderResponse containing the ID of the created smart folder.
Properties
smartFolderID
number
the smart folder ID

Example Request

POST /smart-folders
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "CreateSmartFolderRequest": {
    "name": "...",
    "comparison": "AND",
    "queryGroups": [ {
      "query": [ {
        "key": "DIRECTORY_NAME",
        "operator": "MORE_RECENTLY_THAN",
        "value": "...",
        "secondaryOperator": "NEVER",
        "secondaryValue": "..."
      }, {
        "key": "GENERAL_AGENT_ACTIVATED",
        "operator": "EQUALS",
        "value": "...",
        "secondaryOperator": "DOES_NOT_CONTAIN",
        "secondaryValue": "..."
      } ],
      "comparison": "OR"
    }, {
      "query": [ {
        "key": "GENERAL_AGENT_ACTIVATED",
        "operator": "NOT_EQUALS",
        "value": "...",
        "secondaryOperator": "EQUALS",
        "secondaryValue": "..."
      }, {
        "key": "GENERAL_OS",
        "operator": "EQUALS",
        "value": "...",
        "secondaryOperator": "MORE_RECENTLY_THAN",
        "secondaryValue": "..."
      } ],
      "comparison": "AND"
    } ],
    "awsTagFoldersNameKey": "...",
    "parent": 12345,
    "duplicateOf": 12345,
    "operator": "OLDER_THAN"
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "CreateSmartFolderResponse": {
    "smartFolderID": 12345
  }
}
                    
                  

Delete a smart folder

Delete a smart folder.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

smartFolderID
integer
the smart folder ID.

Response Codes

204
if the request was successful
403
if the user is not authorized to delete a smart folder
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Example Request

DELETE /smart-folders/{smartFolderID}
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 204 No Content
                  

Describe a smart folder

Describe a smart folder.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

smartFolderID
integer
the smart folder ID.

Response Codes

200
if the request was successful
404
if the smart folder does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

SmartFolder
Properties
smartFolderId
number
the smart folder identifier.
name
string
the smart folder name.
parentSmartFolderId
number
the parent smart folder identifier.
type
number
the smart folder type: 1 - A standard query based smart folder 2 - A smart folder with an AWS tag hierarchy 3 - A child smart folder of a smart folder with AWS tag hierarchy (i.e. A smart folder representing an AWS tag value)
childSmartFolders
the list of child smart folders.
queryGroups
the smart folder query groups.
comparison
the comparator used to combine the query groups.
Values
AND
OR
awsTagFoldersNameKey
string
the key of the AWS tag used to create an AWS tag hierarchy.
parentSmartFolders
ParentSmartFolderSummary
-
Properties
smartFolderID
number
the Smart Folder identifier.
queryGroups
QueryGroupSummary
the query groups of the Smart Folder
Properties
queries
QuerySummary
the queries that make up the query group .
Properties
key
the key that specifies the type of Query.
Values
GENERAL_HOST_NAME
GENERAL_DISPLAY_NAME
GENERAL_GROUP_NAME
GENERAL_OS
GENERAL_IP
GENERAL_POLICY
GENERAL_AGENT_ACTIVATED
GENERAL_DOCKER_RUNNING
GENERAL_COMPUTER_TYPE
GENERAL_LAST_RECOMMENDATION_RUN_TIME
GENERAL_LAST_AGENT_COMMUNICATION
GENERAL_AGENT_OFFLINE
GENERAL_HOST_CREATION_TIME
AWS_TAG
AWS_SECURITY_GROUP
AWS_SECURITY_GROUP_ID
AWS_AMI_ID
AWS_ACCOUNT_ID
AWS_ACCOUNT_ALIAS
AWS_REGION_ID
AWS_REGION_NAME
AWS_VPC_ID
AWS_SUBNET_ID
AWS_DIRECTORY_ID
AZURE_SUBSCRIPTION_NAME
AZURE_RESOURCE_GROUP
AZURE_LOCATION
VCENTER_NAME
VCENTER_DATACENTER
VCENTER_FOLDER
VCENTER_ESX_HOST
VCENTER_CUSTOM_ATTRIBUTE
VCLOUD_NAME
VCLOUD_DATACENTER
VCLOUD_APPLICATION
DIRECTORY_NAME
DIRECTORY_FOLDER
displayKey
string
the readable string representation of the query key.
operator
The operator of the Query.
Values
EQUALS
NOT_EQUALS
CONTAINS
DOES_NOT_CONTAIN
ANY_VALUE
IN_RANGE
NOT_IN_RANGE
OLDER_THAN
MORE_RECENTLY_THAN
NEVER
BEFORE
AFTER
displayOperator
string
the readable string representation of the query operator.
value
string
the value of the Query.
secondaryOperator
the secondary operator of the Query.
Values
EQUALS
NOT_EQUALS
CONTAINS
DOES_NOT_CONTAIN
ANY_VALUE
IN_RANGE
NOT_IN_RANGE
OLDER_THAN
MORE_RECENTLY_THAN
NEVER
BEFORE
AFTER
secondaryDisplayOperator
string
the readable string representation of secondary operator.
secondaryValue
string
The secondary value of the Query.
comparison
the Query Group comparison.
Values
AND
OR
comparison
the comparison of the Smart Folder
Values
AND
OR
name
string
the name of the Smart Folder.

Example Request

GET /smart-folders/{smartFolderID}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "SmartFolder": {
    "smartFolderId": 12345,
    "name": "...",
    "parentSmartFolderId": 12345,
    "type": 12345,
    "childSmartFolders": [ {
      "smartFolderId": 12345,
      "name": "...",
      "parentSmartFolderId": 12345,
      "type": 12345,
      "childSmartFolders": [ { }, { } ]
    }, {
      "smartFolderId": 12345,
      "name": "...",
      "parentSmartFolderId": 12345,
      "type": 12345,
      "childSmartFolders": [ { }, { } ]
    } ],
    "queryGroups": [ {
      "query": [ {
        "key": "GENERAL_GROUP_NAME",
        "operator": "AFTER",
        "value": "...",
        "secondaryOperator": "NEVER",
        "secondaryValue": "..."
      }, {
        "key": "AWS_SECURITY_GROUP",
        "operator": "NEVER",
        "value": "...",
        "secondaryOperator": "MORE_RECENTLY_THAN",
        "secondaryValue": "..."
      } ],
      "comparison": "OR"
    }, {
      "query": [ {
        "key": "DIRECTORY_NAME",
        "operator": "ANY_VALUE",
        "value": "...",
        "secondaryOperator": "AFTER",
        "secondaryValue": "..."
      }, {
        "key": "GENERAL_LAST_RECOMMENDATION_RUN_TIME",
        "operator": "MORE_RECENTLY_THAN",
        "value": "...",
        "secondaryOperator": "EQUALS",
        "secondaryValue": "..."
      } ],
      "comparison": "OR"
    } ],
    "comparison": "OR",
    "awsTagFoldersNameKey": "...",
    "parentSmartFolders": [ {
      "smartFolderID": 12345,
      "queryGroups": [ {
        "queries": [ { }, { } ],
        "comparison": "OR"
      }, {
        "queries": [ { }, { } ],
        "comparison": "AND"
      } ],
      "comparison": "OR",
      "name": "..."
    }, {
      "smartFolderID": 12345,
      "queryGroups": [ {
        "queries": [ { }, { } ],
        "comparison": "AND"
      }, {
        "queries": [ { }, { } ],
        "comparison": "AND"
      } ],
      "comparison": "OR",
      "name": "..."
    } ]
  }
}
                    
                  

Modify a smart folder

Modify a smart folder.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

smartFolderID
integer

Request Body

UpdateSmartFolderRequest
a UpdateSmartFolderRequest object describing the smart folder.
Properties
name
string
the smart folder name.
comparison
the comparator used to combine the Query Groups.
Values
AND
OR
queryGroups
the list of Query Groups that make up the Smart Folder.
awsTagFoldersNameKey
string
the Key of the AWS tag used to create an auto generated.
parent
number
the Id of the parent smart folder.

Response Codes

200
if the request was successful
400
if the request is invalid
404
if the smart folder does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Example Request

POST /smart-folders/{smartFolderID}
Content-Type: application/json
Cookie: sID=12345;
                    
{
  "UpdateSmartFolderRequest": {
    "name": "...",
    "comparison": "AND",
    "queryGroups": [ {
      "query": [ {
        "key": "DIRECTORY_FOLDER",
        "operator": "DOES_NOT_CONTAIN",
        "value": "...",
        "secondaryOperator": "DOES_NOT_CONTAIN",
        "secondaryValue": "..."
      }, {
        "key": "AWS_VPC_ID",
        "operator": "CONTAINS",
        "value": "...",
        "secondaryOperator": "DOES_NOT_CONTAIN",
        "secondaryValue": "..."
      } ],
      "comparison": "AND"
    }, {
      "query": [ {
        "key": "VCENTER_DATACENTER",
        "operator": "DOES_NOT_CONTAIN",
        "value": "...",
        "secondaryOperator": "BEFORE",
        "secondaryValue": "..."
      }, {
        "key": "AZURE_LOCATION",
        "operator": "EQUALS",
        "value": "...",
        "secondaryOperator": "IN_RANGE",
        "secondaryValue": "..."
      } ],
      "comparison": "OR"
    } ],
    "awsTagFoldersNameKey": "...",
    "parent": 12345
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
                  

Synchronize a smart folder

Synchronize a smart folder. This is only applicable for a smart folder with an AWS tag hierarchy.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

smartFolderID
integer
the smart folder ID.

Response Codes

200
if the request was successful
403
if the user is not authorized to synchronize a smart folder
404
if the smart folder does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Example Request

POST /smart-folders/{smartFolderID}/synchronize
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
                  

Software Changes

List application drift

Gets the list of unreviewed applications, grouped by SHA256, within the provided search scope.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Request Body

ListApplicationDriftRequest
-
Properties
scope
ScopeWithHostGroup
the search scope.
Properties
hostGroupID
number
the host group ID that this query should be scoped by.
smartFolderID
number
the smart folder ID that this query should be scoped by.
count
number
the number of items to retrieve.
start
number
the starting point for retrieving items, starting at 0. Use this for paging through results.

Response Codes

200
if the request was successful
400
if the request was invalid
403
if the user is not authorized to view drift
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ListApplicationDriftResponse
a ListApplicationDriftResponse object containing the list of unreviewed applications, grouped by SHA256, within the provided search scope.
Properties
items
Item
the list of application drift items that matched the search scope.
Properties
sha256
string
The sha256 of the item.
fileNames
string
The file names that the item appears as within the limits of the query.
count
number
The number of times this item appears within the limits of the query.
total
number
the number of results, including those excluded by pagination parameters.
countOverMaximum
boolean
whether there are more eligible results than could be counted.

Example Request

POST /software-inventory/drift/applications
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "ListApplicationDriftRequest": {
    "scope": {
      "hostGroupID": 12345,
      "smartFolderID": 12345,
      "filters": [ {
        "property": "INSTALL_PATH",
        "operator": "CONTAINS",
        "value": "...",
        "missingMandatoryFields": true
      }, {
        "property": "HOST_NAME",
        "operator": "NOT_CONTAIN",
        "value": "...",
        "missingMandatoryFields": true
      } ],
      "timeRange": {
        "start": 12345,
        "end": 12345
      }
    },
    "count": 12345,
    "start": 12345
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ListApplicationDriftResponse": {
    "items": [ {
      "sha256": "...",
      "fileNames": [ "...", "..." ],
      "count": 12345
    }, {
      "sha256": "...",
      "fileNames": [ "...", "..." ],
      "count": 12345
    } ],
    "total": 12345,
    "countOverMaximum": true
  }
}
                    
                  

List computer drift

Gets the list of hosts that have had unreviewed drift items within the provided search scope.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Request Body

ListComputerDriftRequest
a ListComputerDriftRequest specifying the search scope.
Properties
the search scope.
count
number
the number of items to retrieve.
start
number
the starting point for retrieving items, starting at 0. Use this for paging through results.

Response Codes

200
if the request was successful
400
if the request was invalid
403
if the user is not authorized to view drift
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ListComputerDriftResponse
a ListComputerDriftResponse object containing the list of hosts that have had unreviewed drift items within the provided search scope.
Properties
items
Item
the list of computer drift items that matched the search scope.
Properties
hostID
number
The computer's host ID.
hostName
string
The computer's host name.
displayName
string
The computer's display name.
count
number
The number of drift items on the computer.
total
number
the number of results, including those excluded by pagination parameters.
countOverMaximum
boolean
whether there are more eligible results than could be counted.

Example Request

POST /software-inventory/drift/computers
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "ListComputerDriftRequest": {
    "scope": {
      "hostGroupID": 12345,
      "smartFolderID": 12345,
      "filters": [ {
        "property": "HOST_NAME",
        "operator": "NOT_CONTAIN",
        "value": "...",
        "missingMandatoryFields": true
      }, {
        "property": "CHANGE_BY_PROCESS",
        "operator": "NOT_EQUAL",
        "value": "...",
        "missingMandatoryFields": true
      } ],
      "timeRange": {
        "start": 12345,
        "end": 12345
      }
    },
    "count": 12345,
    "start": 12345
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ListComputerDriftResponse": {
    "items": [ {
      "hostID": 12345,
      "hostName": "...",
      "displayName": "...",
      "count": 12345
    }, {
      "hostID": 12345,
      "hostName": "...",
      "displayName": "...",
      "count": 12345
    } ],
    "total": 12345,
    "countOverMaximum": true
  }
}
                    
                  

Describe drift

Gets metadata describing the drift that has occurred within the provided search scope.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Request Body

DescribeDriftRequest
a DescribeDriftRequest specifying the search scope.
Properties
the search scope. For searching purposes, all drift event times are truncated to the beginning of the hour. Time range searches look for results with hour after the start time and before or equal to the end time.

Response Codes

200
if the request was successful
400
if the request was invalid
403
if the user is not authorized to view drift
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

DescribeDriftResponse
a DescribeDriftResponse with drift metadata counts by hour bucket bounded by the search scope.
Properties
histogram
Histogram
the histogram of the drift that has occurred within the search scope.
Properties
buckets
Bucket
the list of histogram buckets.
Properties
time
number
The start time of the bucket, as the number of milliseconds since January 1, 1970, 00:00:00 GMT.
count
number
The number of items in the bucket.
total
number
Number of total drift between provided start and end time .

Example Request

POST /software-inventory/drift/histogram
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "DescribeDriftRequest": {
    "scope": {
      "hostGroupID": 12345,
      "smartFolderID": 12345,
      "filters": [ {
        "property": "FILE_NAME",
        "operator": "NOT_CONTAIN",
        "value": "...",
        "missingMandatoryFields": true
      }, {
        "property": "FILE_NAME",
        "operator": "CONTAINS",
        "value": "...",
        "missingMandatoryFields": true
      } ],
      "timeRange": {
        "start": 12345,
        "end": 12345
      }
    }
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "DescribeDriftResponse": {
    "histogram": {
      "buckets": [ {
        "time": 12345,
        "count": 12345
      }, {
        "time": 12345,
        "count": 12345
      } ],
      "total": 12345
    }
  }
}
                    
                  

List host groups

Gets the tree of all host groups with hosts that have had unreviewed inventory changes within the provided search scope.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Request Body

ListHostGroupsRequest
a ListHostGroupsRequest specifying the search scope.
Properties
scope
DriftQueryScope
the search scope.
Properties
filters
PropertyFilter
-
Properties
property
Property
-
Values
FILE_NAME
HOST_NAME
INSTALL_PATH
CHANGE_BY_USER
CHANGE_BY_PROCESS
MD5
SHA1
SHA256
operator
Operator
-
Values
CONTAINS
NOT_CONTAIN
EQUALS
NOT_EQUAL
value
string
-
missingMandatoryFields
boolean
Returns true if any mandatory fields are missing
timeRange
TimeRange
The time range with which to limit the query.
Properties
start
number
The beginning of the time range as the number of milliseconds since January 1, 1970, 00:00:00 GMT. If the value is 0 or less, or if it is absent, the DSM will use the time one week before the current time.
end
number
The end of the time range as the number of milliseconds since January 1, 1970, 00:00:00 GMT. If the value is 0 or less, or if it is absent, the DSM will use the current time.

Response Codes

200
if the request was successful
400
if the request was invalid
403
if the user is not authorized to view drift or host groups
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ListHostGroupsResponse
a ListHostGroupsResponse containing the tree of all host groups with hosts that have had unreviewed inventory changes within the provided search scope.
Properties
driftHostGroup
DriftHostGroup
the tree of host groups where drift has occurred within the search scope.
Properties
name
string
The name of the host group.
type
string
The type of the host group.
count
number
The number of drift items in the host group. This includes all drift items in hosts that are part of this host group and any of its descendant groups.
The child groups in this host group, including their own drift item counts.
id
number
The host group ID assigned by the DSM. A host group ID of -1 means that this is the root host group.

Example Request

POST /software-inventory/drift/host-groups
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "ListHostGroupsRequest": {
    "scope": {
      "filters": [ {
        "property": "SHA256",
        "operator": "NOT_EQUAL",
        "value": "...",
        "missingMandatoryFields": true
      }, {
        "property": "SHA256",
        "operator": "CONTAINS",
        "value": "...",
        "missingMandatoryFields": true
      } ],
      "timeRange": {
        "start": 12345,
        "end": 12345
      }
    }
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ListHostGroupsResponse": {
    "driftHostGroup": {
      "name": "...",
      "type": "...",
      "count": 12345,
      "children": [ { }, { } ],
      "id": 12345
    }
  }
}
                    
                  

Describe drift details

Gets computer and file details for the provided inventory change.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

changeID
integer
the change ID

Response Codes

200
if the request was successful
400
if the request was invalid
403
if the user is not authorized to view drift
404
if the drift item does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

DescribeDriftDetailsResponse
a summary of file and computer details for the given change ID.
Properties
driftItemDetails
DriftItemDetails
drift item details.
Properties
The host on which the drift item was found.
vendorName
string
The vendor name associated with the drift item.
productName
string
The product name associated with the drift item.
productVersion
string
The product version associated with the drift item.
fileSize
number
The file size of the drift item in byte
fileVersion
string
The file version associated with the drift item.
fileDescription
string
The file description associated with the drift item.
sha1
string
The SHA1 hash calculated from the drift item.
sha256
string
The SHA256 hash calculated from the drift item.
md5
string
The MD5 hash calculated from the drift item.
fileName
string
The file name of the drift item.
installPath
string
The path on which the drift item was found.
changeEventTime
number
The time the drift item was discovered, as the number of milliseconds since January 1, 1970, 00:00:00 GMT.
createTime
number
The time when the drift item was created, as the number of milliseconds since January 1, 1970, 00:00:00 GMT. Zero will be returned for Drift items reported before 10.2 or when Agent did not report it.
modifyTime
number
The time the drift item was last modified, as the number of milliseconds since January 1, 1970, 00:00:00 GMT. Zero will be returned for Drift items reported before 10.2 or when Agent did not report it.
changeByUser
string
The username of the user that introduced the drift item.
changeByUserID
string
The user ID of the user that introduced the drift item.
changeByProcess
string
The name of the process that introduced the drift item.
changeByProcessID
string
The process ID of the process that introduced the drift item.
ruleset
RulesetSummaryInfo
Summary information about the current ruleset on the host, if any.
Properties
ID
number
The ruleset ID.
name
string
-
shared
boolean
-

Example Request

GET /software-inventory/drift/occurrences/{changeID}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "DescribeDriftDetailsResponse": {
    "driftItemDetails": {
      "host": {
        "id": 12345,
        "hostname": "...",
        "displayname": "...",
        "description": "...",
        "created": 12345,
        "lastModified": 12345,
        "lastUpdateAttempt": "...",
        "agentReportedVersion": "...",
        "externalId": "...",
        "instanceId": "...",
        "lastIpUsed": "...",
        "platform": "...",
        "hostGroupId": 12345,
        "policy": { },
        "hostStatus": { }
      },
      "vendorName": "...",
      "productName": "...",
      "productVersion": "...",
      "fileSize": 12345,
      "fileVersion": "...",
      "fileDescription": "...",
      "sha1": "...",
      "sha256": "...",
      "md5": "...",
      "fileName": "...",
      "installPath": "...",
      "changeEventTime": 12345,
      "createTime": 12345,
      "modifyTime": 12345,
      "changeByUser": "...",
      "changeByUserID": "...",
      "changeByProcess": "...",
      "changeByProcessID": "...",
      "ruleset": {
        "ID": 12345,
        "name": "...",
        "shared": true
      }
    }
  }
}
                    
                  

Review application drift

Performs an allow or block action on all instances of the given application, identified by SHA256, within the provided search scope scope.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

sha256
string
the application sha256

Request Body

ReviewApplicationDriftRequest
a ReviewApplicationDriftRequest specifying the search scope.
Properties
the search scope.
action
Action
the action to perform for this drift item.
Values
allow
block

Response Codes

200
if the request was successful
400
if the request was invalid
403
if the user is not authorized to review drift
404
if the application does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Example Request

POST /software-inventory/drift/applications/{sha256}/action
Content-Type: application/json
Cookie: sID=12345;
                    
{
  "ReviewApplicationDriftRequest": {
    "scope": {
      "hostGroupID": 12345,
      "smartFolderID": 12345,
      "filters": [ {
        "property": "INSTALL_PATH",
        "operator": "NOT_CONTAIN",
        "value": "...",
        "missingMandatoryFields": true
      }, {
        "property": "SHA1",
        "operator": "EQUALS",
        "value": "...",
        "missingMandatoryFields": true
      } ],
      "timeRange": {
        "start": 12345,
        "end": 12345
      }
    },
    "action": "block"
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
                  

Describe an application

Gets details about a given executable, identified by sha256, using inventory change data within the provided search scope.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

sha256
string

Request Body

DescribeApplicationRequest
a DescribeApplicationRequest specifying the search scope.
Properties
Scope of the request.

Response Codes

200
if the request was successful
400
if the request was invalid
403
if the user is not authorized to view drift
404
if the application does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

DescribeApplicationResponse
a DescribeApplicationResponse object containing details about a given executable, identified by sha256, using inventory change data within the given scope.
Properties
applicationDetails
ApplicationDetail
the application details of the drift that has occurred within the search scope.
Properties
fileSize
number
-
count
number
-
fileName
string
-
installPath
string
-
vendorName
string
-
productName
string
-
productVersion
string
-
fileVersion
string
-
fileDescription
string
-
md5
string
-
sha1
string
-
sha256
string
-

Example Request

POST /software-inventory/drift/applications/{sha256}/details
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "DescribeApplicationRequest": {
    "scope": {
      "hostGroupID": 12345,
      "smartFolderID": 12345,
      "filters": [ {
        "property": "SHA256",
        "operator": "CONTAINS",
        "value": "...",
        "missingMandatoryFields": true
      }, {
        "property": "SHA256",
        "operator": "EQUALS",
        "value": "...",
        "missingMandatoryFields": true
      } ],
      "timeRange": {
        "start": 12345,
        "end": 12345
      }
    }
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "DescribeApplicationResponse": {
    "applicationDetails": [ {
      "fileSize": 12345,
      "count": 12345,
      "fileName": "...",
      "installPath": "...",
      "vendorName": "...",
      "productName": "...",
      "productVersion": "...",
      "fileVersion": "...",
      "fileDescription": "..."
    }, {
      "fileSize": 12345,
      "count": 12345,
      "fileName": "...",
      "installPath": "...",
      "vendorName": "...",
      "productName": "...",
      "productVersion": "...",
      "fileVersion": "...",
      "fileDescription": "..."
    } ],
    "md5": "...",
    "sha1": "...",
    "sha256": "..."
  }
}
                    
                  

Describe application drift

Gets a list of the instances of the given unreviewed application, identified by SHA256, within the provided search scope.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

sha256
string
the application sha256

Request Body

DescribeApplicationDriftRequest
a DescribeApplicationDriftRequest specifying the search scope.
Properties
the search scope.
count
number
the number of items to retrieve.
start
number
the starting point for retrieving items, starting at 0. Use this for paging through results.

Response Codes

200
if the request was successful
400
if the request was invalid
403
if the user is not authorized to view drift
404
if the application does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

DescribeApplicationDriftResponse
a DescribeApplicationDriftResponse object containing a list of the instances of the given unreviewed application, identified by SHA256, within the provided search scope.
Properties
items
DriftItemSummary
the list of application drift items that matched the search scope.
Properties
changeID
number
The change ID used by the Deep Security Manager to track the drift item.
sha256
string
the SHA-256 hash of the drift item.
fileName
string
the filename of the drift item.
path
string
the file path where the drift item was detected.
detectionTime
number
the time this item was first detected, as the number of milliseconds since January 1, 1970, 00:00:00 GMT.
hostName
string
the name of the host where this item was detected.
hostID
number
the ID of the host where this item was detected.
changeBy
string
the operating system user ID for the user that made the change.
total
number
the number of results, including those excluded by pagination parameters.
countOverMaximum
boolean
whether there are more eligible results than could be counted.

Example Request

POST /software-inventory/drift/applications/{sha256}/occurrences
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "DescribeApplicationDriftRequest": {
    "scope": {
      "hostGroupID": 12345,
      "smartFolderID": 12345,
      "filters": [ {
        "property": "INSTALL_PATH",
        "operator": "CONTAINS",
        "value": "...",
        "missingMandatoryFields": true
      }, {
        "property": "INSTALL_PATH",
        "operator": "NOT_CONTAIN",
        "value": "...",
        "missingMandatoryFields": true
      } ],
      "timeRange": {
        "start": 12345,
        "end": 12345
      }
    },
    "count": 12345,
    "start": 12345
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "DescribeApplicationDriftResponse": {
    "items": [ {
      "changeID": 12345,
      "sha256": "...",
      "fileName": "...",
      "path": "...",
      "detectionTime": 12345,
      "hostName": "...",
      "hostID": 12345,
      "changeBy": "..."
    }, {
      "changeID": 12345,
      "sha256": "...",
      "fileName": "...",
      "path": "...",
      "detectionTime": 12345,
      "hostName": "...",
      "hostID": 12345,
      "changeBy": "..."
    } ],
    "total": 12345,
    "countOverMaximum": true
  }
}
                    
                  

Review computer drift

Performs an allow or block action on all drift items on the given host ID within the provided search scope.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

hostID
integer
the host ID

Request Body

ReviewComputerDriftRequest
a ReviewComputerDriftRequest specifying the search scope.
Properties
the search scope.
action
the action to perform for this drift item.
Values
allow
block

Response Codes

200
if the request was successful
400
if the request was invalid
403
if the user is not authorized to review drift
404
if the host does not exist or the user is not authorized to view the host
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Example Request

POST /software-inventory/drift/computers/{hostID}/action
Content-Type: application/json
Cookie: sID=12345;
                    
{
  "ReviewComputerDriftRequest": {
    "scope": {
      "filters": [ {
        "property": "SHA256",
        "operator": "NOT_CONTAIN",
        "value": "...",
        "missingMandatoryFields": true
      }, {
        "property": "FILE_NAME",
        "operator": "NOT_EQUAL",
        "value": "...",
        "missingMandatoryFields": true
      } ],
      "timeRange": {
        "start": 12345,
        "end": 12345
      }
    },
    "action": "block"
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
                  

Describe computer drift

Gets a list of all unreviewed drift items within the provided search scope.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

hostID
integer
the host ID

Request Body

DescribeComputerDriftRequest
a DescribeComputerDriftRequest specifying the search scope.
Properties
the search scope.
count
number
the number of items to retrieve.
start
number
the starting point for retrieving items, starting at 0. Use this for paging through results.

Response Codes

200
if the request was successful
400
if the request was invalid
403
if the user is not authorized to view drift
404
if the host does not exist or the user is not authorized to view the host
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

DescribeComputerDriftResponse
a DescribeComputerDriftResponse object containing a list of all unreviewed drift items within the provided search scope.
Properties
the list of application drift items that matched the search scope.
total
number
the number of results, including those excluded by pagination parameters.
countOverMaximum
boolean
whether there are more eligible results than could be counted.

Example Request

POST /software-inventory/drift/computers/{hostID}/occurrences
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "DescribeComputerDriftRequest": {
    "scope": {
      "filters": [ {
        "property": "MD5",
        "operator": "NOT_EQUAL",
        "value": "...",
        "missingMandatoryFields": true
      }, {
        "property": "SHA1",
        "operator": "NOT_EQUAL",
        "value": "...",
        "missingMandatoryFields": true
      } ],
      "timeRange": {
        "start": 12345,
        "end": 12345
      }
    },
    "count": 12345,
    "start": 12345
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "DescribeComputerDriftResponse": {
    "items": [ {
      "changeID": 12345,
      "sha256": "...",
      "fileName": "...",
      "path": "...",
      "detectionTime": 12345,
      "hostName": "...",
      "hostID": 12345,
      "changeBy": "..."
    }, {
      "changeID": 12345,
      "sha256": "...",
      "fileName": "...",
      "path": "...",
      "detectionTime": 12345,
      "hostName": "...",
      "hostID": 12345,
      "changeBy": "..."
    } ],
    "total": 12345,
    "countOverMaximum": true
  }
}
                    
                  

Review drift item

Performs an allow or block action on one inventory change.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

changeID
integer
the change ID

Request Body

ReviewDriftItemRequest
a ReviewComputerDriftRequest specifying the action to take when the application identified in the drift item is launched.
Properties
action
the action to perform for this drift item.
Values
allow
block

Response Codes

200
if the request was successful
400
if the request was invalid
403
if the user is not authorized to review drift
404
if the drift item does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Example Request

POST /software-inventory/drift/occurrences/{changeID}/action
Content-Type: application/json
Cookie: sID=12345;
                    
{
  "ReviewDriftItemRequest": {
    "action": "block"
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
                  

Software inventory

Interface for the SoftwareInventory API.

List inventories

Retrieve the list of all inventory metadata.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Query Parameters

inventoryID
integer
(optional) used to define the starting point for the query. Combine with inventoryIDOp to page through results.
inventoryIDOp
string
(optional, required if inventoryID is specified) Currently supported operations include gt(greater than), ge(greater than or equal to), eq(eqaul to), lt(less than), and le(less than or equal to).
maxItems
integer
(optional) the number of items to retrieve. The maximum value for this parameter is controlled by the "Maximum number of items to retrieve from database" setting on the administrator account, which defaults to 5000.

Response Codes

200
if the request is successful
400
if the request is invalid
403
if the user is not authorized to view inventory metadata
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ListInventoriesResponse
a ListInventoriesResponse containing the list of all software inventory metadata.
Properties
inventories
InventoryMetadataItem
the list of inventory metadata items.
Properties
hostID
number
the host that the inventory scan was done on (or is being done on).
hostName
string
the host name of the host that the inventory scan was done on (or is being done on).
inventoryID
number
the inventory ID.
state
State
the state of the inventory scan.
Values
unknown
Transient state when the inventory build has not yet started.
building
The inventory list is being built on the host.
complete
The inventory scan has been completed.
failed
The inventory scan has failed.
requested-user
The inventory scan has been requested by a user.
startDate
string
the date that the inventory scan was started.
completedDate
string
the date that the inventory scan was completed.
adminName
string
the name of the administrator that initiated the inventory scan.

Example Request

GET /software-inventory?inventoryID={inventoryID}&inventoryIDOp={inventoryIDOp}&maxItems={maxItems}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ListInventoriesResponse": {
    "inventories": [ {
      "hostID": 12345,
      "hostName": "...",
      "inventoryID": 12345,
      "state": "requested-user",
      "startDate": "...",
      "completedDate": "...",
      "adminName": "..."
    }, {
      "hostID": 12345,
      "hostName": "...",
      "inventoryID": 12345,
      "state": "unknown",
      "startDate": "...",
      "completedDate": "...",
      "adminName": "..."
    } ]
  }
}
                    
                  

Create an inventory

Create an inventory of a host.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Request Body

CreateInventoryRequest
a CreateInventoryRequest describing the inventory action to take.
Properties
hostID
number
the host to create an inventory of.
name
string
the name to display for this inventory.
description
string
the description for this inventory.
createRuleset
boolean
whether or not to create a ruleset from this inventory on completion.

Response Codes

200
if the request is successful
400
if the request is invalid
403
if the user is not authorized to create inventory
404
if the host does not exist or the user is not authorized to view the host
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

CreateInventoryResponse
a CreateInventoryResponse carrying the ID of the created inventory list.
Properties
inventoryID
number
the inventory ID for the created inventory.

Example Request

POST /software-inventory
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "CreateInventoryRequest": {
    "hostID": 12345,
    "name": "...",
    "description": "...",
    "createRuleset": true
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "CreateInventoryResponse": {
    "inventoryID": 12345
  }
}
                    
                  

Delete an inventory

Delete an inventory list.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

inventoryID
integer
the inventory list ID.

Response Codes

204
if the request is successful
403
if the user is not authorized to delete inventory
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Example Request

DELETE /software-inventory/{inventoryID}
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 204 No Content
                  

Describe inventory metadata

Retrieve inventory list metadata.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

inventoryID
integer
the inventory list ID.

Response Codes

200
if the request is successful
403
if the user is not authorized to view inventory metadata
404
if the inventory list metadata does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

DescribeInventoryResponse
a DescribeInventoryResponse containing metadata about the inventory list.
Properties
inventoryMetadata
the inventory metadata.

Example Request

GET /software-inventory/{inventoryID}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "DescribeInventoryResponse": {
    "inventoryMetadata": {
      "hostID": 12345,
      "hostName": "...",
      "inventoryID": 12345,
      "state": "failed",
      "startDate": "...",
      "completedDate": "...",
      "adminName": "..."
    }
  }
}
                    
                  

Describe details of an inventory

Retrieve inventory list details.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

inventoryID
integer
the inventory list ID.

Query Parameters

itemID
integer
(optional) used to define the starting point for the query. Combine with itemIDOp to page through results.
itemIDOp
string
(optional, required if itemID is specified) Currently supported operations include gt(greater than), ge(greater than or equal to), eq(eqaul to), lt(less than), and le(less than or equal to).
maxItems
integer
(optional) the number of items to retrieve. The maximum value for this parameter is controlled by the "Maximum number of items to retrieve from database" setting on the administrator account, which defaults to 5000.

Response Codes

200
if the request is successful
403
if the user is not authorized to view inventory
404
if the inventory list does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

GetInventoryResponse
the detailed inventory listing of all applications detected in the inventory scan.
Properties
inventoryItems
InventoryItem
the list of inventory items.
Properties
itemID
number
The item ID corresponding to this inventory item.
vendorName
string
The vendor name as reported by the package management system on the computer.
productName
string
The product name as reported by the package management system on the computer.
productVersion
string
The product version as reported by the package management system on the computer.
fileVersion
string
The file version as reported by the package management system on the computer.
fileDescription
string
The file description as reported by the package management system on the computer.
category
string
The file category as reported by the package management system on the computer.
sha256
string
The SHA-256 hash of the file contents.
sha1
string
The SHA-1 hash of the file contents.
md5
string
The MD5 hash of the file contents.
fileName
string
The file name.
path
string
The file path.
size
number
The file size.

Example Request

GET /software-inventory/{inventoryID}/details?itemID={itemID}&itemIDOp={itemIDOp}&maxItems={maxItems}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "GetInventoryResponse": {
    "inventoryItems": [ {
      "itemID": 12345,
      "vendorName": "...",
      "productName": "...",
      "productVersion": "...",
      "fileVersion": "...",
      "fileDescription": "...",
      "category": "...",
      "sha256": "...",
      "sha1": "...",
      "md5": "...",
      "fileName": "...",
      "path": "...",
      "size": 12345
    }, {
      "itemID": 12345,
      "vendorName": "...",
      "productName": "...",
      "productVersion": "...",
      "fileVersion": "...",
      "fileDescription": "...",
      "category": "...",
      "sha256": "...",
      "sha1": "...",
      "md5": "...",
      "fileName": "...",
      "path": "...",
      "size": 12345
    } ]
  }
}
                    
                  

Suspicious objects

Clear the suspicious objects list

Clear the suspicious objects list

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Response Codes

204
if the request is successful
403
if the user is not authorized to clear the suspicious objects list
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Example Request

DELETE /suspicious-objects
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 204 No Content
                  

Modify the suspicious objects list

Update the suspicious objects list.

Cookie Parameters

sID
string

Query Parameters

deploy
boolean
use to deploy suspicious object list to agents after suspicious object updated. Default value is false (optional).
update
boolean
use to update the suspicious object list from the Trend Micro Control Manager. Default value is true (optional).

Response Codes

200
if the request is successful
403
if the user is not authorized to update the suspicious objects list
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

UpdateSuspiciousObjectsListResponse
a UpdateSuspiciousObjecstListResponse carry the last query time and last update time of suspicious object list. If update action encounter unexpected error will return a response 500 Internal Server Error with body SuspiciousObjectsUpdateError. If deploy action encounter unexpected error will return a response 500 Internal Server Error with body SuspiciousObjectsDeployError. If update and deploy parameters are all set true, it will perform update suspicious object list first then deploy it to agents. Deploy step will not be performed if update step encounter unexpected error.
Properties
lastCheckTime
number
-
lastDownloadTime
number
-

Example Request

POST /suspicious-objects?deploy={deploy}&update={update}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "UpdateSuspiciousObjectsListResponse": {
    "lastCheckTime": 12345,
    "lastDownloadTime": 12345
  }
}
                    
                  

Syslog configurations

Management API for syslog configurations.

List syslog configurations

List syslog configurations.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Query Parameters

maxItems
integer
(optional) the number of items to retrieve. The maximum value for this parameter is controlled by the "Maximum number of items to retrieve from database" setting on the administrator account, which defaults to 5000.
syslogConfigurationID
integer
(optional) used to define the starting point for the query. Combine with syslogConfigurationIDOp to page through results.
syslogConfigurationIDOp
string
(optional, required if syslogConfigurationID is specified) Currently supported operations include gt(greater than), ge(greater than or equal to), eq(equal to), lt(less than), and le(less than or equal to).

Response Codes

200
if the request is successful
400
if the request is invalid
403
if the user is not authorized to view syslog configurations
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ListSyslogConfigurationsResponse
a list of syslog configurations.
Properties
syslogConfigurations
SyslogConfiguration
the list of syslog configurations.
Properties
ID
number
The ID for this syslog configuration.
name
string
The name for this syslog configuration.
description
string
The description for this syslog configuration.
server
string
The destination server for syslog messages.
port
number
The destination port for syslog messages.
transport
Transport
The transport to use when sending syslog messages.
Values
udp
UDP transport. Syslog messages transmitted using the UDP transport are not encrypted and reliable delivery is not guaranteed.
tcp
TCP transport. Syslog messages transmitted using the TCP transport are not encrypted. The TCP transport ensures that message delivery is reliable.
tls
TLS transport. Syslog messages transmitted using the TLS transport are encrypted. The TCP transport ensures that message delivery is reliable.
eventFormat
EventFormat
The event format to use when sending syslog messages.
Values
standard
cef
leef
facility
Facility
The facility value to send with each syslog message.
Values
kernel
user
mail
daemon
authorization
syslog
printer
news
uucp
clock
authpriv
ftp
ntp
log-audit
log-alert
cron
local0
local1
local2
local3
local4
local5
local6
local7
privateKey
string
The private key the Deep Security Manager will use when it contacts the syslog server over TLS.

The private key must be an RSA key in PEM-encoded PKCS#1 or PKCS#8 format.

To prevent accidental disclosure of the private key, the Deep Security Manager will not return this value; it can only be used to set the private key.

certificateChain
string
The identity certificate chain the Deep Security Manager will use when it contacts the syslog server over TLS.

The identity certificate must be the first certificate in the list, followed by the certificate for the issuing certificate authority (if any) and continuing up the issuer chain. The root certificate authority's certificate does not need to be included.

Each element in the list will be an unencrypted PEM-encoded certificate.

direct
boolean
The "direct delivery from agent to syslog server" flag.

Example Request

GET /syslog-configurations?maxItems={maxItems}&syslogConfigurationID={syslogConfigurationID}&syslogConfigurationIDOp={syslogConfigurationIDOp}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ListSyslogConfigurationsResponse": {
    "syslogConfigurations": [ {
      "ID": 12345,
      "name": "...",
      "description": "...",
      "server": "...",
      "port": 12345,
      "transport": "tls",
      "eventFormat": "standard",
      "facility": "printer",
      "privateKey": "...",
      "certificateChain": [ "...", "..." ],
      "direct": true
    }, {
      "ID": 12345,
      "name": "...",
      "description": "...",
      "server": "...",
      "port": 12345,
      "transport": "tcp",
      "eventFormat": "leef",
      "facility": "ftp",
      "privateKey": "...",
      "certificateChain": [ "...", "..." ],
      "direct": true
    } ]
  }
}
                    
                  

Create a syslog configuration

Create a syslog configuration.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Request Body

CreateSyslogConfigurationRequest
the syslog configuration details.
Properties
syslogConfiguration
the syslog configuration.

Response Codes

200
if the request is successful
400
if the request is invalid
403
if the user is not authorized to create a syslog configuration
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

CreateSyslogConfigurationResponse
the created syslog configuration.
Properties
syslogConfiguration
the syslog configuration.

Example Request

POST /syslog-configurations
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "CreateSyslogConfigurationRequest": {
    "syslogConfiguration": {
      "ID": 12345,
      "name": "...",
      "description": "...",
      "server": "...",
      "port": 12345,
      "transport": "udp",
      "eventFormat": "standard",
      "facility": "local4",
      "privateKey": "...",
      "certificateChain": [ "...", "..." ],
      "direct": true
    }
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "CreateSyslogConfigurationResponse": {
    "syslogConfiguration": {
      "ID": 12345,
      "name": "...",
      "description": "...",
      "server": "...",
      "port": 12345,
      "transport": "tls",
      "eventFormat": "leef",
      "facility": "news",
      "privateKey": "...",
      "certificateChain": [ "...", "..." ],
      "direct": true
    }
  }
}
                    
                  

Delete a syslog configuration

Delete a syslog configuration from the Deep Security Manager.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

syslogConfigurationID
integer
the syslog configuration ID.

Response Codes

200
if the request is successful
400
if the syslog configuration cannot be deleted because it is in use
403
if the user is not authorized to delete syslog configurations
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Example Request

DELETE /syslog-configurations/{syslogConfigurationID}
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
                  

Describe a syslog configuration

Get syslog configuration details.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

syslogConfigurationID
integer
the syslog configuration ID.

Response Codes

200
if the request is successful
403
if the user is not authorized to view syslog configurations
404
if the user is authorized to view syslog configurations but the syslog configuration does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

DescribeSyslogConfigurationResponse
syslog configuration details.
Properties
syslogConfiguration
the syslog configuration.

Example Request

GET /syslog-configurations/{syslogConfigurationID}
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "DescribeSyslogConfigurationResponse": {
    "syslogConfiguration": {
      "ID": 12345,
      "name": "...",
      "description": "...",
      "server": "...",
      "port": 12345,
      "transport": "udp",
      "eventFormat": "leef",
      "facility": "user",
      "privateKey": "...",
      "certificateChain": [ "...", "..." ],
      "direct": true
    }
  }
}
                    
                  

Modify a syslog configuration

Modify syslog configuration.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

syslogConfigurationID
integer
the syslog configuration ID.

Request Body

ModifySyslogConfigurationRequest
the syslog configuration details.
Properties
syslogConfiguration
the syslog configuration.

Response Codes

200
if the request is successful
400
if the request is invalid
403
if the user is not authorized to modify syslog configurations
404
if the user is authorized to modify syslog configurations but the syslog configuration does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ModifySyslogConfigurationResponse
the modified syslog configuration.
Properties
syslogConfiguration
the syslog configuration.

Example Request

POST /syslog-configurations/{syslogConfigurationID}
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
                    
{
  "ModifySyslogConfigurationRequest": {
    "syslogConfiguration": {
      "ID": 12345,
      "name": "...",
      "description": "...",
      "server": "...",
      "port": 12345,
      "transport": "tcp",
      "eventFormat": "cef",
      "facility": "printer",
      "privateKey": "...",
      "certificateChain": [ "...", "..." ],
      "direct": true
    }
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ModifySyslogConfigurationResponse": {
    "syslogConfiguration": {
      "ID": 12345,
      "name": "...",
      "description": "...",
      "server": "...",
      "port": 12345,
      "transport": "tls",
      "eventFormat": "cef",
      "facility": "uucp",
      "privateKey": "...",
      "certificateChain": [ "...", "..." ],
      "direct": true
    }
  }
}
                    
                  

Tenant templates

Does not apply to Deep Security as a Service

Multi-tenant environment only

Primary tenant only

Interface for the Tenant Template API.

Describe a tenant template

Does not apply to Deep Security as a Service

Multi-tenant environment only

Primary tenant only

Retrieve the current tenant template.

The template is used when creating new tenants, with the new tenant getting the rules and policies set in the template.

Query Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Response Body

TenantTemplateElement
The information about the tenant template (if any).
Properties
tenantId
number
Return the ID of the tenant the template is based on, or null if there is no template or the tenant ID cannot be determined, for example if the tenant has been deleted.
tenantName
string
Return the name of the tenant the template is based on, or null if there is no template.
dateCreated
number
Return the date at which the template was created, or null if there is no template.

Example Request

GET /tenanttemplate?sID={sID}
Accept: application/json
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "tenantTemplate": {
    "tenantId": 12345,
    "tenantName": "...",
    "dateCreated": 12345
  }
}
                    
                  

Create a tenant template

Does not apply to Deep Security as a Service

Multi-tenant environment only

Primary tenant only

Create a new tenant template using the provided tenantId. This new template replaces the existing template.

Request Body

CreateTenantTemplateRequest
the request parameters.
Properties
tenantId
number
The identifier of the tenant on which to base the template.

Response Body

CreateTenantTemplateResponse
A response with code 200 OK and a body containing a CreateTenantTemplateResponse when the template creation was successful. It will return code 400 Bad Request and a body containing an ErrorMessage when mandatory parameters are missing and/or validation fails.

Example Request

POST /tenanttemplate
Content-Type: application/json
Accept: application/json
                    
{
  "createTenantTemplateRequest": {
    "tenantId": 12345,
    "sessionId": "..."
  }
}
                    
                  

Example Response

HTTP/1.1 201 Created
Content-Type: application/json
                    
{
  "createTenantTemplateResponse": { }
}
                    
                  

Tenants

Does not apply to Deep Security as a Service

Multi-tenant environment only

Primary tenant only

Interface for the Tenant API.

List tenants

Does not apply to Deep Security as a Service

Multi-tenant environment only

Primary tenant only

Retrieve information about all tenants.

Query Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Response Codes

200
if the request is successful
403
if the user is not authorized to view tenant information
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

TenantListing
The collection of tenants.
Properties
tenants
TenantElement
Return the list of tenants
Properties
tenantID
number
The tenant ID.
name
string
The tenant name (required for tenant creation).
databaseServerID
number
The ID of the tenant database server. null implies automatic selection, 0 implies the primary database server.
description
string
A text description of the tenant; this is a free-form text field that can be used to describe the tenant or attach information to them.
guid
string
Return the Tenant GUID, required for agent-initiated activation.
agentInitiatedActivationPassword
string
The activation token used during agent-initiated activation
Agents can be activated from the command line using the syntax:
dsa_control /a dsm://{host}:4120/ tenantID:{guid} token:{agentInitiatedActivationPassword}
state
string
The tenant state, one of:
  • UNDEFINED
  • CREATED
  • ACTIVE
  • SUSPENDED
  • PENDING_DELETION
  • DB_UPGRADE_FAILURE

The state must not be specified when creating a tenant.
The update tenant API only can change state from ACTIVE to SUSPENDED, or from SUSPENDED to ACTIVE.
language
string
The tenant language (required for tenant creation). Allowed languages are those in which Deep Security Manager has been localized, typically:
  • en - English
  • ja - Japanese
  • zh - Chinese

If the combination of language and country does not match any of the locales supported by Deep Security Manager then the tenant will be created using the system's default locale.

country
string
The tenant country (required for tenant creation). Allowed countries are those for which Deep Security Manager has been localized, typically:
  • US - used when language="en" for US English
  • JP - used when language="jp" for Japanese
  • CN - used when language="zh" for Chinese

If the combination of language and country does not match any of the locales supported by Deep Security Manager then the tenant will be created using the system's default locale.

timeZone
string
The tenant time zone (required for tenant creation). Time zones should be specified using identifiers such as those returned from Java's java.util.TimeZone class. For example, "US/Eastern".
demoMode
boolean
Whether or not demo mode is enabled for the tenant.
allModulesVisible
boolean
Whether or not all modules are visible to the tenant. If this value is set to true then the value of modulesVisible is ignored.
licenseMode
string
License Mode gives the status of the license for the selected tenant. This is only reported as information and cannot be set during tenant create or update.
modulesVisible
string

The list of modules visible to the tenant. Possible values are the following module codes:

  • AM - Anti-Malware
  • WRS - Web Reputation
  • FW - Firewall
  • DPI - Intrusion Prevention
  • IM - Integrity Monitoring
  • LI - Log Inspection
  • AC - Application Control
  • SAP - SAP

Ignored if allModulesVisible is true

hideUnlicensedModules
boolean
Whether or not all unlicensed modules are hidden. During tenant creation, if this value is not specified, a default value of true is used.
lastSigninTime
number
last login time for this tenant.

Example Request

GET /tenants?sID={sID}
Accept: application/json
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "tenantListing": {
    "tenants": [ {
      "tenantID": 12345,
      "name": "...",
      "databaseServerID": 12345,
      "description": "...",
      "guid": "...",
      "agentInitiatedActivationPassword": "...",
      "state": "...",
      "language": "...",
      "country": "...",
      "timeZone": "...",
      "demoMode": true,
      "allModulesVisible": true,
      "licenseMode": "...",
      "modulesVisible": [ "...", "..." ],
      "hideUnlicensedModules": true,
      "lastSigninTime": 12345
    }, {
      "tenantID": 12345,
      "name": "...",
      "databaseServerID": 12345,
      "description": "...",
      "guid": "...",
      "agentInitiatedActivationPassword": "...",
      "state": "...",
      "language": "...",
      "country": "...",
      "timeZone": "...",
      "demoMode": true,
      "allModulesVisible": true,
      "licenseMode": "...",
      "modulesVisible": [ "...", "..." ],
      "hideUnlicensedModules": true,
      "lastSigninTime": 12345
    } ]
  }
}
                    
                  

Create a tenant

Does not apply to Deep Security as a Service

Multi-tenant environment only

Primary tenant only

Create a tenant.

Request Body

CreateTenantRequest
contains options to be used for the creation of the new tenant.
Properties
createOptions
CreateTenantOptions
The options to use when creating the tenant.
Properties
adminAccount
string
The name of the master user account to create for the tenant.
adminPassword
string
The password for the master user account to create for the tenant.
adminEmail
string
The email address to associate with the master user account created for the tenant, and as the primary point of contact for the tenant.
activationCodes
string
An list of activation codes that can be used when each tenant licenses features separately (optional).
generateMasterPassword
boolean
-
confirmationRequired
boolean
-
bypassTenantCache
boolean
-
tenantElement
The information about the tenant.

Response Codes

200
if the request is successful
403
if the user is not authorized to create a tenant
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

CreateTenantResponse
A response with status 200 OK and a body containing tenant details when adding the tenant succeeds. If parameter validation fails, it will return a response with status 400 Bad Request and a body containing an ErrorMessage. If parameter validation succeeds but creation of the tenant fails, the tenant will be left in a partially created state, and will need to be deleted.
Properties
tenantID
number
Return the ID of the newly created tenant

Example Request

POST /tenants
Content-Type: application/json
Accept: application/json
                    
{
  "createTenantRequest": {
    "createOptions": {
      "adminAccount": "...",
      "adminPassword": "...",
      "adminEmail": "...",
      "activationCodes": [ "...", "..." ],
      "generateMasterPassword": true,
      "confirmationRequired": true,
      "bypassTenantCache": true
    },
    "tenantElement": {
      "tenantID": 12345,
      "name": "...",
      "databaseServerID": 12345,
      "description": "...",
      "guid": "...",
      "agentInitiatedActivationPassword": "...",
      "state": "...",
      "language": "...",
      "country": "...",
      "timeZone": "...",
      "demoMode": true,
      "allModulesVisible": true,
      "licenseMode": "...",
      "modulesVisible": [ "...", "..." ],
      "hideUnlicensedModules": true,
      "lastSigninTime": 12345
    },
    "sessionId": "..."
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "createTenantResponse": {
    "tenantID": 12345
  }
}
                    
                  

Delete a tenant by ID

Does not apply to Deep Security as a Service

Multi-tenant environment only

Primary tenant only

Delete a tenant by ID.

Path Parameters

tID
integer
The ID of the tenant to delete.

Query Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Response Body

DeleteTenantResponse
A response with status 200 OK and a body containing response information when deletion succeeds. If the tenant does not exist, it will return a response with status 404 Not Found and a body containing an ErrorMessage.

Example Request

DELETE /tenants/id/{tID}?sID={sID}
Accept: application/json
                  

Example Response

HTTP/1.1 204 No Content
Content-Type: application/json
                    
{
  "deleteTenantResponse": { }
}
                    
                  

Describe a tenant by ID

Does not apply to Deep Security as a Service

Multi-tenant environment only

Primary tenant only

Retrieve a tenant by ID.

Path Parameters

tID
integer
The ID of the tenant to retrieve.

Query Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Response Codes

200
if the request is successful
403
if the user is not authorized to view tenant information
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

The tenant's information.

Example Request

GET /tenants/id/{tID}?sID={sID}
Accept: application/json
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "tenant": {
    "tenantID": 12345,
    "name": "...",
    "databaseServerID": 12345,
    "description": "...",
    "guid": "...",
    "agentInitiatedActivationPassword": "...",
    "state": "...",
    "language": "...",
    "country": "...",
    "timeZone": "...",
    "demoMode": true,
    "allModulesVisible": true,
    "licenseMode": "...",
    "modulesVisible": [ "...", "..." ],
    "hideUnlicensedModules": true,
    "lastSigninTime": 12345
  }
}
                    
                  

Delete a tenant by name

Does not apply to Deep Security as a Service

Multi-tenant environment only

Primary tenant only

Delete a tenant by name.

Path Parameters

tName
string
The name of the tenant to delete.

Query Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Response Codes

200
if the request is successful
403
if the user is not authorized to delete tenants
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

DeleteTenantResponse
A response with status 200 OK and a body containing response information when deletion succeeds. If the tenant does not exist, it will return a response with status 404 Not Found and a body containing an ErrorMessage.

Example Request

DELETE /tenants/name/{tName}?sID={sID}
Accept: application/json
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "deleteTenantResponse": { }
}
                    
                  

Describe a tenant by name

Does not apply to Deep Security as a Service

Multi-tenant environment only

Primary tenant only

Retrieve a tenant by name.

Path Parameters

tName
string
The tenant's name

Query Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Response Codes

200
if the request is successful
403
if the user is not authorized to view tenant information
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

The tenant's information.

Example Request

GET /tenants/name/{tName}?sID={sID}
Accept: application/json
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "tenant": {
    "tenantID": 12345,
    "name": "...",
    "databaseServerID": 12345,
    "description": "...",
    "guid": "...",
    "agentInitiatedActivationPassword": "...",
    "state": "...",
    "language": "...",
    "country": "...",
    "timeZone": "...",
    "demoMode": true,
    "allModulesVisible": true,
    "licenseMode": "...",
    "modulesVisible": [ "...", "..." ],
    "hideUnlicensedModules": true,
    "lastSigninTime": 12345
  }
}
                    
                  

Modify a tenant by name

Does not apply to Deep Security as a Service

Multi-tenant environment only

Primary tenant only

Update a tenant's information.

Path Parameters

tName
string
The name of the tenant to update.

Request Body

UpdateTenantRequest
-
Properties
tenantElement
Returns the tenant element class that will be used for the update.

Response Codes

200
if the request is successful
403
if the user is not authorized to modify tenant information
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

UpdateTenantResponse
A response with status 200 OK and a body containing response information when updating the tenant succeeds. If tenant name is null or empty, or an attempt is made to modify the name, it will return a response with status 400 Bad Request and a body containing an ErrorMessage. If the tenant does not exist, it will return a response with status 404 Not Found.

Example Request

PUT /tenants/name/{tName}
Content-Type: application/json
Accept: application/json
                    
{
  "updateTenantRequest": {
    "tenantElement": {
      "tenantID": 12345,
      "name": "...",
      "databaseServerID": 12345,
      "description": "...",
      "guid": "...",
      "agentInitiatedActivationPassword": "...",
      "state": "...",
      "language": "...",
      "country": "...",
      "timeZone": "...",
      "demoMode": true,
      "allModulesVisible": true,
      "licenseMode": "...",
      "modulesVisible": [ "...", "..." ],
      "hideUnlicensedModules": true,
      "lastSigninTime": 12345
    },
    "sessionId": "..."
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "updateTenantResponse": { }
}
                    
                  

Describe tenants by state

Does not apply to Deep Security as a Service

Multi-tenant environment only

Primary tenant only

Get tenants by tenant state

Path Parameters

state
string
Tenant state. Currently supported states are:
  • undefined (Default state)
  • created (Tenant is created)
  • active (Tenant is active)
  • suspended (Tenant is suspended)
  • pending-deletion (Tenant is pending to be deleted)
  • db-upgrade-failure (Tenant database upgrade failure)
  • confirmation-required (Tenant confirmation is required)
  • cache-requires-initialization (Cached tenant is pending to be initialized)
  • cache-initializing (Cached tenant is initializing)
  • cache-ready-for-use (Cached tenant is ready for use)
  • cache-activating (Cached tenant is activating)

Query Parameters

maxItems
integer
(optional) the number of items to retrieve. The maximum value for this parameter is controlled by the "Maximum number of items to retrieve from database" setting on the administrator account, which defaults to 5000.
sID
string
tenantID
integer
(optional) used to define the starting point for the query. Combine with tenantIDOp to page through results.
tenantIDOp
string
(optional, required if tenantID is specified) Currently-supported operations are:
  • gt (greater than)
  • ge (greater than or equal to)
  • eq (equal to)
  • lt (less than)
  • le (less than or equal to)

Response Codes

200
if the request is successful
400
if the request is invalid
403
if the user is not authorized to view tenant information
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

a TenantListing with the tenant details.

Example Request

GET /tenants/state/{state}?maxItems={maxItems}&sID={sID}&tenantID={tenantID}&tenantIDOp={tenantIDOp}
Accept: application/json
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "tenantListing": {
    "tenants": [ {
      "tenantID": 12345,
      "name": "...",
      "databaseServerID": 12345,
      "description": "...",
      "guid": "...",
      "agentInitiatedActivationPassword": "...",
      "state": "...",
      "language": "...",
      "country": "...",
      "timeZone": "...",
      "demoMode": true,
      "allModulesVisible": true,
      "licenseMode": "...",
      "modulesVisible": [ "...", "..." ],
      "hideUnlicensedModules": true,
      "lastSigninTime": 12345
    }, {
      "tenantID": 12345,
      "name": "...",
      "databaseServerID": 12345,
      "description": "...",
      "guid": "...",
      "agentInitiatedActivationPassword": "...",
      "state": "...",
      "language": "...",
      "country": "...",
      "timeZone": "...",
      "demoMode": true,
      "allModulesVisible": true,
      "licenseMode": "...",
      "modulesVisible": [ "...", "..." ],
      "hideUnlicensedModules": true,
      "lastSigninTime": 12345
    } ]
  }
}
                    
                  

Trusted update mode

Interface to the Trusted Update Mode API.

Describe trusted update mode

Get the settings for trusted update mode on a host.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

hostID
integer
the host ID.

Response Codes

200
if the request is successful
400
if the request is invalid
403
if the user is not authorized to view trusted update mode on the host
404
if the host does not exist or the user is not authorized to view the host
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

DescribeTrustedUpdateModeResponse
Properties
endTime
number
the current automatic turn off time of trusted update mode on the host.
startTime
number
the current start time of trusted update mode on the host.
state
State
the current state of trusted update mode on the host.
Values
unknown
off
start-requested
on
stop-requested
reset-duration-requested

Example Request

GET /hosts/{hostID}/trusted-update-mode
Accept: application/json
Cookie: sID=12345;
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "DescribeTrustedUpdateModeResponse": {
    "endTime": 12345,
    "startTime": 12345,
    "state": "unknown"
  }
}
                    
                  

Modify trusted update mode

Modify the settings for trusted update mode on a host.

Cookie Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Path Parameters

hostID
integer

Request Body

ModifyTrustedUpdateModeRequest
a ModifyTrustedUpdateModeRequest capturing the requested new state of trusted update mode on the host.
Properties
enabled
boolean
whether trusted update mode should be enabled.
duration
number
the duration (in minutes) that trusted update mode should be enabled.

Response Codes

200
if the request is successful
400
if the request is invalid
403
if the user is not authorized to modify trusted update mode
404
if the host does not exist or the user is not authorized to view the host
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Example Request

POST /hosts/{hostID}/trusted-update-mode
Content-Type: application/json
Cookie: sID=12345;
                    
{
  "ModifyTrustedUpdateModeRequest": {
    "enabled": true,
    "duration": 12345
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
                  

Web reputation events

Interface for event retrieval

List web reputation events

Get Web Reputation events

Query Parameters

eventId
integer
the event id to query for events. Combined with eventIdOp, the returning events can be filtered according to the id.
eventIdOp
string
defined the events to return. Currently supported operations include gt(greater than), ge(greater than or equal to), eq(eqaul to), lt(less than), and le(less than or equal to). If an unsupported operator is provided, the default is 'eq'.
eventTime
integer
the event time to query for events. It is represented by a long integer, which is the milliseconds since January 1, 1970, 00:00:00 GMT. Combined with eventTimeOp, the returning events can be filtered by the specific milliseconds.
eventTimeOp
string
defined the events to return. Currently supported operations include gt(greater than), ge(greater than or equal to), eq(eqaul to), lt(less than), and le(less than or equal to). If an unsupported operator is provided, the default is 'eq'.
maxItems
integer
the maximum events to return
sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Response Codes

200
if the request is successful
400
if the request is invalid
403
if the user is not authorized to view web reputation events
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

ListWebReputationEventsResponse
a WebReputationEventListing, a collection of the events meet the given criteria.
Properties
lastEventID
number
the last event ID.

This will be 0 if no events are retrieved.

events
WebReputationEvent
the list of events.
Properties
hostID
number
The id of the host the event was recorded on
hostName
string
The host name of the event was recorded on
rank
number
Rank
riskLevel
number
The raw score of the url from 0-100, null if the url was blocked because it was blacklisted. Not currently used for anything besides forwarding to syslog.
url
string
The url that caused the event
webReputationID
number
The primary key of the event entry.
detectionCategory
number
CCCA detection source categories
targetIP
string
CCCA detected target IP
moreEvents
boolean
the indicator that there are more events available.

Example Request

GET /events/webreputation?eventId={eventId}&eventIdOp={eventIdOp}&eventTime={eventTime}&eventTimeOp={eventTimeOp}&maxItems={maxItems}&sID={sID}
Accept: application/json
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "WebReputationEventListing": {
    "lastEventID": 12345,
    "events": [ {
      "hostID": 12345,
      "hostName": "...",
      "rank": 12345,
      "riskLevel": 12345,
      "url": "...",
      "webReputationID": 12345,
      "detectionCategory": 12345,
      "targetIP": "...",
      "logTime": 12345,
      "origin": "APPLIANCEAGENT",
      "tags": "..."
    }, {
      "hostID": 12345,
      "hostName": "...",
      "rank": 12345,
      "riskLevel": 12345,
      "url": "...",
      "webReputationID": 12345,
      "detectionCategory": 12345,
      "targetIP": "...",
      "logTime": 12345,
      "origin": "GUESTAGENT",
      "tags": "..."
    } ],
    "moreEvents": true
  }
}
                    
                  

Describe a web reputation event

Get Web Reputation event with specific event id.

Path Parameters

eventID
integer
the event id to fetch

Query Parameters

sID
string
a session ID returned by the IAuthenticationAPI#login(DSCredentials) Authentication API.

Response Codes

200
if the request is successful
400
if the request is invalid
403
if the user is not authorized to view web reputation events
404
if the event does not exist
429
if the request is throttled due to API request limits
500
if there is a server error processing the request
503
if the server is temporarily unavailable

Response Body

the event with the specific id

Example Request

GET /events/webreputation/{eventID}?sID={sID}
Accept: application/json
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "webReputationEvent": {
    "hostID": 12345,
    "hostName": "...",
    "rank": 12345,
    "riskLevel": 12345,
    "url": "...",
    "webReputationID": 12345,
    "detectionCategory": 12345,
    "targetIP": "...",
    "logTime": 12345,
    "origin": "APPLIANCEAGENT",
    "tags": "..."
  }
}