Monitor mode docs

doc/scapy/troubleshooting.rst

@@ -5,6 +5,20 @@ Troubleshooting
 FAQ
 ===
 
+I can't sniff/inject packets in monitor mode.
+---------------------------------------------
+
+The use monitor mode varies greatly depending on the platform.
+
+- **Windows/OSX - ``conf.use_pcap = True``**
+  The pcap providers must be called differently by Scapy in order for them to create the sockets in monitor mode. You will need to pass the ``monitor=True`` to any calls that open a socket on their own (``send``, ``sniff``...) or to a Scapy socket that you create yourself (``conf.L2Socket``...)
+- **Linux native (with pcap disabled):**
+  You should set the interface in monitor mode on your own. Scapy provides utilitary functions: ``set_iface_monitor`` and ``get_iface_mode`` (linux only), that may be used (they do system calls to ``iwconfig`` and will restart the adapter).
+
+Note that many adapters do not support monitor mode, especially on Windows, or may incorrectly report the headers. See `the Wireshark doc about this <https://wiki.wireshark.org/CaptureSetup/WLAN>`_
+
+We make our best to make this work, if your adapter works with Wireshark for instance, but not with Scapy, feel free to report an issue.
+
 My TCP connections are reset by Scapy or by my kernel.
 ------------------------------------------------------
 The kernel is not aware of what Scapy is doing behind his back. If Scapy sends a SYN, the target replies with a SYN-ACK and your kernel sees it, it will reply with a RST. To prevent this, use local firewall rules (e.g. NetFilter for Linux). Scapy does not mind about local firewalls.

doc/scapy/usage.rst

@@ -1120,14 +1120,17 @@ Wireless frame injection
 .. index::
    single: FakeAP, Dot11, wireless, WLAN
 
+.. note::
+   See the TroubleShooting section for more information on the usage of Monitor mode among Scapy.
+
 Provided that your wireless card and driver are correctly configured for frame injection
 
 ::
 
     $ iw dev wlan0 interface add mon0 type monitor
     $ ifconfig mon0 up
 
-On Windows, if using Npcap, the equivalent would be to call
+On Windows, if using Npcap, the equivalent would be to call::
 
     >>> # Of course, conf.iface can be replaced by any interfaces accessed through IFACES
     ... conf.iface.setmonitor(True)

scapy/arch/linux.py

@@ -422,13 +422,13 @@ def _check_call(commands):
             warning("%s failed !" % " ".join(commands))
             return False
         return True
-    try:
-        assert _check_call(["ifconfig", iface, "down"])
-        assert _check_call(["iwconfig", iface, "mode", s_mode])
-        assert _check_call(["ifconfig", iface, "up"])
-        return True
-    except AssertionError:
+    if not _check_call(["ifconfig", iface, "down"]):
+        return False
+    if not _check_call(["iwconfig", iface, "mode", s_mode]):
         return False
+    if not _check_call(["ifconfig", iface, "up"]):
+        return False
+    return True
 
 
 class L2Socket(SuperSocket):
@@ -440,8 +440,10 @@ def __init__(self, iface=None, type=ETH_P_ALL, promisc=None, filter=None,
         self.type = type
         self.promisc = conf.sniff_promisc if promisc is None else promisc
         if monitor is not None:
-            if not set_iface_monitor(iface, monitor):
-                warning("Could not change interface mode !")
+            warning(
+                "The monitor argument is ineffective on native linux sockets."
+                " Use set_iface_monitor instead."
+            )
         self.ins = socket.socket(socket.AF_PACKET, socket.SOCK_RAW, socket.htons(type))  # noqa: E501
         self.ins.setsockopt(socket.SOL_SOCKET, socket.SO_RCVBUF, 0)
         if not nofilter: