readme.md in aws_recon-0.2.2 vs readme.md in aws_recon-0.2.3
- old
+ new
@@ -1,5 +1,7 @@
+[![Gem Version](https://badge.fury.io/rb/aws_recon.svg)](https://badge.fury.io/rb/aws_recon)
+
# AWS Recon
A multi-threaded AWS inventory collection tool.
The [creators](https://darkbit.io) of this tool have a recurring need to be able to efficiently collect a large amount of AWS resource attributes and metadata to help clients understand their cloud security posture.
@@ -22,35 +24,48 @@
Ruby 2.5.x or 2.6.x (developed and tested with 2.6.5)
### Installation
-Clone this repository, then install the required gems using `bundle`:
+Install the gem:
```
-$ git clone git@github.com:darkbitio/aws-recon.git
-$ cd aws-recon
-$ bundle
+$ gem install aws_recon
+Fetching aws_recon-0.2.2.gem
+Fetching aws-sdk-resources-3.76.0.gem
+Fetching aws-sdk-3.0.1.gem
+Fetching parallel-1.19.2.gem
...
-Using aws-sdk-core 3.103.0
+Successfully installed aws-sdk-3.0.1
+Successfully installed parallel-1.19.2
+Successfully installed aws_recon-0.2.2
+```
+
+Or add it to your Gemfile using `bundle`:
+
+```
+$ bundle add aws_recon
+Fetching gem metadata from https://rubygems.org/
+Resolving dependencies...
...
-Bundle complete! 5 Gemfile dependencies, 259 gems now installed.
-Use `bundle info [gemname]` to see where a bundled gem is installed.
+Using aws-sdk 3.0.1
+Using parallel 1.19.2
+Using aws_recon 0.2.2
```
## Usage
AWS Recon will leverage any AWS credentials currently available to the environment it runs in. If you are collecting from multiple accounts, you may want to leverage something like [aws-vault](https://github.com/99designs/aws-vault) to manage different credentials.
```
-$ aws-vault exec profile -- ./recon.rb
+$ aws-vault exec profile -- aws_recon
```
Plain environment variables will work fine too.
```
-$ AWS_PROFILE=<profile> ./recon.rb
+$ AWS_PROFILE=<profile> aws_recon
```
You may want to use the `-v` or `--verbose` flag initially to see status and activity while collection is running.
In verbose mode, the console output will show:
@@ -60,11 +75,11 @@
```
The `t` prefix indicates which thread a particular request is running under. Region, service, and operation indicate which request operation is currently in progress and where.
```
-$ ./recon.rb -v
+$ aws_recon -v
t0.global.EC2.describe_account_attributes
t2.global.S3.list_buckets
t3.global.Support.describe_trusted_advisor_checks
t2.global.S3.list_buckets.acl
@@ -85,15 +100,15 @@
```
#### Example command line options
```
-$ AWS_PROFILE=<profile> ./recon.rb -s S3,EC2 -r global,us-east-1,us-east-2
+$ AWS_PROFILE=<profile> aws_recon -s S3,EC2 -r global,us-east-1,us-east-2
```
```
-$ AWS_PROFILE=<profile> ./recon.rb --services S3,EC2 --regions global,us-east-1,us-east-2
+$ AWS_PROFILE=<profile> aws_recon --services S3,EC2 --regions global,us-east-1,us-east-2
```
#### Errors
An exception will be raised on `AccessDeniedException` errors. This typically means your user/role doesn't have the necessary permissions to get/list/describe for that service. These exceptions are raised so troubleshooting access issues is easier.
@@ -116,15 +131,15 @@
### Options
Most users will want to limit collection to relevant services and regions. Running without any options will attempt to collect all resources from all 16 regular regions.
```
-$ ./recon.rb -h
+$ aws_recon -h
AWS Recon - AWS Inventory Collector
-Usage: ./recon.rb [options]
+Usage: aws_recon [options]
-r, --regions [REGIONS] Regions to scan, separated by comma (default: all)
-n, --not-regions [REGIONS] Regions to skip, separated by comma (default: none)
-s, --services [SERVICES] Services to scan, separated by comma (default: all)
-x, --not-services [SERVICES] Services to skip, separated by comma (default: none)
-c, --config [CONFIG] Specify config file for services & regions (e.g. config.yaml)
@@ -207,9 +222,24 @@
- [x] Xray
### Additional Coverage
One of the primary motivations for AWS Recon was to build a tool that is easy to maintain and extend. If you feel like coverage could be improved for a particular service, we would welcome PRs to that effect. Anyone with a moderate familiarity with Ruby will be able to mimic the pattern used by the existing collectors to query a specific service and add the results to the resource collection.
+
+### Development
+
+Clone this repository, then install the required gems using `bundle`:
+
+```
+$ git clone git@github.com:darkbitio/aws-recon.git
+$ cd aws-recon
+$ bundle
+...
+Using aws-sdk-core 3.103.0
+...
+Bundle complete! 5 Gemfile dependencies, 259 gems now installed.
+Use `bundle info [gemname]` to see where a bundled gem is installed.
+```
### TODO
- [ ] Optionally suppress AWS API errors instead of re-raising them
- [ ] Package as a gem