Re-upload after passing the review, and rewrite the README to support…

… Chinese.

.gitignore

@@ -0,0 +1,21 @@
+#.gitignore
+/.vscode/
+/bin/
+/build/
+/dist/
+/doc/private/
+/res/private/
+/src/bluescan/upper/
+/src/firmware/
+/src/bluescan/poc/bugs.md
+/test/
+
+/.yotta.json
+/install.rec
+/Makefile
+/module.json
+
+__pycache__/
+
+bluescan.spec
+bluescan.egg-info

README-Chinese.md

@@ -0,0 +1,110 @@
+# bluescan：一个强大的蓝牙扫描器
+
+先前的蓝牙扫描工具都是零零散散，而且年久失修对吗？于是我们有了这个基于现代 Python 3 开发的强大蓝牙扫描器 —— bluescan。
+
+在测试新的蓝牙目标时，该扫描器可以帮助我们做好情报收集工作，比如：
+
+* BR 设备扫描
+* LE 设备扫描
+* SDP 服务扫描
+* LMP 特性扫描
+* GATT 服务扫描
+* 漏洞扫描 (demo)
+
+## 依赖
+
+bluescan 在底层基于 Linux 官方的 BlueZ 蓝牙协议栈。如下依赖的包需要被安装：
+
+```sh
+sudo apt install libglib2.0-dev libbluetooth-dev
+```
+
+当在 Linux 虚拟机中使用该工具时，建议让虚拟机独占一个搭载博通或 CSR 芯片的 USB 蓝牙适配器，比如 [Ostran 奥视通 USB 蓝牙适配器 OST-105 CSR 8150 v4.0](https://item.taobao.com/item.htm?spm=a230r.1.14.14.21b6705fm5gjj3&id=38948169460&ns=1&abbucket=6#detail)。如果你想尝试下漏洞扫描 (demo)，请参考 [ojasookert/CVE-2017-0785](https://github.com/ojasookert/CVE-2017-0785) 的 `README.md` 来解决依赖问题。
+
+## 安装
+
+最新的 bluescan 会被上传到 PyPI 上，因此执行如下命令即可安装 bluescan：
+
+```sh
+sudo pip3 install bluescan
+```
+
+## 功能和使用方法
+
+```txt
+$ bluescan -h
+bluescan v0.1.0
+
+A powerful Bluetooth scanner.
+
+Usage:
+    bluescan (-h | --help)
+    bluescan (-v | --version)
+    bluescan [-i <hcix>] -m br [--inquiry-len=<n>]
+    bluescan [-i <hcix>] -m lmp BD_ADDR
+    bluescan [-i <hcix>] -m sdp BD_ADDR
+    bluescan [-i <hcix>] -m le [--timeout=<sec>] [--le-scan-type=<type>] [--sort=<key>]
+    bluescan [-i <hcix>] -m gatt [--include-descriptor] --addr-type=<type> BD_ADDR
+    bluescan [-i <hcix>] -m vuln --addr-type=br BD_ADDR
+
+Arguments:
+    BD_ADDR    Target Bluetooth device address
+
+Options:
+    -h, --help                  Display this help
+    -v, --version               Show the version
+    -i <hcix>                   HCI device for scan [default: hci0]
+    -m <mode>                   Scan mode, support BR, LE, LMP, SDP, GATT and vuln
+    --inquiry-len=<n>           Inquiry_Length parameter of HCI_Inquiry command [default: 8]
+    --timeout=<sec>             Duration of LE scan [default: 10]
+    --le-scan-type=<type>       Active or passive scan for LE scan [default: active]
+    --sort=<key>                Sort the discovered devices by key, only support RSSI now [default: rssi]
+    --include-descriptor        Fetch descriptor information
+    --addr-type=<type>          Public, random or BR
+```
+
+### BR 设备扫描 `-m br`
+
+经典蓝牙设备可能使用三种技术：BR (Basic Rate)、EDR (Enhanced Data Rate) 以及 AMP (Alternate MAC/PHY)。由于它们都属于 Basic Rate system，因此在扫描这些设备时统称为 BR 设备扫描：
+
+![BR scan](https://github.com/fO-000/bluescan/blob/master/res/example-br-scan.png)
+
+如上图，通过 BR 设备扫描，我们可以拿到周围经典蓝牙设备的地址、名称、类型以及 RSSI。
+
+### LE 设备扫描 `-m le`
+
+蓝牙除了 Basic Rate system 就是 Low Energy (LE) system 了。当扫描周围的低功耗蓝牙设备时，称为 LE 设备扫描：
+
+![LE scan](https://github.com/fO-000/bluescan/blob/master/res/example-le-scan.png)
+
+如上图，通过 LE 扫描，我们可以拿到周围低功耗蓝牙设备的地址、地址类型、连接状态、RSSI 以及 GAP 数据。
+
+### SDP 服务扫描 `-m sdp`
+
+经典蓝牙设备通过 SDP 告诉外界自己开放的服务。通过 SDP 扫描，我们可以拿到指定经典蓝牙设备的 service record：
+
+![SDP scan](https://github.com/fO-000/bluescan/blob/master/res/example-sdp-scan.png)
+
+之后可以尝试连接这些 service，做进一步的安全测试。
+
+### LMP 特性扫描 `-m lmp`
+
+探测经典蓝牙设备的 LMP 特性，可以让我们判断目标设备底层的安全特性：
+
+![LMP scan](https://github.com/fO-000/bluescan/blob/master/res/example-lmp-scan.png)
+
+### GATT 服务扫描 `-m gatt`
+
+低功耗蓝牙设备通过 GATT 告诉外界自己开放的服务。通过 GATT 扫描，我们可以拿到指定低功耗蓝牙设备的 GATT 数据。之后可以尝试读写这些 GATT 数据，做进一步的安全测试：
+
+![GATT scan](https://github.com/fO-000/bluescan/blob/master/res/example-gatt-scan.png)
+
+### 漏洞扫描 `-m vul` (demo)
+
+漏洞扫描还处于 demo 阶段，目前仅支持 CVE-2017-0785：
+
+```txt
+$ sudo bluescan -m vuln --addr-type=br ??:??:??:??:??:??
+... ...
+CVE-2017-0785
+```

README.md

@@ -1,3 +1,112 @@
-# bluescan
+# bluescan ---- A powerful Bluetooth scanner
 
-The project will be uploaded after passing the new review.
+> This document is also available in Chinese. See [README-Chinese.md](https://github.com/fO-000/bluescan/blob/master/README-Chinese.md)
+
+Aren't the previous Bluetooth scanning tools scattered and in disrepair? So we have this powerful Bluetooth scanner based on modern Python 3 ---- bluescan.
+
+When hacking new Bluetooth targets, the scanner can help us to collect intelligence, such as:
+
+* BR devices
+* LE devices
+* LMP features
+* GATT services
+* SDP services
+* Vulnerabilities (demo)
+
+## Requirements
+
+This tool is based on BlueZ, the official Linux Bluetooth stack. The following packages need to be installed:
+
+```sh
+sudo apt install libglib2.0-dev libbluetooth-dev
+```
+
+When you play this tool in a Linux virtual machine, connecting a USB Bluetooth adapter using a Broadcom or CSR chip is recommended, like the [Ostran Bluetooth USB Adapter OST-105 CSR 8150 v4.0](https://item.taobao.com/item.htm?spm=a230r.1.14.14.21b6705fm5gjj3&id=38948169460&ns=1&abbucket=6#detail). And if you want to try the vulnerability scanning, see `README.md` of [ojasookert/CVE-2017-0785](https://github.com/ojasookert/CVE-2017-0785).
+
+## Install
+
+The lastest bluescan will be uploaded to PyPI, so the following command can install bluescan:
+
+```sh
+sudo pip3 install bluescan
+```
+
+## Usage
+
+```txt
+$ bluescan -h
+bluescan v0.1.0
+
+A powerful Bluetooth scanner.
+
+Usage:
+    bluescan (-h | --help)
+    bluescan (-v | --version)
+    bluescan [-i <hcix>] -m br [--inquiry-len=<n>]
+    bluescan [-i <hcix>] -m lmp BD_ADDR
+    bluescan [-i <hcix>] -m sdp BD_ADDR
+    bluescan [-i <hcix>] -m le [--timeout=<sec>] [--le-scan-type=<type>] [--sort=<key>]
+    bluescan [-i <hcix>] -m gatt [--include-descriptor] --addr-type=<type> BD_ADDR
+    bluescan [-i <hcix>] -m vuln --addr-type=br BD_ADDR
+
+Arguments:
+    BD_ADDR    Target Bluetooth device address
+
+Options:
+    -h, --help                  Display this help
+    -v, --version               Show the version
+    -i <hcix>                   HCI device for scan [default: hci0]
+    -m <mode>                   Scan mode, support BR, LE, LMP, SDP, GATT and vuln
+    --inquiry-len=<n>           Inquiry_Length parameter of HCI_Inquiry command [default: 8]
+    --timeout=<sec>             Duration of LE scan [default: 10]
+    --le-scan-type=<type>       Active or passive scan for LE scan [default: active]
+    --sort=<key>                Sort the discovered devices by key, only support RSSI now [default: rssi]
+    --include-descriptor        Fetch descriptor information
+    --addr-type=<type>          Public, random or BR
+```
+
+### Scan BR devices `-m br`
+
+Classic Bluetooth devices may use three technologies: BR (Basic Rate), EDR (Enhanced Data Rate), and AMP (Alternate MAC/PHY). Since they all belong to the Basic Rate system, so when scanning these devices we call them BR device scanning:
+
+![BR scan](https://github.com/fO-000/bluescan/blob/master/res/example-br-scan.png)
+
+As shown above, through BR device scanning, we can get the address, name, device type, and RSSI of the surrounding classic Bluetooth devices.
+
+### Scan LE devices `-m le`
+
+Bluetooth technology, in addition to the Basic Rate system, is Low Energy (LE) system. When scanning Bluetooth low energy devices, it is called LE device scanning:
+
+![LE scan](https://github.com/fO-000/bluescan/blob/master/res/example-le-scan.png)
+
+As shown above, through LE device scanning, we can get the address, address type, connection status, RSSI, and GAP data of the surrounding LE devices.
+
+### Scan SDP services
+
+Classic Bluetooth devices tell the outside world about their open services through SDP. After SDP scanning, we can get service records of the specified classic Bluetooth device:
+
+![SDP scan](https://github.com/fO-000/bluescan/blob/master/res/example-sdp-scan.png)
+
+You can try to connect to these services for further hacking.
+
+### Scan LMP features
+
+Detecting the LMP features of classic Bluetooth devices allows us to judge the underlying security features of the classic Bluetooth device:
+
+![LMP scan](https://github.com/fO-000/bluescan/blob/master/res/example-lmp-scan.png)
+
+### Scan GATT services
+
+LE devices tell the outside world about their open services through GATT. After GATT scanning, we can get the GATT service of the specified LE device. You can try to read and write these GATT data for further hacking:
+
+![GATT scan](https://github.com/fO-000/bluescan/blob/master/res/example-gatt-scan.png)
+
+### Vulnerabilities scanning (demo)
+
+Vulnerability scanning is still in the demo stage, and currently only supports CVE-2017-0785:
+
+```txt
+$ sudo bluescan -m vuln --addr-type=br ??:??:??:??:??:??
+... ...
+CVE-2017-0785
+```

setup.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+
+import os
+import shutil
+from pathlib import Path
+from setuptools.command.install import install
+from distutils.command.clean import clean
+from setuptools import setup, find_packages
+
+
+BLUESCAN_PATH = os.path.abspath(Path(__file__).parent)
+
+
+def read(fname):
+    return open(os.path.join(os.path.dirname(__file__), fname)).read()
+
+
+class MyInstall(install):
+    def run(self):
+        super().run()
+        print('[INFO] install bluescan_prompt.bash')
+        shutil.copy(
+            'src/bluescan/bluescan_prompt.bash', '/etc/bash_completion.d'
+        )
+
+
+class MyClean(clean):
+    def run(self):
+        super().run()
+        dirs = [
+            os.path.join(BLUESCAN_PATH, 'build'),
+            os.path.join(BLUESCAN_PATH, 'dist'),
+            os.path.join(BLUESCAN_PATH, 'src', 'bluescan.egg-info'),
+            os.path.join(BLUESCAN_PATH, 'src', 'bluescan', '__pycache__')
+        ]
+
+        for d in dirs:
+            shutil.rmtree(d, ignore_errors=True)
+
+
+if __name__ == "__main__":
+    setup(
+        name='bluescan',
+        version='0.1.0',
+        license = "BSD",
+        packages=find_packages('src'), # include all packages under src
+        package_dir={'':'src'}, # tell distutils packages are under src
+        entry_points={
+            'console_scripts': [
+                'bluescan=bluescan.__main__:main'
+            ]
+        },
+        package_data={
+            "bluescan": ["res/*.txt"]
+        },
+        #scripts=['src/bluescan/bluescan.py'],
+
+        install_requires=[
+            'pybluez>=0.23', 'bluepy>=1.3.0', 'docopt>=0.6.2', 
+            'termcolor>=1.1.0'
+        ],
+
+        # metadata to display on PyPI
+        author="fO_000",
+        author_email="[email protected]",
+        description='A powerful Bluetooth scanner for scanning BR/LE devices, LMP, SDP, GATT and vulnerabilities!',
+        long_description=read('README.md'),
+        long_description_content_type='text/markdown',
+        url='https://github.com/fO-000/bluescan',
+        # project_urls={
+        #     "Bug Tracker": "None",
+        #     "Documentation": "None",
+        #     "Source Code": "None",
+        # },
+
+        cmdclass={
+            'install': MyInstall,
+            'clean': MyClean
+        }
+    )

src/bluescan/__init__.py

@@ -0,0 +1,8 @@
+#!/usr/bin/env python3
+
+from .hci import HCI
+
+class BlueScanner():
+    def __init__(self, iface='hci0'):
+        self.iface = iface
+        self.devid = HCI.hcix2devid(self.iface)