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, or cloud providers)
- Start and stop Reasoning
- Disable and enable scheduled scans
- Remove and update scheduled scans
Tip
Use the BMC Discovery user interface to perform the functionality provided by the tw_scan_control command line utility (see Performing a discovery run). If you choose to run the utility, read the information in this section to learn its usage and to understand the risks and potential impact on your environment.
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_controlutility. - 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:
tw_scan_control [options] endpoint
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, or192.168.1.*). - Cloud provider (for example
awswhich represents Amazon Web Services. To determine supported providers, see to determine the cloud providers supported).
- IPv4 address (for example
- options are any of the options described in the following table and the common command line options described in Using command line utilities.
Note
Scanning the following address types is not supported:
• IPv6 link local addresses (prefix fe80::/64)
• IPv6 multicast addresses (prefix ff00::/8)
• IPv6 network prefix (for example fda8:7554:2721:a8b3::/64)
• IPv4 multicast addresses (224.0.0.0 to 239.255.255.255)
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=IDyou are required to enter the list of corresponding range IDs. You can view the list of range IDs by using the--listand--list-fullcommand line options.
Common options to manage snapshot and scheduled scans
Note
The common command line options are described in Using command line utilities.
By using the common options for snapshot and scheduled scans with the tw_scan_control command line utility, you can perform the following:
Starting and stopping discovery
Use the following common options with the tw_scan_control command line utility to start and stop discovery:
Command Line Option | Description |
|---|---|
| Starts Reasoning. This is equivalent to clicking START ALL SCANS. |
| Stops Reasoning. This is equivalent to clicking STOP ALL SCANS. |
User examples
To start discovery:
tw_scan_control --start
To stop discovery:
tw_scan_control --stop
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:
Command Line Option | Description |
|---|---|
| Adds a new scan range. |
| Scans the IP addresses (located in a file or listed at the command prompt) in random order. |
| Specifies the scan level to use. This can be one of the following:
Replaces the obsolete option |
| Specifies the company name to use for a scan in a multitenant deployment. This value is checked against the list of known companies. |
--force-company | Bypass company name validation performed by --company. |
| Specifies a file or a list of files as arguments. They must be plain text files with a new line delimited list of IP addresses, or IP ranges. See IP addresses listed in a file for an example of usage, and an example file. |
| Specifies the label for the scan. |
| Specifies the vault passphrase to use. |
--outpost=OUTPOST_ID | Perform the scan using the specified BMC Discovery Outpost. Cannot be used with the
When you specify the BMC Discovery Outpost, the scope applied to the discovered endpoints is taken from the BMC Discovery Outpost. The |
--allow-tpl-scan | Allow patterns to start new scans against these endpoints. |
--cloud-provider=NAME | Specifies a cloud provider to scan. This option can only be followed by other options specific to cloud discovery. |
--help-cloud-provider | Lists the available cloud providers, and provides information on the options available for each cloud provider. For more information, see to determine the cloud providers supported. |
--scan-option-ping | Ping before scanning. This is the equivalent of setting the UI option Ping hosts before scanning. For more information on this option, see Configuring discovery settings. |
--scan-option-no-ping | Do not ping before scanning. This is the equivalent of not setting the UI option Ping hosts before scanning. For more information on this option, see Configuring discovery settings. |
--scope=SCOPE | Specifies a scope to apply to the scan. Only required if you have scope configured on your appliance. The |
| Turns off informational messages. |
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
tw_scan_control --add 192.168.0.1
To specify an immediate scan of a range of IP addresses:
tw_scan_control --add 192.168.0.1-10
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).
[tideway@appliance01 ~]$ tw_reasoningstatus --username=system --discovery-outposts
Id: e10da13871621dcc2abc7f00000105ca
Scan Ranges: Allow all IPs
Exclude Ranges: None
Version: Internal
Last contact:
Discovery_Appliance: 2020-05-06 14:13:16 BST
Name: DiscoOutpost01
Id: 6fa1b63871646f6a1e800a3123e30b38
Scan Ranges: Allow all IPs
Exclude Ranges: None
Version: 12.0.0.0 (release 807173)
Last contact:
Discovery_Appliance: 2020-05-06 14:13:17 BST
[tideway@appliance01 ~]$
[tideway@appliance01 ~]$ tw_scan_control --outpost=DiscoOutpost01 --add 192.168.0.1-10
Password for BMC Discovery UI user system:
Added snapshot scan IP range
[tideway@appliance01 ~]$
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:
tw_scan_control --add --file ~/scanlist
The example below shows a file containing IP address and range information:
# Lines begining with a hash (#) are treated as comments # IPv4 addresses (newline separated) 192.168.1.100 192.168.1.105 # IPv6 addresses 2001:500:100:1187:203:baff:fe44:91a0 # IPv4 ranges 192.168.1.200-205 192.168.1.200/24 192.168.1.*
To specify an immediate scan of a cloud provider
In this example you must supply the provider, the region, and the cloud credential:
tw_scan_control --username=system --add --cloud-provider=aws region=eu-west-2 credential="BMC AWS"
To determine the cloud providers supported
[tideway@appliance01 ~]$ tw_scan_control --help-cloud-provider
usage: tw_scan_control <action> --cloud-provider <provider> [options]
Get additional help for a cloud provider by using:
tw_scan_control --cloud-provider <provider> --help-cloud-provider
Available cloud providers:
aws
azure
[tideway@appliance01 ~]$
To see the options available for a supported cloud provider
[tideway@appliance01 ~]$ tw_scan_control --help-cloud-provider --cloud-provider aws
usage: tw_scan_control <action> --cloud-provider <provider> [options]
Cloud provider aws options are:
credential=<credential> Credential for the scan
regions=<region>,... OR
region=<region> [region=<region>]...
List of regions to scan
[tideway@appliance01 ~]$
To see the regions available for a supported cloud provider
[tideway@appliance01 ~]$ tw_scan_control --help-cloud-provider --cloud-provider aws regions
usage: tw_scan_control <action> --cloud-provider <provider> [options]
Cloud provider aws options are:
regions=<region>,... OR
region=<region> [region=<region>]...
List of regions to scan
Values: ap-northeast-1, ap-northeast-2, ap-south-1, ap-southeast-1,
ap-southeast-2, ca-central-1, eu-central-1, eu-west-1, eu-west-2,
sa-east-1, us-east-1, us-east-2, us-west-1 and us-west-2
[tideway@appliance01 ~]$
To specify an immediate scan of a cloud provider
[tideway@bleedingedge ~]$ tw_scan_control --label=Whippet --add --cloud-provider=aws region=eu-west-2 credential="BMC AWS" Password for BMC Discovery UI user system: Added snapshot scan cloud range [tideway@bleedingedge ~]$
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:
Command Line Option | Description |
|---|---|
| Lists all scan ranges. |
| Lists all scan ranges with all IP addresses. |
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
[tideway@appliance01 ~]$ tw_scan_control --list --username=system Password for BMC Discovery UI user system: ID Enabled Label User Scan type TPL scan Scanning bd254b356649463f009089485e42588e True TEST system Scheduled False 192.168.0.1-10 [tideway@appliance01 ~]$
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:
Command Line Option | Description |
|---|---|
| Enables the specified scheduled scan. The scan ID is determined using |
| Disables the specified scheduled scan. The scan ID is determined using |
To disable a scheduled scan
tw_scan_control --disable 6ee6e73209c64a4e9c0a0a8148a76f8b
To enable a scheduled scan which has been disabled
tw_scan_control --enable 6ee6e73209c64a4e9c0a0a8148a76f8b
Adding scheduled discovery runs
You can schedule discovery runs which are daily, weekly, and monthly for which the following options with the tw_scan_control command line utility are available:
- 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
Command Line Option | Description |
|---|---|
| Sets the start time of a scheduled scan. |
| Sets the end time of a scheduled scan. |
| Sets the duration of scheduled scans. |
| Sets the scheduled scan to run to its completion. |
Options for scheduling daily discovery runs
Command Line Option | Description |
|---|---|
| Adds a daily scheduled scan. |
--daily-frequency=FREQUENCY | Adds a repeating daily scan which is started every FREQUENCY hours and runs to completion. FREQUENCY can be 1, 2, 3, 4, 6, 8 or 12 hours. When specifying a repeating daily scan, you must also specify a start time ( The start time is a start time in the series, that is, when you schedule a repeating scan using |
To specify a daily scheduled scan of a range of IP addresses with specified start and end time and label it TEST
tw_scan_control --daily --start-time=21:30 --end-time=23:30 --label=TEST --add 192.168.0.1-10
To specify a daily scheduled scan of IP addresses listed in a file
tw_scan_control --daily --start-time=21:30 --end-time=23:30 --add --file ~/scanlist
To specify a daily scheduled scan of a range of IP addresses with specified start time and duration
tw_scan_control --daily --start-time=21:30 --duration=00:06:30 --add 192.168.0.1-10
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:
tw_scan_control --daily-frequency=6 --start-time=07:35 --no-end-time --add 192.168.0.1-10
To specify a daily scheduled scan of regions of a cloud provider with specified start time and duration
tw_scan_control --daily --start-time=23:30 --duration=00:00:30 --add --cloud-provider=aws region=eu-west-2 credential="BMC AWS"
To specify a daily repeating scan of regions of a cloud provider with specified start time every 12 hours
tw_scan_control --daily-frequency=12 --start-time=07:30 --no-end-time --add --cloud-provider=aws region=eu-west-2 credential="BMC AWS"
Options for scheduling weekly discovery runs
Command Line Option | Description |
|---|---|
| Adds a weekly scheduled scan. |
| Sets the weekly scheduled scan start week day. The range of the start weekday is monday, tuesday, and so on. |
| Sets the weekly scheduled scan end week day. The range of the end weekday is monday, tuesday, and so on. |
To specify a weekly scheduled scan of a range of IP addresses with specified start time and day and specified end time and day
tw_scan_control --weekly --weekly-start-week-days=monday --weekly-end-week-day=tuesday --start-time=21:30 --end-time=20:30 --add 192.168.0.1-10
Options for scheduling monthly discovery runs
Command Line Option | Description |
|---|---|
| Adds a monthly scheduled scan. |
| Sets the monthly scheduled scan start day. The range of the day is from 1 to 31. |
| Sets the monthly scheduled scan end day. The range of the day is from 1 to 31. |
| Sets the monthly scheduled scan start week. The range of the week is first, second, third, fourth, and last. |
| Sets the monthly scheduled scan start week day of the week. The range of the weekday is monday, tuesday, and so on. |
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
tw_scan_control --monthly --monthly-start-week-day=monday --monthly-start-week=first --start-time=21:30 --no-end-time --add 192.168.0.1-10
Backward compatible options
Use the following backward compatible options with the tw_scan_control command line utility to add recurrent scans:
Command Line Option | Description |
|---|---|
| Adds a daily recurrent range. This option specifies a recurrent range scan that must be modified with |
| Specifies the duration for the recurring scan to last (in hours). |
| Sets the start time for recurrent ranges (in hours) after midnight |
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:
Command Line Option | Description |
|---|---|
| Cancels any running scans and deletes all scheduled scans. Replaces the obsolete option |
| Removes chosen scan ranges. |
| Updates (edits) the specified scheduled discovery run. The discovery run is specified using its range ID which can be determined by running the |
To remove a chosen scan range
tw_scan_control --remove 6ee6e7320aa7c5716c140a8148a76f8b
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:
tw_scan_control --daily --start-time=14:30 --end-time=17:30 --add 192.168.0.1-10
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.
Note
Deprecated utilities and options
The tw_injectip utility is now deprecated and might be removed in future releases. Its functionality is available in the tw_scan_control utility which has all of the same options.
The --clean, --replace, and --scanLevel options are obsolete and have been replaced by the --clear, --update, and --scan-level options.
Comments
Log in or register to comment.