diff --git a/README.md b/README.md index 6ada6cd..ef960ef 100644 --- a/README.md +++ b/README.md @@ -1,137 +1,126 @@ # aws-s3-baseline -A micro-baseline to check for insecure or public S3 buckets and bucket objects in your AWS Environment. +A micro-baseline to check for insecure or public S3 buckets and bucket objects in your AWS Environment. This [InSpec](https://github.com/chef/inspec) compliance profile verifies that you do not have any insure or open to public S3 Bucket or Bucket Objects in your AWS Environment in an automated way. -## Description +NOTE: Small Word of Warning -This [InSpec](https://github.com/chef/inspec) compliance profile verifies that you do not have any insure or open to public S3 Bucket or Bucket Objects in your AWS Environment in an automated way. - -InSpec is an open-source run-time framework and rule language used to specify compliance, security, and policy requirements for testing any node in your infrastructure. - -## Versioning and State of Development -This project uses the [Semantic Versioning Policy](https://semver.org/). - -### Branches -The master branch contains the latest version of the software leading up to a new release. - -Other branches contain feature-specific updates. - -### Tags -Tags indicate official releases of the project. - -Please note 0.x releases are works in progress (WIP) and may change at any time. - -## Requirements - -- [InSpec](http://inspec.io/) at least version 3.x -- [AWS CLI](https://aws.amazon.com/cli/) at least version 2.x - -## Setting up AWS credentials for InSpec - -InSpec uses the standard AWS authentication mechanisms. Typically, you will create an IAM user specifically for auditing activities. +In this InSpec profile implementation, the `s3-objects-no-public-access` control iterates through and verifies every objects in each bucket in your AWS Environment, thus its runtime will depend on the number of objects in your S3 Buckets. -- Create an IAM user in the AWS console, with your choice of username. Check the box marked “Programmatic Access.” -- On the Permissions screen, choose Direct Attach. Select the AWS-managed IAM Profile named “ReadOnlyAccess.” If you wish to restrict the user further, you may do so; see individual InSpec resources to identify which permissions are required. -- After generating the key, record the Access Key ID and Secret Key. +## Getting Started +It is intended and recommended that InSpec and this profile be run from a __"runner"__ host (such as a DevOps orchestration server, an administrative management system, or a developer's workstation/laptop) against the target remotely over __ssh__. -## Get started +__For the best security of the runner, always install on the runner the _latest version_ of InSpec and supporting Ruby language components.__ -The following attributes can be configured in an attributes file. More information about InSpec attributes can be found in the [InSpec Profile Documentation](https://www.inspec.io/docs/reference/profiles/). - -``` -# Description: List of buckets exempted from inspection. -exception_bucket_list: [] +The latest versions and installation options are available at the [InSpec](http://inspec.io/) site. -``` +This baseline also requires the AWS Command Line Interface (CLI) which is available at the [AWS CLI](https://aws.amazon.com/cli/) site. -Bundle install required gems
-- `bundle install` +### Getting MFA Aware AWS Access, Secret and Session Tokens -Before running the profile with InSpec, define environment variables with your AWS region and credentials. InSpec supports the following standard AWS variables: +You will need to ensure your AWS CLI environment has the right system environment variables set with your AWS region and credentials and session token to use the AWS CLI and InSpec resources in the AWS environment. InSpec supports the following standard AWS variables: - `AWS_REGION` - `AWS_ACCESS_KEY_ID` - `AWS_SECRET_ACCESS_KEY` -- `AWS_SESSION_TOKEN` (required if MFA is enabled) +- `AWS_SESSION_TOKEN` (optional) - required if MFA is enabled ### Notes on MFA -In an AWS MFA enabled enviroment - you need to use derived credentials to use the CLI. Your default AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY will not satisfy the MFA Policies in the AWS environment for full use of the AWS API. +In any AWS MFA enabled environment - you need to use `derived credentials` to use the CLI. Your default `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` will not satisfy the MFA Policies in AWS environments. - The AWS documentation is here: https://docs.aws.amazon.com/cli/latest/reference/sts/get-session-token.html - The AWS profile documentation is here: https://docs.aws.amazon.com/cli/latest/userguide/cli-multiple-profiles.html - A useful bash script for automating this is here: https://gist.github.com/dinvlad/d1bc0a45419abc277eb86f2d1ce70625 -*Prior* to running the InSpec Profile, you will need to generate credentials: - -1. aws sts get-session-token --serial-number arn:aws:iam::<$YOUR-MFA-SERIAL> --token-code <$YOUR-CURRENT-MFA-TOKEN> --profile=<$YOUR-AWS-PROFILE> +To generate credentials using an AWS Profile you will need to use the following AWS CLI commands. -2. Then export the AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_SESSION_TOKEN that was generated by the above command. + a. `aws sts get-session-token --serial-number arn:aws:iam::<$YOUR-MFA-SERIAL> --token-code <$YOUR-CURRENT-MFA-TOKEN> --profile=<$YOUR-AWS-PROFILE>` -## NOTE: Small Word of Warning + b. Then export the `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` and `AWS_SESSION_TOKEN` that was generated by the above command. -In this InSpec profile implementation, the `s3-objects-no-public-access` control iterates through and verifies every objects in each bucket in your AWS Environment, thus its runtime will depend on the number of objects in your S3 Buckets. +## Tailoring to Your Environment +The following inputs must be configured in an inputs ".yml" file for the profile to run correctly for your specific environment. More information about InSpec inputs can be found in the [InSpec Profile Documentation](https://www.inspec.io/docs/reference/profiles/). + +``` +# Description: List of buckets exempted from inspection. +exception_bucket_list: [] +``` ## Usage -InSpec makes it easy to run your tests wherever you need. More options listed here: [InSpec cli](http://inspec.io/docs/reference/cli/) - ``` -# Clone Inspec Profile -$ git clone https://github.com/aaronlippold/aws-s3-baseline - -# Install Gems -$ bundle install - # Set required ENV variables $ export AWS_ACCESS_KEY_ID=key-id $ export AWS_SECRET_ACCESS_KEY=access-key $ export AWS_SESSION_TOKEN=session-token # if MFA is enabled +``` -# run profile locally and directly from Github -$ inspec exec /path/to/profile -t aws:// - -# run profile locally and directly from Github with cli & json output -$ inspec exec /path/to/profile -t aws:// --reporter cli json:aws-results.json +# Running This Baseline Directly from Github ``` +# How to run +inspec exec https://github.com/mitre/aws-s3-baseline/archive/master.tar.gz --target aws:// --input-file= --reporter=cli json: +``` + +### Different Run Options -### Run individual controls + [Full exec options](https://docs.chef.io/inspec/cli/#options-3) -In order to verify individual controls, just provide the control ids to InSpec: +## Running This Baseline from a local Archive copy + +If your runner is not always expected to have direct access to GitHub, use the following steps to create an archive bundle of this baseline and all of its dependent tests: + +(Git is required to clone the InSpec profile using the instructions below. Git can be downloaded from the [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) site.) + +When the __"runner"__ host uses this profile baseline for the first time, follow these steps: ``` -$ inspec exec /path/to/profile --controls s3-buckets-no-public-access -t aws:// +mkdir profiles +cd profiles +git clone https://github.com/mitre/aws-s3-baseline +inspec archive aws-s3-baseline +inspec exec --target aws:// --input-file= --reporter=cli json: ``` +For every successive run, follow these steps to always have the latest version of this baseline: -## Contributors + Kudos - -- Rony Xavier [rx294](https://github.com/rx294) -- Matthew Dromazos [dromazmj](https://github.com/dromazmj) -- Aaron Lippold [aaronlippold](https://github.com/aaronlippold) +``` +cd aws-s3-baseline +git pull +cd .. +inspec archive aws-s3-baseline --overwrite +inspec exec --target aws:// --input-file= --reporter=cli json: +``` -## License and Author +## Using Heimdall for Viewing the JSON Results +The JSON results output file can be loaded into __[heimdall-lite](https://heimdall-lite.mitre.org/)__ for a user-interactive, graphical view of the InSpec results. -### Authors +The JSON InSpec results file may also be loaded into a __[full heimdall server](https://github.com/mitre/heimdall)__, allowing for additional functionality such as to store and compare multiple profile runs. -- Author:: Rony Xavier [rxavier@mitre.org](mailto:rxaiver@mitre.org) -- Author:: Matthew Dromazos [dromazmj@dukes.jmu.edu](mailto:mattdromazos9@gmail.com ) -- Author:: Aaron Lippold [lippold@gmail.com](mailto:lippold@gmail.com) +## Authors -### NOTICE +* Rony Xavier - [rx294](https://github.com/rx294) +* Aaron Lippold - [aaronlippold](https://github.com/aaronlippold) +* Matthew Dromazos - [dromazmj](https://github.com/dromazmj) -© 2018 The MITRE Corporation. +### Special Thanks -Approved for Public Release; Distribution Unlimited. Case Number 18-3678. +* Shivani Karikar - [karikarshivani](https://github.com/karikarshivani) ### NOTICE + +© 2018-2020 The MITRE Corporation. + +Approved for Public Release; Distribution Unlimited. Case Number 18-3678. + +### NOTICE + MITRE hereby grants express written permission to use, reproduce, distribute, modify, and otherwise leverage this software to the extent permitted by the licensed terms provided in the LICENSE.md file included with this project. ### NOTICE This software was produced for the U. S. Government under Contract Number HHSM-500-2012-00008I, and is subject to Federal Acquisition Regulation Clause 52.227-14, Rights in Data-General. -No other use other than that granted to the U. S. Government, or to those acting on behalf of the U. S. Government under that Clause is authorized without the express written permission of The MITRE Corporation. +No other use other than that granted to the U. S. Government, or to those acting on behalf of the U. S. Government under that Clause is authorized without the express written permission of The MITRE Corporation. -For further information, please contact The MITRE Corporation, Contracts Management Office, 7515 Colshire Drive, McLean, VA 22102-7539, (703) 983-6000. +For further information, please contact The MITRE Corporation, Contracts Management Office, 7515 Colshire Drive, McLean, VA 22102-7539, (703) 983-6000. \ No newline at end of file diff --git a/inspec.yml b/inspec.yml index 5df0d8e..7014827 100644 --- a/inspec.yml +++ b/inspec.yml @@ -1,14 +1,14 @@ name: aws-s3-baseline -title: AWS S3 Public Buckets and Objects Benchmark +title: aws-s3-baseline maintainer: MITRE InSpec Team copyright: MITRE, 2018 copyright_email: inspec@mitre.org license: Apache-2.0 -version: 1.0.0 -summary: An example baseline to test if you have any public s3 buckets or objects +summary: 'InSpec validation example baseline profile for AWS S3 - to test if you have public buckets' +version: 1.0.1 +inspec_version: ">= 4.0" supports: - platform: aws -inspec_version: ">= 4.0" depends: - name: inspec-aws