Added packaging constructs to allow installation using pip or pipx (

Tib3rius#48)

* Restructured program to enable packaging. Moved main into its own function and resolved global dependency issues. Configured pyproject.toml

* Restructured configuration management such that configuration files are stored in the default user configuration directory for the OS they're using, utilising appdirs

* Added exclusion for byte compiled python files

* Removed build files from version control

* Restructured config file initialisation into a function so that it can be called by the entrypoint main() function

* Resolved issues updating global variables from within function scope. Added global identifiers to global variables to make them more readily identifiable as such

* Formatting revision

* Updated documentation to reflect package installation instructions and usage

* Grammatical revision to improve instructional clarity

* Added default sudo for udp scans to prompt for password to elevate privileges

* Added an installation command for all required packages to the README

* Added manual installation instructions, clarification of oscp vm limitations installing pip3, and instructions on how to elevate privileges when installed with pipx

* Formatting revision to improve clarity of instructions and added requirements.txt

* Removed hardcoded sudo commands from default scan configurations

* Changed suggestion to add alias to .bashrc to .profile as this is what's used by default in kali to set initial temrinal conditions

* Fixed error in manual installation that would have resulted in installing python2 packages

.gitignore

@@ -0,0 +1,139 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+*.pyc
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/

README.md

@@ -26,24 +26,66 @@ AutoRecon was inspired by three tools which the author used during the OSCP labs
 
 ## Requirements
 
-* Python 3
-* colorama
-* toml
+- Python 3
+- `python3-pip`
+- `pipx` (optional, but recommended)
 
-Once Python 3 is installed, pip3 can be used to install the other requirements:
+### Python 3
+
+If you don't have these installed, and are running Kali Linux, you can execute the following:
 
 ```bash
-$ pip3 install -r requirements.txt
+$ sudo apt install python3
+$ sudo apt install python3-pip
 ```
 
-Several people have indicated that installing pip3 via apt on the OSCP Kali version makes the host unstable. In these cases, pip3 can be installed by running the following commands:
+Additionally, if you experience any issues with the stability of the `python3-pip` installation (as reported by a number of people installing `pip3` via `apt` on the OSCP distribution of Kali), you can install it manually as follows:
 
 ```bash
 $ curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
 $ python3 get-pip.py
 ```
 
-The "pip3" command should now be usable.
+The `pip3` command should now be usable.
+
+### `pipx`
+
+Further, it's recommended you use `pipx` to manage your python packages; this installs each python package in it's own virtualenv, and makes it available in the global context, which avoids conflicting package dependencies and the resulting instability. To summarise the installation instructions:
+
+```bash
+$ python3 -m pip install --user pipx
+$ python3 -m pipx ensurepath
+```
+
+Note that if you want to elevate privileges to run a program installed with `pipx`, with `sudo`, you have two options:
+
+1. Append the appropriate path to your execution command, using _one_ of the following examples (recommended):
+
+```bash
+$ sudo env "PATH=$PATH" autorecon [OPTIONS]
+$ sudo $(which autorecon) [OPTIONS]
+```
+
+To make this easier, you could add the following alias to your `~/.profile` (or equivalent):
+
+```
+alias sudo="sudo env \"PATH=$PATH\""
+```
+
+2. Add the `pipx` binary path to the `secure_path` set in `/etc/sudoers`
+
+```bash
+sudo visudo /etc/sudoers
+```
+
+Update the `secure_path` directive as follows:
+```
+Defaults	secure_path="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/home/kali/.local/bin"
+```
+
+If you're not using Kali Linux, make sure to adjust the path to the relevant user. Further detail on the installation of `pipx` is available in their installation instructions available [here](https://pipxproject.github.io/pipx/installation/). Please refer to this for any issues you experience.
+
+### Supporting packages
 
 Several commands used in AutoRecon reference the SecLists project, in the directory /usr/share/seclists/. You can either manually download the SecLists project to this directory (https://github.com/danielmiessler/SecLists), or if you are using Kali Linux (**highly recommended**) you can run the following:
 
@@ -75,12 +117,50 @@ whatweb
 wkhtmltoimage
 ```
 
+On Kali Linux, you can ensure these are all installed using the following command:
+
+```bash
+$ sudo apt install curl enum4linux gobuster nbtscan nikto nmap onesixtyone oscanner smbclient smbmap smtp-user-enum snmp sslscan sipvicious tnscmd10g whatweb wkhtmltopdf
+```
+
+## Installation
+
+Ensure you have all of the requirements installed as per the previous section.
+
+### Using `pipx` (recommended)
+
+```bash
+$ pipx install git+https://github.com/Tib3rius/AutoRecon.git
+```
+
+### Using `pip`
+
+```bash
+$ python3 -m pip install git+https://github.com/Tib3rius/AutoRecon.git
+```
+
+### Manual
+
+If you'd prefer not to use `pip` or `pipx`, you can always still install and execute `autorecon.py` manually as a script. First install the dependencies:
+
+```bash
+$ python3 -m pip install -r requirements.txt
+```
+
+You will then be able to run the `autorecon.py` script (from `<AUTORECON_ROOT_DIR>/src/autorecon`):
+
+```bash
+$ python3 autorecon.py [OPTIONS] 127.0.0.1
+```
+
+See detailed usage options below.
+
 ## Usage
 
 AutoRecon uses Python 3 specific functionality and does not support Python 2.
 
 ```
-usage: autorecon.py [-h] [-t TARGET_FILE] [-ct <number>] [-cs <number>]
+usage: autorecon    [-h] [-t TARGET_FILE] [-ct <number>] [-cs <number>]
                     [--profile PROFILE_NAME] [-o OUTPUT_DIR] [--single-target]
                     [--only-scans-dir] [--heartbeat HEARTBEAT]
                     [--nmap NMAP | --nmap-append NMAP_APPEND] [-v]
@@ -135,7 +215,7 @@ optional arguments:
 **Scanning a single target:**
 
 ```
-python3 autorecon.py 127.0.0.1
+$ autorecon 127.0.0.1
 [*] Scanning target 127.0.0.1
 [*] Running service detection nmap-full-tcp on 127.0.0.1
 [*] Running service detection nmap-top-20-udp on 127.0.0.1
@@ -183,7 +263,7 @@ Note that the actual command line output will be colorized if your terminal supp
 **Scanning multiple targets**
 
 ```
-python3 autorecon.py 192.168.1.100 192.168.1.1/30 localhost
+$ autorecon 192.168.1.100 192.168.1.1/30 localhost
 [*] Scanning target 192.168.1.100
 [*] Scanning target 192.168.1.1
 [*] Scanning target 192.168.1.2
@@ -208,7 +288,7 @@ AutoRecon supports multiple targets per scan, and will expand IP ranges provided
 **Scanning multiple targets with advanced options**
 
 ```
-python3 autorecon.py -ct 2 -cs 2 -vv -o outputdir 192.168.1.100 192.168.1.1/30 localhost
+$ autorecon -ct 2 -cs 2 -vv -o outputdir 192.168.1.100 192.168.1.1/30 localhost
 [*] Scanning target 192.168.1.100
 [*] Scanning target 192.168.1.1
 [*] Running service detection nmap-quick on 192.168.1.100 with nmap -vv --reason -Pn -sV -sC --version-all -oN "/root/outputdir/192.168.1.100/scans/_quick_tcp_nmap.txt" -oX "/root/outputdir/192.168.1.100/scans/_quick_tcp_nmap.xml" 192.168.1.100

poetry.toml

@@ -0,0 +1,2 @@
+[virtualenvs]
+create = true

pyproject.toml

@@ -0,0 +1,28 @@
+[tool.poetry]
+name = "autorecon"
+version = "1.0.0"
+description = "A multi-threaded network reconaissance tool which performs automated enumeration of services"
+authors = ["Tib3rius"]
+license = "GPL-3.0-only"
+readme = "README.md"
+homepage = "https://github.com/Tib3rius/AutoRecon"
+repository = "https://github.com/Tib3rius/AutoRecon"
+packages = [
+	{include = "autorecon", from = "src"},
+]
+
+[tool.poetry.dependencies]
+python = "^3.7"
+toml = "^0.10.0"
+colorama = "^0.4.3"
+appdirs = "^1.4.3"
+
+[tool.poetry.dev-dependencies]
+
+
+[tool.poetry.scripts]
+autorecon = 'autorecon.autorecon:main'
+
+[build-system]
+requires = ["poetry>=0.12"]
+build-backend = "poetry.masonry.api"

requirements.txt

@@ -1,2 +1,3 @@
 colorama
 toml
+appdirs