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

98 lines
4.6 KiB
Markdown

# 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.