SSL Network Operations

SSLClosed TLS (Transport Layer Security) and its predecessor SSL (Secure Sockets Layer) are protocols for establishing authenticated and encrypted links between networked computers. Network Operations include adding, editing and deleting SSL network definitions, initiating a manual scan and monitoring scheduled network scan jobs.

Tip:  SSL scan jobs use priority rules to determine which job segments run first if there are multiple job segments to be run (large jobs are divided into multiple job segments—see Monitoring Network Scan Jobs with View Scan Details). Job segments are run with the following priority rules:
  • Job segments for Scan Now jobs (see Initiating a Manual Scan) are run ahead of those for scheduled jobs.
  • New job segments for in-progress jobs with multiple segments are prioritized based on job age—segments for jobs that have been running the longest move to the front of the line.
  • New job segments for in progress jobs with multiple segments start ahead of job segments for jobs that have not yet started.

Figure 256: SSL Network Discovery

To define a new network or edit an existing one:

  1. In the Management Portal, browse to Locations > SSL Discovery.
  2. On the SSL Network Discovery page, select the Network Definitions tab (the default when you first visit the page).
  3. On the Network Definitions tab, click New Network to setup a network to scan, or select an existing network from the grid and click Edit.

  4. The SSL Network Definition dialog is divided into four tabs: Basic, Advanced, Network Ranges, and Quiet Hours. Enter the network information for each tab, as required. Each tab is described in detail below.

    In the SSL Network Definition dialog on the Basic tab, enter the following information:

    • Name: Enter a name for the network. The network name can be anything; however, it is recommended that the name reflect the subnet or location that you will be discovering with the network.
      Tip:  The SSL network name is searchable with certificate search and also appears in the location details grid of the certificate details, if the certificate was found during an SSL scan.
    • Description: Enter a description for the network.
    • Orchestrator Pool: From the dropdown, select an orchestratorClosed Keyfactor orchestrators perform a variety of functions, including managing certificate stores and SSH key stores. pool that contains orchestrators with SSL discovery and monitoring capabilities.
      Note:  Keyfactor Command is installed with a Default Orchestrator Pool and orchestrators with SSL discovery and monitoring capabilities created in Keyfactor Command are automatically assigned to that pool.
    • Discovery/Monitoring Schedule: Select the discovery and monitoring job frequency. Possible options are:
      • Off—No jobs will run.
      • Daily—Enter selected time.
      • Interval—Enter an interval from every 10 minutes to every 12 hours.
      • Weekly—Enter a selected day or days of the week at a selected time.
      • Monthly—Enter a selected day of the month (1st through 27th) at a selected time.
      Note:  The configured schedule determines when the scan is requested to start. The actual start of the scan is dependent on the orchestrator heartbeat Interval, which is defined by the Heartbeat Interval (minutes) application setting (see Application Settings). The default is 5 minutes.
    • Notification Recipients: Enter one or more email address(es) of the recipients who should receive monitoring results (newline separated).

    Figure 257: Define a New Network—Basic Tab

    In the SSL Network Definition dialog on the Advanced tab, enter the following information:

    • Scanning Enabled : Click to enable scanning for the network. If unchecked, no new network scans will be scheduled, but the current scan will finish, if this setting is changed during a scan also, the network will appear as Disabled on the SSL Network Discovery page.
    • Automatically monitor network endpoints during discovery: Enable this option to instruct the orchestrator to tag endpointClosed An endpoint is a URL that enables the API to gain access to resources on a server. certificates, found during discovery scanning, for monitoring. It is recommended to enable this option.
    • Request robots.txt: Each network definition contains an option to do a GET on robots.txt on endpoints. Orchestrators perform a GET /robots.txt request to behave like a webcrawler and provide an explanation of network activity.
    • Discover Timeout (in ms): Enter the amount of time (in milliseconds) the scan will wait (before timing out) to discover the endpoint. Shorter timeout periods will increase the overall scanning throughput, however will also increase the chance of missing a certificate on a slow or congested network
    • Monitor Timeout (in ms): Enter the amount of time (in milliseconds) the scan will wait (before timing out) to receive the discovered endpoint certificate expiration details.
    • Expiration Alert (in days): Enter the number of days within which to begin warning regarding upcoming expiration in notification email messages.

    Figure 258: Define a New Network—Advanced Tab

    There are two sections to the Network Ranges Tab: Add Range and Ranges. For each named network defined, multiple ranges are allowed. New networks can be added by using either the add range tool, or pasting the IP address, hostnameClosed The unique identifier that serves as name of a computer. It is sometimes presented as a fully qualified domain name (e.g. servername.keyexample.com) and sometimes just as a short name (e.g. servername)., or network notation into the Network Ranges box.

    The Add Range section is for adding new networks via the add range tool.

    When you arrive at the Network Ranges tab, the Add Range section shows default values of type: Network Notation and CIDR Block of '0.0.0.0/24:443 '. Notice that the details grid reflects the default value and the default type; network notation. As you begin entry of a new network range of the type network notation, the details section will reflect your entries as you type, allowing you to verify your entry. The details grid will not show if you chose another type of notation.

    Define new network locations, using the add range tool, as follows:

    1. In the Add Range section of the page, select your desired method for adding a location in the Type dropdown. The available options are:
    2. Enter the desired network notation, IP address, or host name, and click the Add action button.
    3. Repeat this step for multiple IP addresses or host names. Each entry will be added as a newline in the Network Ranges box at the bottom of the dialog.
    4. Click Save.

    Figure 259: Define a New Network—Network Ranges Tab

    The details grid displays only for the type network notation and will only display the value being typed in the CIDR block, or the last value entered. The fields in the details grid are defined as follows:

    • Range: This is the range of addresses reflected by the CIDR notation entered.

    • Mask: Defined by the bitmask (between 1 -30) applied to the address in the CIDR block to identify the IP addresses included. The bigger the mask the fewer IP addresses will fall under the defined range. For example, with a '/24', the first 3 sections of the IP address must match exactly, while the last section can be any value from 0 to 255.

    • Hosts: This is the number of useable IP addresses in a given CIDR. (This is always two less than the number of endpoints. This is because the smallest address is reserved as the address of the overall network the CIDR represents, while the largest is used as the 'broadcast' address).

    • Ports: This is the number of ports the given CIDR will have.

    • Endpoints: The endpoints number reflects the number of endpoints based on the network size (/24, /25, etc) times the number of ports defined. Each time you go up in network size the network number will double ('/24' has 256, '/23' has 512, '/22' has 1,024 etc). So if you have just one port defined, the number of endpoints will be 256 for a ‘/24’ network, but if you had 3 ports (like say 443-445) that number would jump to 768. The same scenario for a '/23' network would be 512 for one port and 1,536 for three ports.

    You can see any existing network definitions in the Network Ranges box in the Ranges section of the dialog.  The Ranges section:

    • Displays existing defined network ranges.

    • Allows you to edit or delete existing network ranges. To delete a network range, highlight the selected range and click Delete on your keyboard. To edit a network range, highlight the selection to change and type over with the desired value(s).

    • Accepts typed or pasted ranges, bypassing the add range tool. To add a network range, click inside the network ranges text box and type the desired value(s) or paste from your local clipboard. Ranges added this way must also contain the ports notation (e.g, :443).

    • Validates network ranges as defined. To validate the list of ranges defined for the network, click the Validate action button. Based on the result, either a green "Network ranges are valid" message will display, or an alert will pop up with the list of invalid ranges.

    Quiet hours are ranges of hours or days during which scanning will not take place. Any scans in progress when the quiet hour window is reached will pause for the duration of the window and resume when the window is complete. SSL scans will show a status of In Quiet Hours if scanning is currently in that status.

    In the SSL Network Definition dialog on the Quiet Hours tab, define quiet hour periods as follows:

    1. In the Add Quiet Hours section of the page, select a day and time to begin a quiet hour period in the Start section.
    2. Select a day of the week and time to end the quiet hour period in the End section.
    3. Click Add to add the quiet hour period to the Quiet Hours section of the page.
    4. Repeat the above steps for any additional quiet hour periods.
    Note:  Quiet hours replace and expand upon the blackout period option that existed in previous versions of Keyfactor Command.

    Figure 260: Define a New Network—Quiet Hours Tab

  5. Click Save to save the new network definition or changes.
  1. In the Management Portal, browse to Locations > SSL Discovery.
  2. On the SSL Network Discovery page, select the Network Definitions tab (the default when you first visit the page).
  3. On the Network Definitions tab, highlight the row in the SSL network grid of the network to delete and click Delete at the top of the grid or right-click the network in the grid and choose Delete from the right-click menu.
  4. On the Confirm Operation alert, click OK to confirm or Cancel to cancel the operation.

