# network_scanner

**Repository Path**: ChiZhung/network_scanner

## Basic Information

- **Project Name**: network_scanner
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-09-29
- **Last Updated**: 2020-12-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Network Discovery and Subnet Scanning with Python, using python-nmap library.

## Overview
提供了子网内的主机发现，与对于子网内任意网段、主机的网络扫描

## Prerequisites
python版本3+

需要安装python-nmap
```cmd
pip3 install python-nmap
```
**Troubleshooting**
- If you did pip install the libraries but you are met with the error *ModuleNotFoundError* , please try installing the libraries with apt using:
```cmd
sudo apt install python3-nmap
```

## Installment
1. 进入到network_scanner目录下，然后执行`python3 setup.py install`将本模块安装到python lib中
2. 可以直接通过执行network_scanner命令行来操作

## Uninstallment
`pip3 uninstall network_scanner`

## Help
```text
usage: network_scanner [-h] [-v--version] [-f HOSTS] [-F HOSTS] [-a ARGS]
                  [-p PORTS]

optional arguments:
  -h, --help            show this help message and exit
  -v--version           Print version then exit.
  -f HOSTS, --find-hosts=HOSTS
                        find all hosts alive in the subnet specified.
  -F HOSTS, --find-info=HOSTS
                        find all info of hosts alive in the subnet specified.
  -a ARGS, --args=ARGS  specify the user-defined args.
  -p PORTS, --ports=PORTS
                        specify the ports scanned.
```

## Running
1. 主机发现
    * 调用形式：network_scanner \<-f|--find-hosts HOSTS\> \[-a|--args ARGS\]
    * 解释：通过制定FIND_HOSTS来指定需要扫描的子网，当不使用默认的nmap扫描选项的时候，可以自己手动指定ARGS
    * 举例
        1. `network_scanner -f 127.0.0.1`
        2. `network_scanner -f 192.168.0.0/16`
        3. `network_scanner -f 192.168.0.0/16 --args='-PS'`
    * 返回格式
        1. 正常输出
        ```json5
        {
            "status": 200,  // int, require
            "data": ["192.168.0.1", "192.168.0.5"] // list<string>, require
        } 
        ```
        2. 异常输出
        ```json5
        {
            "status": 400,  // int, require
            "err_msg": "Internal Error." // string
        } 
        ```
    * 注意：
        * 由于使用命令行，返回的结果直接输出到stdout，对于一些辅助的信息，比如进度之类的是输出到stderr中的
2. 网络基本信息扫描
    * 调用形式：network_scanner \<-F|--find-info HOSTS\> \[-p|--ports PORTS\] \[-a|--args ARGS\]
    * 解释：通过制定HOSTS来指定需要扫描的子网，可选指定ports表明扫描的端口，当不使用默认的nmap扫描选项的时候，可以自己手动指定ARGS
    * 举例
        1. `network_scanner -F 127.0.0.1`
        2. `network_scanner --find-info=192.168.0.0/16 -p 80-1024`
        3. `network_scanner -F 192.168.0.0/16 -p 80,443 --args='-sV'`
    * 返回格式
        1. 正常输出
        ```json5
        {
            "status": 200,  // int, require
            "data": [ // dict, require
                // 可能返回的list是空的
                {
                    "host": "192.168.220.1",
                    "mac": "00:50:56:C0:00:08",
                    "vendor": "VMware",
                    "status": "up"
                }, 
                {
                    "host": "192.168.220.128", // str, require
                    "status": "up", // str, require, [up, down]
                    "uptime": "3748789s", // str, optional, 单位s
                    "tcp": {  // dict, optional
                        "service": "ssh", // str, optional
                        "service-version": "8.3p1 Debian 1",  // str, optional
                        "service-port": 22, // str, optional
                        "service-status": "open", // str, optional
                        "service-product": "OpenSSH"  // str, optional
                    },
                    "udp": { // dict, optional
                        // 格式同tcp
                    },
                    "os-name": "Linux 2.6.32", // str, optional
                    "cpe": [{ // list, optional
                        "type": "general purpose",
                        "cpe": "cpe:/o:linux:linux_kernel:2.6.32"
                    }]
                }, 
                {
                    "host": "192.168.220.2",
                    "mac": "00:50:56:E8:67:5D",
                    "vendor": "VMware",
                    "status": "up",
                    "tcp": {
                        "service": "domain",
                        "service-port": 53,
                        "service-status": "open",
                        "service-product": "ISC BIND"
                    },
                    "os-name": "VMware Player virtual NAT device",
                    "cpe": [{
                        "type": "specialized",
                        "cpe": "cpe:/a:vmware:player"
                    }]
	            },
                {
                    "host": "192.168.220.254",
                    "mac": "00:50:56:F5:BD:08",
                    "vendor": "VMware",
                    "status": "up"
                }
            ]    
        } 
        ```
        2. 异常输出
        ```json5
        {
            "status": 400,  // int, require
            "err_msg": "Internal Error." // string
        } 
        ```
    * 注意：
        * 由于使用命令行，返回的结果直接输出到stdout，对于一些辅助的信息，比如进度之类的是输出到stderr中的

## Advice
建议在应用侧加一个cache，使用LRU+TTL的策略，若查询命中且没有超过ttl，则直接从cache中返回结果，否则走network_scanner,
然后数据再填入cache中