Skip to content

Commit

Permalink
Updated files to standardize
Browse files Browse the repository at this point in the history 
Signed-off-by: karikarshivani <[email protected]>
  • Loading branch information
@karikarshivani
karikarshivani committed Jan 29, 2021
1 parent c1b0a79 commit bdc1251
Show file tree
Hide file tree
Showing 2 changed files with 72 additions and 83 deletions.
147 changes: 68 additions & 79 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -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 <br>
- `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=<path_to_your_inputs_file/name_of_your_inputs_file.yml> --reporter=cli json:<path_to_your_output_file/name_of_your_output_file.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 <name of generated archive> --target aws:// --input-file=<path_to_your_inputs_file/name_of_your_inputs_file.yml> --reporter=cli json:<path_to_your_output_file/name_of_your_output_file.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 <name of generated archive> --target aws:// --input-file=<path_to_your_inputs_file/name_of_your_inputs_file.yml> --reporter=cli json:<path_to_your_output_file/name_of_your_output_file.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 [[email protected]](mailto:[email protected])
- Author:: Matthew Dromazos [[email protected]](mailto:[email protected] )
- Author:: Aaron Lippold [[email protected]](mailto:[email protected])
## 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.
8 changes: 4 additions & 4 deletions inspec.yml
View file
Original file line number Diff line number Diff line change
@@ -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: [email protected]
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
Expand Down

0 comments on commit bdc1251

Please sign in to comment.