From 920a0a07689d1bb2f529b657dc8d6fb071868aab Mon Sep 17 00:00:00 2001 From: Pierre Lalet Date: Fri, 17 Dec 2021 17:05:50 +0100 Subject: [PATCH] Initial documentation --- README.md | 2 +- doc/Makefile | 19 +++++++++ doc/conf.py | 53 ++++++++++++++++++++++++ doc/{ => img}/demo.gif | Bin doc/img/logo.png | Bin 0 -> 3102 bytes doc/index.rst | 35 ++++++++++++++++ doc/usage.rst | 90 +++++++++++++++++++++++++++++++++++++++++ 7 files changed, 198 insertions(+), 1 deletion(-) create mode 100644 doc/Makefile create mode 100644 doc/conf.py rename doc/{ => img}/demo.gif (100%) create mode 100644 doc/img/logo.png create mode 100644 doc/index.rst create mode 100644 doc/usage.rst diff --git a/README.md b/README.md index d9a58a1..075e7a0 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ For example, when it receives network packets: * **masscanned** answers to `TCP SYN` (any port) with `TCP SYN/ACK` on any port, * **masscanned** answers to `HTTP` requests (any verb) over `TCP/UDP` (any port) with a `HTTP 401` web page. -![demo](doc/demo.gif) +![demo](doc/img/demo.gif) **Masscanned** currently supports most common protocols at layers 2-3-4, and a few application protocols: diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..5128596 --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,19 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 0000000..bbedcb5 --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,53 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +from ast import literal_eval +import configparser +import os + +# -- Path setup -------------------------------------------------------------- + +# -- Project information ----------------------------------------------------- + +project = "IVRE" +copyright = "2021, The IVRE project" +html_logo = "img/logo.png" +master_doc = "index" + +def parse_cargo(): + config = configparser.ConfigParser() + config.read(os.path.join("..", "Cargo.toml")) + if "package" not in config: + return None, None, None + package = config["package"] + try: + author = literal_eval(package.get("authors"))[0].split("<", 1)[0].strip() + except KeyError: + authors = None + return literal_eval(package.get("name")), author, literal_eval(package.get("version")) + +project, author, version = parse_cargo() + +# -- General configuration --------------------------------------------------- + +extensions = [] + +autosectionlabel_prefix_document = True + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "sphinx_rtd_theme" diff --git a/doc/demo.gif b/doc/img/demo.gif similarity index 100% rename from doc/demo.gif rename to doc/img/demo.gif diff --git a/doc/img/logo.png b/doc/img/logo.png new file mode 100644 index 0000000000000000000000000000000000000000..b9b5199bbfda4420a774c2d422ac55adef546bbf GIT binary patch literal 3102 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 but can be used independently. + +The code is on `GitHub `_. + +Here is a quick demo: + +|demo| + +Status of this documentation +---------------------------- + +This documentation is a work in progress! + +Content +------- + +.. toctree:: + :maxdepth: 3 + :caption: Usage: + :glob: + + usage + + +.. |demo| image:: img/demo.gif diff --git a/doc/usage.rst b/doc/usage.rst new file mode 100644 index 0000000..60e11f0 --- /dev/null +++ b/doc/usage.rst @@ -0,0 +1,90 @@ +Using Masscanned +================ + +Dedicated addresses +~~~~~~~~~~~~~~~~~~~ + +Masscanned is designed to handle its own IP addresses, which means +that the host should not have those addresses configures, and +Masscanned will answer ARP requests (or ICMPv6 ND neighbor +solicitations). + +The host may have one or more (IPv4 and/or IPv6) addresses configured +on an interface also used by Masscanned, but those addresses must be +different from those configured to be used by Masscanned. + +In that situation (dedicated addresses), just run: + +:: + + # masscanned -i -f + + +Addresses shared with the host +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sometimes it is desirable to have an IP address used by the host +(e.g., for administration tasks) and by Masscanned (to handle all +other incoming packets). + +Since this is not implemented in Masscanned, a tiny hack is needed: we +are going to run Masscanned on a ``veth`` interface. + +For this example, we suppose: + +- The interface is ``eth0``, the address is ``192.168.0.10``. +- We want Masscanned to handle all the traffic except for incoming SSH + connections on TCP/22 port. + +We create a ``veth`` pair of interfaces, on which we are going to use +the 0.255.0.0/31 network (which should not be a problem since +0.0.0.0/8 is reserved as "Current Network"): + +:: + + # ip link add to_masscanned type veth peer masscanned + # ip link set masscanned up + # ip link set to_masscanned up + # ip addr add 0.255.0.0/31 dev to_masscanned + # masscanned -i masscanned + +Masscanned can now be used, but only from the host where it runs: + +:: + + # ping -c 1 0.255.0.1 + PING 0.255.0.1 (0.255.0.1) 56(84) octets de données. + 64 octets de 0.255.0.1 : icmp_seq=1 ttl=64 temps=0.442 ms + + --- statistiques ping 0.255.0.1 --- + 1 paquets transmis, 1 reçus, 0% packet loss, time 0ms + rtt min/avg/max/mdev = 0.442/0.442/0.442/0.000 ms + +Now, we are going to use Netfilter / ``iptables`` to redirect incoming +traffic to Masscanned: + +:: + + # sysctl -w net.ipv4.ip_forward=1 + # iptables -t nat -A PREROUTING -i eth0 -d 192.168.0.10 -p tcp --dport 22 -j ACCEPT + # iptables -t nat -A PREROUTING -i eth0 -d 192.168.0.10/32 -j DNAT --to-destination 0.255.0.1 + +And, from another host on the 192.168.0.0/24 network: + +:: + + # ping -c 1 192.168.0.10 + PING 192.168.0.10 (192.168.0.10) 56(84) octets de données. + 64 octets de 192.168.0.10 : icmp_seq=1 ttl=63 temps=0.366 ms + + --- statistiques ping 192.168.0.10 --- + 1 paquets transmis, 1 reçus, 0% packet loss, time 0ms + rtt min/avg/max/mdev = 0.366/0.366/0.366/0.000 ms + + +The Masscanned output: + +:: + + WARN - ARP-Reply to ea:c0:d6:20:0c:6a for IP 0.255.0.1 + WARN - ICMP-Echo-Reply to ICMP-Echo-Request