PyShell

Custom shell, written in Python
Report Bug · Request Feature

• 1. About The Project
  • 1.1. Built With
• 2. Getting Started
  • 2.1. Prerequisites
    • 2.1.1. Windows
    • 2.1.2. Linux
    • 2.1.3. Arch Linux
  • 2.2. Installation
• 3. Usage
• 4. Plugins
• 5. Compiling
• 6. Features
  • 6.1. Included plugins
    • 6.1.1. MacLookup
    • 6.1.2. Networking
    • 6.1.3. SQLite
    • 6.1.4. SSH Manager
  • 6.2. Customization
• 7. Roadmap
• 8. Contributing
• 9. License
• 10. Contact

1. About The Project

1.1. Built With

• Prompt-toolkit
• Yapsy
• PyGit

2. Getting Started

To get a local copy up and running, follow these simple steps.

2.1. Prerequisites

You will need Python and pip installed on your system. Version 3.9.0 or higher is recommended but not necessarily required.

2.1.1. Windows

• Python

2.1.2. Linux

Debian/Ubuntu

sudo apt install python3 python3-pip

2.1.3. Arch Linux

sudo pacman -S python python-pip

2.2. Installation

1. Clone the repo

   git clone https://github.com/Stax124/Shell.git

2. Move to the project directory

   cd Shell

3. OPTIONAL Install required packages manually if automatic fails (if pip doesn't work, try pip3 instead)

   pip install -r requirements.txt

3. Usage

Shell is invoked by running the shell.py file. It will try to install all the necessary modules and invoke main.py file.

python3 shell.py

shell.py supports argparse, so you can also run the following command:

python3 shell.py --help

Current shell menu should look like this:

usage: shell.py [-h] [-d DIRECTORY] [-v] [command ...]

positional arguments:
  command               Execute following command

optional arguments:
  -h, --help            show this help message and exit
  -d DIRECTORY, --directory DIRECTORY
                        Start in specified directory
  -v, --verbose

4. Plugins

Shell can be extended with plugins.

For now, included plugins are: MacLookup, Networking, SQLite, SSH Manager.

New plugins can be easily developed from the included template in plugins directory called example. Feel free to have a look at one of the included plugins as well for more information.

Plugins will not work if you compile the shell.

5. Compiling

You will need to install the following dependencies:

• PyInstaller - pip install pyinstaller

You can compile the shell by running the following command:

pyinstaller --onefile shell.py

Output will be in dist directory.

6. Features

6.1. Included plugins

6.1.1. MacLookup

• Find a device type by its MAC address

6.1.2. Networking

• Do a quick TCP/IP scan of target. (This is just a small utility, not a full-featured network scanner like nmap)

6.1.3. SQLite

• Connect to a SQLite database and execute queries

6.1.4. SSH Manager

• Save multiple ssh connection details and quickly connect to them

6.2. Customization

• Customize the shell's look and feel by editing ~/.voidshell
• All currently available public variables accessible for shell customization are
  • RETURNCODE
  • DOMAIN
  • USER
  • PATH
  • ROOT
  • REPO
  • TIME
  • SYSTEM
  • WIN32EDITION
  • WIN32VER
  • MACOSVER
  • MACHINETYPE
  • PLATFORM
  • CPUCOUNT
  • LOGIN
  • PID

7. Roadmap

• Add support for custom environments
• Add support for using brackets in commands
• Fix issue with unstable piping

See the open issues for a list of proposed features (and known issues).

8. Contributing

Contributions are what makes the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

9. License

Distributed under the GPL-3.0 License. See LICENSE for more information.

10. Contact

Tomáš Novák - [email protected]

Project Link: https://github.com/Stax124/Shell