tw_scan_control

The tw_scan_control command line utility enables you to do the following:

• Perform immediate and scheduled scans of endpoints (IP addresses, ranges, cloud or API providers)
• Start and stop Reasoning
• Disable and enable scheduled scans
• Remove and update scheduled scans

This page contains the following sections which describe these topics in detail:

• Using the tw_scan_control utility—This section contains the general guidelines to use the tw_scan_control utility. 
• Common options to manage snapshot and scheduled scans—This section contains information about the common options to manage snapshot and scheduled scans, such as starting and stopping discovery and adding discovery runs.
• Options to manage scheduled scans—This section contains information about the options to manage scheduled scans, such as adding scheduled discovery runs, enabling and disabling scheduled discovery runs, listing scheduled discovery runs, and updating and deleting scheduled discovery runs.
• Overlapping of scheduled scans and excludes—This section contains information about the expected behavior in the event of overlapping of scheduled scans and excludes.

Using the tw_scan_control utility

To use the utility, type the following command:

where:

• endpoint is a single entry or a space separated list of IP address information, or cloud provider, in the following formats:
  • IPv4 address (for example 192.168.1.100).
  • IPv6 address (for example 2001:500:100:1187:203:baff:fe44:91a0).
  • IPv4 range (for example 192.168.1.100-105, 192.168.1.100/24, or 192.168.1.*).
  • Cloud provider (for example aws which represents Amazon Web Services. To determine supported providers, see to determine the cloud providers supported).
• options are any of the options described in the following table and the common command line options described in Using-command-line-utilities.

In each of the sections below, user examples have been included for your reference. In these examples, the user name is system and the password is not specified on the command line. The utility prompts for the password after you enter the command. Type the commands on a single line; line breaks are provided in the examples to make them easier to read. Note the following:

• If you want to scan a range of IP addresses listed in a file, make sure that the IP addresses are arranged in a newline separated list.
• With --enable, --disable, --remove, and --update=ID you are required to enter the list of corresponding range IDs. You can view the list of range IDs by using the --list and --list-full command line options.

Common options to manage snapshot and scheduled scans

By using the common options for snapshot and scheduled scans with the tw_scan_control command line utility, you can perform the following:

• Start and stop discovery
• Add discovery runs

Starting and stopping discovery

Use the following common options with the tw_scan_control command line utility to start and stop discovery:

User examples

To start discovery:

To stop discovery:

Adding discovery runs

Use the following common options with the tw_scan_control command line utility to add snapshot and scheduled scans and specify run details:

The following examples show various types of snapshot scans. For user examples related to scheduled scans, see the Options to manage scheduled scans section.

To specify an immediate scan of a single IP address

To specify an immediate scan of a range of IP addresses:

To specify an immediate scan of a range of IP addresses using a particular BMC Discovery Outpost

 Specify the BMC Discovery Outpost by name (DiscoOutpost01) or ID (6fa1b63871646f6a1e800a3123e30b38). Alternatively, you can require that the appliance performs the discovery: name (Local discovery) or ID (e10da13871621dcc2abc7f00000105ca).

You can specify BMC Discovery Outpost or the appliance in the same way for scheduled scans.

To specify an immediate scan of IP addresses listed in a file:

The example below shows a file containing IP address and range information:

To specify an immediate scan of a cloud provider

In this example you must supply the provider, the region, and the cloud credential:

To determine the cloud providers supported 

To see the options available for a supported cloud provider

To see the regions available for a supported cloud provider

To specify an immediate scan of an API provider

To determine the API providers supported 

To see the options available for a supported API provider

Options to manage scheduled scans

By using the scheduled scan options with the tw_scan_control command line utility, you can perform the following:

• List scheduled discovery runs
• Enable and disable scheduled discovery runs
• Add scheduled discovery runs
• Update and delete scheduled discovery runs

Listing scheduled discovery runs

