...
Code Block |
---|
{ "access_token": "bbc0c85653fdc4b83d108cba7641bfcbbc77586dfb8f32d08973770a90fe", "type": "discoveries", "attributes": { "name": "My Test Discovery", "type": "subnet", "subnet": "192.169.1.150" "org_id": 1, "scan_options": {<removed for brevity>}, "match_options": {<removed for brevity>}, } } } |
The Endpoints
At present, we have endpoints for nearly every collection. They are listed here - Collections.
Options
Format
...
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.
...
Code Block |
---|
sort=[-]{attribute} |
Current
NOTE - Removed from 5.0.0. Please use components.current=n or components.current=IN('y','n') instead (if required).
By default, only attributes with "current=y" are retrieved. To override this, set current as below.
Code Block |
---|
current={y|n|all} |
GroupBy
...
NOTE - Removed from 5.0.0.
Code Block |
---|
groupby={attribute} |
Limit
When requesting JSON, by default no limit is set.
...
Code Block |
---|
offset={int} |
Properties
Requested The requested properties should be in a comma-separated list. Properties should be fully qualified - ie, system.hostname (not just hostname).
NOTE - From 5.0.0 onwards, the system table has been replace by the devices table - so devices.name, not system.name.
Code Block |
---|
properties=system.id,system.name,system.status |
...
All endpoints URLs are of the format http://{server}/omk/open-audit/{endpoint}
Devices
...
NOTE - From 5.0.0 all endpoint URLs are of the form - http://{server}/open-audit/index.php/{endpoint}
Devices
NOTE - From 5.0.0 the sub_resource item has been replaced by the components endpoint.
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_resourcecomponents?components.type={sub_resource name}&sub_resourcecomponents.device_id={sub_resource id} | To return a specific item all items 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:
...
| service |
Examples
NOTE - Where there are two examples, the second is for 5.0.0 a newer versions.
NOTE #3 - You should substitute items in the URL enclosed in {} brackets with the relevant items for your environment.
Retrieve all devices with the standard columns:
Code Block |
---|
GET http://{server}/omk/open-audit/devices
GET http://{server}/open-audit/index.php/devices |
Retrieve all devices running Windows.
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 |
Retrieve the first 10 devices running Windows ordered by hostname
Code Block |
---|
GET http://{server}/omk/open-audit/devices?system.os_group=Windows&limit=10&sort=system.hostname GET http://{server}/omk/open-audit/index.php/devices?devices.os_group=Windows&limit=10&sort=devices.hostname |
Retrieve the properties id, ip, hostname, domain, type from all devices running Windows.
Code Block |
---|
GET http://{server}/omk/open-audit/devices?system.os_group=Windows |
Retrieve the first 10 devices running Windows ordered by hostname
Code Block |
---|
properties=system.id,system.ip,system.hostname,system.domain,system.type GET http://{server}/omk/open-audit/index.php/devices?system.os_group=Windows&limit=10&sort=system.hostname |
...
properties=devices.id,devices.ip,devices.hostname,devices.domain,devices.type |
Retrieve all details about the device with id 88.
Code Block |
---|
GET http://{server}/omk/open-audit/devices/88?properties=system.id,system.ip,system.hostname,system.domain,system.type |
...
include=all
GET http://{server}/open-audit/index.php/devices/88 |
Retrieve a list of devices in the 192.168.1.0/24 subnet
Code Block |
---|
GET http://{server}/omk/open-audit/devices/88?include=all |
...
?sub_resource=ip&ip.network=192.168.1.0/24 |
...
Code Block |
---|
&properties=system.id,system.hostname,system.domain,ip.ip GET http://{server}/omk/open-audit/index.php/devices?sub_resource=ip&ip.network=192.168.1.0/24&properties=systemdevices.id,systemdevices.hostname,systemdevices.domain,ip.ip |
Retrieve a list of devices with OS Name like Windows 2008
...
like Windows 2008
Code Block |
---|
GET http://{server}/omk/open-audit/devices?system.os_name=likeWindows 2008 GET http://{server}/omk/open-audit/index.php/devices?systemdevices.os_name=likeWindows 2008 |
...
Code Block |
---|
curl --cookie-jar cookies.txt --form password=password --form username=admin http://localhost{server}/open-audit/index.php/logon |
...
Code Block |
---|
curl -X POST -b cookies.txt http://localhost{server}/open-audit/index.php/credentials -d "data[attributes][name]=test_creds&data[attributes][org_id]=1&data[attributes][type]=ssh&data[attributes][credentials][username]=my_new_user&data[attributes][credentials][password]=my_new_password" |
...
Code Block |
---|
curl -X GET -b cookies.txt http://localhost{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).
Code Block |
---|
curl -X PATCH -b cookies.txt -d 'data={"data":{"id":"3","type":"devices","attributes":{"description":"Test Description"}}}' http://localhost{server}/open-audit/index.php/devices/3 |
...