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.
Updated for Open-AudIT 3.5.4 onward on 2021-11-29.
Logon
Request
| Section | |||
|---|---|---|---|
| URL | POST | http://localhost/open-audit/index.php/logon | |
| Headers | Accept | application/json | |
| Body | Type | form-data | |
| Key | username | admin | |
| Key | password | password |
Response
{
"access_token": "[]",
"active": "y",
"dashboard_id": "1",
"devices_default_display_columns": "",
"edited_by": "Administrator",
"edited_date": "2024-10-02 11:40:15",
"email": "admin@openaudit",
"full_name": "Administrator",
"id": 1,
"lang": "en",
"ldap": "",
"list_table_format": "",
"name": "admin",
"org_id": 1,
"orgs": "[1]",
"password": "",
"roles":
[
"admin",
"org_admin"
],
"toolbar_style": "icontext",
"type": "user"
}
Read Devices
Logon as above, then.
Request
| Section | ||
|---|---|---|
| URL | GET | http://localhost/open-audit/index.php/devices |
| Headers | Accept | application/json |
Response
Note - restricted to one item in the data array, normally you will retrieve all items.
{
"meta": {
"action": "collection",
"collection": "devices",
"request_method": "GET",
"remote_addr": "::1",
"format": "json",
"id": null,
"access_token": "60485c922d98010d0b6e9a746b15bd50144eccc18ef8896ad28e1e11fc3f",
"baseurl": "http://localhost:8080/",
"debug": false,
"filtered": 1,
"groupby": "",
"header": 200,
"include": "",
"license_string": "",
"limit": 1,
"microtime": 1728348706.632546,
"offset": 0,
"properties": [
"devices.id",
"devices.icon",
"devices.type",
"devices.name",
"devices.ip",
"devices.uuid",
"devices.hostname",
"devices.dns_hostname",
"devices.domain",
"devices.dns_domain",
"devices.dbus_identifier",
"devices.fqdn",
"devices.dns_fqdn",
"devices.description",
"devices.os_group",
"devices.os_family",
"devices.os_name",
"devices.os_version",
"devices.manufacturer",
"devices.model",
"devices.serial",
"devices.form_factor",
"devices.status",
"devices.environment",
"devices.class",
"devices.function",
"devices.org_id",
"devices.location_id",
"devices.snmp_oid",
"devices.sysDescr",
"devices.sysObjectID",
"devices.sysUpTime",
"devices.sysContact",
"devices.sysName",
"devices.sysLocation",
"devices.first_seen",
"devices.last_seen",
"devices.last_seen_by",
"devices.identification",
"devices.tags"
],
"query_string": "limit=1",
"requestor": "",
"server_app_version": "5.6.0",
"server_platform": "MacOS 15.0.1 Sequoia",
"sort": "",
"time_start": 1728348706.64449,
"time_end": 1728348706.714915,
"time_elapsed": "0.08",
"total": 111,
"timestamp": "2024-10-08 10:51:46",
"timezone": "UTC +10:00",
"version": 1,
"filter": [
{
"name": "devices.org_id",
"function": "whereIn",
"operator": "in",
"value": [
"1"
]
}
],
"received_data": [],
"sql": [],
"heading": "Devices",
"icon": "fa fa-desktop",
"data_order": [
"id",
"icon",
"type",
"name",
"ip",
"uuid",
"hostname",
"dns_hostname",
"domain",
"dns_domain",
"dbus_identifier",
"fqdn",
"dns_fqdn",
"description",
"os_group",
"os_family",
"os_name",
"os_version",
"manufacturer",
"model",
"serial",
"form_factor",
"status",
"environment",
"class",
"function",
"org_id",
"location_id",
"snmp_oid",
"sysDescr",
"sysObjectID",
"sysUpTime",
"sysContact",
"sysName",
"sysLocation",
"first_seen",
"last_seen",
"last_seen_by",
"identification",
"tags"
]
},
"links": {},
"included": {
"antivirus": 8,
"audit_log": 140,
"bios": 70,
"change_log": 12642,
"disk": 342,
"dns": 0,
"edit_log": 3006,
"file": 35,
"firewall": 3,
"firewall_rule": 1073,
"executable": 101,
"ip": 301,
"log": 742,
"memory": 128,
"module": 619,
"monitor": 27,
"motherboard": 62,
"netstat": 2524,
"network": 618,
"nmap": 65,
"optical": 23,
"pagefile": 26,
"partition": 422,
"policy": 1033,
"print_queue": 10,
"processor": 77,
"route": 947,
"server": 65,
"server_item": 134,
"service": 12164,
"share": 47,
"software": 43305,
"software_key": 35,
"sound": 58,
"task": 4339,
"user": 1689,
"user_group": 2375,
"variable": 2142,
"video": 75,
"vm": 89,
"windows": 39
},
"logs": [],
"data": [
{
"id": 5,
"type": "devices",
"attributes": {
"id": 5,
"icon": "redhat",
"type": "computer",
"name": "redhat9",
"ip": "192.168.1.53",
"uuid": "9d762f99-55cb-5f42-a4ea-3704c5be0333",
"hostname": "redhat9",
"dns_hostname": "redhat9",
"domain": "open-audit.lan",
"dns_domain": "open-audit.local",
"dbus_identifier": "db348c97aadf4b38847d236483fe9f79",
"fqdn": "redhat9.open-audit.lan",
"dns_fqdn": "redhat9.open-audit.local",
"description": "",
"os_group": "Linux",
"os_family": "RedHat",
"os_name": "Red Hat Enterprise Linux release 9.4 (Plow)",
"os_version": "9.4",
"manufacturer": "innotek GmbH",
"model": "VirtualBox",
"serial": "",
"form_factor": "Virtual",
"status": "production",
"environment": "production",
"class": "server",
"function": "",
"org_id": 1,
"location_id": 1,
"snmp_oid": "",
"sysDescr": "",
"sysObjectID": "",
"sysUpTime": "",
"sysContact": "",
"sysName": "",
"sysLocation": "",
"first_seen": "2024-08-27 14:43:31",
"last_seen": "2024-09-27 13:20:29",
"last_seen_by": "audit_ssh",
"identification": "Server from innotek GmbH",
"tags": [],
"orgs.name": "Default Organisation",
"orgs.id": 1,
"locations.name": "Default Location",
"locations.id": 1,
"mycount": "1",
"audit_class": "fa fa-check text-success",
"audit_text": "Discovered and audited computer.",
"ip_padded": "192.168.001.053"
}
}
]
}
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 | { |
Response
Note, generated from a discoveries read. The actual output should be almost identical.
{
"data":
[
{
"attributes":
{
"ad_domain": "",
"ad_server": "",
"cloud_id": 1,
"cloud_name": "",
"command_options": "",
"description": "Subnet - 192.168.1.0/24",
"devices_assigned_to_location": null,
"devices_assigned_to_org": null,
"discard": "n",
"duration": "00:00:00",
"edited_by": "Administrator",
"edited_date": "2021-11-29 13:16:53",
"id": 3,
"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",
"match_options":
{
"match_dbus": "",
"match_dns_fqdn": "",
"match_dns_hostname": "",
"match_fqdn": "",
"match_hostname": "",
"match_hostname_dbus": "",
"match_hostname_serial": "",
"match_hostname_uuid": "",
"match_ip": "",
"match_ip_no_data": "",
"match_mac": "",
"match_mac_vmware": "",
"match_serial": "",
"match_serial_type": "",
"match_sysname": "",
"match_sysname_serial": "",
"match_uuid": ""
},
"name": "My Testing Discovery",
"network_address": "",
"org_id": 1,
"orgs.id": 1,
"scan_options":
{
"exclude_ip": "",
"exclude_tcp_ports": "",
"exclude_udp_ports": "",
"filtered": "",
"id": "1",
"nmap_tcp_ports": "",
"nmap_udp_ports": "",
"open|filtered": "",
"ping": "",
"script_timeout": "",
"service_version": "",
"snmp_timeout": "",
"ssh_ports": "",
"ssh_timeout": "",
"tcp_ports": "",
"timeout": "",
"timing": "",
"udp_ports": "",
"wmi_timeout": ""
},
"seed_ip": "",
"seed_ping": "y",
"seed_restrict_to_private": "y",
"seed_restrict_to_subnet": "y",
"status": "",
"subnet": "192.168.1.0/24",
"system.id": 0,
"system_id": 0,
"type": "subnet"
},
"id": 3,
"links":
{
"self": "http://dev.local/omk/open-audit/discoveries/3"
},
"type": "discoveries"
}
],
"included": [],
"issues": [],
"meta":
{
"access_token": "ef4421add7e6f2741a2830a1b0262d3b678cc33efdacdd9442d5a871f474",
"action": "read",
"as_at": "",
"baseurl": "http://dev.local/omk/open-audit",
"collection": "discoveries",
"current": "y",
"data_order":
[
"discoveries.id",
"discoveries.name",
"discoveries.org_id",
"discoveries.description",
"discoveries.type",
"discoveries.subnet",
"discoveries.seed_ip",
"discoveries.seed_restrict_to_subnet",
"discoveries.seed_restrict_to_private",
"discoveries.seed_ping",
"discoveries.ad_domain",
"discoveries.ad_server",
"discoveries.devices_assigned_to_org",
"discoveries.devices_assigned_to_location",
"discoveries.network_address",
"discoveries.system_id",
"discoveries.scan_options",
"discoveries.match_options",
"discoveries.command_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.cloud_id",
"discoveries.cloud_name",
"discoveries.edited_by",
"discoveries.edited_date",
"orgs.id",
"system.id"
],
"debug": false,
"filter": [],
"filtered": 1,
"format": "json",
"groupby": "",
"header": "HTTP/1.1 200 OK",
"heading": "Discoveries",
"id": 3,
"include": "",
"limit": 1000,
"nmap_version": 7,
"offset": 0,
"properties": ".*",
"query_parameters": [],
"query_string": "",
"received_data": [],
"request_method": "GET",
"requestor": "commercial",
"server_app_version": "4.3.0",
"server_platform": "Debian GNU/Linux 9 (stretch)",
"sort": "",
"sub_resource": "",
"timestamp": "2021-11-29 13:24:45",
"timezone": "UTC +1000",
"total": 1,
"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
Note - generated from pre 3.5.4. Attribute outputs will be as above for 3.5.4 onward.
{
"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"
}
]
}