Use the following common options with the tw_scan_control command line utility to list scheduled discovery runs:

Listing the scheduled discovery runs gives you information about them, such as the range ID corresponding to a run, whether the run has been enabled or disabled, the label and IP addresses or ranges associated with a run, and so on.

To list all scan ranges

Enabling and disabling scheduled discovery runs

Use the following common options with the tw_scan_control command line utility to enable or disable scheduled scans:

To disable a scheduled scan

To enable a scheduled scan which has been disabled

Adding scheduled discovery runs

You can schedule daily, weekly, and monthly discovery runs. The following options are available with the tw_scan_control command line utility:

• Common options for scheduled discovery runs
• Options for scheduling daily discovery runs
• Options for scheduling weekly discovery runs
• Options for scheduling monthly discovery runs
• Backward compatible options

Common options for scheduled discovery runs

Options for scheduling daily discovery runs

To specify a daily scheduled scan of a range of IP addresses with specified start and end time and label it TEST

To specify a daily scheduled scan of IP addresses listed in a file

To specify a daily scheduled scan of a range of IP addresses with specified start time and duration

To specify a daily repeating scan of a range of IP addresses with specified start time every six hours

When you specify this scan, the series is set up as 01:35, 07:35, 13:35, and 19:35. The first scan to take place is the one that the clock time next reaches. For example, if you specify the repeating scan at midnight, the first one to take place is the 01:35 scan. If you specify the repeating scan at 3:00pm, the first one to take place is the 19:35 scan:

To specify a daily scheduled scan of regions of a cloud provider with specified start time and duration

To specify a daily repeating scan of regions of a cloud provider with specified start time every 12 hours

Options for scheduling weekly discovery runs

To specify a weekly scheduled scan of a range of IP addresses with specified start time and day and specified end time and day

Options for scheduling monthly discovery runs

To specify a monthly scheduled scan of a range of IP addresses with specified start time and day of the week and ends on completion of the scan

Backward compatible options

Use the following backward compatible options with the tw_scan_control command line utility to add recurrent scans:

Updating and deleting scheduled discovery runs

Use the following common options with the tw_scan_control command line utility to update or delete scheduled discovery runs:

To remove a chosen scan range

To update a chosen scheduled scan

Assume that you have set the following daily scheduled scan for an IP range where the start time is 14:30 and the end time is 17:30:

The following are examples of updating the scheduled scan added above.

• To update the start time to 20:30 and the end time to 23:50, run the following command:

  tw_scan_control --daily --start-time=20:30 --end-time=23:50 
  --update=6ee6e7321031ae6a6fb80a8148a76f8b 192.168.0.1-10

• To update it from a daily to a weekly scheduled scan, which starts on Monday at 07:30 and ends on Tuesday at 11:50, run the following command:

  tw_scan_control --weekly --weekly-start-week-days=monday --weekly-end-week-day=tuesday
  --start-time=07:30 --end-time=11:50 --update=6ee6e732105205be37020a8148a76f8b 192.168.0.1-10

Overlapping of scheduled scans and excludes

In the case of permanent excludes, discovery of the excluded endpoints never starts. However, in the case of an overlap of scheduled scans and scheduled excludes, the following behavior is expected:

• If a scheduled exclude overlaps with a scheduled scan, discovery of the excluded endpoints will not start until the scheduled exclude is no longer in effect.
• If the scheduled exclude ends before the scheduled scan end time, discovery of the excluded endpoints can start.
• If the scheduled exclude ends after the scheduled scan end time, the excluded endpoints will wait until the next time the scheduled scan runs.
• If one or more scheduled excludes overlap completely with a scheduled scan, the excluded endpoints will behave like permanent excludes. This is to prevent it from waiting forever to discover those excluded endpoints that it will never be able to scan.
• If a scheduled exclude is active and a snapshot scan is running, any excluded endpoint will be skipped by the scan and will have an excluded end state.

Related topics

• Using-command-line-utilities