Dome9 API Reference

This is Dome9's RESTful API Reference. Read api getting started guide at : http://developer.dome9.com

Resources

servers/{id}

General

Server is correlates to a user's server with a Dome9 agent installed. Sometimes we use the terminology 'agent' instead of server.

resource-wide template parameters
parameter value description

id

string

Default:

Will return the agent (server) with that id. If not specificed will return all servers (that user has permissions for).

Methods

GET

This method lists all the servers (agents) on your account or return a specific server if id is provided.

request query parameters
parameter value description

format

string

One of:

  • json (default)
  • xml
  • html

Response format. This could be supplied as querystring param or as HTTP header 'Accepts'. Note: if using as part of header please append 'application/'. Example- Accept:application/json. If omitted, default value is HTML view (view in a browser)

available response representations:

cloud/{id}

Methods

GET

This method lists all the cloud accounts managed by your Dome9 account. Each region is considered as an independant account.

accessleases/{id}

General

Access Leases provide on demand access to a Dome9 protected service. It is recommended to first be familiar with this concept using Dome9 Central Web Application. The Access Lease can be acquired for 2 kinds of services: (a.) Service of a Dome9 security group that is attached to a server. The lease is for the specific rule in the calculated (inherited) policy of this server (1 service of 1 server) (b.) Service of Cloud security group. Accessing this service will provide access to all instances that are connected to this security group.

resource-wide template parameters
parameter value description

id

string

Specific access lease id. If not specified, will list all active leases for the user. If user is a super-user, it will list all active leases of the account

Methods

GET

This method lists all the active AccessLeases (or a single lease if 'id' is provided).

request query parameters
parameter value description

format

string

One of:

  • json (default)
  • xml
  • html

Response format. This could be supplied as querystring param or as HTTP header 'Accepts'. Note: if using as part of header please append 'application/'. Example- Accept:application/json. If omitted, default value is HTML view (view in a browser)

POST

Create a new Access Lease

request query parameters
parameter value description

ServiceURI

string (required)

The URI of the target service of the Access Lease. This should be a 'service' that belongs to a server (see server/{id}/inheritedpolicy) or to a Cloud Security Group (see cloud/{id}/securitygroups/policy)

Name

string

User friendy name of the Access Lease.

IP

string

RECOMMENDED NOT TO SET THIS FILED. This is the IP address that will be opened by the lease. If not specifid the system will use the (external) IP address of the calling client.

ExpirationMinutes

integer

Number of minutes until automatic termination of the lease by Dome9 central. If not set, system will use 60 minutes as default.

Note

string

Additional text field that is displayed in Central

available response representations:

DELETE

Will delete an active Access Lease given its 'id'

request query parameters
parameter value description

format

string

One of:

  • json (default)
  • xml
  • html

Response format. This could be supplied as querystring param or as HTTP header 'Accepts'. Note: if using as part of header please append 'application/'. Example- Accept:application/json. If omitted, default value is HTML view (view in a browser)

blacklist

General

Blacklist is account wide setting that applies for all Dome9 Agents. This api endpoint is used for bulk operations (update) of the entire list. Use the alternate blacklist/items/ endpoint to create/delete specific item. Note that blacklist is currently supported for agent-based deployments

Methods

GET

This method return the Blacklist entity with all its items

request query parameters
parameter value description

format

string

One of:

  • json (default)
  • xml
  • html

Response format. This could be supplied as querystring param or as HTTP header 'Accepts'. Note: if using as part of header please append 'application/'. Example- Accept:application/json. If omitted, default value is HTML view (view in a browser)

PUT

Update the entire Blacklist

request query parameters
parameter value description

Items

string (required)

A list of CIDR objects (each CIDR object contains the fields 'IP', 'Comment' and 'TTL')

acceptable request representations:

available response representations:

blacklist/items/{IP}

General

Blacklist is account wide setting that applies for all Dome9 Agents. This api endpoint is used for operations (get/create/update/delete) on a specific list item . Use the alternate blacklist/ endpoint to perform bulk operations on the entire list.

resource-wide template parameters
parameter value description

IP

string

Specific IP item in the Blacklist (IP or CIDR notation. Ex. 10.0.0.1 or 192.168.0.0/24 ).

Methods

GET

This method lists all blacklist item (or a single item if 'IP' is provided).

request query parameters
parameter value description

format

string

One of:

  • json (default)
  • xml
  • html

