tw_excluderanges

The tw_excluderanges utility enables you to do the following:

  • add permanent and scheduled excludes of IP addresses or ranges
  • disable and enable excludes
  • remove and update excludes

Recommendation

Use the BMC Discovery user interface to perform the functionality provided by the tw_excluderanges command line utility (see Running Discovery). If you choose to run the utility, read the documentation in this section to learn its usage and to understand the risks and potential impact on your environment.

This page contains the following sections:

  • Using the tw_excluderanges utility—This section contains the general guidelines to use the tw_excluderanges utility. 
  • Common options to manage immediate and scheduled excludes—This section contains information about the common options to manage immediate and scheduled excludes, such as adding a new exclude, adding an exclude description, specifying a file, specifying a label, and so on.
  • Options to manage scheduled excludes—This section contains information about the options to manage scheduled excludes, such as adding scheduled exclude, enabling and disabling scheduled excludes, listing excludes, updating and deleting scheduled excludes, and so on.
  • Overlapping of scheduled scans and excludes—This section contains information about the expected behavior in the event of overlapping of scheduled scans and excludes.
  • Importing IP ranges to use as exclude ranges—This section contains information about importing multiple IP ranges from a text file to use as exclude ranges.

Using the tw_excluderanges utility

To use the utility, type the following command:

tw_excluderanges [options] args

where:

  • args is one of the following arguments:
    • with --disable--enable or --remove, a list of range IDs

    • with -f a list of filenames containing IP ranges to exclude

    • otherwise a list of IP ranges to exclude

If you do not select an argument in the command, a list of the currently excluded ranges is displayed, which includes the exclude range ID and additional information about that range. You could redirect this output to a file and then clean it up in a text editor to serve as a file which could then be imported.

Common options to manage immediate and scheduled excludes

The common command line options are described in Using command line utilities.

Following are the common options for immediate and scheduled excludes with the tw_excluderanges command line utility:

Command Line Option

Description

-a, --add

Adds a new exclude range.

-d, --description=DESCRIPTION

Specifies a description for the exclude range.

-f, --file

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. This is useful for importing large numbers of exclude ranges.

--label=LABEL

Specifies the label for the exclude range.

--silent

Turns off informational messages.

User examples:

To permanently exclude an IP range from discovery:

tw_excluderanges --add 192.168.0.1-10

To specify an exclude IP range listed in a file:

tw_excluderanges --add --file /tmp/ExcludeFile.txt

Options to manage scheduled excludes

The options to manage scheduled excludes with the tw_excluderanges command line utility enable you to perform the following:

Enabling and disabling scheduled excludes

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

Command Line Option

Description

--enable

Enables the chosen exclude ranges.

--disable

Disables the chosen exclude ranges.

User examples:

To enable a chosen exclude range:

tw_excluderanges --enable 6ee6e7321061632854040a8148a76f8b

To disable a chosen exclude range:

tw_excluderanges --disable 6ee6e7321061632854040a8148a76f8b

Adding scheduled excludes

Use the following common options with the tw_excluderanges command line utility to add scheduled excludes and specify its details:

Command Line Option

Description

--daily

Adds a daily scheduled exclude range.

--duration=DD:HH:MM

Sets the duration of a scheduled exclude.

--start-time=HH:MM

Sets the start time of a scheduled exclude.

--end-time=HH:MM

Sets the end time of a scheduled exclude.

--weekly

Adds a weekly scheduled exclude.

--weekly-start-week-days=WEEKDAYS

Sets the weekly scheduled exclude start week day of the week. The range of the weekday is monday, tuesday, and so on.

--weekly-end-week-day=WEEKDAY

Sets the weekly scheduled exclude end week day of the week. The range of the weekday is monday, tuesday, and so on.

--monthly

Adds a monthly scheduled exclude.

--monthly-start-day=DAY

Sets the monthly scheduled exclude start day. The range of the day is from 1 to 31.

--monthly-end-day=DAY

Sets the monthly scheduled exclude end day. The range of the day is from 1 to 31.

--monthly-start-week=WEEK

Sets the monthly scheduled exclude start week. The range of the week is first, second, third, fourth, and last.

