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.
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.
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.
Applies to Deep Security as a Service only
Applies to Deep Security as a Service only
Retrieve AWS billing records
GET /aws-billing/meteringRecords?endDate={endDate}&startDate={startDate} Accept: application/json Cookie: sID=12345;
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": "..."
} ]
}
}
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:
List administrator roles.
When the "all hosts" flag is true
, rights assigned to the role will apply to all hosts.
When the "all policies" flag is true
, rights assigned to the role will apply to all policies.
When the "allow GUI access" flag is true
, administrators with this role will be allowed to access the Deep Security Manager console.
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.
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.
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.
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.
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.
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.
GET /administrator-roles?administratorRoleID={administratorRoleID}&administratorRoleIDOp={administratorRoleIDOp}&maxItems={maxItems} Accept: application/json Cookie: sID=12345;
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 a new administrator role.
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 ]
}
}
}
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 /administrator-roles/{roleID} Cookie: sID=12345;
HTTP/1.1 200 OK
Describe an administrator role.
GET /administrator-roles/{roleID} Accept: application/json Cookie: sID=12345;
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.
Any unset elements in the request object will be left unchanged by the modify 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 ]
}
}
}
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 ]
}
}
}
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.
POST /administrator-roles/{roleID}/host-groups
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
{
"AddAdministratorRoleHostGroupsRequest": {
"hostGroups": [ 12345, 12345 ]
}
}
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 ]
}
}
}
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.
PUT /administrator-roles/{roleID}/host-groups
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
{
"ModifyAdministratorRoleHostGroupsRequest": {
"hostGroups": [ 12345, 12345 ]
}
}
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 ]
}
}
}
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.
POST /administrator-roles/{roleID}/hosts
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
{
"AddAdministratorRoleHostsRequest": {
"hosts": [ 12345, 12345 ]
}
}
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 ]
}
}
}
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.
PUT /administrator-roles/{roleID}/hosts
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
{
"ModifyAdministratorRoleHostsRequest": {
"hosts": [ 12345, 12345 ]
}
}
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 ]
}
}
}
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.
POST /administrator-roles/{roleID}/policies
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
{
"AddAdministratorRolePoliciesRequest": {
"policies": [ 12345, 12345 ]
}
}
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 ]
}
}
}
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.
PUT /administrator-roles/{roleID}/policies
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
{
"ModifyAdministratorRolePoliciesRequest": {
"policies": [ 12345, 12345 ]
}
}
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 ]
}
}
}
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.
POST /administrator-roles/{roleID}/rights
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
{
"AddAdministratorRoleRightsRequest": {
"rights": [ "...", "..." ]
}
}
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 ]
}
}
}
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.
PUT /administrator-roles/{roleID}/rights
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
{
"ModifyAdministratorRoleRightsRequest": {
"rights": [ "...", "..." ]
}
}
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 ]
}
}
}
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.DELETE /administrator-roles/{roleID}/host-groups/{hostGroupID} Accept: application/json Cookie: sID=12345;
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 ]
}
}
}
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.DELETE /administrator-roles/{roleID}/hosts/{hostID} Accept: application/json Cookie: sID=12345;
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 ]
}
}
}
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.DELETE /administrator-roles/{roleID}/policies/{policyID} Accept: application/json Cookie: sID=12345;
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 ]
}
}
}
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.
DELETE /administrator-roles/{roleID}/rights/{rightID} Accept: application/json Cookie: sID=12345;
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 ]
}
}
}
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.
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.
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.
The locale is specified in IETF BCP 47 format,
for example en-US
. Deep Security supports three locales for administrators:
en-US
- US Englishja-JP
- Japanesezh-CN
- Simplified ChineseDeep 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.
The administrator time format determines whether times are shown in 12-hour or 24-hour format in the Deep Security Manager console.
If the "password never expires" flag is set to true
, then the Deep Security Manager password expiry settings will not apply to this administrator.
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.
If you enable the report PDF password, any reports sent to the administrator will be protected using the report PDF password.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
GET /administrators?administratorID={administratorID}&administratorIDOp={administratorIDOp}&maxItems={maxItems} Accept: application/json Cookie: sID=12345;
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 a new administrator.
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
}
}
}
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 /administrators/{administratorID} Cookie: sID=12345;
HTTP/1.1 200 OK
Describe an administrator.
GET /administrators/{administratorID} Accept: application/json Cookie: sID=12345;
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.
Any unset elements in the request object will be left unchanged by the modify 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
}
}
}
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.
GET /administrators/{administratorID}/ui-preferences/{pageName} Accept: application/json Cookie: sID=12345;
HTTP/1.1 200 OK
Content-Type: application/json
{
"ListUIPreferencesResponse": {
"uiPreferences": [ {
"key": "...",
"value": "..."
}, {
"key": "...",
"value": "..."
} ]
}
}
Modify UI preferences.
POST /administrators/{administratorID}/ui-preferences/{pageName}
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
{
"ModifyUIPreferencesRequest": {
"uiPreferences": [ {
"key": "...",
"value": "..."
}, {
"key": "...",
"value": "..."
} ]
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"ModifyUIPreferencesResponse": {
"uiPreferences": [ {
"key": "...",
"value": "..."
}, {
"key": "...",
"value": "..."
} ]
}
}
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.
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.
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.
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.
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.
When disabled no alerts of this type will be raised by the Deep Security Manager.
Either warning or critical.
When set this flag indicates that an email notification should be sent each time the conditions change for an alert of this type.
When set this flag indicates that an email notification should be sent each time the conditions change for an alert of this type.
When set this flag indicates that an email notification should be sent each time an alert of this type is resolved.
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.
GET /alert-types?alertTypeID={alertTypeID}&maxItems={maxItems}&op={op}&overrides={overrides} Accept: application/json Cookie: sID=12345;
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 to default values.
DELETE /alert-types/{alertTypeID} Cookie: sID=12345;
HTTP/1.1 200 OK
Describe an alert type.
GET /alert-types/{alertTypeID}?overrides={overrides} Accept: application/json Cookie: sID=12345;
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.
Any unset elements in the request object will be left unchanged by the modify 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
}
}
}
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
}
}
}
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
The value will be one of:
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.
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.
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.
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.
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.
The value will be one of:
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.
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.
GET /alerts?alertID={alertID}&dismissed={dismissed}&maxItems={maxItems}&op={op} Accept: application/json Cookie: sID=12345;
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.
DELETE /alerts/{alertID} Cookie: sID=12345;
HTTP/1.1 200 OK
Describe an alert.
GET /alerts/{alertID}?dismissed={dismissed} Accept: application/json Cookie: sID=12345;
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 for one target.
DELETE /alerts/{alertID}/target/{targetID} Cookie: sID=12345;
HTTP/1.1 200 OK
Interface for event retrieval
Get anti-malware events.
This will be 0
if no events are retrieved.
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
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
GET /events/antimalware?eventId={eventId}&eventIdOp={eventIdOp}&eventTime={eventTime}&eventTimeOp={eventTimeOp}&maxItems={maxItems}&sID={sID} Accept: application/json
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
}
}
Get an anti-malware event.
GET /events/antimalware/{eventId}?sID={sID} Accept: application/json
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": "..."
}
}
Interface for retrieving Application Control events.
Get Application Control events.
This will be 0
if no events are retrieved.
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
.
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.
Event types is one of the following:
- Execution of Unrecognized Software Allowed
- Execution of Unrecognized Software Blocked
- Execution of Software Blocked by Rule
GET /events/appcontrol?eventID={eventID}&eventIDOp={eventIDOp}&eventTime={eventTime}&eventTimeOp={eventTimeOp}&maxItems={maxItems} Accept: application/json Cookie: sID=12345;
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
}
}
Get the Application Control event with the specified event ID.
GET /events/appcontrol/{eventID} Accept: application/json Cookie: sID=12345;
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
}
}
}
Interface for the authentication API.
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.
POST /authentication/login
Content-Type: application/json
Accept: application/json
{
"dsCredentials": {
"tenantName": "...",
"userName": "...",
"password": "...",
"applicationInfos": {
"applicationName": "...",
"applicationVersion": "...",
"serverName": "...",
"requestID": "..."
},
"mfaCode": "..."
}
}
HTTP/1.1 200 OK
Content-Type: application/json
...
Ends the client session. The given session ID will not be usable after this call.
200 OK
when the logout succeeds.
The returned string is purely informational and can be ignored.
200 OK
when the logout succeeds.
The returned string is purely informational and can be ignored.
DELETE /authentication/logout?sID={sID} Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json
...
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:
GET /authentication/signinastenant/name/{tenantName}?sID={sID} Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json
...
Applies to AWS Marketplace only
Primary tenant only
Interface for AWS MMS usage retrieval
Applies to AWS Marketplace only
Primary tenant only
Get AWS MMS Usage data - detailed view
GET /mms/details?endDate={endDate}&sID={sID}&startDate={startDate} Accept: application/json
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": "..."
} ]
}
}
Applies to AWS Marketplace only
Primary tenant only
Get AWS MMS Usage data - summary view
GET /mms/summary?endDate={endDate}&sID={sID}&startDate={startDate} Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json
{
"##default": {
"summary": [ {
"usageDate": 12345,
"category": "...",
"instanceCount": 12345,
"status": "..."
}, {
"usageDate": 12345,
"category": "...",
"instanceCount": 12345,
"status": "..."
} ]
}
}
Interface for the Cloud Account API. For AWS Cloud Accounts, see 'Cloud Accounts - AWS'
Lists all of the cloud accounts that are in Deep Security
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
GET /cloudaccounts Accept: application/json Cookie: sID=12345;
HTTP/1.1 200 OK
Content-Type: application/json
{
"ListCloudAccountsResponse": {
"cloudAccount": [ {
"id": 12345,
"cloudType": "...",
"name": "...",
"lastTimeSynchronized": 12345
}, {
"id": 12345,
"cloudType": "...",
"name": "...",
"lastTimeSynchronized": 12345
} ]
}
}
Add a new cloud account.
The following fields of the CloudAccountElement are mandatory:
For VCLOUD
For AZURE
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.
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": "..."
}
}
HTTP/1.1 201 Created
Content-Type: application/json
{
"createCloudAccountResponse": {
"cloudAccountId": 12345
}
}
Delete a cloud account.
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
.
DELETE /cloudaccounts/{cloudAccountID}?sID={sID} Accept: application/json
HTTP/1.1 204 No Content
Content-Type: application/json
{
"deleteCloudAccountResponse": { }
}
Get a specific cloud account.
404 Not Found
when trying to retrieve a non-existent cloud account.
GET /cloudaccounts/{cloudAccountID}?sID={sID} Accept: application/json
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": "..."
}
}
Update cloud account information.
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.
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": "..."
}
}
HTTP/1.1 204 No Content
Content-Type: application/json
{
"updateCloudAccountResponse": { }
}
Synchronize a cloud account by ID.
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
.
PUT /cloudaccounts/{cloudAccountID}/synchronize?sID={sID} Accept: application/json
HTTP/1.1 204 No Content
Content-Type: application/json
{
"synchronizeCloudAccountResponse": {
"startTime": 12345,
"endTime": 12345
}
}
Test a cloud account connection against its supporting cloud provider.
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
.
PUT /cloudaccounts/{cloudAccountID}/testconnection?sID={sID} Accept: application/json
HTTP/1.1 204 No Content
Content-Type: application/json
{
"testCloudAccountResponse": { }
}
Interface for the AWS Account API.
Create a new AWS account cloud connector.
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
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
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"AddAwsAccountResponse": {
"awsAccountId": "...",
"internalId": 12345,
"awsAccountAlias": "..."
}
}
Delete an existing AWS account cloud connector.
DELETE /cloudaccounts/aws/{internalID} Cookie: sID=12345;
HTTP/1.1 200 OK
Describe an existing AWS account cloud connector.
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
GET /cloudaccounts/aws/{internalID} Accept: application/json Cookie: sID=12345;
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
}
}
Trigger a sync of the specified AWS account cloud connector.
POST /cloudaccounts/aws/{internalID}/sync Cookie: sID=12345;
HTTP/1.1 200 OK
Update the specified AWS cloud account
POST /cloudaccounts/aws/{internalID}/update
Content-Type: application/json
Cookie: sID=12345;
{
"UpdateAwsAccountRequest": {
"useInstanceRole": true,
"awsCredentials": {
"accessKeyId": "...",
"secretKey": "..."
},
"seedRegion": "...",
"crossAccountRole": {
"roleArn": "...",
"externalId": "..."
},
"workspacesEnabled": true
}
}
HTTP/1.1 200 OK
Support interface for retrieving diagnostic information from the system.
Retrieve the manager diagnostics package.
GET /support/manager/diagnostics-package?verbose={verbose} Accept: application/json Cookie: sID=12345;
HTTP/1.1 200 OK
Content-Type: application/json
...
Retrieve the agent diagnostics package for a specific host.
If the agent is not reachable, then only the manager diagnostics will be included.
GET /support/hosts/{hostID}/diagnostics-package Accept: application/json Cookie: sID=12345;
HTTP/1.1 200 OK
Content-Type: application/json
...
Interface to the Event-Based Task API.
List event-based tasks.
true
and false
.true
and false
.This action requires a parameter. The parameter value is the policy identifier for the policy that will be assigned to the computer.
This action requires a parameter. The parameter value is the relay identifier for the relay that will be assigned to the computer.
This action requires a parameter. The parameter value is the host group identifier for the host group that the computer will be assigned to.
GET /tasks/event-based Accept: application/json Cookie: sID=12345;
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 a new event-based task.
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
} ]
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"CreateEventBasedTaskResponse": {
"taskID": 12345
}
}
Delete an event-based task.
DELETE /tasks/event-based/{id} Cookie: sID=12345;
HTTP/1.1 200 OK
Interface for the Host Group API.
List the entire host group tree
GET /host-groups Accept: application/json Cookie: sID=12345;
HTTP/1.1 200 OK
Content-Type: application/json
{
"ListHostGroupsResponse": {
"hostGroups": [ {
"children": [ { }, { } ],
"id": 12345,
"name": "...",
"type": "..."
}, {
"children": [ { }, { } ],
"id": 12345,
"name": "...",
"type": "..."
} ]
}
}
Interface for host scanner settings.
Delete any host-level scanner setting overrides on a host.
DELETE /hosts/{hostID}/scanner/settings Cookie: sID=12345;
HTTP/1.1 204 No Content
Describe the scanner settings on a host.
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.
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.
GET /hosts/{hostID}/scanner/settings?overrides={overrides} Accept: application/json Cookie: sID=12345;
HTTP/1.1 200 OK
Content-Type: application/json
{
"DescribeHostScannerSettingsResponse": {
"sap": {
"state": "inherited",
"description": "..."
}
}
}
Modify the scanner settings on a host.
POST /hosts/{hostID}/scanner/settings
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
{
"ModifyHostScannerSettingsRequest": {
"sap": {
"state": "inherited",
"description": "..."
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"ModifyHostScannerSettingsResponse": {
"sap": {
"state": "off",
"description": "..."
}
}
}
Delete host-level antimalware setting already defined in antimalware settings overrides on a host.
DELETE /hosts/{hostID}/antimalware/settings Cookie: sID=12345;
HTTP/1.1 204 No Content
Describe the antimalware settings on a host.
GET /hosts/{hostID}/antimalware/settings?overrides={overrides} Accept: application/json Cookie: sID=12345;
HTTP/1.1 200 OK
Content-Type: application/json
{
"DescribeAntimalwareSettingsResponse": {
"settings": {
"predictiveMachineLearningExceptions": [ "...", "..." ]
}
}
}
Modify the antimalware settings on a host.
POST /hosts/{hostID}/antimalware/settings
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
{
"ModifyAntiMalwareSettingsRequest": {
"settings": {
"predictiveMachineLearningExceptions": [ "...", "..." ]
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"ModifyAntiMalwareSettingsResponse": {
"settings": {
"predictiveMachineLearningExceptions": [ "...", "..." ]
}
}
}
Delete any policy-level antimalware setting: AntiMalwareSettings overrides on a policy.
DELETE /policies/{policyID}/antimalware/settings Cookie: sID=12345;
HTTP/1.1 204 No Content
Describe the antimalware settings on a policy.
GET /policies/{policyID}/antimalware/settings?overrides={overrides} Accept: application/json Cookie: sID=12345;
HTTP/1.1 200 OK
Content-Type: application/json
{
"DescribeAntimalwareSettingsResponse": {
"settings": {
"predictiveMachineLearningExceptions": [ "...", "..." ]
}
}
}
Modify the antimalware settings on a policy.
POST /policies/{policyID}/antimalware/settings
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
{
"ModifyAntiMalwareSettingsRequest": {
"settings": {
"predictiveMachineLearningExceptions": [ "...", "..." ]
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"ModifyAntiMalwareSettingsResponse": {
"settings": {
"predictiveMachineLearningExceptions": [ "...", "..." ]
}
}
}
Applies to Deep Security as a Service only
Applies to Deep Security as a Service only
Retrieve a list of instance rate data
GET /monitoring/usages/hosts/instancerates Accept: application/json Cookie: sID=12345;
HTTP/1.1 200 OK
Content-Type: application/json
{
"ListInstanceRatesResponse": {
"instanceRates": [ {
"instanceName": "...",
"rate": 12345.0
}, {
"instanceName": "...",
"rate": 12345.0
} ]
}
}
Interface for 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.
This will be 0
if no events are retrieved.
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
.
GET /events/integrity?eventID={eventID}&eventIDOp={eventIDOp}&eventTime={eventTime}&eventTimeOp={eventTimeOp}&extendedDesc={extendedDesc}&maxItems={maxItems} Accept: application/json Cookie: sID=12345;
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
}
}
Get the Integrity event with the specified event ID.
GET /events/integrity/{eventID}?extendedDesc={extendedDesc} Accept: application/json Cookie: sID=12345;
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
}
}
}
Interface for the licensing API.
Describe the license status of DSM modules. The level of detail depends on user permissions.
GET /license Accept: application/json Cookie: sID=12345;
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
}
}
}
}
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
POST /license?update={update}
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
{
"UpdateLicenseActivationCodesRequest": {
"activationCodes": [ "...", "..." ]
}
}
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 API.
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.
This will be 0
if no events are retrieved.
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
.
GET /events/logInspection?eventID={eventID}&eventIDOp={eventIDOp}&eventTime={eventTime}&eventTimeOp={eventTimeOp}&maxItems={maxItems} Accept: application/json Cookie: sID=12345;
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
}
}
Get the Log Inspection event with the specified event ID.
GET /events/logInspection/{eventID} Accept: application/json Cookie: sID=12345;
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": "..."
}
}
}
Does not apply to Deep Security as a Service
Primary tenant only
Interface to the manager node API.
Does not apply to Deep Security as a Service
Primary tenant only
List manager nodes.
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.
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.
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.
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.
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.
This may not be the actual machine hostname on the manager node; it is the name used for the manager node in the database.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
GET /manager-nodes?id={id}&maxItems={maxItems}&op={op} Accept: application/json Cookie: sID=12345;
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": "..."
} ]
}
}
Does not apply to Deep Security as a Service
Primary tenant only
Delete a manager node.
DELETE /manager-nodes/{managerNodeID} Cookie: sID=12345;
HTTP/1.1 200 OK
Does not apply to Deep Security as a Service
Primary tenant only
Describe a manager node.
GET /manager-nodes/{managerNodeID} Accept: application/json Cookie: sID=12345;
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": "..."
}
}
}
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.
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": "..."
}
}
}
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": "..."
}
}
}
Does not apply to Deep Security as a Service
Primary tenant only
Interface for the Multi Tenant Configuration API.
Does not apply to Deep Security as a Service
Primary tenant only
Configuration of DSM Multi Tenant settings.
GET /multitenantconfiguration?sID={sID} Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json
{
"multiTenantConfiguration": {
"activationCode": "...",
"configurationType": "...",
"licenseModeType": "..."
}
}
Does not apply to Deep Security as a Service
Primary tenant only
Set the multi-tenant configuration.
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.
PUT /multitenantconfiguration
Content-Type: application/json
Accept: application/json
{
"updateMultiTenantConfigurationRequest": {
"multiTenantConfigurationElement": {
"activationCode": "...",
"configurationType": "...",
"licenseModeType": "..."
},
"sessionId": "..."
}
}
HTTP/1.1 204 No Content
Content-Type: application/json
{
"updateMultiTenantConfigurationResponse": { }
}
Management API for News Feed.
Get metadata about the news feed.
GET /newsfeed?background={background} Accept: application/json Cookie: sID=12345;
HTTP/1.1 200 OK
Content-Type: application/json
{
"DescribeNewsFeedResponse": {
"hasCriticalEntry": true,
"hasCommunicationError": true,
"newEntries": 12345
}
}
List news feed entries.
GET /newsfeed/entries?all={all}&entryID={entryID}&entryIDOp={entryIDOp}&maxItems={maxItems} Accept: application/json Cookie: sID=12345;
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 a news feed entry.
DELETE /newsfeed/entries/{entryID} Cookie: sID=12345;
HTTP/1.1 204 No Content
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
Does not apply to Deep Security as a Service
Primary tenant only
List performance profiles.
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.
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.
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.
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.
GET /performance-profiles?maxItems={maxItems}&op={op}&performanceProfileID={performanceProfileID} Accept: application/json Cookie: sID=12345;
HTTP/1.1 200 OK
Content-Type: application/json
{
"ListPerformanceProfilesResponse": {
"performanceProfiles": [ {
"ID": 12345,
"name": "...",
"preferred": true,
"content": "..."
}, {
"ID": 12345,
"name": "...",
"preferred": true,
"content": "..."
} ]
}
}
Does not apply to Deep Security as a Service
Primary tenant only
Create a performance profile.
PUT /performance-profiles
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
{
"CreatePerformanceProfileRequest": {
"performanceProfile": {
"ID": 12345,
"name": "...",
"preferred": true,
"content": "..."
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"CreatePerformanceProfileResponse": {
"performanceProfile": {
"ID": 12345,
"name": "...",
"preferred": true,
"content": "..."
}
}
}
Does not apply to Deep Security as a Service
Primary tenant only
Delete a performance profile.
DELETE /performance-profiles/{performanceProfileID} Cookie: sID=12345;
HTTP/1.1 200 OK
Does not apply to Deep Security as a Service
Primary tenant only
Describe a performance profile.
GET /performance-profiles/{performanceProfileID} Accept: application/json Cookie: sID=12345;
HTTP/1.1 200 OK
Content-Type: application/json
{
"DescribePerformanceProfileResponse": {
"performanceProfile": {
"ID": 12345,
"name": "...",
"preferred": true,
"content": "..."
}
}
}
Does not apply to Deep Security as a Service
Primary tenant only
Modify a performance profile.
POST /performance-profiles/{performanceProfileID}
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
{
"ModifyPerformanceProfileRequest": {
"performanceProfile": {
"ID": 12345,
"name": "...",
"preferred": true,
"content": "..."
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"ModifyPerformanceProfileResponse": {
"performanceProfile": {
"ID": 12345,
"name": "...",
"preferred": true,
"content": "..."
}
}
}
Interface to the Application Control Policy API.
Retrieve the application control settings for a policy.
GET /policies/{policyID}/application-control Accept: application/json Cookie: sID=12345;
HTTP/1.1 200 OK
Content-Type: application/json
{
"DescribeApplicationControlPolicyResponse": {
"appControlPolicyParameters": {
"state": "on",
"lockdown": true,
"whitelistMode": "inherit",
"rulesetID": 12345
}
}
}
Modify the application control portion of a policy.
POST /policies/{policyID}/application-control
Content-Type: application/json
Cookie: sID=12345;
{
"ModifyApplicationControlPolicyRequest": {
"appControlPolicyParameters": {
"state": "off",
"lockdown": true,
"whitelistMode": "shared",
"rulesetID": 12345
}
}
}
HTTP/1.1 200 OK
Interface for scanner settings in the security policy.
Delete any policy-level scanner setting overrides on a policy.
DELETE /policies/{policyID}/scanner/settings Cookie: sID=12345;
HTTP/1.1 204 No Content
Describe the scanner settings on a policy.
GET /policies/{policyID}/scanner/settings?overrides={overrides} Accept: application/json Cookie: sID=12345;
HTTP/1.1 200 OK
Content-Type: application/json
{
"DescribePolicyScannerSettingsResponse": {
"sap": {
"state": "off",
"description": "..."
}
}
}
Modify the scanner settings on a policy.
POST /policies/{policyID}/scanner/settings
Content-Type: application/json
Accept: application/json
Cookie: sID=12345;
{
"ModifyPolicyScannerSettingsRequest": {
"sap": {
"state": "inherited",
"description": "..."
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"ModifyPolicyScannerSettingsResponse": {
"sap": {
"state": "off",
"description": "..."
}
}
}
Interface to the Proxy API.
List proxies.
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.
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.
GET /proxies?defaultType={defaultType}&id={id}&maxItems={maxItems}&op={op} Accept: application/json Cookie: sID=12345;
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 new proxy.
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": "..."
}
}
}
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 /proxies/{proxyID} Cookie: sID=12345;
HTTP/1.1 200 OK
Describe a proxy.
GET /proxies/{proxyID} Accept: application/json Cookie: sID=12345;
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.
Any unset elements in the request object will be left unchanged by the modify 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": "..."
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"UpdateProxyResponse": {
"proxy": {
"ID": 12345,
"name": "...",
"description": "...",
"address": "...",
"port": 12345,
"protocol": "socks5",
"authenticated": true,
"username": "...",
"password": "..."
}
}
}
Interface to the Relay Group API.
List relay groups
GET /relay-groups?ascending={ascending}&background={background}&expanded={expanded}&maxItems={maxItems}&offset={offset}&sortBy={sortBy} Accept: application/json Cookie: sID=12345;
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.
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"