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:

...

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:

...

To create a resource, you should POST the required data. The format of your data shoudl be in the form:

data[attributes][ATTRIBUTE_NAME]

You should substitute the required column (eg, org_id) for ATTRIBUTE_NAME.

When POSTing data, you must include an access token. An access token is generated with every request type, so make a GET (for example) and Accept: applicaiotn/json, parse the response for meta→access_token, and include that with your request. This will be in the field data[access_token], IE, the top level.

The format of your data should be in the formIn 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]

Examples at the bottom of this page.

All endpoints also have a minimum list of required fields. These are:

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]

Examples 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'
collectors -    'name', 'org_id', 'status'
configuration - 'value'
connections -   'name', 'org_id'
credentials -   'name', 'org_id', 'type', 'credentials'
dashboards -    'name', 'options'
discoveries -   'name', 'org_id', 'type', 'network_address', 'other'
fields -        applications -  'name', 'org_id', 'type', 'placement', 'group_id'
attributes -files -         'name', 'org_id', 'type', 'resource', 'value'
collectors -path'
groups -        'name', 'org_id', 'statussql'
configuration - 'value'
connectionsldap_servers -   'name', 'org_id'
credentials -   'name, 'lang', 'host', 'port', 'secure', 'org_iddomain', 'type', 'credentials'
dashboards -    'nameversion', 'use_roles', 'optionsrefresh'
discoverieslicenses -      'name', 'org_id', 'typeorg_descendants', 'networkpurchase_addresscount', 'othermatch_string'
fieldslocations -        'name', 'org_id', 'type', 'placementname', 'grouporg_id'
filesnetworks -         'name', 'org_id', 'pathnetwork'
groupsorgs -          'name', 'orgparent_id', 'sql'
ldap_serversqueries -  'name', 'org_id', 'lang', 'host', 'port', 'secure', 'domainname', 'typeorg_id', 'versionsql', 'usemenu_rolescategory', 'refreshmenu_display'
licensesroles -         'name', 'permissions'
scripts -       'org_idname', 'org_descendantsid', 'purchase_countoptions', 'matchbased_stringon'
locationssummaries -     'name', 'org_id'
networks -     , 'nametable', 'org_idcolumn', 'networkmenu_category'
orgstasks -          'name', 'parentorg_id'
queries -       'name, 'type', 'sub_resource_id', 'uuid', 'enabled', 'minute', 'hour', 'orgday_of_idmonth', 'sqlmonth', 'menu_category', 'menu_display'
rolesday_of_week'
users -         'name', 'permissions'
scripts -       'nameorg_id', 'lang', 'org_idactive', 'optionsroles', 'based_onorgs'
summarieswidgets -     'name', 'org_id', 'tablename', 'columnorg_id', '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', 'active', 'roles', 'orgs'
widgets -       'name', 'org_id', 'type'type'

An example JSON POST body is below. This should be attached to the "data" form item.

Code Block

{
  "access_token": "bbc0c85653fdc4b83d108cba7641bfcbbc77586dfb8f32d08973770a90fe",
  "type": "discoveries",
  "attributes": {
    "name": "My Test Discovery",
    "type": "subnet",
    "network_address": "http://127.0.0.1/open-audit/",
    "org_id": 1,
    "other": {
      "subnet": "192.169.1.150"
    }
  }
}

The Endpoints

At present we have endpoints for nearly every collection. They are listed here - Collections.

...

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	y	update	update_form	{collection}::update	/{collection}/{id}/update	Show the script details with the option to update attributes using PATCH to /{collection}/{id}
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.

...

Sort

To sort by a database column, user "sort={attribute}". To reverse sort, insert a minus, thus "sort=-{attribute}".

...

Code Block
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 =. Properties should be fully qualified - ie, system.hostname (not just hostname).

...

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

audit_log
bios
change_log
credentials
disk
dns
edit_log
ip
log
memory
module
monitor
motherboard

netstat
network
optical
pagefile
partition
print_queue
processor
route
san
scsi
server
server_item

service
share
software
software_key
sound
task
user
user_group
variable
video
vm
windows

Examples

Retrieve all devices with the standard columns:

...

Code Block
GET http://{server}/omk/open-audit/devices?system.os_name=likeWindows 2008

...

CURL Examples

Logging in

Code Block
curl --cookie-jar cookies.txt --form password=password --form username=admin http://localhost/open-audit/index.php/logon

...

Space shortcuts

Page tree

Versions Compared

Old Version 33

New Version 34

Key

Access Model

The Endpoints

API Routes

Web Application Routes

Sort

Filter

Devices

Device sub_resource Names

Examples

Space shortcuts

Page tree

Page History

Versions Compared

Old Version 33

New Version 34

Key

Access Model

The Endpoints

API Routes

Web Application Routes

Sort

Filter

Devices

Device sub_resource Names

Examples