Dome9 API Getting Started

General

Intro

This document describes Dome9ís users API .
Its current functionality is to enable viewing of Dome9 security entities and to allow creating, updating and deleting Access-Leases, IP Lists and Global BlackList.
Note: Please make yourself familiar with the Dome9 Web interface and concepts before using the API.
We made it easy to start developing with our API without even reading this doc. Just point your browser to these main endpoints and examine the returned data (in HTML format): (Use your Dome9 username[your email] and your private API key. It is found at: https://secure.dome9.com/settings)

Base URL

The base URL for production environment is: https://api.dome9.com/v1/

Your Request Format

Authentication
Dome9 API uses standard HTTP basic authentication over a secure SSL channel. Use your Dome9ís username (email) as a username. Use your private API key as the password (found at: https://secure.dome9.com/settings)
HTTP Verbs
The request should be based on standard HTTP request using one of the verbs: GET, POST, PUT, DELETE - relevant to the resource.
Controlling Response Format - the desired response format should be set by the user in 1 of these ways:
Posting Data
We currently support POSTing data in a standard HTTP Form Post format (x-www-form-urlencoded)

Response Format

The API response can be in one of the supported formats:JSON, XML, CSV, HTML.
See request format documentation to learn how to control the response format

cUrl Examples

Listing all my servers
curl -u username@mycompany.com:MYAPIKEY https://api.dome9.com/v1/servers/?format=json 
Get a single server
View a server configuration in a HTML browser friendly format
curl -u username@mycompany.com:MYAPIKEY https://api.dome9.com/v1/servers/XXXXX
Listing all my cloud accounts and regions (with their security groups)
This example is in xml format
curl -u username@mycompany.com:MYAPIKEY https://api.dome9.com/v1/cloud/?format=xml 
Listing all active access leases
curl -u username@mycompany.com:MYAPIKEY https://api.dome9.com/v1/accessleases/?format=json
Acquire access lease for SSH service (on a server with agent)
Get 60 minutes lease for an SSH on one of the servers. Note that only the single mandatory filed (ServiceURI) is provided.
curl -u username@mycompany.com:MYAPIKEY -X POST -d "ServiceURI=https://api.dome9.com/v1/servers/XXXXX/inheritedpolicy/TCP-22" https://api.dome9.com/v1/accessleases/?format=json
Acquire access lease for SSH service (on a cloud security group [agent-less])
Get 60 minutes lease for an SSH service defined in one of the cloud security groups. This leases would affect all instances (servers) connected to this security group. This is the similar to the previous example, with a difference only in the target service (ServiceURI) of the lease.
curl -u username@mycompany.com:MYAPIKEY -X POST -d "ServiceURI=https://api.dome9.com/v1/cloud/XXXXX/securitygroups/YYYYY/policy/ZZZZZ" https://api.dome9.com/v1/accessleases/?format=json
Terminating an existing access lease
(Note that the Dome9 system would terminate the lease automatically if its time has come)
curl -u username@mycompany.com:MYAPIKEY -X DELETE  https://api.dome9.com/v1/accessleases/XXXXX?format=json
Creating a Blacklist
This will create a blacklist with 2 items. The first one has a comment. Note how to pass a collection to the API
curl -H "Accept: application/json" -u username@mycompany.com:MYAPIKEY -X PUT -d "Items=[{IP:\"1.2.3.4\",Comment:\"my comment1\"},{IP:"2.3.4.3/24"}]"  https://api.dome9.com/v1/blacklist
Adding an item to the Blacklist (1 Line IDS integration)
A very simple way to connect your IDS/ honey pot system to Dome9 - affecting all Dome9 agents in your account. This will add an item to the blacklist. If this item already exists - it will override its comment and TTL fields with the new values. The TTL value is in seconds (starting from now).
curl -H "Accept: application/json" -u username@mycompany.com:MYAPIKEY -X "POST" -d "IP=1.2.3.4&TTL=3600&Comment=my comment"  https://api.dome9.com/v1/blacklist/Items/
Delete an existing item from the Blacklist
This will delete an existing item from the Blacklist. It is possible to use IP address or CIDR notation. In this example we are deleting the IP address 1.2.3.4 from the list
curl -H "Accept: application/json" -u username@mycompany.com:MYAPIKEY -X "DELETE"  https://api.dome9.com/v1/blacklist/Items/1.2.3.4
Listing all AWS security groups
curl -H "Accept: application/json" -u username@mycompany.com:MYAPIKEY  https://api.dome9.com/v1/cloudsecuritygroups
Modify an AWS security group's protection mode
This will change the protection mode of an AWS security group (full protection or monitor only). In this example we are updating the security group with id 12345, changing its protection mode to "full manage"
curl -H "Accept: application/json" -u username@mycompany.com:MYAPIKEY -X "PUT"  https://api.dome9.com/v1/cloudsecuritygroups/12345  -d "IsProtected=true"