# Autoshell ![Autoshell][logo]
[![Build Status](https://travis-ci.org/PackeTsar/autoshell.svg?branch=master)](https://travis-ci.org/PackeTsar/autoshell)
[![PyPI](https://img.shields.io/pypi/v/autoshell.svg)](https://pypi.python.org/pypi/autoshell)
[![Python Versions](https://img.shields.io/pypi/pyversions/autoshell.svg)](https://pypi.python.org/pypi/autoshell)
A simple, fully programmable, shell-based network automation utility
Quick Install: `pip install autoshell`
Get started fast with the **[Autoshell Tutorial](TUTORIAL-1.md)**
-----------------------------------------
## VERSION ##
The version of Autoshell documented here is: **0.0.43**
-----------------------------------------
## TABLE OF CONTENTS ##
1. [What is Autoshell](#what-is-autoshell)
2. [Requirements](#requirements)
3. [Installation](#installation)
4. [Getting Started](#getting-started)
5. [Contributing](#contributing)
6. [Autoshell Tutorial](TUTORIAL-1.md)
-----------------------------------------
## WHAT IS AUTOSHELL ##
Autoshell is a Command-Line Utility and Python Library built to make quick automation tasks of a network easy.
Autoshell is a "shell" application in that it handles a part of the automation process, mainly parsing user arguments and connecting to hosts. It then depends on bundled and/or user-written modules to perform desired tasks on the connected hosts. Since Autoshell does the heavy lifting (connecting to hosts, importing modules, sorting through credentials, providing module libraries, etc) it allows the modules to be very short and simple while making their effects quite powerful.
-----------------------------------------
## INSTALLATION ##
The installation process is also covered in the **[Autoshell Tutorial](TUTORIAL-1.md)**
<!--
< ### Autoshell Binaries (Easiest)
You can download and use the Autoshell binaries if you do not want to install the Python interpreter. This is the quickest way to start using Autoshell, but since more advanced usage of Autoshell requires you to write your own modules using Python, it is recommended that you follow the below process to install Python and PIP on your operating system, then use PIP to install Autoshell.
-->
### Prepare Your OS
#### Windows
1. If you have not yet installed Python on your Windows OS, then download and install the latest Python2 or Python3 from [Python Downloads Page](https://www.python.org/downloads/)
- Make sure to check the box during installation which adds Python to PATH. Labeled something like `Add Python 3.7 to PATH`
2. Once Python is installed, you should be able to open a command window, type `python`, hit ENTER, and see a Python prompt opened. Type `quit()` to exit it. You should also be able to run the command `pip` and see its options. If both of these work, then move on to install Autoshell.
- If this does not work, you will need to add the Python installation directory path to the Windows PATH variable
- The easiest way to do this is to find the new shortcut for Python in your start menu, right-click on the shortcut, and find the folder path for the `python.exe` file
- For Python2, this will likely be something like `C:\Python27`
- For Python3, this will likely be something like `C:\Users\<USERNAME>\AppData\Local\Programs\Python\Python37`
- Open your Advanced System Settings window, navigate to the "Advanced" tab, and click the "Environment Variables" button
- Create a new system variable:
- Variable name: `PYTHON_HOME`
- Variable value: <your_python_installation_directory>
- Now modify the PATH system variable by appending the text `;%PYTHON_HOME%\;%PYTHON_HOME%;%PYTHON_HOME%\Scripts\` to the end of it.
- Close out your windows, open a command window and make sure you can run the commands `python` and `pip`
#### MacOS
MacOS often comes with a native version of Python, but we likely want to upgrade that and install PIP. The best way to do this is with a MacOS Linux-like package manager called [Homebrew](https://brew.sh/). You can visit the below pages to walk you through installing Homebrew and an updated Python interpreter along with it
1. Open Terminal and run: `xcode-select --install`. This will open a window. Click **'Get Xcode'** and install it from the app store.
2. Install Homebrew. Run: `/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"`
3. Install latest Python2: `brew install python@2`
4. Install latest Python3: `brew install python`
5. Link your default Python path to the new install `brew link --overwrite python`
6. Close Terminal and reopen it. You should see Python 2.7.15 when you run `python -V`
7. Once Python is installed, you should be able to open Terminal, type `python`, hit ENTER, and see a Python prompt opened. Type `quit()` to exit it. You should also be able to run the command `pip` and see its options. If both of these work, then move on to [Install Autoshell](#install-autoshell-using-pip-recommended)
- Additional resources on [Installing Python 2 on Mac OS X](https://docs.python-guide.org/starting/install/osx/)
- Additional resources on [Installing Python 3 on Mac OS X](https://docs.python-guide.org/starting/install3/osx/)
#### Linux
1. Install required OS packages
- **Raspberry Pi** may need Python and PIP `sudo apt install -y python-pip` as well as `sudo apt-get install libffi-dev`
- **Debian (Ubuntu)** distributions may need Python and PIP
- Install Python and PIP: `sudo apt install -y python-pip`
- **RHEL (CentOS)** distributions usually need PIP
- Install the EPEL package: `sudo yum install -y epel-release`
- Install PIP: `sudo yum install -y python-pip`
### Install Autoshell using PIP (Recommended)
1. Install Autoshell using pip by running the command `pip install autoshell`
2. Once the install completes, you should be able to run the command `autoshell -h` and see the help menu. Autoshell is now ready to use.
### Install Autoshell from source (Advanced)
1. Retrieve the source code repository using one of the two below methods
- **Method #1**: Install a Git client (process differs depending on OS) and clone the Autoshell repository using Git `git clone https://github.com/packetsar/autoshell.git`
- Change to the branch you want to install using `git checkout <branch_name>`
- **Method #2**: Download and extract the repository files from the [Github Repo](https://github.com/PackeTsar/autoshell)
- Make sure to download the branch you want to install
2. Move into the autoshell project directory `cd autoshell`
3. Run the setup.py file to build the package into the ./build/ directory `python setup.py build`
4. Use PIP to install the package `pip install .`
5. Once the install completes, you should be able to run the command `autoshell -h` and see the help menu. Autoshell is now ready to use.
-----------------------------------------
## GETTING STARTED ##
Below are some nuts and bolts to help you understand how to use Autoshell. If you want a quick 'how-to', then check out the **[Autoshell Tutorial](TUTORIAL-1.md)**.
Once you have installed Autoshell, you can see the command guide with `autoshell -h`.
Since modules are able to add their own arguments into the argument parser when they are imported, you can see a module's help by importing it (ie: `-m crawl`) and then adding the `-h` argument. You can see this by trying `autoshell -m crawl -h`, there you will see a section of argument descriptions for the Crawl module.
The simplest way to connect to a host is to point Autoshell directly at it (`autoshell 192.168.1.1`). If you do not provide credentials, it will prompt you for them. It is easy to add them inline with `-c username:password`. You are able to add as many hosts and credentials as you want and they are processed in the order you provide them.
### Credentials
Credentials can be provided to Autoshell in a few different ways:
1. **At the command line as a string.** The default full form