pistol-rs

The library must be run as root (Linux, *BSD) or administrator (Windows), the stable version of rust is recommended.

Import from crates.io

[dependencies]
pistol = "^3"

On Windows, download winpcap here or npcap here SDK, then place Packet.lib from the Lib/x64 folder in your root of code (Note: the npcap did not test by libpnet according to the doc of libpnet).

Cross Platform Support

libpnet bug on Windows

Bug issues: https://github.com/libpnet/libpnet/issues/707, the libpnet cannot get IPv6 address on Windows.

Therefore, until libpnet fixes this bug, IPv6 on Windows is not supported yet.

libpnet bug on rust nightly version

Bug issue: https://github.com/libpnet/libpnet/issues/686

Host Discovery (Ping Scanning)

The implementation of the `pistol' host discovery according to the nmap documentation.

Port Scanning Techniques and Algorithms

The implementation of the pistol port scan according to the nmap pdf and documentation.

Flood Attack

Remote OS Detection

OS Detection on IPv6?

On ipv6, the fingerprints are unreadable and meaningless to humans, see here for details, and nmap uses logistic regression to match target OS on ipv6, but the matching algorithm is quite outdated with confusing design logic.

The first is about the ST, RT and EXTRA metrics in fingerprints in detection on ipv6, these three metrics are not used at all in the code, at the same time, there is no detailed description of how ST and RT are calculated, I don't know why nmap would keep them in the final fingerprint.

The second is NI probes. In the relevant document of nmap, it describes the specific structure of NI probe, but I don't see anything about it in the code, and it seems to completely ignore this probe when do predict use logistic regression.

Furthermore, for the current mainstream operating systems, ipv6 fingerprint support is not as rich as ipv4, so try the ipv4 first.

Service and Application Version Detection

Debugs

use pistol::Logger;

fn main() {
    let _ = Logger::init_debug_logging();
    // let _ = Logger::init_warn_logging();
    // your code below
    ...
}

Examples

0. Create the Target

Now you can include both IPv4 and IPv6 addresses in the Target when create the scan target, and pistol will automatically invoke the corresponding algorithm to handle it.

However, please note that some algorithms can only work with certain protocols, e.g. Idel scan can only be used with IPv4, if it is used with IPv6 it will do nothing and show a warning message.

use pistol::Target;
use pistol::Host;
use std::net::Ipv4Addr;
use std::net::Ipv6Addr;

fn main() {
    let dst_ipv4 = Ipv4Addr::new(192, 168, 72, 134);
    let host1 = Host::new(dst_ipv4.into(), Some(vec![22, 99]));
    let dst_ipv6 = Ipv6Addr::new(0xfe80, 0, 0, 0, 0x020c, 0x29ff, 0xfeb6, 0x8d99);
    let host2 = Host::new(dst_ipv6.into(), Some(vec![443, 8080]));
    let target = Target::new(vec![host1, host2]);
    // your code below
    ...
}

If you don't want to use Target, you can also use the _raw functions we provide, for example, the corresponding raw function for tcp_syn_scan is tcp_syn_scan_raw.

Note that the _raw function is blocking.

1. SYN Port Scan Example

use pistol::scan::tcp_syn_scan;
use pistol::Target;
use pistol::Host;
use std::net::Ipv4Addr;
use std::time::Duration;
use subnetwork::CrossIpv4Pool;

fn main() {
    // When using scanning, please use a real local address to get the return packet.
    // And for flood attacks, please consider using a fake address.
    // If the value here is None, the programme will automatically look up the available addresses from the existing interfaces on the device.
    // In some complex network environments, if the program cannot automatically identify the source IP address, you can set the source IP address manually here.
    let src_ipv4 = None;
    // If the value of `source port` is `None`, the program will generate the source port randomly.
    let src_port = None;
    let timeout = Some(Duration::new(1, 0));
    let start = Ipv4Addr::new(192, 168, 5, 1);
    let end = Ipv4Addr::new(192, 168, 5, 10);
    // The destination address is from 192.168.5.1 to 192.168.5.10.
    let subnet = CrossIpv4Pool::new(start, end).unwrap();
    let mut hosts = vec![];
    for ip in subnet {
        // Test with a example port `22`
        let host = Host::new(ip.into(), Some(vec![22]));
        hosts.push(host);
    }
    let target = Target::new(hosts);
    // Number of tests
    let tests = 2;
    let ret = tcp_syn_scan(
        target,
        src_ipv4,
        src_port,
        timeout,
        tests
    ).unwrap();
    println!("{}", ret);
}

Output

+-----------+--------------+-----------+--------------------------------------------+-----------+
|                                    Scan Results (tests:2)                                     |
+-----------+--------------+-----------+--------------------------------------------+-----------+
|    id     |     addr     |   port    |                   status                   | avg cost  |
+-----------+--------------+-----------+--------------------------------------------+-----------+
|     1     | 192.168.5.1  |    22     | OP(0)OF(0)F(2)UF(0)C(0)UR(0)CF(0)E(0)OL(0) | 1061.39ms |
+-----------+--------------+-----------+--------------------------------------------+-----------+
|     2     | 192.168.5.2  |    22     | OP(0)OF(0)F(0)UF(0)C(2)UR(0)CF(0)E(0)OL(0) |  74.26ms  |
+-----------+--------------+-----------+--------------------------------------------+-----------+
|     3     | 192.168.5.3  |    22     | OP(0)OF(0)F(0)UF(0)C(0)UR(0)CF(0)E(0)OL(2) | 1079.59ms |
+-----------+--------------+-----------+--------------------------------------------+-----------+
|     4     | 192.168.5.4  |    22     | OP(0)OF(0)F(0)UF(0)C(0)UR(0)CF(0)E(0)OL(2) | 1077.55ms |
+-----------+--------------+-----------+--------------------------------------------+-----------+
|     5     | 192.168.5.5  |    22     | OP(0)OF(0)F(0)UF(0)C(0)UR(0)CF(0)E(0)OL(2) | 1094.39ms |
+-----------+--------------+-----------+--------------------------------------------+-----------+
|     6     | 192.168.5.6  |    22     | OP(0)OF(0)F(0)UF(0)C(0)UR(0)CF(0)E(0)OL(2) | 1093.97ms |
+-----------+--------------+-----------+--------------------------------------------+-----------+
|     7     | 192.168.5.7  |    22     | OP(0)OF(0)F(0)UF(0)C(0)UR(0)CF(0)E(0)OL(2) | 1093.10ms |
+-----------+--------------+-----------+--------------------------------------------+-----------+
|     8     | 192.168.5.8  |    22     | OP(0)OF(0)F(0)UF(0)C(0)UR(0)CF(0)E(0)OL(2) | 1093.42ms |
+-----------+--------------+-----------+--------------------------------------------+-----------+
|     9     | 192.168.5.9  |    22     | OP(0)OF(0)F(0)UF(0)C(0)UR(0)CF(0)E(0)OL(2) | 1090.77ms |
+-----------+--------------+-----------+--------------------------------------------+-----------+
|    10     | 192.168.5.10 |    22     | OP(0)OF(0)F(0)UF(0)C(0)UR(0)CF(0)E(0)OL(2) | 1089.91ms |
+-----------+--------------+-----------+--------------------------------------------+-----------+
| NOTE:                                                                                         |
| OP: OPEN, OF: OPEN_OR_FILTERED, F: FILTERED,                                                  |
| UF: UNFILTERED, C: CLOSED, UR: UNREACHABLE,                                                   |
| CF: CLOSE_OF_FILTERED, E: ERROR, OL: OFFLINE.                                                 |
+-----------+--------------+-----------+--------------------------------------------+-----------+
| total used time: 1177.12ms                                                                    |
| avg time cost: 984.83ms                                                                       |
| open ports: 0                                                                                 |
+-----------+--------------+-----------+--------------------------------------------+-----------+

Or

use pistol::scan::tcp_syn_scan_raw;
use std::net::Ipv4Addr;
use std::time::Duration;

fn main() {
    let dst_ipv4 = Ipv4Addr::new(192, 168, 5, 1);
    let dst_port = 80;
    let src_ipv4 = None;
    let src_port = None;
    let timeout = Some(Duration::new(1, 0));
    let (port_status, _time_cost) = tcp_syn_scan_raw(dst_ipv4.into(), dst_port, src_ipv4, src_port, timeout).unwrap();
    println!("{:?}", port_status);
}

2. Remote OS Detect Example

The test target server is ubuntu 22.04 server.

use pistol::os::os_detect;
use pistol::Target;
use pistol::Host;
use std::net::Ipv4Addr;
use std::time::Duration;

fn main() {
    // If the value of `src_ipv4` is `None`, the program will find it auto.
    let src_ipv4 = None;
    let dst_ipv4 = Ipv4Addr::new(192, 168, 5, 133);
    // `dst_open_tcp_port` must be a certain open tcp port.
    let dst_open_tcp_port = 22;
    // `dst_closed_tcp_port` must be a certain closed tcp port.
    let dst_closed_tcp_port = 8765;
    // `dst_closed_udp_port` must be a certain closed udp port.
    let dst_closed_udp_port = 9876;
    let host = Host::new(
        dst_ipv4.into(),
        Some(vec![
            dst_open_tcp_port,   // The order of these three ports cannot be disrupted.
            dst_closed_tcp_port,
            dst_closed_udp_port,
        ]),
    );
    let target = Target::new(vec![host]);
    let timeout = Some(Duration::new(3, 0));
    let top_k = 3;

    // The `fingerprint` is the obtained fingerprint of the target OS.
    // Return the `top_k` best results (the number of os detect result may not equal to `top_k`), sorted by score.
    let ret = os_detect(
        target,
        src_ipv4,
        top_k,
        timeout,
    ).unwrap();
    println!("{}", ret);
}

output

+------+---------------+------+--------+-----------------------+-------------------------------------------------------------------+
|                                                        OS Detect Results                                                         |
+------+---------------+------+--------+-----------------------+-------------------------------------------------------------------+
|  id  |     addr      | rank | score  |        details        |                                cpe                                |
+------+---------------+------+--------+-----------------------+-------------------------------------------------------------------+
|  1   | 192.168.5.133 |  #1  | 75/101 |   Linux 4.15 - 5.6    | cpe:/o:linux:linux_kernel:4 auto|cpe:/o:linux:linux_kernel:5 auto |
+------+---------------+------+--------+-----------------------+-------------------------------------------------------------------+
|  2   | 192.168.5.133 |  #2  | 75/101 |    Linux 5.0 - 5.3    |                 cpe:/o:linux:linux_kernel:5 auto                  |
+------+---------------+------+--------+-----------------------+-------------------------------------------------------------------+
|  3   | 192.168.5.133 |  #3  | 74/101 |       Linux 5.4       |                cpe:/o:linux:linux_kernel:5.4 auto                 |
+------+---------------+------+--------+-----------------------+-------------------------------------------------------------------+
|  4   | 192.168.5.133 |  #4  | 68/101 | Linux 2.6.24 - 2.6.36 |                cpe:/o:linux:linux_kernel:2.6 auto                 |
+------+---------------+------+--------+-----------------------+-------------------------------------------------------------------+
| total used time: 8638.91ms                                                                                                       |
| avg time cost: 8583.76ms                                                                                                         |
+------+---------------+------+--------+-----------------------+-------------------------------------------------------------------+

3. Remote OS Detect Example on IPv6

The test target server is ubuntu 22.04 server.

use pistol::os::os_detect;
use pistol::Target;
use pistol::Host;
use std::net::Ipv4Addr;
use std::time::Duration;

fn main() {
    let src_ipv6 = None;
    let dst_ipv6: Ipv6Addr = "fe80::20c:29ff:fe2c:9e4".parse().unwrap();
    let dst_open_tcp_port = 22;
    let dst_closed_tcp_port = 8765;
    let dst_closed_udp_port = 9876;
    let host = Host::new(
        dst_ipv6.into(),
        Some(vec![
            dst_open_tcp_port,
            dst_closed_tcp_port,
            dst_closed_udp_port,
        ]),
    );

    let target = Target::new(vec![host]);
    let timeout = Some(Duration::new(3, 0));
    let top_k = 3;
    let ret = os_detect(target, src_ipv6, top_k, timeout).unwrap();
    println!("{}", ret);
}

Output

+------+-------------------------+------+-------+--------------------------+---------------------------------------------------------+
|                                                         OS Detect Results                                                          |
+------+-------------------------+------+-------+--------------------------+---------------------------------------------------------+
|  id  |          addr           | rank | score |         details          |                           cpe                           |
+------+-------------------------+------+-------+--------------------------+---------------------------------------------------------+
|  1   | fe80::20c:29ff:fe2c:9e4 |  #1  |  0.9  |        Linux 4.19        |             cpe:/o:linux:linux_kernel:4.19              |
+------+-------------------------+------+-------+--------------------------+---------------------------------------------------------+
|  2   | fe80::20c:29ff:fe2c:9e4 |  #2  |  0.5  |     Linux 3.13 - 4.6     | cpe:/o:linux:linux_kernel:3 cpe:/o:linux:linux_kernel:4 |
+------+-------------------------+------+-------+--------------------------+---------------------------------------------------------+
|  3   | fe80::20c:29ff:fe2c:9e4 |  #3  |  0.0  | Android 7.1 (Linux 3.18) |                                                         |
+------+-------------------------+------+-------+--------------------------+---------------------------------------------------------+
| total used time: 10476.07ms                                                                                                        |
| avg time cost: 10474.73ms                                                                                                          |
+------+-------------------------+------+-------+--------------------------+---------------------------------------------------------+

According to the nmap documentation, the novelty value (third column in the table) must be less than 15 for the probe result to be meaningful, so when this value is greater than 15, an empty list is returned. Same when the two highest OS classes have scores that differ by less than 10%, the classification is considered ambiguous and not a successful match.

3. Remote Service Detect Example

• 192.168.1.51 - Ubuntu 22.04 (ssh: 22, httpd: 80)

use pistol::vs::vs_scan;
use pistol::vs::ExcludePorts;
use pistol::Target;
use pistol::Host;
use std::net::Ipv4Addr;
use std::time::Duration;

fn main() {
    let dst_addr = Ipv4Addr::new(192, 168, 1, 51);
    let host = Host::new(dst_addr.into(), Some(vec![22, 80]));
    let target = Target::new(vec![host]);
    let timeout = Some(Duration::new(1, 0));
    // only_null_probe = true, only_tcp_recommended = any, only_udp_recomended = any: only try the NULL probe (for TCP)
    // only_tcp_recommended = true: only try the tcp probe recommended port
    // only_udp_recommended = true: only try the udp probe recommended port
    let (only_null_probe, only_tcp_recommended, only_udp_recomended) = (false, true, true);
    let exclude_ports = Some(ExcludePorts::new(vec![51, 52]));
    let intensity = 7; // nmap default
    let ret = vs_scan(
        target,
        only_null_probe,
        only_tcp_recommended,
        only_udp_recommended,
        exclude_ports,
        intensity,
        timeout,
    )..unwrap();
    println!("{}", ret);
}

Output

+--------+---------------+--------+---------+
|           Service Scan Results            |
+--------+---------------+--------+---------+
|   id   |     addr      |  port  | service |
+--------+---------------+--------+---------+
|   1    | 192.168.5.133 |   22   |   ssh   |
+--------+---------------+--------+---------+
|   2    | 192.168.5.133 |   80   |  http   |
+--------+---------------+--------+---------+
| total used time: 22594.33ms               |
| avg time cost: 21161.98ms                 |
+--------+---------------+--------+---------+