At any time, you can view the status of the latest scan jobs by viewing scan details from the SSL Discovery page. Right-click the network location in the grid and choose View Scan Details from the right-click menu or highlight the row in the network grid and click View Scan Details at the top of the grid.

This takes you to a separate page with separate tabs for Discovery and Monitoring jobs (see Figure 261: SSL Network Scan Details Page). Details for the last scanned job display above the grid in each tab and the scanned segments for the latest scan populate the grid. You will only see more than one row in the grid if the SSL management job was broken into segments due to having a large number of endpoints. The number of endpoints per segment is configurable (see the SSL Maximum Scan Job Size setting in Application Settings: Agents Tab). The grid will display the latest completed job and will be refreshed with new scan details when the next scan begins.

Figure 261: SSL Network Scan Details Page

To view details for a segment, double-click the segment, right-click the segment and choose Details from the right-click menu, or highlight the row in the scan details grid and click Details at the top of the grid (see SSL Network Scan Detail Segment Details).

Figure 262: SSL Network Scan Detail Segment Details

Tip:  If jobs are taking longer to complete than expected, see Slow SSL Jobs.

In addition to SSL scanning jobs that can be run as scheduled, the Network Definitions tab includes a feature that allows you to manually initiate a scan for a configured network at any time that a scan is not already running for the network or the network is not in quiet hours. When you initiate a scan using the scan now feature, you can choose whether to run a discovery scan, a monitoring scan, or both.

To initiate a manual scan for a network:

  1. In the Management Portal, browse to Locations > SSL Discovery.
  2. On the SSL Network Discovery page, select the Network Definitions tab (the default when you first visit the page).
  3. On the Network Definitions tab, highlight the row in the SSL network grid of the network to scan and click Scan Now at the top of the grid or right-click the network in the grid and choose Scan Now from the right-click menu. The scan will begin immediately.
Tip:  If a scan is already in progress for the network, the option to start a scan of that type will be grayed out and cannot be selected.

Figure 263: SSL Network ScanNow

Resetting an SSL scan deletes all scan jobs, scan job parts, logical scan jobs, and current schedules associated with the selected network. The agent job status relating to the SSL scans is set to failed and completed, and the agent is forced to register for a new session. Afterward, Scan Now is enabled to allow you to initiate a manual scan. When you select Reset Scan, you will receive a Confirm Operation message. Click OK to proceed or Cancel to quit.

Tip:  If you have an SSL scan job that appears stuck or crashed without a failure result, you can use the reset scan option to cancel the dysfunctional scan job.

See the Results documentation for more information on these action buttons.