| Table of Contents |
|---|
Introduction
Open-AudIT has a JSON Restful API to be used both in the web interface and via JSON requests.
...
The format of your data should be in the form:
data[attributes][ATTRIBUTE_NAME]
You should substitute the required column (eg, org_id) for ATTRIBUTE_NAME.
In the case where we store several fields (usually in JSON format) inside a BIGTEXT MySQL field (eg: credentials.credentials - the credentials column in the credentials table), you should use the format:
data[attributes][credentials][credentials][username]
Som examples are at the bottom of this page.
All endpoints also have a minimum list of required fields. These are:
applications:
...
name,org_id
attributes:
...
name,org_id,type,resource,value
baselines:
...
name,org_id
buildings:
...
name,org_id,location_id
clouds:
...
name,org_id,type,credentials,options
clusters:
...
name,org_id
collectors:
...
name,org_id,type,host,community,username,password
connections:
...
name,org_id
credentials:
...
name,org_id,type,credentials
dashboards:
...
name,org_id,options,sidebar
devices:
...
name,org_id
discoveries:
...
name,org_id,type
discovery_scan_options:
...
name,org_id,ping,service_version,filtered,open|filtered,timing,nmap_tcp_ports,nmap_udp_ports
fields:
...
name,org_id,type
files:
...
name,org_id,path
groups:
...
name,org_id,sql
integrations:
...
name,org_id,attributes,fields
ldap_servers:
...
name,org_id,lang,host,port,secure,domain,type,version,use_auth,use_roles,refresh
licenses:
...
name,org_id,org_descendants,purchase_count,match_string
locations:
...
name,org_id
networks:
...
name,org_id,network
orgs:
...
name,parent_id
queries:
...
name,org_id,sql,menu_category,menu_display
racks:
...
name,org_id,ru_height
rack_devices:
...
rack_id,device_id,position,height
roles:
...
name,permissions
rules:
...
name,org_id
scripts:
...
name,org_id,options,based_on
summaries:
...
name,org_id,table,column,menu_category
tasks:
...
name,org_id,type,sub_resource_id,uuid,enabled,minute,hour,day_of_month,month,day_of_week
users:
...
name,org_id,lang,roles,orgs
widgets:
...
name,org_id,type
An example JSON POST body is below. This should be attached to the "data" form item.
...
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
NOTE - Removed from 5.0.0.
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.
API Routes
Request Method | ID | Action | Resulting Function | Permission Required | URL Example | Notes |
|---|---|---|---|---|---|---|
POST | n | create | {collection}::create | /{collection} | Insert a new {collection} entry. | |
GET | y | read | {collection}::read | /{collection}/{id} | Returns a {collection} details. | |
PATCH | y | update | {collection}::update | /{collection}/{id} | Update an attribute of a {collection} entry. | |
DELETE | y | delete | {collection}::delete | /{collection}/{id} | Delete a {collection} entry. | |
GET | n | collection | {collection}::read | /{collection} | Returns a list of {collection}. |
Web Application Routes
Request Method | ID | Action | Resulting Function | Permission Required | URL Example | Notes |
|---|---|---|---|---|---|---|
GET | n | create | create_form | {collection}::create | /{collection}/create | Displays a standard web form for submission to POST /{collection}. |
GET | n | import | import_form | {collection}::create | /{collection}/import | Displays a standard web form for submission to POST /{collection}/import. |
POST | n | import | import | {collection}::create | /{collection}/import | Import multiple {collection} using a CSV. |
GET | y | execute | execute | (collection)::see below | /{collection}/{id}/execute | Some collections can be executed - queries, etc - see below. |
Execute permissions required per endpoint
Endpoint | Permission |
|---|---|
baselines | read |
clouds | read |
dashboards | read |
database | update |
discovery | update |
groups | read |
queries | read |
summaries | read |
tasks | read |
Sort
To sort by a database column, use "sort={attribute}". To reverse sort, insert a minus, thus "sort=-{attribute}".
...
NOTE - From 5.0.0 the sub_resource item has been replaced by the components endpoint.
Type | Endpoint v4 | v5 | ||
|---|---|---|---|---|
GET | /system | /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 | /system/{id} | /devices/{id} | Return an individual devices details. | |
GET | /system?sub_resource={sub_resource |
name} | /components?components.type={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 | /system/{id}?sub_resource={sub_resource |
name} | /components?components.type={sub_resource |
name}&components.device_id={id} | To return all items in a sub_resource for a specific device. | |
GET | /system/{id}?sub_resource={sub_resource |
name}&sub_resource_id={sub_resource |
id} | /components/{sub_resource |
id}?components.type={sub_resource |
name} | To return a specific sub_resource item. |
Device sub_resource names / component types
NAME | NAME | NAME |
|---|---|---|
audit_log | netstat | service |
Examples
NOTE - Where there are two examples, the second is for 5Below are v5.0.0 a newer versionsand onward URLs.
NOTE #3 - You should substitute items in the URL enclosed in {} brackets with the relevant items for your environment (and do not include the actual brackets themselves!).
Retrieve all devices with the standard columns:
| Code Block |
|---|
GET http://{server}/omk/open-audit/devices
GET http://{server}/open-audit/index.php/devices |
...
| Code Block |
|---|
GET http://{server}/omk/open-audit/devices?system.os_group=Windows
GET http://{server}/open-audit/index.php/devices?devices.os_group=Windows |
...
| Code Block |
|---|
GET http://{server}/omk/open-audit/devices?system.os_group=Windows&limit=10&sort=system.hostname
GET http://{server}/open-audit/indexindex.php/devices?devices.os_group=Windows&limit=10&sort=devices.hostname |
...
| Code Block |
|---|
GET http://{server}/omk/open-audit/index.php/devices?properties=systemdevices.id,systemdevices.ip,systemdevices.hostname,systemdevices.domain,system.type
GET http://{server}/open-audit/index.php/devices?properties=devices.id,devices.ip,devices.hostname,devices.domain,devices.type |
...
devices.type |
Retrieve all details about the device with id 88.
| Code Block |
|---|
GET http://{server}/omk/open-audit/devices/88?include=all
GET http://{server}/open-audit/index.php/devices/88 |
Retrieve a list of devices in the 192.168.1.0/24 subnet
...
devices in the 192.168.1.0/24
...
subnet
| Code Block |
|---|
GET http://{server}/open-audit/index.php/devices?ip.network=192.168.1.0/24&properties=devices.id,devices.hostname,devices.domain,ip.ip |
Retrieve a list of devices with OS Name like Windows 2008
| Code Block |
|---|
GET http://{server}/omk/open-audit/devices?system.os_name=likeWindows 2008
GET http://{server}/open-audit/index.php/devices?devices.os_name=likeWindows 2008 |
...
| Code Block |
|---|
curl -X GET -b cookies.txt http://{server}/open-audit/index.php/credentials |
Update attributes
NOTE - The curly brackets in the data filed should be used as-is (not replaced as per other examples above).
...