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

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

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

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:

• Enable and disable scheduled excludes
• Add scheduled excludes
• List scheduled excludes
• Update and delete scheduled excludes

Enabling and disabling scheduled excludes

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

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:

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:

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:

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-105, 192.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 ~]$