--monthly-start-week-day=WEEKDAY

Sets the monthly scheduled exclude start week day of the week. The range of the weekday is monday, tuesday, and so on.

User examples:

To add a daily exclude IP range from discovery:

tw_excluderanges --daily --start-time=9:30 --end-time=11:30 --add 142.158.0.1-22

To specify a description for the exclude range:

tw_excluderanges --daily --start-time=9:30 --end-time=11:30 --description=TEST --add 142.158.0.33-67

To specify a duration for the exclude range:

tw_excluderanges --label=TEST --daily --start-time=9:30 --duration=00:06:30 --add 142.158.0.1-22

To add a monthly exclude IP range from discovery:

tw_excluderanges --monthly --monthly-start-week-day=monday 
--monthly-start-week=first --start-time=21:30 --duration 00:06:30 --add 162.153.0.3-18

To add a weekly exclude IP range from discovery:

tw_excluderanges --weekly --weekly-start-week-days=monday 
--weekly-end-week-day=tuesday --start-time=21:30 --end-time=20:30 --add 123.142.0.6-13

Listing scheduled excludes

Use the following common options with the tw_excluderanges command line utility to list scheduled excludes:

Command Line Option

Description

--list

Lists all exclude ranges.

--list-full

Lists all exclude ranges with all IP addresses.

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

User examples:

To list all exclude ranges with all IP addresses:

tw_excluderanges --list-full

Updating and deleting scheduled excludes

Use the following common options with the tw_excluderanges command line utility to update or delete scheduled excludes:

Command Line Option

Description

--clear

Removes all exclude ranges.

--update=ID

Updates (edit) the specified scheduled exclude. The exclude is specified using its range ID which can be determined by running the list or list-full options.

-r, --remove

Removes chosen exclude ranges.

-x, --replace

If addresses supplied, adds a new exclude range, then delete all the old exclude ranges.

User examples:

To remove all exclude ranges from discovery:

tw_excluderanges --clear

To remove a chosen exclude range from discovery:

tw_excluderanges --remove 6ee6e73210ac294696f60a8148a76f8b

To update a chosen scheduled exclude:

Let us assume that you have set the following daily scheduled exclude for an IP range, where the start time is 14:30 and the end time is 17:30:

tw_excluderanges --daily --start-time=14:30 --end-time=17:30 --add 182.158.2.5-15
  • To update the start time to 20:30 and the end time to 23:50, you will run the following command:
tw_excluderanges --daily --start-time=20:30 --end-time=23:50 
--update=6ee6e73210b111bf7bec0a8148a76f8b 182.158.2.5-15
  • 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, you will run the following command:
tw_excluderanges --weekly --weekly-start-week-days=monday --weekly-end-week-day=tuesday 
--start-time=07:30 --end-time=11:50 --update=6ee6e73210b111bf7bec0a8148a76f8b 182.158.2.5-15

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.

Importing IP ranges to use as exclude ranges

You can import multiple IP addresses or IPv4 address ranges if they are contained in text files, one IP address or range per line. Ranges can be specified as usual:

  • IPv4 address—For example 192.168.1.100.
  • IPv6 address—For example fe80::655d:69d7:4bfa:d768.
  • IPv4 range—For example 192.168.1.100-105192.168.1.100/24, or 192.168.1.*.

An example file called excludes1.txt:

192.168.1.100
192.168.1.110-120

A second example file called excludes2.txt:

192.168.2.100-105
192.168.2.*
192.168.3.0/24
2001:500:100:1187:203:baff:fe44:91a0

Import the exclude ranges from the two files using the following command:

[tideway@appliance01 ~]$ tw_excluderanges --username=system --add
  --name="Imported Ranges" --file excludes1.txt excludes2.txt
Password:
Feeding file excludes1.txt 
Feeding file excludes2.txt
Add excluded range: 192.168.1.100,192.168.1.110-120,192.168.2.100-105,
192.168.2.*,192.168.3.0/24,2001:500:100:1187:203:baff:fe44:91a0 Imported Ranges
[tideway@appliance01 ~]$
Was this page helpful? Yes No Submitting... Thank you

Comments