Response format. This could be supplied as querystring param or as HTTP header 'Accepts'. Note: if using as part of header please append 'application/'. Example- Accept:application/json. If omitted, default value is HTML view (view in a browser)

POST

Create or update a single Blacklist item. An item is identified by its IP field.

request query parameters
parameter value description

IP

string (required)

IP or CIDR notation ("192.168.0.1/24") of the blacklisted item. Note: In this method this field could be set in the url or in the post-data.

Comment

string

Optional comment for this item. It is recommended to set this field with some convention to distinguish between human and automatic entries.

TTL

integer

Optional ttl (in seconds) for this item. After this number of seconds the item will be removed from the blacklist.

acceptable request representations:

DELETE

Remove a single item from the Blacklist given its IP

iplist/{id}

General

IP Lists allows you to group several IP addresses and networks into reusable policy objects. It is recommended to first be familiar with this concept using Dome9 Central Web Application. Only super-users are allowed to use this API.

resource-wide template parameters
parameter value description

id

string

Default:

Specific id of the ip list. If not specified, will return all the ip lists in the account.

Methods

GET

This method lists all the ip lists on your account or return a specific ip lists if id is provided.

request query parameters
parameter value description

format

string

One of:

  • json (default)
  • xml
  • html

Response format. This could be supplied as querystring param or as HTTP header 'Accepts'. Note: if using as part of header please append 'application/'. Example- Accept:application/json. If omitted, default value is HTML view (view in a browser)

available response representations:

POST

This method creates a new ip list in your account.

request query parameters
parameter value description

Name

string (required)

A name for the new list

Description

string

Optional description of the new list

Items

string (required)

A list of CIDR objects (each CIDR object contains 'IP' field and 'Comment' field)

acceptable request representations:

PUT

This method updates an existing ip list in your account. The Id parameter is required.

request query parameters
parameter value description

Description

string

Optional new description of the new list, remains unchanged if not specified.

Items

string

Optional list of CIDR objects to replace to old one, remains unchanged if not specified.

acceptable request representations:

DELETE

This method deletes an ip list from your account. The Id parameter is required.

iplists/{id}/items/{IP}

General

IP Lists allows you to group several IP addresses and networks into reusable policy objects. This api endpoint is used for operations (get/create/update/delete) on a specific list item . Use the alternate iplists/{id} endpoint to perform bulk operations on entire lists.

resource-wide template parameters
parameter value description

id

string (required)

Default:

Specific id of the ip list.

IP

string

Specific IP item in the Blacklist (IP or CIDR notation. Ex. 10.0.0.1 or 192.168.0.0/24 ).

Methods

GET

This method lists all the ip list's items (or a single item if 'IP' is provided).

request query parameters
parameter value description

format

string

One of:

  • json (default)
  • xml
  • html

Response format. This could be supplied as querystring param or as HTTP header 'Accepts'. Note: if using as part of header please append 'application/'. Example- Accept:application/json. If omitted, default value is HTML view (view in a browser)

POST

Create or update a single IP List item. An item is identified by its IP field.

request query parameters
parameter value description

IP

string (required)

IP or CIDR notation ("192.168.0.1/24") of the item. Note: In this method this field could be set in the url or in the post-data.

Comment

string

Optional comment for this item. It is recommended to set this field with some convention to distinguish between human and automatic entries.

acceptable request representations:

DELETE

Remove a single item from the an IP List given its IP

Representations

server (application/json)

{ "Id":0000000, "Name":"my web server", "SecurityGroupIds":[1,3], "InheritedPolicy": [ { "Id":"6-80", "ServerId":1000,"Name":"Web", "Description":"HTTP web server", "Port":"80", "Protocol":"TCP", "NormallyOpen":false, "AllowedIPs":[""], "URI":"https://api.dome9.com/v1/servers/1000/inheritedpolicy/TCP-80" }, { "Id":"6-3389", "ServerId":1000, "Name":"Remote Desktop", "Description":"", "Port":"3389", "Protocol":"TCP", "NormallyOpen":false, "AllowedIPs":[""], "URI":"https://api.dome9.com/v1/servers/1000/inheritedpolicy/TCP-3389" } ] ,"Status": { "AgentState":"Accessible", "ReportedIP":"100.200.100.200", "LastKA":"\/Date(1334753222349)\/", "Platform":"Linux", "OSVersion":"Ubuntu", "AgentVersion":"0.6.1.1" }, "URI":"https://api.dome9.com/v1/servers/1000" }

