Create Discovery
In order to run the discovery process, we need to create new Discovery.
Discovery behavior is defined by the Connector implementing the Discovery Provider.
How a Discovery is configured depends on whether the Connector was registered as v2 or v1, see Discovery Provider v1 and v2.
The Discovery imports what it finds as you, the user who creates it. You need the create permission on certificates to import certificates, and on keys to import keys; what you may not create is not imported, and the Discovery ends Warning.
Create Discovery using the API
Discovery Provider v2
First, we find out what the Connector can discover:
curl -X GET \
--cacert [ca-cert] \
--cert [client-cert] \
--cert-type [type] \
-H "Accept: application/json" \
https://[domain]:[port]/api/v1/discoveries/ef092b12-e181-4734-8e34-73152612a945/resources
#https://[domain]:[port]/api/v1/discoveries/{connectorUuid}/resources
The Network Discovery Provider discovers the certificates it finds on a host, and the public keys they carry:
[
{ "resource": "certificates" },
{ "resource": "keys" }
]
Next, we get the Attributes that configure the run:
curl -X GET \
--cacert [ca-cert] \
--cert [client-cert] \
--cert-type [type] \
-H "Accept: application/json" \
https://[domain]:[port]/api/v1/discoveries/ef092b12-e181-4734-8e34-73152612a945/attributes
#https://[domain]:[port]/api/v1/discoveries/{connectorUuid}/attributes
This returns the Attributes of the run, such as the hosts and ports to scan:
[
{
"uuid": "2cc7b1ee-7656-4844-a651-aed2300b750b",
"name": "data_hosts",
"type": "data",
"contentType": "string",
"description": "Addresses, hostnames, ranges or subnets to scan. One target per entry.",
"properties": { "label": "Hosts", "required": true, "list": true, "multiSelect": true, "extensibleList": true, ... },
...
},
{
"uuid": "acc48fc4-803e-45b1-951f-02764abcbbe8",
"name": "data_ports",
"type": "data",
"contentType": "string",
"description": "Ports to probe on each host, as a single port or a range. One per entry; leave empty to scan 443.",
...
},
...
]
A Connector can also have Attributes of its own for each resource, which GET /api/v1/discoveries/{connectorUuid}/{resource}/attributes returns, for example .../certificates/attributes. The Network Discovery Provider has none: everything it needs configures the run as a whole.
Knowing the resources and the attributes, we can create the Discovery:
curl -X POST \
--cacert [ca-cert] \
--cert [client-cert] \
--cert-type [type] \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
--data '
{
"name": "ILM Hostname Discovery",
"connectorUuid": "ef092b12-e181-4734-8e34-73152612a945",
"resources": ["certificates", "keys"],
"attributes": [
{
"version": "v3",
"uuid": "2cc7b1ee-7656-4844-a651-aed2300b750b",
"name": "data_hosts",
"contentType": "string",
"content": [ { "contentType": "string", "data": "www.example.com" } ]
},
{
"version": "v3",
"uuid": "acc48fc4-803e-45b1-951f-02764abcbbe8",
"name": "data_ports",
"contentType": "string",
"content": [ { "contentType": "string", "data": "443" } ]
}
]
}' \
https://[domain]:[port]/api/v1/discoveries
resourcesis required, and every resource must be one theConnectordiscovers.resourceAttributescarries theAttributesof each resource, keyed by resource, for example"resourceAttributes": { "certificates": [ ... ] }. It may only name resources inresources.interfaceUuidis needed only when theConnectorexposes more than onediscoveryinterface; with exactly one, it is selected automatically. The interfaces and theiruuidare listed in theConnector's details,GET /api/v2/connectors/{uuid}, underinterfaces, as the entries whosecodeisdiscovery.triggersoptionally lists the triggers to evaluate on the newly discovered certificates.
The platform starts the Discovery at the Connector before it answers. When the Connector refuses the configuration, the request fails with the Connector's answer and no Discovery is created. Otherwise, its uuid is sent back:
{
"uuid": "c0aaafda-a731-4175-8ec4-2cdcd06015fa"
}
If the Connector cannot be reached, the request fails and no Discovery is created. If the Connector fails once it has been asked to start the Discovery, for example with a server error or a timeout, the Discovery is created and ends Failed with the reason in its message.
Discovery Provider v1
For a Connector registered as v1, we need to know the Attributes of the Kind we use:
curl -X GET \
--cacert [ca-cert] \
--cert [client-cert] \
--cert-type [type] \
-H "Accept: application/json" \
https://[domain]:[port]/api/v1/connectors/ef092b12-e181-4734-8e34-73152612a945/discoveryProvider/IP-Hostname/attributes
#https://[domain]:[port]/api/v1/connectors/{uuid}/{functionGroup}/{kind}/attributes
To get details about the Connector, you can use the API call described in Register Connector.
This returns the list of applicable attributes for the Discovery process, such as:
[
{
"uuid": "1b6c48ad-c1c7-4c82-91ef-3b61bc9f52ac",
"name": "ip",
"type": "data",
"contentType": "string",
"properties": { "label": "IPs/Hostnames", "required": true, ... },
...
},
{
"uuid": "a9091e0d-f9b9-4514-b275-1dd52aa870ec",
"name": "port",
"type": "data",
"contentType": "string",
"content": [ { "data": "443", "reference": "443" } ],
"properties": { "label": "Ports", "required": false, ... },
...
},
...
]
Knowing the attributes, we can create the Discovery with its kind. A v1 Discovery takes no resources or resourceAttributes:
curl -X POST \
--cacert [ca-cert] \
--cert [client-cert] \
--cert-type [type] \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
--data '
{
"name": "ILM Hostname Discovery",
"connectorUuid": "ef092b12-e181-4734-8e34-73152612a945",
"kind": "IP-Hostname",
"attributes": [
{
"version": "v2",
"uuid": "1b6c48ad-c1c7-4c82-91ef-3b61bc9f52ac",
"name": "ip",
"contentType": "string",
"content": [ { "data": "www.example.com" } ]
},
{
"version": "v2",
"uuid": "a9091e0d-f9b9-4514-b275-1dd52aa870ec",
"name": "port",
"contentType": "string",
"content": [ { "data": "443" } ]
}
]
}' \
https://[domain]:[port]/api/v1/discoveries
When the Discovery process is successfully created, its uuid is sent back:
{
"uuid": "c0aaafda-a731-4175-8ec4-2cdcd06015fa"
}
Create Discovery using the Web Interface
Follow these steps to create new Network Discovery:
-
Click Discoveries in the left menu to display the Discovery Store
-
Click Add (plus symbol )
-
In Create Discovery, fill in:
- Discovery Name:
ILM Hostname Discovery - Discovery Provider:
Network Discovery Provider - Interface: shown only when the provider exposes more than one discovery interface, as
Discovery (v2)and so on. Select the one to use - Resources:
CertificateandKey
- Discovery Name:
-
On the Connector Attributes tab, fill in the run attributes:
- Hosts:
www.example.com - Ports:
443
The Certificate and Key tabs hold the attributes of each resource. The
Network Discovery Providerhas none of its own, and the tabs say so. - Hosts:
-
Optionally, select Triggers to evaluate on the newly discovered certificates. The Triggers widget is shown when the discovery targets certificates.
-
Optionally, switch on Schedule to create a scheduled job instead of running the discovery once now, and fill in its Job Name and Cron Expression (UTC), and whether it runs One Time Only.
-
Click Create to start the
Discovery
The detail of the new Discovery opens, or the detail of the job when it was scheduled. You have successfully created the Discovery to discover certificates and keys from the website www.example.com.
For a Connector registered as v1, the form has no Interface and Resources. Select its Kind instead, for example IP-Hostname, and fill in the attributes of the Connector Attributes tab that appear for it.