Merge branch 'master' into all-contributors/add-cmnatic

Updated README to include instructions on building the new Dockerfile

.all-contributorsrc

@@ -68,12 +68,6 @@
       ]
     },
     {
-      "login": "Atul9",
-      "name": "Atul Bhosale",
-      "avatar_url": "https://avatars1.githubusercontent.com/u/3390330?v=4",
-      "profile": "https://github.com/Atul9",
-      "contributions": [
-        "doc"
       "login": "royharoush",
       "name": "royharoush",
       "avatar_url": "https://avatars3.githubusercontent.com/u/8113056?v=4",
@@ -82,6 +76,45 @@
         "ideas",
         "design"
       ]
+    },
+    {
+      "login": "Atul9",
+      "name": "Atul Bhosale",
+      "avatar_url": "https://avatars1.githubusercontent.com/u/3390330?v=4",
+      "profile": "https://github.com/Atul9",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "TGotwig",
+      "name": "Thomas Gotwig",
+      "avatar_url": "https://avatars0.githubusercontent.com/u/30773779?v=4",
+      "profile": "https://tgotwig.me",
+      "contributions": [
+        "platform"
+      ]
+    },
+    {
+      "login": "remigourdon",
+      "name": "Rémi Gourdon",
+      "avatar_url": "https://avatars3.githubusercontent.com/u/2874133?v=4",
+      "profile": "https://github.com/remigourdon",
+      "contributions": [
+        "doc",
+        "code"
+      ]
+    },
+    {
+      "login": "cmnatic",
+      "name": "Ben (CMNatic)",
+      "avatar_url": "https://avatars3.githubusercontent.com/u/4163116?v=4",
+      "profile": "https://cmnatic.co.uk",
+      "contributions": [
+        "code",
+        "doc",
+        "design"
+      ]
     }
   ],
   "contributorsPerLine": 7,

Cargo.lock

@@ -663,9 +663,9 @@ checksum = "26412eb97c6b088a6997e05f69403a802a92d520de2f8e63c2b65f9e0f47c4e8"
 
 [[package]]
 name = "rlimit"
