Introduction
Here are some examples for using the Open-AudIT API via Postman.
When beginning a new request, we always logon and store the returned cookie for future use. In addition to the cookie, if we want to create a resource (Orgs, Locations, Credentials, Discoveries, et al) we need to provide an access token. An access token is generated with every request (except logon) and any of the last 20 (by default, settable in the configuration) will be accepted. You should always aim to use the last access token issued. An example token is in the Get Device List response, below.
Logon
Request
Section | |||
---|---|---|---|
URL | POST | http://localhost/omk/open-audit/login | |
Headers | Accept | application/json | |
Body | Type | form-data | |
Key | username | admin | |
Key | password | password |
Response
{ "message": "Authenticated as user admin", "ok": 1 }
Read Devices
Logon as above, then.
Request
Section | ||
---|---|---|
URL | GET | http://localhost/omk/open-audit/devices |
Headers | Accept | application/json |
Response
Note - restricted to one item in the data array, normally you will retrieve all items.
{ "data": [ { "attributes": { "locations.id": 1, "orgs.id": 1, "orgs.name": "Default Organisation", "system.class": "virtual server", "system.dbus_identifier": "", "system.description": "win 2008r2 with iis", "system.dns_domain": "", "system.dns_fqdn": "", "system.dns_hostname": "", "system.domain": "open-audit.local", "system.environment": "production", "system.first_seen": "2020-03-19 11:47:50", "system.form_factor": "Virtual", "system.fqdn": "win2012r2_web02.open-audit.local", "system.function": "", "system.hostname": "win2012r2_web02", "system.icon": "windows", "system.id": 19, "system.identification": "Virtual server from VMware, Inc.", "system.ip": "192.168.1.138", "system.ip_padded": "192.168.001.138", "system.last_seen": "2020-03-19 11:48:42", "system.last_seen_by": "audit", "system.location_id": 1, "system.manufacturer": "VMware, Inc.", "system.model": "VMware Virtual Platform", "system.name": "win2012r2_web02", "system.org_id": 1, "system.os_family": "Windows 2008", "system.os_group": "Windows", "system.os_name": "Microsoft Windows Server 2008 R2 Standard", "system.os_version": "6.1.7601", "system.serial": "VMware-56 4d 3a 1e b9 d5 13 17-fc 68 fb 3d e5 5a b6 77", "system.snmp_oid": "", "system.status": "production", "system.sysContact": "", "system.sysDescr": "", "system.sysLocation": "", "system.sysName": "", "system.sysObjectID": "", "system.sysUpTime": "", "system.type": "computer", "system.uuid": "1E3A4D56-D5B9-1713-FC68-FB3DE55AB677" }, "id": 19, "links": { "self": "http://localhost/omk/open-audit/system/19" }, "type": "system" } ], "included": [], "links": { "first": "http://localhost/omk/open-audit/devices?properties=default", "last": "http://localhost/omk/open-audit/devices?properties=default", "next": "http://localhost/omk/open-audit/devices?properties=default", "prev": "http://localhost/omk/open-audit/devices?properties=default", "self": "http://localhost/omk/open-audit/devices" }, "meta": { "access_token": "23652075c7660006c281bf33589620dc093bdbedf8eb7ed1223449a95748", "action": "collection", "baseurl": "http://localhost/omk/open-audit", "collection": "devices", "current": "y", "data_order": [ "system.id", "system.uuid", "system.name", "system.ip", "system.hostname", "system.dns_hostname", "system.domain", "system.dns_domain", "system.dbus_identifier", "system.fqdn", "system.dns_fqdn", "system.description", "system.type", "system.icon", "system.os_group", "system.os_family", "system.os_name", "system.os_version", "system.manufacturer", "system.model", "system.serial", "system.form_factor", "system.status", "system.environment", "system.class", "system.function", "system.org_id", "system.location_id", "system.snmp_oid", "system.sysDescr", "system.sysObjectID", "system.sysUpTime", "system.sysContact", "system.sysName", "system.sysLocation", "system.first_seen", "system.last_seen", "system.last_seen_by", "system.identification", "orgs.name", "system.ip_padded", "orgs.id", "locations.id" ], "debug": false, "filter": [], "filtered": 19, "format": "json", "groupby": "", "header": "HTTP/1.1 200 OK", "heading": "Devices", "id": null, "ids": 0, "include": "", "limit": 1000, "offset": 0, "properties": "system.id,system.uuid,system.name,system.ip,system.hostname,system.dns_hostname,system.domain,system.dns_domain,system.dbus_identifier,system.fqdn,system.dns_fqdn,system.description,system.type,system.icon,system.os_group,system.os_family,system.os_name,system.os_version,system.manufacturer,system.model,system.serial,system.form_factor,system.status,system.environment,system.class,system.function,system.org_id,system.location_id,system.snmp_oid,system.sysDescr,system.sysObjectID,system.sysUpTime,system.sysContact,system.sysName,system.sysLocation,system.first_seen,system.last_seen,system.last_seen_by,system.identification", "query_parameters": [ { "name": "properties", "operator": "", "value": "default" } ], "query_string": "properties=default", "received_data": [], "request_method": "GET", "requestor": "commercial", "sort": "", "sub_resource": "", "sub_resource_id": 0, "timestamp": "2020-03-24 13:47:56", "timezone": "UTC +1000", "total": 19, "version": 1 } }
Create Discovery
Logon as above, then request list of devices (or any available endpoint) so we can use the meta → access_token in our request (see above response).
Request
Section | |||
---|---|---|---|
URL | POST | http://localhost/omk/open-audit/discoveries | |
Headers | Accept | application/json | |
Body | Type | form-data | |
Key | data | { "access_token": "23652075c7660006c281bf33589620dc093bdbedf8eb7ed1223449a95748", "type": "discoveries", "attributes": { "name": "My Testing Discovery", "type": "subnet", "network_address": "http://127.0.0.1/open-audit/", "org_id": 1, "other": { "subnet": "192.169.1.0/24" } } } |
Response
{ "data": [ { "attributes": { "description": "Subnet - 192.169.1.0/24", "devices_assigned_to_location": null, "devices_assigned_to_org": null, "discard": "n", "duration": "00:00:00", "edited_by": "Administrator", "edited_date": "2020-03-24 13:53:08", "id": 5, "ip_all_count": 0, "ip_audited_count": 0, "ip_discovered_count": 0, "ip_responding_count": 0, "ip_scanned_count": 0, "last_finished": "2000-01-01 00:00:00", "last_run": "2000-01-01 00:00:00", "name": "My Testing Discovery", "network_address": "http://127.0.0.1/open-audit/", "options": "", "org_id": 1, "orgs.id": 1, "other": { "nmap": { "discovery_scan_option_id": "1", "exclude_ip": "", "exclude_tcp_ports": "", "exclude_udp_ports": "", "filtered": "n", "nmap_tcp_ports": "0", "nmap_udp_ports": "0", "ping": "y", "service_version": "n", "ssh_ports": "22", "tcp_ports": "22,135,62078", "timeout": "0", "timing": "4", "udp_ports": "161" }, "subnet": "192.169.1.0/24" }, "status": "", "system.id": 0, "system_id": 0, "type": "subnet" }, "id": 5, "links": { "self": "/omk/open-audit/discoveries/5" }, "type": "discoveries" } ], "errors": [], "included": [], "links": { "first": null, "last": null, "next": null, "prev": null, "self": "http://localhost/omk/open-audit/discoveries" }, "meta": { "access_token": "94abae66d364697699d0a44e7cfba111c769882bf832014b2ea287623650", "action": "create", "baseurl": "http://localhost/omk/open-audit", "collection": "discoveries", "current": "y", "data_order": [ "discoveries.id", "discoveries.name", "discoveries.org_id", "discoveries.description", "discoveries.type", "discoveries.devices_assigned_to_org", "discoveries.devices_assigned_to_location", "discoveries.network_address", "discoveries.system_id", "discoveries.options", "discoveries.discard", "discoveries.last_run", "discoveries.last_finished", "discoveries.duration", "discoveries.status", "discoveries.ip_all_count", "discoveries.ip_responding_count", "discoveries.ip_scanned_count", "discoveries.ip_discovered_count", "discoveries.ip_audited_count", "discoveries.edited_by", "discoveries.edited_date", "orgs.id", "system.id", "other.subnet", "other.nmap" ], "debug": false, "filter": [], "filtered": "", "format": "json", "groupby": "", "header": "HTTP/1.1 201 Created", "heading": "Discoveries", "id": 5, "ids": 0, "include": "", "limit": 1000, "offset": 0, "properties": "*", "query_parameters": [], "query_string": "", "received_data": { "access_token": "23652075c7660006c281bf33589620dc093bdbedf8eb7ed1223449a95748", "attributes": { "description": "Subnet - 192.169.1.0/24", "name": "My Testing Discovery", "network_address": "http://127.0.0.1/open-audit/", "org_id": 1, "other": "{\"subnet\":\"192.169.1.0\\/24\",\"nmap\":{\"discovery_scan_option_id\":\"1\",\"ping\":\"y\",\"service_version\":\"n\",\"filtered\":\"n\",\"timeout\":\"0\",\"timing\":\"4\",\"nmap_tcp_ports\":\"0\",\"nmap_udp_ports\":\"0\",\"tcp_ports\":\"22,135,62078\",\"udp_ports\":\"161\",\"exclude_tcp_ports\":\"\",\"exclude_udp_ports\":\"\",\"exclude_ip\":\"\",\"ssh_ports\":\"22\"}}", "type": "subnet" }, "type": "discoveries" }, "request_method": "POST", "requestor": "", "sort": "", "sub_resource": "", "sub_resource_id": 0, "timestamp": "2020-03-24 13:53:08", "timezone": "UTC +1000", "total": 0, "version": 1 } }
Update Discovery
Logon as above, then.
Request
Section | |||
---|---|---|---|
URL | PATCH | http://localhost/omk/open-audit/discoveries/5 | |
Headers | Accept | application/json | |
Body | Type | x-www-form-urlencoded | |
Key | data | { |
Response
{ "data": [ { "attributes": { "description": "Subnet - 192.169.1.0/24", "devices_assigned_to_location": null, "devices_assigned_to_org": null, "discard": "n", "duration": "00:00:00", "edited_by": "Administrator", "edited_date": "2020-03-24 14:13:36", "id": 5, "ip_all_count": 0, "ip_audited_count": 0, "ip_discovered_count": 0, "ip_responding_count": 0, "ip_scanned_count": 0, "last_finished": "2000-01-01 00:00:00", "last_run": "2000-01-01 00:00:00", "name": "My New Name OMK", "network_address": "http://127.0.0.1/open-audit/", "options": "", "org_id": 1, "orgs.id": 1, "other": { "nmap": { "discovery_scan_option_id": "1", "exclude_ip": "", "exclude_tcp_ports": "", "exclude_udp_ports": "", "filtered": "n", "nmap_tcp_ports": "0", "nmap_udp_ports": "0", "ping": "y", "service_version": "n", "ssh_ports": "22", "tcp_ports": "22,135,62078", "timeout": "0", "timing": "4", "udp_ports": "161" }, "subnet": "192.169.1.0/24" }, "status": "", "system.id": 0, "system_id": 0, "type": "subnet" }, "id": 5, "links": { "self": "/omk/open-audit/discoveries/5" }, "type": "discoveries" } ], "errors": [], "included": [], "links": { "first": null, "last": null, "next": null, "prev": null, "self": "http://localhost/omk/open-audit/discoveries/5" }, "meta": { "access_token": "47049142d113e4e316ae4219afdf54d6a6d034ff779a42fd5198a720da2e", "action": "update", "baseurl": "http://localhost/omk/open-audit", "collection": "discoveries", "current": "y", "data_order": [ "discoveries.id", "discoveries.name", "discoveries.org_id", "discoveries.description", "discoveries.type", "discoveries.devices_assigned_to_org", "discoveries.devices_assigned_to_location", "discoveries.network_address", "discoveries.system_id", "discoveries.options", "discoveries.discard", "discoveries.last_run", "discoveries.last_finished", "discoveries.duration", "discoveries.status", "discoveries.ip_all_count", "discoveries.ip_responding_count", "discoveries.ip_scanned_count", "discoveries.ip_discovered_count", "discoveries.ip_audited_count", "discoveries.edited_by", "discoveries.edited_date", "orgs.id", "system.id", "other.subnet", "other.nmap" ], "debug": false, "filter": [], "filtered": "", "format": "json", "groupby": "", "header": "HTTP/1.1 200 OK", "heading": "Discoveries", "id": 5, "ids": 0, "include": "", "limit": 1000, "offset": 0, "properties": "*", "query_parameters": [], "query_string": "", "received_data": { "attributes": { "id": 5, "name": "My New Name OMK" }, "id": 5, "type": "discoveries" }, "request_method": "PATCH", "requestor": "", "sort": "", "sub_resource": "", "sub_resource_id": 0, "timestamp": "2020-03-24 14:13:36", "timezone": "UTC +1000", "total": 0, "version": 1 } }
Delete Discovery
Logon as above, then.
Request
Section | ||
---|---|---|
URL | DELETE | http://localhost/omk/open-audit/discoveries/5 |
Headers | Accept | application/json |
Response
{ "meta": { "access_token": "530d34dc6304ebd361d088d7831e4ce9d276ac8a4826837bdf36e8e84c87", "action": "delete", "baseurl": "http://localhost/open-audit/", "collection": "discoveries", "current": "y", "debug": false, "filtered": "", "format": "json", "groupby": "", "header": "HTTP/1.1 200 OK", "id": 5, "ids": 0, "include": "", "limit": 1000, "offset": 0, "properties": "*", "query_string": "", "request_method": "DELETE", "requestor": "", "sort": "", "sub_resource": "", "sub_resource_id": 0, "total": 0, "timestamp": "2020-03-24 14:22:38", "timezone": "UTC +1000", "version": 1, "filter": [], "query_parameters": [], "received_data": [], "heading": "Discoveries", "data_order": [] }, "links": { "self": "http://localhost/open-audit/index.php/discoveries/5", "first": null, "last": null, "next": null, "prev": null }, "included": [], "data": [ { "type": "discoveries" } ] }