mgeeky-Penetration-Testing-Tools/clouds/aws/pentest-ec2-manager/README.md

# pentest-ec2-manager

A set of utilities for quick starting, ssh-ing and stopping of temporary EC2 instances intended to be used for Web out-of-band tests (SSRF, reverse-shells, dns/http/other daemons).
Those scripts are useful for managing *single* EC2 instance, which is picked based on specific characteristics: `key-name`, `image-id`, `security-group-name`, `instance-type`. 

Most common use case:
- _Performing SSRF tests._ - When you want to quickly assert there is out-of-band request going over to attacker-controlled machine

**CAUTION NOTE**: Files in this repository are preconfigured/hardcoded with some intial specific configurations. Those configurations are placed on top of each script file, one can change them easily.


### Installation

Installation is pretty straightforward assuming you have AWS account already and AWS Access Key (AKIA...) and AWS Secret Key with you.

If you have AWS account, installation can be started using `init.sh` script. This script assumes you can use `sudo` to pull in prerequisities.
```
bash $ ./init.sh

----------------------------------------------

:: AWS EC2 single-instance management utilities installation script.

This script is going to:
	- Update your repos & install packages such as: ssh, cron, jq, ruby, rubygems, awscli, gem bundler, gem 'aws-sdk-ec2'
	- Configure your AWS credentials
	- Create AWS security groups, EC2 key pairs
	- Integrate EC2 management aliases into the end of your .bashrc
	- Add a cron job that will notify you every two hours if your EC2 machine is up and running

----------------------------------------------

Would you like to proceed? [Y/n] 
```

After hitting `Y` it shall configure AWS CLI for you, pull `aws-sdk-ec2` for ruby and then create Security Groups, Key Pairs and append things to your bashrc.


### Usage

After script installation is over, your bash will get preloaded (in `~/.bashrc`) with following aliases:

* `startpentestec2` - Starts EC2 Instance if it exists, otherwise creates it
* `stoppentestec2` - Stops EC2 Instance
* `terminatepentestec2` - Terminates EC2 Instance (which means also deletes that instance's Elastic Block Store / hdd)
* `sshpentestec2` - Attemtps to SSH into managed EC2 instance.
* `getpentestec2` - Obtains IPv4 address of managed EC2 instance.
* `checkpentestec2` - Prints out EC2 Instance status (running, stopped, notcreated, pending, etc)

If you do not want to use bash aliases, or prefer having it your own way, you can call the `aws-manager.rb` script directly:

```
bash $ ruby aws-manager.rb --help

Usage: aws-manager.rb [options] <func> <name>

Available 'func' values:
    - start			Starts an EC2 instance. If it does not exist, it is to be created
    - stop			Stops the EC2 instance. It does not terminate it.
    - restart			Restarts the EC2 instance
    - terminate			Terminates the EC2 instance.
    - address			Gets an IPv4 address of the EC2 instance. If verbose options is set, will return more FQDN also.
    - status			Checks what is a status of picked EC2 instance.
    - ssh			Opens a ssh connection with specified instance. If it is not running, it is to be created and started.
    - notify			Sends gnome notification using "notify-send" with running instance uptime.

Options:
    -h, --help                       Display this screen
    -q, --quiet                      Surpress informative output.
    -v, --verbose                    Turn on verbose logging.
        --debug                      Turn on debug logging.
    -d, --aws-path=PATH              Path to shared AWS credentials file. Default value that will be used: $AWS_PATH/credentials 
        --profile=NAME               AWS credentials profile to use. Should no option is given, "default" is used.
    -p, --region=REGION              AWS regoin to use. Default one: "us-east-1".
    -i, --image-id=ID                AWS image ID to create an EC2 from. Default: 'ami-07360d1b1c9e13198
    -k, --key-name=KEY               AWS EC2 Key Name to use. Default: 'ec2-pentest-key
    -s, --security-group-name=NAME   AWS EC2 Security Group name to use. Default: 'ec2-pentest-usage
    -t, --instance-type=TYPE         Instance type to spin. Default: 't2.micro
    -u, --user=USER                  SSH user to log into when doing 'ssh'. Default: 'ec2-user

```


Typical usage boils down to issuing `func` operations. Eventually one would like to observe what happens under the hood using one of those flags:
* `-v`
* `--debug`

On the other hand, it is possible to surpress script's output nearly entirely using:
* `-q`
flag.


### TODO

* Test, bug fixes
* Support different Regions. Currently scripts are fixed on using one region.
* Support more than one instance. Very far aim to reach.