Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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


URLPOSThttp://localhost/omk/open-audit/login
HeadersAcceptapplication/json
BodyTypeform-data

Keyusernameadmin

Keypasswordpassword

...

Section


URLPOSThttp://localhost/omk/open-audit/discoveries
HeadersAcceptapplication/json
BodyTypeform-data

Keydata{
    {
        "access_token": "
23652075c7660006c281bf33589620dc093bdbedf8eb7ed1223449a95748
bcb3f959c14f0daf959e3de92e4213201a56bc205e31b63f35c3f9299670",

      "type": "discoveries",

        "attributes":
     
{ "name
  {
            "description": "
My
Subnet 
Testing Discovery", "type": "subnet", "network_address": "http://127.0.0.1/open-audit/", "org_id": 1, "other": { "subnet": "192.169.1.0/24" } } }

Response

- 192.168.1.0/24",
            "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",
            "org_id": 1,
            "scan_options": "{\"exclude_ip\":\"\",\"exclude_tcp_ports\":\"\",\"exclude_udp_ports\":\"\",\"filtered\":\"\",\"id\":\"1\",\"nmap_tcp_ports\":\"\",\"nmap_udp_ports\":\"\",\"open|filtered\":\"\",\"ping\":\"\",\"service_version\":\"\",\"ssh_ports\":\"\",\"tcp_ports\":\"\",\"timeout\":\"\",\"timing\":\"\",\"udp_ports\":\"\",\"script_timeout\":\"\",\"snmp_timeout\":\"\",\"ssh_timeout\":\"\",\"wmi_timeout\":\"\"}",
          "subnet": "192.168.1.0/24",
            "type": "subnet"
      }
    }

Response

Note, generated from a discoveries read. The actual output should be almost identical.

Code Block
{
    "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"
        }
    ],
    "dictionary":
    {
        "about": "<p>Discoveries are at the very heart of what Open-AudIT does.<br /><br />How else would you know \"What is on my network?\"<br /><br />Discoveries are preprepared data items that enable you to run a discovery upon a network in a single click, without entering the details of that network each and every time.<br /><br />For more detailed information, check the Open-AudIT <a href=\"https://community.opmantek.com/display/OA/discoveries\">Knowledge Base</a>.<br /><br /></p>",
        "attributes":
        {
            "create":
            [
                "name",
                "org_id",
                "type"
            ],
            "fields":
            [
                "id",
                "name",
                "org_id",
                "description",
                "type",
                "subnet",
                "seed_ip",
                "seed_restrict_to_subnet",
                "seed_restrict_to_private",
                "seed_ping",
                "ad_domain",
                "ad_server",
                "devices_assigned_to_org",
                "devices_assigned_to_location",
                "network_address",
                "system_id",
                "scan_options",
                "match_options",
                "command_options",
                "discard",
                "last_run",
                "last_finished",
                "duration",
                "status",
                "ip_all_count",
                "ip_responding_count",
                "ip_scanned_count",
                "ip_discovered_count",
                "ip_audited_count",
                "cloud_id",
                "cloud_name",
                "edited_by",
                "edited_date"
            ],
            "update":
            [
                "name",
                "org_id",
                "description",
                "type",
                "subnet",
                "seed_ip",
                "seed_restrict_to_subnet",
                "seed_restrict_to_private",
                "seed_ping",
                "ad_domain",
                "ad_server",
                "devices_assigned_to_org",
                "devices_assigned_to_location",
                "network_address",
                "system_id",
                "scan_options",
                "match_options",
                "command_options",
                "discard",
                "last_run",
                "last_finished",
                "duration",
                "status",
                "ip_all_count",
                "ip_responding_count",
                "ip_scanned_count",
                "ip_discovered_count",
                "ip_audited_count",
                "cloud_id",
                "cloud_name"
            ]
        },
        "columns":
        {
            "ad_domain": "The Active Directory domain to retrieve a list of subnets from.",
            "ad_server": "The Active Directory server to retrieve a list of subnets from.",
            "complete": "A internal field that indicates if the discovery has completed.",
            "description": "Your description of this item.",
            "device_count": "The number of devices found by this discovery.",
            "devices_assigned_to_location": "Any discovered devices will be assigned to this Location if set. Links to <code>locations.id</code>.",
            "devices_assigned_to_org": "Any discovered devices will be assigned to this Org if set. If not set, they are assigned to the 'org_id' of this discovery. Links to <code>orgs.id</code>.",
            "discard": "Used internally when discovering a single device.",
            "edited_by": "The name of the user who last changed or added this item (read only).",
            "edited_date": "The date this item was changed or added (read only). NOTE - This is the timestamp from the server.",
            "id": "The internal identifier column in the database (read only).",
            "last_run": "A calculated field that is updated each time the discovery has been executed.",
            "limit": "The number of devices to limit this discovery to.",
            "match_dbus": "Should we match a device based on its dbus id.",
            "match_dns_fqdn": "Should we match a device based on its DNS fqdn.",
            "match_dns_hostname": "Should we match a device based on its DNS hostname.",
            "match_fqdn": "Should we match a device based on its fqdn.",
            "match_hostname": "Should we match a device based only on its hostname.",
            "match_hostname_dbus": "Should we match a device based on its hostname and dbus id.",
            "match_hostname_serial": "Should we match a device based on its hostname and serial.",
            "match_hostname_uuid": "Should we match a device based on its hostname and UUID.",
            "match_ip": "Should we match a device based on its ip.",
            "match_ip_no_data": "Should we match a device based on its ip if we have an existing device with no data.",
            "match_mac": "Should we match a device based on its mac address.",
            "match_mac_vmware": "Should we match a device based mac address even if its a known likely duplicate from VMware.",
            "match_options": "A JSON document containing the required attributes overriding the default device match options.",
            "match_serial": "Should we match a device based on its serial number.",
            "match_serial_type": "Should we match a device based on its serial and type.",
            "match_sysname": "Should we match a device based only on its SNMP sysName.",
            "match_sysname_serial": "Should we match a device based only on its SNMP sysName and serial.",
            "match_uuid": "Should we match a device based on its UUID.",
            "name": "The name given to this item. Ideally it should be unique.",
            "network_address": "The URL the audit_* scripts should submit their result to.",
            "org_id": "The Organisation that owns this item. Links to <code>orgs.id</code>.",
            "scan_options": "A JSON document containing the required attributes overriding the chosen discovery_scan_options.",
            "scan_options.exclude_ip": "Exclude these IP addresses from being Nmap scanned.",
            "scan_options.exclude_tcp_ports": "Do not scan these TCP ports.",
            "scan_options.exclude_udp_ports": "Do not scan these UDP ports.",
            "scan_options.filtered": "If a port responds with filtered, should we consider it available.",
            "scan_options.id": "The set of options for Nmap for this discovery. Links to discovery_scan_options.id.",
            "scan_options.nmap_tcp_ports": "Scan the Nmap top number of TCP ports.",
            "scan_options.nmap_udp_ports": "Scan the Nmap top number of UDP ports.",
            "scan_options.open|filtered": "If a port responds with open|filtered, should we consider it available.",
            "scan_options.ping": "The device must respond to an Nmap ping before it is considered online.",
            "scan_options.service_version": "Should we use Nmaps Service Version detection. This will considerably slow the discovery scan.",
            "scan_options.ssh_ports": "Check this port for any SSH service.",
            "scan_options.tcp_ports": "A list of custom TCP ports to scan.",
            "scan_options.timeout": "How long should Nmap wait for a response, per target device.",
            "scan_options.timing": "The Nmap timing preset.",
            "scan_options.udp_ports": "A list of custom UDP ports to scan.",
            "seed_ip": "The IP of the device to start a seed discovery with.",
            "seed_ping": "For a seed discovery, should I ping the subnet before running the discovery.",
            "seed_restrict_to_private": "For a seed discovery, should I only discover IPs in the private IP address space.",
            "seed_restrict_to_subnet": "For a seed discovery, should I only discover IPs on the chosen subnet.",
            "subnet": "The network subnet to execute the discovery on.",
            "system_id": "Used internally when discovering a single device. Links to <code>system.id</code>.",
            "type": "Currently supported types are 'subnet' and 'active directory'."
        },
        "marketing": "<p>Discoveries are at the very heart of what Open-AudIT does. How else would you know \"What is on my network?\"<br /><br />Easily run a discovery upon a network in a single click, without entering the details of that network each and every time.<br /><br />Use Open-AudIT Professional and Enterprise to schedule your Discoveries to run automatically whenever you like.<br /><br />For more detailed information, check the Open-AudIT <a href=\"https://community.opmantek.com/display/OA/discoveries\">Knowledge Base</a>.<br /><br /></p>",
        "notes": "<p>Some examples of valid Subnet attributes are: 192.168.1.1 (a single IP address), 192.168.1.0/24 (a subnet), 192.168.1-3.1-20 (a range of IP addresses).<br /><br /><b>NOTE</b> - Only a subnet (as per the examples - 192.168.1.0/24) will be able to automatically create a valid network for Open-AudIT. <br /><br />If you use an Active Directory type, make sure you have appropriate credentials to talk to your Domain Controller already in <a href=\"../credentials\">credentials</a>.</p>",
        "product": "community",
        "sentence": "Open-AudIT Enterprise discovers every device on your network.",
        "table": "discoveries"
    },
    "included":
   
Code Block
{
    "data": [
        {
            "attributes":
            {
                "descriptioncommand_options": "Subnet - 192.169.1.0/24",
                "devices_assigned_to_locationdescription": null,
"Approximately 1 second per target. Scan only the ports that Open-AudIT needs to use to talk "devices_assigned_to_org": null,
                "discard": "n",
                "duration": "00:00:00" the device and detect an IOS device (WMI, SSH, SNMP, Apple Sync). An open|filtered port is considered closed. Device must respond to an Nmap ping. Use aggressive timing.",
                "edited_by": "Administratorsystem",
                "edited_date": "20202000-0301-2401 1300:5300:0800",
                "idexclude_ip": 5"",
                "ipexclude_alltcp_countports": 0"",
                "ipexclude_auditedudp_countports": 0"",
                "ip_discovered_countfiltered": 0,
                "ip_responding_count": 0"n",
                "ip_scanned_countid": 01,
                "last_finished": "2000-01-01 00:00:00 "name": "UltraFast",
                "lastnmap_tcp_runports": "2000-01-01 00:00:000",
                "namenmap_udp_ports": "My Testing Discovery0",
                "network_addressopen|filtered": "http://127.0.0.1/open-audit/n",
                "options": "",
                "org_id": 1,
                "orgs.id": 1,
                "otherping": {
    "y",
                "nmapports_in_order": {"n",
                        "discovery_scan_option_id"ports_stop_after": "10",
                        "excludescript_iptimeout": "0",
        
                "excludeservice_tcp_portsversion": "n",
                        "excludesnmp_udp_portstimeout": "0",
                        "filteredssh_ports": "n22",
                        "nmapssh_tcp_portstimeout": "0",
                        "nmap_udp"tcp_ports": "022,135,62078",
                        "pingtimeout": "y0",
                        "service_version"timing": "n4",
                        "sshudp_ports": "22161",
                "wmi_timeout": "0"
            "tcp_ports": "22,135,62078"},
            "id": 1,
            "timeoutlinks": "0",

            {
                "timingself": "4",http://dev.local/omk/open-audit/discovery_scan_options/1"
            },
            "udp_portstype": "161discovery_scan_options"
                    },
        {
            "subnetattributes": "192.169.1.0/24"
                },{
                "statusad_group": "open-audit_orgs_default_organisation",
                "system.iddescription": 0"",
                "systemdevice_idcount": 0,
                "typeedited_by": "subnetsystem",
            },
    "edited_date": "2000-01-01 00:00:00",
      "id": 5,
            "linksid": {1,
                "selfname": "/omk/open-audit/discoveries/5"
   Default Organisation",
         },
            "type"parent_id": "discoveries"1,
        }
    ],
    "errorstype": [],
"organisation"
        "included": [],
    "links": {
},
            "firstid": null1,
            "lastlinks":
 null,
          "next": null, {
        "prev": null,
        "self": "http://localhostdev.local/omk/open-audit/orgs/discoveries1"
            },
      "meta      "type": {
 "orgs"
        }
    ],
    "access_tokenissues":
  "94abae66d364697699d0a44e7cfba111c769882bf832014b2ea287623650",  [],
    "links":
    {
        "action": "createfirst": "http://dev.local/omk/open-audit/discoveries/3",
        "baseurllast": "http://localhostdev.local/omk/open-audit/discoveries/3",
        "collectionnext": "http://dev.local/omk/open-audit/discoveries/3",
        "currentprev": "yhttp://dev.local/omk/open-audit/discoveries/3",
        "data_orderself": [
            "discoveries.id","http://dev.local/omk/open-audit/discoveries/3"
            "discoveries.name",
        },
    "discoveries.org_id",
meta":
    {
        "access_token": "discoveries.descriptionef4421add7e6f2741a2830a1b0262d3b678cc33efdacdd9442d5a871f474",
           "action": "discoveries.typeread",
            "discoveries.devices_assigned_to_org"as_at": "",
            "discoveries.devices_assigned_to_location"baseurl": "http://dev.local/omk/open-audit",
           "collection": "discoveries.network_address",
            "discoveries.system_id"current": "y",
            "discoveries.options","data_order":
            "discoveries.discard",[
            "discoveries.last_runid",
            "discoveries.last_finishedname",
            "discoveries.durationorg_id",
            "discoveries.statusdescription",
            "discoveries.ip_all_counttype",
            "discoveries.ip_responding_countsubnet",
            "discoveries.seed_ip_scanned_count",
            "discoveries.ipseed_restrict_discoveredto_countsubnet",
            "discoveries.ipseed_restrict_auditedto_countprivate",
            "discoveries.editedseed_byping",
            "discoveries.editedad_datedomain",
            "orgsdiscoveries.idad_server",
            "system.iddiscoveries.devices_assigned_to_org",
            "other.subnetdiscoveries.devices_assigned_to_location",
            "otherdiscoveries.nmapnetwork_address",
        ],
        "debug": false,
        "filter": [],
"discoveries.system_id",
           "filtered": "discoveries.scan_options",
           "format": "jsondiscoveries.match_options",
           "groupby": "discoveries.command_options",
        "header":    "HTTP/1.1 201 Createddiscoveries.discard",
           "heading": "Discoveriesdiscoveries.last_run",
         "id": 5,
   "discoveries.last_finished",
            "ids": 0discoveries.duration",
        "include":    "discoveries.status",
        "limit": 1000,
        "offset": 0,
discoveries.ip_all_count",
           "properties": "*discoveries.ip_responding_count",
            "query_parameters": [],
discoveries.ip_scanned_count",
            "query_string": "discoveries.ip_discovered_count",
            "received_data": {discoveries.ip_audited_count",
            "access_token": "23652075c7660006c281bf33589620dc093bdbedf8eb7ed1223449a95748"discoveries.cloud_id",
            "attributes": {
    discoveries.cloud_name",
            "description": "Subnet - 192.169.1.0/24discoveries.edited_by",
            "discoveries.edited_date",
    "name": "My Testing Discovery",
     "orgs.id",
           "network_address": "http://127.0.0.1/open-audit/",system.id"
        ],
        "org_iddebug": 1false,
                "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\"}}",
"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": [],
        "typequery_string": "subnet",
            }"received_data": [],
            "type"request_method": "discoveries"
        }GET",
        "request_methodrequestor": "POSTcommercial",
        "requestorserver_app_version": "4.3.0",
        "sortserver_platform": "Debian GNU/Linux 9 (stretch)",
        "sub_resourcesort": "",
        "sub_resource_id": 0"",
        "timestamp": "20202021-0311-2429 13:5324:0845",
        "timezone": "UTC +1000",
        "total": 01,
        "version": 1
    }
}


Update Discovery

...

Section


URLPATCHhttp://localhost/omk/open-audit/discoveries/5
HeadersAcceptapplication/json
BodyTypex-www-form-urlencoded

Keydata
{
   "id": 5,
   "type": "discoveries",
   "attributes": {
      "name": "My New Name OMK"
   }
}

Response

Note - generated from pre 3.5.4. Attribute outputs will be as above for 3.5.4 onward.

Code Block
{
    "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
    }
}

...