-version = "0.3.0"
+version = "0.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e6d26e65e82a1e2628c5f209ec12f4508fa50e644bd2f264138e60129d61eae8"
+checksum = "49b02d62c38353a6fce45c25ca19783e25dd5f495ca681c674a4ee15aa4c1536"
 dependencies = [
  "cfg-if",
  "libc",

Cargo.toml

@@ -18,7 +18,7 @@ colored = "2.0.0"
 structopt = "0.3.16"
 async-std = "1.6.2"
 futures = "0.3"
-rlimit = "0.3.0"
+rlimit = "0.4.0"
 shell-words = "1.0.0"
 log = "0.4.0"
 env_logger = "0.7.1"

Dockerfile

@@ -0,0 +1,22 @@
+FROM rust:alpine as builder
+RUN apk update && \
+    apk add build-base && \
+    rm -rf /var/cache/apk/*
+
+WORKDIR /usr/src/rustscan
+COPY . .
+RUN cargo install --path .
+
+FROM alpine
+LABEL author="Hydragyrum <https://github.com/Hydragyrum>"
+RUN ulimit -n 100000 && \
+    apk update && \
+    apk add \
+    nmap nmap-scripts wget \
+    && \
+    rm -rf /var/cache/apk/*
+COPY --from=builder /usr/local/cargo/bin/rustscan /usr/local/bin/rustscan
+RUN addgroup -S rustscan && \
+    adduser -S -G rustscan rustscan
+USER rustscan
+ENTRYPOINT ["/usr/local/bin/rustscan"]

Makefile

@@ -0,0 +1,21 @@
+install:
+	cargo install cross
+
+build:
+	make build-linux
+	make build-mac
+
+	make shasum
+
+build-linux:
+	@echo 'Building for Linux... 🐧'
+	cross build --release --target=x86_64-unknown-linux-musl
+	mkdir -p target/release-archives && tar -czf target/release-archives/rustscan-linux.tar.gz target/x86_64-unknown-linux-musl/release/rustscan 
+
+build-mac:
+	@echo 'Building for MacOS... 🍏'
+	cross build --release --target=x86_64-apple-darwin
+	mkdir -p target/release-archives && tar -czf target/release-archives/rustscan-mac.tar.gz target/x86_64-apple-darwin/release/rustscan
+
+shasum:
+	shasum -a 256 target/release-archives/rustscan-*.tar.gz

README.md

@@ -1,5 +1,5 @@
 <p align="center">
-➡️ 
+➡️
 <a href="https://discord.gg/GFrQsGy">Discord</a> |
  <a href="https://github.com/RustScan/RustScan#-full-installation-guide">Installation Guide</a> |
  <a href="https://github.com/RustScan/RustScan#-usage">Usage Guide</a>
@@ -8,7 +8,7 @@
 <img src="pictures/rustscan.png">
 </p>
 <p align="center">
-<u><b> Turns a 17 minutes Nmap scan into 19 seconds. </b></u><br> Find all open ports <b>fast</b> with RustScan, automatically pipe them into Nmap. 
+<u><b> Turns a 17 minutes Nmap scan into 19 seconds. </b></u><br> Find all open ports <b>fast</b> with RustScan, automatically pipe them into Nmap.
 </p>
 <p align="center">
 <img alt="AUR version" src="https://img.shields.io/aur/version/rustscan-bin">
@@ -98,7 +98,7 @@ The easiest way to install RustScan is to use one of the packages provided for y
 
 The most universal way is to use `cargo`, Rust's built in package manager (think Pip but for Rust). [Follow this guide to installing Rust & Cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html).
 
-If you face any issues at all, please leave a GitHub issue. I have only tested this on Linux, so there may be issues for Mac OS or Windows. 
+If you face any issues at all, please leave a GitHub issue. I have only tested this on Linux, so there may be issues for Mac OS or Windows.
 
 Note: sometimes Rust doesn't add Cargo to the path. Please see [this issue](https://github.com/rust-lang/rustup/issues/2436) for how to fix that.
 
@@ -108,7 +108,7 @@ Download the .deb file from the releases page:
 
 [https://github.com/brandonskerritt/RustScan/releases](https://github.com/brandonskerritt/RustScan/releases)
 
-Run the commpand `dpkg -i` on the file. 
+Run the commpand `dpkg -i` on the file.
 
 Note: sometimes you can double click the file to achieve the same result.
 
@@ -122,7 +122,9 @@ Docker is the recommended way of installing RustScan. This is because:
 
 To install Docker, [follow their guide](https://docs.docker.com/engine/install/).
 
-**Once Docker is installed, run this command against the IP you want to target.**
+**Once Docker is installed, you can either build your own image using the `Dockerfile` (alpine) provided in the repo, or alternatively, use the published Docker image like below (most convenient)**
+
+Simply run this command against the IP you want to target:
 
 ```
 docker run -it --rm --name rustscan cmnatic/rustscan:debian-buster rustscan 127.0.0.1
@@ -130,8 +132,6 @@ docker run -it --rm --name rustscan cmnatic/rustscan:debian-buster rustscan 127.
 
 Note: this will scan the Docker's localhost, not your own.
 
-This will download the Docker image. 
-
 Once done, you will no longer need to re-download the image (except when RustScan updates) and can use RustScan like a normal application.
 
 You will have to run this command every time, so we suggest aliasing it to something memorable.
@@ -146,6 +146,18 @@ Then we can:
 rustscan 127.0.0.1 -t 500 -b 1500 -- -A
 ```
 
+#### To build your own image:
+
+Download the repo:
+```
+git clone https://github.com/RustScan/RustScan.git
+```
+
+Build away!
+```
+docker build -t <yourimagename> .
+```
+
 ## 🍺 HomeBrew
 
 **Note for Mac users** Mac OS has a very, very small ulimit size. This will negatively impact RustScan by a significant amount. Please use the Docker container, or tell RustScan to up the ulimit size on every run.
@@ -186,43 +198,47 @@ rustscan -h
 ```
 
 ```
-RustScan 1.2.0
-Bee https://github.com/brandonskerritt
-Fast Port Scanner built in Rust
-WARNING Do not use this program against sensitive infrastructure. The specified server may not be able to handle this
-many socket connections at once.
+rustscan 1.7.1
+Fast Port Scanner built in Rust. WARNING Do not use this program against sensitive infrastructure since the specified
+server may not be able to handle this many socket connections at once. - Discord https://discord.gg/GFrQsGy - GitHub
+https://github.com/RustScan/RustScan
 
 USAGE:
-    rustscan [FLAGS] [OPTIONS] <ip> [command]...
+    rustscan [FLAGS] [OPTIONS] <ips>... [-- <command>...]
 
 FLAGS:
-    -h, --help       Prints help information
-    -q, --quiet      Quiet mode. Only output the ports. No Nmap. Useful for grep or outputting to a file.
-    -V, --version    Prints version information
+    -a, --accessible
+    -h, --help          Prints help information
+    -q, --quiet         Quiet mode. Only output the ports. No Nmap. Useful for grep or outputting to a file
+    -V, --version       Prints version information
 
 OPTIONS:
-    -T, --timeout <T>    The timeout before a port is assumed to be close. In MS. [default: 1500]
-    -b, --batch <b>      Increases speed of scanning. The batch size for port scanning. Depends on your open file limit
-                         of OS. If you do 65535 it will do every port at the same time. Although, your OS may not
-                         support this. [default: 4500]
-    -u, --ulimit <u>     Automatically ups the ULIMIT with the value you provided.
+    -b, --batch-size <batch-size>    The batch size for port scanning, it increases or slows the speed of scanning.
+                                     Depends on the open file limit of your OS.  If you do 65535 it will do every port
+                                     at the same time. Although, your OS may not support this [default: 4500]
+        --scan-order <scan-order>    The order of scanning to be performed. The "serial" option will scan ports in
+                                     ascending order while the "random" option will scan ports randomly [default:
+                                     serial]  [possible values: Serial, Random]
+    -t, --timeout <timeout>          The timeout in milliseconds before a port is assumed to be closed [default: 1500]
+    -u, --ulimit <ulimit>            Automatically ups the ULIMIT with the value you provided
 
 ARGS:
-    <ip>            The IP address to scan
-    <command>...    The Nmap arguments to run. To use the argument -A, end RustScan's args with '-- -A'. To run
-                    EXAMPLE: 'rustscan -T 1500 127.0.0.1 -- -A -sC'. This argument auto runs nmap {your commands}
-                    -vvv -p $PORTS 
+    <ips>...        A list of comma separated IP addresses to be scanned
+    <command>...    The Nmap arguments to run. To use the argument -A, end RustScan's args with '-- -A'. Example:
+                    'rustscan -T 1500 127.0.0.1 -- -A -sC'. This command adds -Pn -vvv -p $PORTS automatically to
+                    nmap. For things like --script '(safe and vuln)' enclose it in quotations marks \"'(safe and
+                    vuln)'\"")
 ```
 
 The format is `rustscan -b 500 -T 1500 192.168.0.1` to scan 192.168.0.1 with 500 batch size with a timeout of 1500ms. The timeout is how long RustScan waits for a response until it assumes the port is closed.
 
-The batch size determines how fast RustScan is. Set it to 65k, and it will scan all 65k ports at the same time. This means at at 65k batch size, RustScan will take TIMEOUT long to scan all ports. Essentially, if timeout is 1000ms, **RustScan can scan in 1 second**. 
+The batch size determines how fast RustScan is. Set it to 65k, and it will scan all 65k ports at the same time. This means at at 65k batch size, RustScan will take TIMEOUT long to scan all ports. Essentially, if timeout is 1000ms, **RustScan can scan in 1 second**.
 
 Your operating system may not support this, but it is worth it to play around and see where your open file limit is. Shortly I will be releasing a dockerised version with a much larger open file limit, so this will be possible.
 
 ## ⚠️ WARNING
 
-This program, by default, scans 5000 ports at a time (5000 per second). 
+This program, by default, scans 5000 ports at a time (5000 per second).
 
 This may cause damage to a server, or may make it incredibly obvious you are scanning the server.
 
@@ -245,7 +261,7 @@ This limit changes from OS to OS.
 
 RustScan does not automatically create defaults (other than 5000) like Nmap does with their -T1, -T2 system.
 
-By figuring out for yourself the optimal batch size, you will know that RustScan is the most optimised port scanner for your system. 
+By figuring out for yourself the optimal batch size, you will know that RustScan is the most optimised port scanner for your system.
 
 There are 2 things you can do:
 1. Decrease batch size
@@ -274,16 +290,16 @@ ulimit -n 5000
 ```
 
 **Mac OS**
-Mac OS has, from what I can tell, a naturally very low open file descriptor limit. The limit for Ubuntu is 8800. The limit for Mac OS is 255! 
+Mac OS has, from what I can tell, a naturally very low open file descriptor limit. The limit for Ubuntu is 8800. The limit for Mac OS is 255!
 
-In this case, I would say it is safe to increase the open file limit. As most Linux based OS' have limits in the thousands. 
+In this case, I would say it is safe to increase the open file limit. As most Linux based OS' have limits in the thousands.
 
-Although, if this breaks anything, please don't blame me. 
+Although, if this breaks anything, please don't blame me.
 
 **Windows Subsystem for Linux**
-Windows Subsystem for Linux does not support ulimit (see issue #39). 
+Windows Subsystem for Linux does not support ulimit (see issue #39).
 
-The best way is to use it on a host computer, in Docker, or in a VM that isn't WSL. 
+The best way is to use it on a host computer, in Docker, or in a VM that isn't WSL.
 
 **Automatic Ulimit updating**
 We are currently working on automatic Ulimit updating. If it is too high, it will lower itself. If it is too low, it will suggest a higher Ulimit. Watch [this issue](https://github.com/brandonskerritt/RustScan/issues/25) for more.
@@ -291,7 +307,7 @@ We are currently working on automatic Ulimit updating. If it is too high, it wil
 ## 🔌 Nmap Custom Flags
 To run your own nmap commands, end the RustScan command with `-- -A` where `--` indicates "end of RustScan flags, please do not parse anything further" and any flags after that will be entered into nmap.
 
-RustScan automatically runs `nmap -vvv -p $PORTS $IP`. To make it run `-A`, execute the command `rustscan 127.0.0.1 -- -A`. 
+RustScan automatically runs `nmap -vvv -p $PORTS $IP`. To make it run `-A`, execute the command `rustscan 127.0.0.1 -- -A`.
 
 If you want to run commands such as `--script (vuln and safe)`, you will need to enclose it in quotations like so `--script '"(vuln and safe) or default"'`.
 
@@ -320,7 +336,7 @@ TL;DR if you abuse members of our community you will be **perma-banned** 🤗
 
 RustScan has 2 major labels for GitHub issues you should look at:
 * Good First issue
-These are issues for newcomers to open source! 
+These are issues for newcomers to open source!
 [https://github.com/RustScan/RustScan/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22](https://github.com/RustScan/RustScan/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)
 * Help wanted
 These are issues that aren't really for newcomers, but we could still do wiht help!
@@ -349,7 +365,7 @@ Please read the [contributing.md file](contributing.md)
 
 ## Contributors ✨
 <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
-[![All Contributors](https://img.shields.io/badge/all_contributors-7-orange.svg?style=flat-square)](#contributors-)
+[![All Contributors](https://img.shields.io/badge/all_contributors-11-orange.svg?style=flat-square)](#contributors-)
 <!-- ALL-CONTRIBUTORS-BADGE:END -->
 
 Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
@@ -365,9 +381,14 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
     <td align="center"><a href="http://bernardoamc.github.io/"><img src="https://avatars0.githubusercontent.com/u/428984?v=4" width="100px;" alt=""/><br /><sub><b>Bernardo Araujo</b></sub></a><br /><a href="https://github.com/RustScan/RustScan/commits?author=bernardoamc" title="Code">💻</a> <a href="https://github.com/RustScan/RustScan/issues?q=author%3Abernardoamc" title="Bug reports">🐛</a> <a href="#design-bernardoamc" title="Design">🎨</a></td>
     <td align="center"><a href="https://github.com/Isona"><img src="https://avatars2.githubusercontent.com/u/11759523?v=4" width="100px;" alt=""/><br /><sub><b>Izzy Whistlecroft</b></sub></a><br /><a href="https://github.com/RustScan/RustScan/issues?q=author%3AIsona" title="Bug reports">🐛</a></td>
     <td align="center"><a href="https://imlonghao.com"><img src="https://avatars1.githubusercontent.com/u/4951333?v=4" width="100px;" alt=""/><br /><sub><b>imlonghao</b></sub></a><br /><a href="https://github.com/RustScan/RustScan/issues?q=author%3Aimlonghao" title="Bug reports">🐛</a> <a href="#maintenance-imlonghao" title="Maintenance">🚧</a></td>
-    <td align="center"><a href="https://github.com/Atul9"><img src="https://avatars1.githubusercontent.com/u/3390330?v=4" width="100px;" alt=""/><br /><sub><b>Atul Bhosale</b></sub></a><br /><a href="https://github.com/RustScan/RustScan/commits?author=Atul9" title="Documentation">📖</a></td>
     <td align="center"><a href="https://github.com/royharoush"><img src="https://avatars3.githubusercontent.com/u/8113056?v=4" width="100px;" alt=""/><br /><sub><b>royharoush</b></sub></a><br /><a href="#ideas-royharoush" title="Ideas, Planning, & Feedback">🤔</a> <a href="#design-royharoush" title="Design">🎨</a></td>
   </tr>
+  <tr>
+    <td align="center"><a href="https://github.com/Atul9"><img src="https://avatars1.githubusercontent.com/u/3390330?v=4" width="100px;" alt=""/><br /><sub><b>Atul Bhosale</b></sub></a><br /><a href="https://github.com/RustScan/RustScan/commits?author=Atul9" title="Code">💻</a></td>
+    <td align="center"><a href="https://tgotwig.me"><img src="https://avatars0.githubusercontent.com/u/30773779?v=4" width="100px;" alt=""/><br /><sub><b>Thomas Gotwig</b></sub></a><br /><a href="#platform-TGotwig" title="Packaging/porting to new platform">📦</a></td>
+    <td align="center"><a href="https://github.com/remigourdon"><img src="https://avatars3.githubusercontent.com/u/2874133?v=4" width="100px;" alt=""/><br /><sub><b>Rémi Gourdon</b></sub></a><br /><a href="https://github.com/RustScan/RustScan/commits?author=remigourdon" title="Documentation">📖</a> <a href="https://github.com/RustScan/RustScan/commits?author=remigourdon" title="Code">💻</a></td>
+    <td align="center"><a href="https://cmnatic.co.uk"><img src="https://avatars3.githubusercontent.com/u/4163116?v=4" width="100px;" alt=""/><br /><sub><b>Ben (CMNatic)</b></sub></a><br /><a href="https://github.com/RustScan/RustScan/commits?author=cmnatic" title="Code">💻</a> <a href="https://github.com/RustScan/RustScan/commits?author=cmnatic" title="Documentation">📖</a> <a href="#design-cmnatic" title="Design">🎨</a></td>
+  </tr>
 </table>
 
 <!-- markdownlint-enable -->

src/main.rs

@@ -134,7 +134,7 @@ fn main() {
 
         let x = format!("{} Looks like I didn't find any open ports for {:?}. This is usually caused by a high batch size.
         \n*I used {} batch size, consider lowering to {} with {} or a comfortable number for your system.
-        \n Alternatively, increase the timeout if your ping is high. Rustscan -T 2000 for 2000 second timeout.\n",
+        \n Alternatively, increase the timeout if your ping is high. Rustscan -t 2000 for 2000 second timeout.\n",
         "ERROR",
         ip,
         opts.batch_size,

src/port_strategy/mod.rs

@@ -2,6 +2,10 @@ mod range_iterator;
 use super::ScanOrder;
 use range_iterator::RangeIterator;
 
+/// Represents options of port scanning.
+///
+/// Right now all these options involve ranges, but in the future
+/// it will also contain custom lists of ports.
 pub enum PortStrategy {
     Serial(SerialRange),
     Random(RandomRange),
@@ -23,10 +27,14 @@ impl PortStrategy {
     }
 }
 
+/// Trait associated with a port strategy. Each PortStrategy must be able
+/// to generate an order for future port scanning.
 trait RangeOrder {
     fn generate(&self) -> Vec<u16>;
 }
 
+/// As the name implies SerialRange will always generate a vector in
+/// ascending order.
 pub struct SerialRange {
     start: u16,
     end: u16,
@@ -38,12 +46,23 @@ impl RangeOrder for SerialRange {
     }
 }
 
+/// As the name implies RandomRange will always generate a vector with
+/// a random order. This vector is built following the LCG algorithm.
 pub struct RandomRange {
     start: u16,
     end: u16,
 }
 
 impl RangeOrder for RandomRange {
+    // Right now using RangeIterator and generating a range + shuffling the
+    // vector is pretty much the same. The advantages of it will come once
+    // we have to generate different ranges for different IPs without storing
+    // actual vectors.
+    //
+    // Another benefit of RangeIterator is that it always generate a range with
+    // a certain distance between the items in the Array. The chances of having
+    // port numbers close to each other are pretty slim due to the way the
+    // algorithm works.
     fn generate(&self) -> Vec<u16> {
         RangeIterator::new(self.start.into(), self.end.into()).collect()
     }