Document some limitations of decoys in the source and in the reference

guide. They don't honor scan delay and may violate congestion control.

Both this things should be fixed. I was going to do it by having
get_next_target_probe just return the same probe multiple times, and
then either extend struct probespec to include a source address or have
sendIPScanProbe keep track of the decoy index and fill in source
addresses. But I was stopped by timing pings. Those should certainly be
decoyed, but in the code they are just sent as they are needed, and
don't have a dispatching function to modify. What would be good is a
global queue of probes waiting to be sent you could just insert all your
spoofed probes into, and then let the rest of the code take care of
scheduling them.

docs/refguide.xml

@@ -2604,7 +2604,11 @@ lists the relevant options and describes what they do.</para>
           ICMP, SYN, ACK, or whatever) and during the actual port
           scanning phase. Decoys are also used during remote OS
           detection (<option>-O</option>).  Decoys do not work with
-          version detection or TCP connect scan.</para>
+          version detection or TCP connect scan.  When a scan delay is
+          in effect, the delay is enforced between each batch of
+          spoofed probes, not between each individual probe. Because
+          decoys are sent as a batch all at once, they may temporarily
+          violate congestion control limits.</para>
 
           <para>It is worth noting that using too many decoys may
           slow your scan and potentially even make it less

scan_engine.cc

@@ -2694,7 +2694,12 @@ static UltraProbe *sendArpScanProbe(UltraScanInfo *USI, HostScanStats *hss,
 }
 
 /* If this is NOT a ping probe, set pingseq to 0.  Otherwise it will be the
-   ping sequence number (they start at 1).  The probe sent is returned. */
+   ping sequence number (they start at 1).  The probe sent is returned.
+   
+   This function also handles the sending of decoys. There is no fine-grained
+   control of this; all decoys are sent at once on one call of this function.
+   This means that decoys do not honor any scan delay and may violate congestion
+   control limits. */
 static UltraProbe *sendIPScanProbe(UltraScanInfo *USI, HostScanStats *hss, 
 			    const probespec *pspec, u8 tryno, u8 pingseq) {
   u8 *packet = NULL;