server (application/xml)

<Server xmlns:i="http://www.w3.org/2001/XMLSchema-instance"><Id>9879879</Id><InheritedPolicy><ServicePort><AllowedIPs><string /></AllowedIPs><Description>HTTP web server</Description><Name>Web</Name><NormallyOpen>true</NormallyOpen><Port>80</Port><Protocol>tcp</Protocol><URI>https://api.dome9.com/v1/servers/6565861/inheritedpolicy/TCP-80</URI><Id>TCP-80</Id><ServerId>6565861</ServerId></ServicePort><ServicePort><AllowedIPs><string /></AllowedIPs><Description>Remote connections for MySQL server</Description><Name>121121</Name><NormallyOpen>true</NormallyOpen><Port>3306</Port><Protocol>tcp</Protocol><URI>https://api.dome9.com/v1/servers/6565861/inheritedpolicy/TCP-3306</URI><Id>TCP-3306</Id><ServerId>6565861</ServerId></ServicePort></InheritedPolicy><Name>web1</Name><SecurityGroupIds><long>162</long></SecurityGroupIds><Status><AgentState>Accessible</AgentState><AgentVersion /><IsDirty>true</IsDirty><LastKA>2012-08-02T11:10:00.661Z</LastKA><OSVersion i:nil="true" /><Platform>Linux</Platform><ReportedIP>100.200.100.200</ReportedIP></Status><URI>https://api.dome9.com/v1/servers/5861</URI></Server>

server (text/html)

(just perform a request in a browser)

lease created response (application/json)

{ "Resource": { "Id":"deaddead9063410999d4c27f2c670000", "Name":"Cacti service", "ServiceURI":"https://api.dome9.com/v1/servers/2103213/inheritedpolicy/TCP-80","IP":"100.200.100.200", "Created":"2012-08-27T15:19:09Z", "User":"john@acme.com", "ExpirationMinutes":180, "URI":"https://api.dome9.com/v1/accessleases/deaddea-0000-0000-99d4-c27f2c670000" }, "StatusCode":201, "Message":"AccessLease created" }

lease created response (application/xml)

...

Put blacklist request (application/x-www-form-urlencoded)

Items=[{IP:"1.2.3.4",Comment:"abcd"},{IP:"2.2.2.2/24"}]

Get Blacklist response (application/json)

{ "Items":[{"Comment":"my comment1","IP":"1.1.1.1\/32"},{"Comment":"3 is a bad number","IP":"3.3.3.3\/32"}],"URI":"https:\/\/api.dome9.com\/v1\/blacklist" }

Get Blacklist response (application/xml)

...

Post blacklist item request (application/x-www-form-urlencoded)

IP=1.2.3.4&Comment=hi there

Post blacklist item request with TTL (application/x-www-form-urlencoded)

IP=1.2.3.4&Comment=Blocked by IDS&TTL=3600

Get IP List response (application/json)

{ "Id": 1, "Name": "Office IPs", "Description": "Our office IPs ranges", "Items": [ { "Comment": "Marketing FTP", "IP": "1.1.1.1\/32" }, { "Comment": "", "IP": "2.2.0.0\/16" } ], "URI": "https:\/\/api.dome9.com\/v1\/iplists\/1" }

Get IP List response (application/xml)

<IPList xmlns:i="http://www.w3.org/2001/XMLSchema-instance"><Id>1</Id><Name>Office IPs</Name><Description>Our office IPs ranges</Description><Items><CIDR><Comment>Marketing FTP</Comment><IP>1.1.1.1/32</IP></CIDR><CIDR><Comment /><IP>2.2.0.0/16</IP></CIDR></Items><URI>https://api.dome9.com/v1/iplists/1</URI></IPList>

Post IP List request (application/x-www-form-urlencoded)

Name=My New IP List&Description=It contains all my ips&Items=[{IP:"1.2.3.4",Comment:"abcd"},{IP:"2.2.2.2/24"}]

Put IP List request (application/x-www-form-urlencoded)

Items=[{IP:"1.2.3.4",Comment:"abcd"},{IP:"2.2.2.2/24"}]

Change IP List Description request (application/x-www-form-urlencoded)

Description=New Description

Post iplist item request (application/x-www-form-urlencoded)

IP=1.2.3.4&Comment=hi there