Introduction
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.
How Does it Work?
A discovery can be created using the web interface if a user has a role that contains the discoveries::create permission. Go to menu: Discover -> Discoveries -> Create Discoveries. There is also a "+" button on the collection page.Creating a Discovery
View Discovery Details
Go to menu: Discover -> Discoveries -> List Discoveries.
You will see a list of attributes. You can view an attribute by clicking on the blue view button. You can also edit or delete Discovery.
Let's execute a discovery. After creating the discovery entry you should be on that discovery entries details page. In the panel header on the upper right of the page is a group of buttons. The button that looks like an old fashioned "play" icon (a triangle) will execute this discovery. Click it and we're off to the races. If you're on the Discoveries list page, on the left side is a green triangle, the same icon as on the details page. Click that and the discovery will be executed. You should shortly see the beginning logs from the executing discovery. And that's all there is to a executing a discovery. You can also schedule the discovery to be executed by navigating to menu → Admin → Tasks → Create Tasks.Executing a Discovery
Database Schema (4.0.3)
The schema for the database is below. It can also be found in the application is the user has database::read permission by going to menu: Admin -> Database -> List Tables, then clicking on the "discoveries" table.
CREATE TABLE `discoveries` (
`id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`name` varchar(200) NOT NULL DEFAULT '',
`org_id` int(10) unsigned NOT NULL DEFAULT '1',
`description` text NOT NULL,
`type` varchar(100) NOT NULL DEFAULT '',
`subnet` varchar(45) NOT NULL DEFAULT '',
`seed_ip` varchar(45) NOT NULL DEFAULT '',
`seed_restrict_to_subnet` enum('y','n') NOT NULL DEFAULT 'y',
`seed_restrict_to_private` enum('y','n') NOT NULL DEFAULT 'y',
`ad_domain` varchar(200) NOT NULL DEFAULT '',
`ad_server` varchar(45) NOT NULL DEFAULT '',
`devices_assigned_to_org` int(10) unsigned DEFAULT NULL,
`devices_assigned_to_location` int(10) unsigned DEFAULT NULL,
`network_address` varchar(100) NOT NULL DEFAULT '',
`system_id` int(10) unsigned NOT NULL DEFAULT '0',
`other` text NOT NULL,
`scan_options` text NOT NULL,
`match_options` text NOT NULL,
`command_options` text NOT NULL,
`discard` enum('y','n') NOT NULL DEFAULT 'n',
`last_run` datetime NOT NULL DEFAULT '2000-01-01 00:00:00',
`last_finished` datetime NOT NULL DEFAULT '2000-01-01 00:00:00',
`duration` time NOT NULL DEFAULT '00:00:00',
`status` varchar(20) NOT NULL DEFAULT '',
`ip_all_count` int(10) unsigned NOT NULL DEFAULT '0',
`ip_responding_count` int(10) unsigned NOT NULL DEFAULT '0',
`ip_scanned_count` int(10) unsigned NOT NULL DEFAULT '0',
`ip_discovered_count` int(10) unsigned NOT NULL DEFAULT '0',
`ip_audited_count` int(10) unsigned NOT NULL DEFAULT '0',
`edited_by` varchar(200) NOT NULL DEFAULT '',
`edited_date` datetime NOT NULL DEFAULT '2000-01-01 00:00:00',
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
Database Schema (3.3.0 - 4.0.3)
The schema for the database is below. It can also be found in the application is the user has database::read permission by going to menu: Admin -> Database -> List Tables, then clicking on the "discoveries" table.
CREATE TABLE `discoveries` (
`id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`name` varchar(200) NOT NULL DEFAULT '',
`org_id` int(10) unsigned NOT NULL DEFAULT '1',
`description` text NOT NULL,
`type` varchar(100) NOT NULL DEFAULT '',
`devices_assigned_to_org` int(10) unsigned DEFAULT NULL,
`devices_assigned_to_location` int(10) unsigned DEFAULT NULL,
`network_address` varchar(100) NOT NULL DEFAULT '',
`system_id` int(10) unsigned NOT NULL DEFAULT '0',
`other` text NOT NULL,
`options` text NOT NULL,
`discard` enum('y','n') NOT NULL DEFAULT 'n',
`last_run` datetime NOT NULL DEFAULT '2000-01-01 00:00:00',
`last_finished` datetime NOT NULL DEFAULT '2000-01-01 00:00:00',
`duration` time NOT NULL DEFAULT '00:00:00',
`status` varchar(20) NOT NULL DEFAULT '',
`ip_all_count` int(10) unsigned NOT NULL DEFAULT '0',
`ip_responding_count` int(10) unsigned NOT NULL DEFAULT '0',
`ip_scanned_count` int(10) unsigned NOT NULL DEFAULT '0',
`ip_discovered_count` int(10) unsigned NOT NULL DEFAULT '0',
`ip_audited_count` int(10) unsigned NOT NULL DEFAULT '0',
`edited_by` varchar(200) NOT NULL DEFAULT '',
`edited_date` datetime NOT NULL DEFAULT '2000-01-01 00:00:00',
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
Database Schema (2.3.0 - 3.3.0)
The schema for the database is below. It can also be found in the application is the user has database::read permission by going to menu: Admin -> Database -> List Tables, then clicking on the "discoveries" table.
CREATE TABLE `discoveries` (
`id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`name` varchar(200) NOT NULL DEFAULT '',
`org_id` int(10) unsigned NOT NULL DEFAULT '1',
`description` text NOT NULL,
`type` varchar(100) NOT NULL DEFAULT '',
`devices_assigned_to_org` int(10) unsigned DEFAULT NULL,
`devices_assigned_to_location` int(10) unsigned DEFAULT NULL,
`network_address` varchar(100) NOT NULL DEFAULT '',
`system_id` int(10) unsigned NOT NULL DEFAULT '0',
`other` text NOT NULL,
`options` text NOT NULL,
`device_count` int(10) unsigned NOT NULL DEFAULT '0',
`limit` int(10) unsigned NOT NULL DEFAULT '0',
`discard` enum('y','n') NOT NULL DEFAULT 'n',
`edited_by` varchar(200) NOT NULL DEFAULT '',
`edited_date` datetime NOT NULL DEFAULT '2000-01-01 00:00:00',
`last_run` datetime NOT NULL DEFAULT '2000-01-01 00:00:00',
`complete` enum('y','n') NOT NULL DEFAULT 'y',
`status` varchar(20) NOT NULL DEFAULT '',
`discovered` varchar(20) NOT NULL DEFAULT '',
`last_log` datetime NOT NULL DEFAULT '2000-01-01 00:00:00',
`duration` time NOT NULL DEFAULT '00:00:00',
`pid` int(10) unsigned NOT NULL DEFAULT '0',
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
Database Schema (pre 2.3.0)
The schema for the database is below. It can also be found in the application is the user has database::read permission by going to menu: Admin -> Database -> List Tables, then clicking on the "discoveries" table.
CREATE TABLE `discoveries` (
`id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`name` varchar(100) NOT NULL DEFAULT '',
`org_id` int(10) unsigned NOT NULL DEFAULT '1',
`description` varchar(100) NOT NULL DEFAULT '',
`type` varchar(100) NOT NULL DEFAULT '',
`devices_assigned_to_org` int(10) unsigned DEFAULT NULL,
`devices_assigned_to_location` int(10) unsigned DEFAULT NULL,
`network_address` varchar(100) NOT NULL DEFAULT '',
`system_id` int(10) unsigned NOT NULL DEFAULT '0',
`other` text NOT NULL,
`device_count` int(10) unsigned NOT NULL DEFAULT '0',
`discard` enum('y','n') NOT NULL DEFAULT 'n',
`created_by` varchar(200) NOT NULL DEFAULT '',
`created_on` datetime NOT NULL DEFAULT '2000-01-01 00:00:00',
`last_run` datetime NOT NULL DEFAULT '2000-01-01 00:00:00',
`complete` enum('y','n') NOT NULL DEFAULT 'n',
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
Example Database Entry
Discoveries are stored in the database in the "discoveries" table. A typical entry will look as below (for 4.0.3 onward).
id: 1
name: My Network
org_id: 1
description: Subnet - 192.168.1.0/24
type: subnet
subnet: 192.168.1.0/24
seed_ip:
seed_restrict_to_subnet: y
seed_restrict_to_private: y
ad_domain:
ad_server:
devices_assigned_to_org: NULL
devices_assigned_to_location: NULL
network_address:
system_id: 0
other:
scan_options: {"exclude_ip":"","exclude_tcp_ports":"","exclude_udp_ports":"","filtered":"","id":"1","nmap_tcp_ports":"","nma...
match_options: {"match_dbus":"","match_dns_fqdn":"","match_dns_hostname":"","match_fqdn":"","match_hostname":"","match_hostna...
command_options:
discard: n
last_run: 2000-01-01 00:00:00
last_finished: 2000-01-01 00:00:00
duration: 00:00:00
status:
ip_all_count: 0
ip_responding_count: 0
ip_scanned_count: 0
ip_discovered_count: 0
ip_audited_count: 0
edited_by: Administrator
edited_date: 2021-02-19 10:46:00
API / Web Access
You can access the /discoveries collection using the normal Open-AudIT JSON based API. Just like any other collection. Please see the API documentation for further details.
API Routes
Request Method | ID | Action | Resulting Function | Permission Required | URL Example | Notes | Example Response |
|---|---|---|---|---|---|---|---|
| POST | n | create | discoveries::create | /discoveries | Insert a new discoveries entry. | discoveries_create.json | |
| GET | y | read | discoveries::read | /discoveries/{id} | Returns a discovery's details. | discoveries_create.json | |
| PATCH | y | update | discoveries::update | /discoveries/{id} | Update an attribute of a discoveries entry. | discoveries_update.json | |
| DELETE | y | delete | discoveries::delete | /discoveries/{id} | Delete a discoveries entry. | discoveries_delete.json | |
| GET | n | collection | discoveries::read | /discoveries | Returns a list of discoveries. | discoveries_collection.json | |
| GET | y | execute | discoveries::read | /discoveries/{id}/execute | Execute (run) a discovery. | discoveries_execute.json |
Web Application Routes
Request Method | ID | Action | Resulting Function | Permission Required | URL Example | Notes |
|---|---|---|---|---|---|---|
| GET | n | create | create_form | discoveries::create | /discoveries/create | Displays a standard web form for submission to POST /discoveries. |
| GET | n | import | import_form | discoveries::create | /discoveries/import | Displays a standard web form for submission to POST /discoveries/import. |
| POST | n | import | import | discoveries::create | /discoveries/import | Import multiple discoveries using a CSV. |