Introduction
Open-AudIT has a JSON Restful API to be used both in the web interface and via JSON requests.
Open-AudIT's API
Open-AudIT is basing its API on http://jsonapi.org with the intention of providing simple and intuitive access in a manner familiar to developers.
In addition to this API, the web interface will use the same request format and supply some additional actions.
Access Model
The API is using our new model of access. Instead of a user <-> group model, we're using user <-> organisation. If you're having trouble at this early stage, just use the 'administrator' or 'open-audit_enterprise' account(s). We have not created the GUI screens to associate a user to an organisation as yet. If you wish to use another account you could run the below SQL directly to create the association:
INSERT INTO oa_user_org VALUES (NULL, $user_id, $org_id, 10, '');
Where your new $user_id and $org_id can be found in the Open-AudIT web interface.
The API uses a cookie. You can request a cookie by sending a POST to the URL below, containing the username and password attributes and values:
http://{server}/omk/open-audit/login
The Endpoints
At present we have endpoints for nearly every collection. They are listed here - Collections.
Options
Format
Using the format option is useful when using a web browser but you wish to see the result in JSON format. Adding format=json achieves this. Normally a web browser will set its accept header to HTML, so in that case, we return the rendered page. Using an API to retrieve JSON you should set the accept header to "json/application". You can override this by providing the format option in the URL.
We tend to use the Google Chrome extension called Postman for testing actual restful queries. You might like to install and test with that. http://www.getpostman.com.
Action
When using the API the default action is determined according to the format and URL. You can override this by providing the 'action' option in the URL. An example of this is when creating a new item. You would normally use POST to /item but in the case of a web user, you need a web form to be able to fill out the item details. In that case, there is no facility for this in a typical JSON Restful API. We work around this by providing action=create in a GET request for the URL. IE - http://{server}/omk/open-audit/networks?action=create. The default action if nothing matches below is to return a collection of items.
| Request | Name | ID | Result | Implemented |
|---|---|---|---|---|
| GET | Return a collection of items | Y | ||
| ANY | list | Return a collection of items. | Y | |
| GET | create | Show an HTML form to create a new item. | N | |
| GET | import | N | ||
| GET | read | Y | Show the details of an item. | Y |
| GET | edit | Y | Show a form to edit an item's details. | Y |
Sort
To sort by a database column, user "sort={attribute}". To reverse sort, insert a minus, thus "sort=-{attribute}".
sort=[-]{attribute}
Current
By default, only attributes with "current=y" are retrieved. To override this, set current as below.
current={y|n|all}
GroupBy
groupby={attribute}
Limit
When requesting JSON, by default no limit is set.
When requesting screen display, the limit is set to 1000 by default.
limit={int}
Offset
The offset is the count of devices you wish to return data from.
offset={int}
Properties
Requested properties should be in a comma-separated list.
properties=id,name,status
You can also specify properties using the below format.
properties=["id","name","status"]
Filter
To filter by a property value, use the property name. Operators that should precede the value are !=, >, >=, <, <=, 'like' and '!like'. If no operator is specified, the default is =.
{attribute}=[operator]{value}
End Points
All endpoints URLs are of the format http://{server}/omk/open-audit/{endpoint}
Devices
| Type | Endpoint | ||
|---|---|---|---|
| GET | /devices | Return a collection of devices with the default set of columns from the system table (system.system_id, system.icon, system.man_type, system.hostname, system.domain, system.man_ip_address, system.man_description, system.man_os_family, system.man_status) | |
| GET | /devices/{id} | Return an individual devices details. | |
| GET | /devices?sub_resource={sub_resource name} | To return all items in a sub_resource for a collection of devices. If you wanted all software you would use http://{server}/open-audit/index.php/devices?sub_resource=software | |
| GET | /devices/{id}?sub_resource={sub_resource name} | To return all items in a sub_resource for a specific device. | |
| GET | /devices?sub_resource={sub_resource name}&sub_resource_id={sub_resource id} | To return a specific item in a sub_resource for a collection of devices - not especially useful. You would more likely use the below (request a sub_resource items from a specific device) | |
| GET | /devices{id}?sub_resource={sub_resource name}&sub_resource_id={sub_resource id} | To return a specific sub_resource item for a specific device. |
Device sub_resource Names
| NAME | NAME | NAME |
|---|---|---|
audit_log | netstat | service |
Examples
Retrieve all devices with the standard columns:
GET http://{server}/omk/open-audit/devices
Retrieve all devices running Windows.
GET http://{server}/omk/open-audit/devices?system.os_group=Windows
Retrieve the first 10 devices running Windows ordered by hostname
GET http://{server}/omk/open-audit/devices?system.os_group=Windows&limit=10&sort=system.hostname
Retrieve the properties id, ip, hostname, domain, type from all devices
GET http://{server}/omk/open-audit/devices?properties=system.id,system.ip,system.hostname,system.domain,system.type
Retrieve all details about the device with id 88.
GET http://{server}/omk/open-audit/devices/88?include=all
Retrieve a list of devices in the 192.168.1.0/24 subnet
GET http://{server}/omk/open-audit/devices?sub_resource=ip&ip.network=192.168.1.0/24&properties=system.id,system.hostname,system.domain,ip.ip
Retrieve a list of devices with OS Name like Windows 2008
GET http://{server}/omk/open-audit/devices?system.os_name=likeWindows 2008