aws-execute

Intelligent AWS integrated wrapper for pentest tools targeting EC2 resources

Features

• Provides shell commands/scripts with the data and variables required to run pentest tools against AWS EC2 instances. This includes access to ip addresses, domain names, etc.
• Powerful templating engine to allow for templating commands and scripts with the specific data for the specific scenario
• Runs as a daemon to execute commands against ephemeral EC2 instances
• Runs the given command or script against each new instance via tracking AWS InstanceID's
• Exposes most EC2 data such as public IP addresses and public DNS names allowing this tool to be used on externals and internals
• Automatic credential detection and use from environment, AWS config, and EC2 instance IAM roles
• Provides a dump mode to allow users to dump data from the API in either;
  1. A default format
  2. Templated format allowing users to build complex data formats such as JSON with only the data they want

Specifying AWS API Credentials

The credential chain looks for credentials in the following order:

1. Environment variables.
   • Static Credentials (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN)
   • Web Identity Token (AWS_WEB_IDENTITY_TOKEN_FILE)
2. Shared configuration files. These are for boxes that have the aws command installed and configured.
   • credentials file under .aws folder that is in the users home folder.
   • config file under .aws folder that is in the users home folder.
3. IAM role for tasks. If running as a 'Task'.
4. When running on an Amazon EC2 instance; IAM role for Amazon EC2.
   • In this scenario, simply having the binary on the EC2 instance will allow the binary to automagically retrieve the appropriate access credentials provided the EC2 instance is assigned appropriate privileges through IAM roles.

Getting a binary

Have golang 1.16+ installed.

1. Clone
   • git clone git@github.ibm.com:X-Force-Red/aws-execute.git && cd aws-execute
2. Compile for your platform
   • make release build
3. Binary will be a executable located in $PWD/build

Detailed Usage

Usage of aws-execute:
Author: Michael Mitchell

Description: 
  This program allows the user to provide commands with the data and variables contained within AWS via templating the
  command with placeholders for AWS data.
  
Notes:
  * Internally, this program passes the entire provided command as an argument to `bash -c`. This is done to avoid
    having to determine and process positional arguments on *unix like systems. Make sure `bash` is installed on your
    system.
  * This program is not safe against malicious data from the AWS API. If the AWS API were to return malicious
    data, it is possible to exploit this program for remote shell command execution.
    
Flag Synopsis:
  -c, --command string           The command to execute for each Instance. This parameter supports the same templating
                                 options as --dump. Please note that 'nil' variables are not handled specially, and
                                 will result in <nil> being placed in the command. You can account for this via the
                                 templating functions if this is important to you, or let the command continuously
                                 fail. If the command being executed takes longer than the backoff value for errors -e
                                 (--error-backoff) to fail, you should increase the -e (--error-backoff) to be around
                                 2 times as long as it takes the command to fail. If the command fails fast, use the
                                 default. (Default: '')
                                 
      --dump string              Print information about every Instance. Optionally, this flag can also take a format
                                 string that will be used to control how the output is structured. The format string
                                 uses golang template/text semantics with the variables identified with -v
                                 (--template-variables). (Default: 'false')
                                 
  -e, --error-backoff duration   The delay between retrying the 'command' (-c) after it errored. Errors are tried
                                 before everything else. (Default: '5m0s')
                                 
  -h, --help                     Print this help information then exit. (Default: 'false')
                                 
  -i, --interval duration        Interval to query the AWS API for EC2 Instances. This interval is not affected by
                                 scanning and will continue regardless of where the scanner is at on scanning.
                                 (Default: '5m0s')
                                 
  -p, --profile string           AWS Console profile to use. This can be very helpful if you have access to multiple
                                 console profiles and need to validate what each one has visibility into. (Default: '')
                                 
  -r, --regions strings          AWS regions to scan in the form of region-1,region-2,region-3. (Default: '[]')
                                 
  -R, --restore string           Restore from a state file. The only command line option that are restored are -r
                                 (--regions) and -c '--command'. This is done to prevent inconsistencies in the
                                 restored state's instances regions and errors. (Default: 'false')
                                 
  -s, --save-state-to string     Set the file to use to save state to instead of a dynamically generated default
                                 (Default: '')
                                 
  -v, --template-variables       Print the template variable options for the templating functionality. Variables are
                                 referenced via {{.VARIABLE_NAME_HERE}} where VARIABLE_NAME_HERE is replaced with the
                                 variable you want to print. (Default: 'false')
                                 
  -t, --threads uint             Number of 'command's to execute in parallel. (Default: '1')
                                 
  -E, --toggle-errors            Toggle showing errors. By default errors are shown. (Default: 'true')
                                 
  -S, --toggle-successes         Toggle showing instance command successes. By default these are not shown. (Default:
                                 'false')
                                 
  -V, --version                  Print version information and exit. (Default: 'false')
                                 
Examples:
  aws-execute -c 'nmap -sS {{.PrivateIpAddress}} -oA {{.InstanceId}}' -r us-east-1,us-west-1
      Execute nmap on the private ip for each Instance in the us-east-1 and us-west-1 regions. If the private ip for
      the Instance doesn't exist, this command will fail fast. Instances will be scanned 1 at a time (default) and
      failed nmap commands will be retried on the given Instance after 5 minutes (default). New Instances will be
      retrieved from the AWS api every 5 minutes (default) and added to the pool of Instances to execute the nmap
      command against.

  aws-execute -t 10 -c 'nmap -sS {{.PublicIpAddress}} -oA {{.InstanceId}}' -r us-east-1
      Execute nmap on the public ip for each Instance in the us-east-1 region with up to 10 Instances being 'scanned'
      at the same time. Everything else is the same as above.

  aws-execute -c 'amass intel -d {{.PublicDnsName}} -whois >{{.InstanceId}}.whois' -e 10m -r us-east-1
      Execute amass for whois information against the PublicDnsName for each Instance. Run against 1 Instance at a
      time and retry failed commands after 10 minutes. Everything else is the same as above.

  aws-execute -v
      Print the variables that can be used in command templating

  aws-execute --dump -r us-east-1,us-east-2,us-west-1
      Dump every Instances id, internal ip, internal dns, external ip, and external dns for us-east-1, us-east-2, and
      the us-west-1 regions.

  aws-execute --dump='{{.PublicIpAddress}},{{.InstanceId}},{{.VpcId}}' -r us-east-1,us-east-2,us-west-1 | grep -v nil
      Dump every PublicIpAddress, InstanceId, and VpcId in a csv-like format (specified by the format string). Grep
      out the missing data elements, as they are of no use to a CSV like that, and dump the data for the us-east-1,
      us-east-2, and the us-west-1 regions.

Author(s)

• Michael Mitchell

ToDo:

• Cleanup output when in the daemon mode
• State file and resume
• Precompile execute commands on retrieval from AWS API. Reduces load when running many commands at once.
• Support AWS 'Profiles'. This can be done currently via ENV variable; AWS_PROFILE=myprofilehere