You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 17 Next »

Introduction

Open-AudIT is implementing a JSON Restful API to be used both in the web interface and via JSON requests.

NOTE - This API is not ready for a full release as yet and items below are subject to change.As at 1.12.6 though, this is how it stands. We don't envision big breaking changes going forward, but until such time as we give the official "released" stamp of approval, items are subject to (and indeed WILL) change.

NOTE - This page is incomplete and is being updated as we work towards a released verion of the API.

Open-AudIT's API

Open-AudIT is basing it's 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 username and password attributes and values:

http://{server}/open-audit/index.php/login/login_auth

 

The Endpoints

At present we have endpoints for:

devices - The devices, bg surprise.

orgs - The organisations setup within.

networks - The networks detected by Open-AudIT. This also doubles as our "blessed subnets" list.

Collections to be introduced

Locations, scripts, files, users, discoveries, config, additional fields, groups queries and more are planned. Basically everything that is possible to move to the new model inside Open-AudIT will be.

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 contain the string "json". That might be "json/application" or whatever you like. 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}/open-audit/index.php/networks?action=create. The default action if noting matches below is to return a collection of items.

RequestNameIDResultImplemented
GET  Return a collection of itemsY
ANYlist Return a collection of items.Y
GETcreate Show a HTML form to create a new item.N
GETimport  N
GETreadYShow the details of an item.Y
GETeditYShow a form to edit an item's details.Y
POST / PUT / PATCH YUpdate an item's details.Y
DELETE YDelete an item.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, 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={attribute 1},{attribute 2},{attribute 3}

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}

Version

To request a different version of the API (currently only v1 exists), use the attribute 'version'.

version=[1]

 

End Points

All endpoints URLs are of the format http://{server}/open-audit/index.php/{endpoint}

NOTE - The below examples use SQL column names from 1.12.6. This are in the process of being revised for our next release.

Devices

TypeEndpoint  
GET/devicesReturn 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?subresource={subresource name}To return all items in a subresource 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}?subresource={subresource name}To return all items in a subresource for a specific device. 
GET/devices?sub_resource={subresource name}&sub_resource_id={subresource id}To return a specific item in a subresource for a collection of devices - not especially useful. You would more likely use the below (request a subresource items from a specific device) 
GET/devices{id}?sub_resource={subresource name}&sub_resource_id={subresource id}To return a specific subresource item for a specific device. 
POST | PUT | PATCH/devices/{id}

To update a device attribute. The body of the POST should be JSON formatted using the attribute name 'data'.

An example post updating the description is below.

data: {
    "id":1,
    "description":"This is a test"
}
 

Device SubResource Names

NAMENAMENAME

audit_log
bios
change_log
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:

GET http://{server}/open-audit/index.php/devices

Retrieve all devices running Windows.

GET http://{server}/open-audit/index.php/devices?os_group=Windows

Retrieve the first 10 devices running Windows ordered by hostname

GET http://{server}/open-audit/index.php/devices?os_group=Windows&limit=10&sort=hostname

Retrieve the properties id, ip, hostname, domain, type from all devices

GET http://{server}/open-audit/index.php/devices?properties=system_id,man_ip_address,hostname,domain,man_type

Retrieve all details about device with system_id 88.

GET http://{server}/open-audit/index.php/devices/88

Retrieve a list of devices in the 192.168.1.0/24 subnet

GET http://{server}/open-audit/index.php/devices?sub_resource=ip&ip.network=192.168.1.0/24&properties=system.system_id,system.hostname,system.domain,ip.ip

Retrieve a list of devices with OS Name like Windows 2008

GET http://{server}/open-audit/index.php/devices?os_name=likeWindows 2008

 

Networks

 

Orgs

 

 

 

 

  • No labels