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": "other-medium-or-smaller",
      "instanceCount": 12345,
      "status": "...",
      "dateBilled": 12345,
      "processed": true,
      "meteringRecordID": "..."
    }, {
      "endDate": 12345,
      "category": "aws-xlarge-or-bigger",
      "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": "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
    }, {
      "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
    } ]
  }
}
                    
                  

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": "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
    }
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "CreateAdministratorResponse": {
    "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
    }
  }
}
                    
                  

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": "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
    }
  }
}
                    
                  

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": "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
                    
{
  "UpdateAdministratorResponse": {
    "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
    }
  }
}
                    
                  

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": "warning",
      "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": "warning",
      "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": "SPYWARE",
      "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": "AGENT",
      "tags": "..."
    }, {
      "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": "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": "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": "SUSPICIOUS_FILE",
    "protocol": 12345,
    "quarantineRecordID": 12345,
    "scanResultAction1": 12345,
    "scanResultAction2": 12345,
    "scanAction1": 12345,
    "scanAction2": 12345,
    "scanType": "MANUAL",
    "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": "blacklisted",
      "fileName": "...",
      "rulesetID": 12345,
      "groupID": "...",
      "groupName": "...",
      "action": "unknown",
      "path": "...",
      "processID": 12345,
      "processName": "...",
      "userID": "...",
      "userName": "...",
      "logTime": 12345,
      "repeatCount": 12345,
      "aggregationType": 12345
    }, {
      "eventID": 12345,
      "sha1": "...",
      "sha256": "...",
      "md5": "...",
      "hostID": 12345,
      "hostName": "...",
      "tags": "...",
      "blockReason": "not-whitelisted",
      "fileName": "...",
      "rulesetID": 12345,
      "groupID": "...",
      "groupName": "...",
      "action": "blocked",
      "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": "unknown",
      "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.

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": "..."
    },
    "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": "..."
  }
}
                    
                  

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": "..."
    },
    "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-moved-by-system",
      "enabled": true,
      "conditions": [ {
        "field": "applianceProtectionActivated",
        "key": "...",
        "value": "..."
      }, {
        "field": "esx",
        "key": "...",
        "value": "..."
      } ],
      "actions": [ {
        "type": "deactivate",
        "parameterValue": 12345
      }, {
        "type": "assign-policy",
        "parameterValue": 12345
      } ]
    }, {
      "id": 12345,
      "name": "...",
      "type": "nsx-protection-changed",
      "enabled": true,
      "conditions": [ {
        "field": "tag",
        "key": "...",
        "value": "..."
      }, {
        "field": "folder",
        "key": "...",
        "value": "..."
      } ],
      "actions": [ {
        "type": "assign-relay",
        "parameterValue": 12345
      }, {
        "type": "activate",
        "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-ip-changed",
      "enabled": true,
      "conditions": [ {
        "field": "esx",
        "key": "...",
        "value": "..."
      }, {
        "field": "tag",
        "key": "...",
        "value": "..."
      } ],
      "actions": [ {
        "type": "assign-relay",
        "parameterValue": 12345
      }, {
        "type": "assign-relay",
        "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": "inherited",
      "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": "high",
      "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": "low",
      "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": "high",
      "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": "service"
    }, {
      "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": "on",
      "lockdown": true,
      "whitelistMode": "inherit",
      "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": "off",
      "lockdown": true,
      "whitelistMode": "shared",
      "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": "off",
      "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": "inherited",
      "description": "..."
    }
  }
}
                    
                  

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
                    
{
  "ModifyPolicyScannerSettingsResponse": {
    "sap": {
      "state": "off",
      "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": "socks4",
      "authenticated": true,
      "username": "...",
      "password": "..."
    }, {
      "ID": 12345,
      "name": "...",
      "description": "...",
      "address": "...",
      "port": 12345,
      "protocol": "http",
      "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": "http",
      "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": "socks5",
      "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": "socks5",
      "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": "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
    }, {
      "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
    } ],
    "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.