Add --max-rate to go with --min-rate.

CHANGELOG

@@ -113,6 +113,8 @@ o Nmap's makefile will now install menu items for launching zenmap as
 o Nmap will no longer misreport a localhost-responce during -PN scans
   [Michael]
 
+o There is a new --max-rate option complementary to --min-rate. [David]
+
 Nmap 4.68 [2008-6-28]
 
 o Doug integrated all of your version detection submissions and

NmapOps.cc

@@ -192,6 +192,7 @@ void NmapOps::Initialize() {
   debugging = 0;
   verbose = 0;
   min_packet_send_rate = 0.0; /* Unset. */
+  max_packet_send_rate = 0.0; /* Unset. */
   randomize_hosts = 0;
   sendpref = PACKET_SEND_NOPREF;
   spoofsource = 0;
@@ -443,6 +444,10 @@ void NmapOps::ValidateOptions() {
   if (max_parallelism && min_parallelism && (min_parallelism > max_parallelism)) {
     fatal("--min-parallelism=%i must be less than or equal to --max-parallelism=%i",min_parallelism,max_parallelism);
   }
+
+  if (min_packet_send_rate != 0.0 && max_packet_send_rate != 0.0 && min_packet_send_rate > max_packet_send_rate) {
+    fatal("--min-rate=%g must be less than or equal to --max-rate=%g", min_packet_send_rate, max_packet_send_rate);
+  }
   
   if (af() == AF_INET6 && (numdecoys|osscan|bouncescan|fragscan|ackscan|finscan|idlescan|ipprotscan|maimonscan|nullscan|synscan|udpscan|windowscan|xmasscan)) {
     fatal("Sorry -- IPv6 support is currently only available for connect() scan (-sT), ping scan (-sP), and list scan (-sL).  OS detection and decoys are also not supported with IPv6.  Further support is under consideration.");

NmapOps.h

@@ -180,6 +180,8 @@ class NmapOps {
   int verbose;
   /* The requested minimum packet sending rate, or 0.0 if unset. */
   float min_packet_send_rate;
+  /* The requested maximum packet sending rate, or 0.0 if unset. */
+  float max_packet_send_rate;
   int randomize_hosts;
   int spoofsource; /* -S used */
   int fastscan;

docs/refguide.xml

@@ -2460,6 +2460,35 @@ timing.</para>
         </listitem>
       </varlistentry>
 
+      <varlistentry>
+        <term>
+        <option>--max-rate <replaceable>number</replaceable></option>
+        (Specify a maximum scanning rate)
+        <indexterm><primary><option>--max-rate</option></primary></indexterm>
+        </term>
+        <listitem>
+
+<para>Complementary to <option>--min-rate</option> is
+<option>--max-rate</option>, which limits a scan's sending rate to a
+given maximum. Use <option>--max-rate 100</option>, for example, to
+limit sending to 100 packets per second on a fast network. Use
+<option>--max-rate 0.1</option> for a slow scan of one packet every ten
+seconds.</para>
+
+<para><option>--max-rate</option>, like <option>--min-rate</option>, is
+a global option affecting an entire scan. It affects only port and host
+discovery scans. Unlike <option>--min-rate</option>, which is a
+<quote>best-effort</quote> option, <option>--max-rate</option> is a hard
+upper bound on the scanning rate.</para>
+
+<para>Nmap may go slower than the maximum rate if conditions require it.
+To keep the sending rate within a specified range, use
+<option>--min-rate</option> and <option>--max-rate</option>
+together.</para>
+
+        </listitem>
+      </varlistentry>
+
       <varlistentry>
         <term><option>--defeat-rst-ratelimit</option>
         <indexterm><primary><option>--defeat-rst-ratelimit</option></primary></indexterm></term>

nmap.cc

@@ -279,6 +279,7 @@ printf("%s %s ( %s )\n"
        "  --host-timeout <time>: Give up on target after this long\n"
        "  --scan-delay/--max-scan-delay <time>: Adjust delay between probes\n"
        "  --min-rate <number>: Send packets no slower than <number> per second\n"
+       "  --max-rate <number>: Send packets no faster than <number> per second\n"
        "FIREWALL/IDS EVASION AND SPOOFING:\n"
        "  -f; --mtu <val>: fragment packets (optionally w/given MTU)\n"
        "  -D <decoy1,decoy2[,ME],...>: Cloak a scan with decoys\n"
@@ -676,6 +677,8 @@ int nmap_main(int argc, char *argv[]) {
       {"ip-options", required_argument, 0, 0},
       {"min_rate", required_argument, 0, 0},
       {"min-rate", required_argument, 0, 0},
+      {"max-rate", required_argument, 0, 0},
+      {"max-rate", required_argument, 0, 0},
       {0, 0, 0, 0}
     };
 
@@ -936,6 +939,9 @@ int nmap_main(int argc, char *argv[]) {
       } else if(optcmp(long_options[option_index].name, "min-rate") == 0) {
         if (sscanf(optarg, "%f", &o.min_packet_send_rate) != 1 || o.min_packet_send_rate <= 0.0)
           fatal("Argument to --min-rate must be a positive floating-point number");
+      } else if(optcmp(long_options[option_index].name, "max-rate") == 0) {
+        if (sscanf(optarg, "%f", &o.max_packet_send_rate) != 1 || o.max_packet_send_rate <= 0.0)
+          fatal("Argument to --max-rate must be a positive floating-point number");
       } else {
 	fatal("Unknown long option (%s) given@#!$#$", long_options[option_index].name);
       }
@@ -1537,7 +1543,7 @@ int nmap_main(int argc, char *argv[]) {
     log_write(LOG_PLAIN, "  max-scan-delay: TCP %d, UDP %d\n", o.maxTCPScanDelay(), o.maxUDPScanDelay());
     log_write(LOG_PLAIN, "  parallelism: min %d, max %d\n", o.min_parallelism, o.max_parallelism);
     log_write(LOG_PLAIN, "  max-retries: %d, host-timeout: %ld\n", o.getMaxRetransmissions(), o.host_timeout);
-    log_write(LOG_PLAIN, "  min-rate: %g\n", o.min_packet_send_rate);
+    log_write(LOG_PLAIN, "  min-rate: %g, max-rate: %g\n", o.min_packet_send_rate, o.max_packet_send_rate);
     log_write(LOG_PLAIN, "---------------------------------------------\n");
   }
 

scan_engine.cc

@@ -337,8 +337,14 @@ public:
   /* Value of numprobes_sent at lastping_sent time -- to ensure that we don't
      send too many pings when probes are going slowly. */
   int lastping_sent_numprobes; 
-  /* When to send the next probe, to keep the minimum up. Used only when a
+
-     minimum sending rate (o.min_packet_send_rate) is set. */
+  /* These two variables control minimum- and maximum-rate sending (--min-rate
+     and --max-rate). send_no_earlier_than is for --max-rate and
+     send_no_later_than is for --min-rate; they have effect only when the
+     respective command-line option is given. An attempt is made to keep the
+     sending rate within the interval, however for send_no_later_than it is not
+     guaranteed. */
+  struct timeval send_no_earlier_than;
   struct timeval send_no_later_than;
 
   /* The host to which global pings are sent. This is kept updated to be the
@@ -863,6 +869,7 @@ GroupScanStats::GroupScanStats(UltraScanInfo *UltraSI) {
   probes_sent = probes_sent_at_last_wait = 0;
   probes_replied_to = 0;
   lastping_sent = lastrcvd = USI->now;
+  send_no_earlier_than = USI->now;
   send_no_later_than = USI->now;
   lastping_sent_numprobes = 0;
   pinghost = NULL;
@@ -875,11 +882,23 @@ GroupScanStats::~GroupScanStats() {
 }
 
 void GroupScanStats::probeSent() {
-  /* Find the next scheduled send time for minimum-rate scanning. */
+  /* Find a new scheduling interval for minimum- and maximum-rate sending.
+     Recall that these have effect only when --min-rate or --max-rate is
+     given. */
+
+  TIMEVAL_ADD(send_no_earlier_than, send_no_earlier_than,
+    (time_t) (1000000.0 / o.max_packet_send_rate));
+  if (TIMEVAL_SUBTRACT(send_no_earlier_than, USI->now) < 0) {
+    /* Even after incrementing send_no_earlier_than, it's still in the past.
+       That means more packets could be sent immediately and make the rate too
+       high. Catch the time up to the present to prevent that. */
+    send_no_earlier_than = USI->now;
+  }
+
   if (TIMEVAL_SUBTRACT(send_no_later_than, USI->now) > 0) {
-    /* The next scheduled send is in the future. That means we're ahead of
+    /* The next scheduled send is in the future. That means there's slack time
-       schedule, but it also means there's slack time during which the sending
+       during which the sending rate could drop. Pull the time back to the
-       rate could drop. Reschedule the send to keep that from happening. */
+       present to prevent that. */
     send_no_later_than = USI->now;
   }
   TIMEVAL_ADD(send_no_later_than, send_no_later_than,
@@ -921,6 +940,20 @@ bool GroupScanStats::sendOK(struct timeval *when) {
   if (recentsends >= 50)
     return false;
 
+  /* Enforce a maximum scanning rate, if necessary. If it's too early to send,
+     return false. If not, mark now as a good time to send and allow the
+     congestion control to override it. */
+  if (o.max_packet_send_rate != 0.0) {
+    if (TIMEVAL_SUBTRACT(send_no_earlier_than, USI->now) > 0) {
+      if (when)
+        *when = send_no_earlier_than;
+      return false;
+    } else {
+      if (when)
+        *when = USI->now;
+    }
+  }
+
   /* In case the user specifically asked for no group congestion control */
   if (o.nogcc) {
     if (when)
@@ -929,9 +962,9 @@ bool GroupScanStats::sendOK(struct timeval *when) {
   }
 
   /* Enforce a minimum scanning rate, if necessary. If we're ahead of schedule,
-     record the time of the next scheduled send. If we're behind schedule,
+     record the time of the next scheduled send and submit to congestion
-     return true to indicate that we need to send now, regardless of any
+     control. If we're behind schedule, return true to indicate that we need to
-     congestion control. */
+     send right now. */
   if (o.min_packet_send_rate != 0.0) {
     if (TIMEVAL_SUBTRACT(send_no_later_than, USI->now) > 0) {
       if (when)