cloudgoat 2.4.0
A vulnerable AWS environment generator for Pentesters.
Requires Python: <4.0,>=3.9

# CloudGoat (☁️🐐)
[![Rhino](https://img.shields.io/badge/rhino-vulnerable%20%7C%20tool-red?logo=data:image/png;base64,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)](https://rhinosecuritylabs.com) [![PyPI](https://img.shields.io/badge/python-3.9+-blue.svg)](https://github.com/RhinoSecurityLabs/cloudgoat) [![GitHub license](https://img.shields.io/badge/license-BSD-brightgreen.svg)](https://github.com/RhinoSecurityLabs/cloudgoat/blob/master/LICENSE) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/RhinoSecurityLabs/cloudgoat/pulls)

_CloudGoat is Rhino Security Labs' "Vulnerable by Design" cloud deployment tool._

<p align="center">
  <img src="https://rhinosecuritylabs.com/wp-content/uploads/2018/07/cloudgoat-e1533043938802-1140x400.jpg" width=350/>
</p>


# Quick reference
- **Where to get help**:
[the Rhino Security Labs Discord](https://discord.gg/xFXmqytprV), or [Stack Overflow](https://stackoverflow.com/search?tab=newest&q=cloudgoat)

- **Where to file issues**:
[https://github.com/RhinoSecurityLabs/cloudgoat/issues](https://github.com/RhinoSecurityLabs/cloudgoat/issues)

- **Maintained by**:
[the CloudGoat Community](https://github.com/RhinoSecurityLabs/cloudgoat)

# CloudGoat 2.0 is here!

CloudGoat is Rhino Security Labs' "Vulnerable by Design" cloud deployment tool. It allows you to hone your cloud cybersecurity skills by creating and completing several "capture-the-flag" style scenarios. Each scenario is composed of cloud resources arranged together to create a structured learning experience. Some scenarios are easy, some are hard, and many offer multiple paths to victory. As the attacker, it is your mission to explore the environment, identify vulnerabilities, and exploit your way to the scenario's goal(s).

Below are our main goals for CloudGoat:

* **Focused, Curated, High-Quality Learning Experiences** - Each of CloudGoat’s scenarios should provide the opportunity for experimentation, exploration, and building hands-on cloud security skills.
* **Good Documentation** - We've done our best to ensure that CloudGoat’s scenarios are well-documented and easy to understand and evaluate in terms of difficulty, content, structure, and skills-required.
* **Easy to Install and Use** - We understand that CloudGoat is a means to an end - learning and practicing cloud security penetration testing. Therefore, we aim to keep things simple, straightforward, and reliable.
* **Modularity** - Each scenario is a standalone learning environment with a clear goal (or set of goals), and CloudGoat is able to start up, reset, or shut down each scenario independently.
* **Expandability** - CloudGoat’s core components (python app and scenarios) are designed to permit easy and independent expansion - by us or the community.

Before you proceed, please take note of these warnings!

> **Warning #1:** CloudGoat creates intentionally vulnerable resources into your account. DO NOT deploy CloudGoat in a production environment or alongside any sensitive resources.

> **Warning #2:** CloudGoat can only manage resources it creates. If you create any resources yourself in the course of a scenario, you should remove them manually before running the `destroy` command.

## Requirements

* Linux or MacOS. Windows is not officially supported.
  * Argument tab-completion requires bash 4.2+ (Linux, or OSX with some difficulty).
* Python3.9+ is required.
* Terraform >= 1.5.0 [installed and in your $PATH](https://learn.hashicorp.com/terraform/getting-started/install.html).
* The AWS CLI [installed and in your $PATH](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html), and an AWS account with sufficient privileges to create and destroy resources.
* The AZ CLI [installed and in your $PATH](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli#install), and an Azure account with sufficient privileges to create and destroy resources.
* [jq](https://stedolan.github.io/jq/)

Linux
```bash
sudo apt install terraform awscli azure-cli jq -y
```

Mac
```bash
brew install terraform awscli azure-cli jq
```

## Quick Start

To install CloudGoat, make sure your system meets the requirements above, and then run the following commands:

```bash
pipx install cloudgoat
```
You may also want to run some quick configuration commands - it'll save you some time later:

Configure for AWS - tell CloudGoat which AWS profile to use.
```bash
cloudgoat config aws
```
Configure for Azure - tell CloudGoat which Azure subscription to use.
```bash
cloudgoat config azure
```
Log in to Azure - CloudGoat uses the active `az` account.
```bash
az login
```

Configure whitelist
```bash
cloudgoat config whitelist --auto
```
Now, at your command, CloudGoat can `create` an instance of a scenario in the cloud. When the environment is ready, a new folder will be created in the project base directory named after the scenario and with a unique scenario ID appended. Inside this folder will be a file called `start.txt`, which will contain all of the resources you'll need to begin the scenario, though these are also printed to your console when the `create` command completes. Sometimes an SSH keypair named `cloudgoat`/`cloudgoat.pub` will be created as well.

> **Note:** Don't delete or modify the scenario instance folder or the files inside, as this could prevent CloudGoat from being able to manage your scenario's resources.

As you work through the scenario, feel free to refer to the scenario's readme if you need direction. If you get stuck, there are cheat sheets linked at the bottom of each route's walkthrough.

When you are finished with the scenario, delete any resources you created yourself (remember: CloudGoat can only manage resources it creates) and then run the `destroy` command. It's always a good idea to take a quick glance at your web-console afterwards - just in case something didn't get deleted.

You can read the full documentation for CloudGoat's commands [here in the Usage Guide section](#usage-guide).

## How to use CloudGoat's Docker image

[![Try in PWD](https://github.com/play-with-docker/stacks/raw/cff22438cb4195ace27f9b15784bbb497047afa7/assets/images/button.png)](http://play-with-docker.com?stack=https://raw.githubusercontent.com/RhinoSecurityLabs/cloudgoat/master/docker_stack.yml)

### Option 1: Run with default entrypoint
```console
docker run -it rhinosecuritylabs/cloudgoat:latest
```

### Option 2: Run with AWS config and credentials

> Warning: Running this command will mount your local AWS configuration files into the Docker container when it is launched. This means that any user with access to the container will have access to your host computer's AWS credentials.

```console
docker run -it -v ~/.aws:/root/.aws/ rhinosecuritylabs/cloudgoat:latest
```

## Scenarios Available
(Grouped by Difficulty)

<details open>
  <summary><strong>Easy</strong></summary>

---

### data_secrets (Easy)
`cloudgoat create data_secrets`

In this scenario, you start with an IAM user with limited permissions. Your task is to identify a misconfigured EC2 instance leaking credentials in its User Data, allowing you to gain SSH access. From there, you must pivot by exploiting the Instance Metadata Service (IMDS) to steal a role, enumerate Lambda functions to find hidden environment variables, and finally compromise a user with access to the scenario's objective: a secret stored in AWS Secrets Manager.

[Visit Scenario Page.](cloudgoat/scenarios/aws/data_secrets/README.md)  

Contributed by Tyler Ramsbey
---

### beanstalk_secrets (Easy)
`cloudgoat create beanstalk_secrets`

In this scenario, you are provided with low-privileged AWS credentials that grant limited access to Elastic Beanstalk. Your task is to enumerate the Elastic Beanstalk environment and discover misconfigured environment variables containing secondary credentials. Using these secondary credentials, you can enumerate IAM permissions to eventually create an access key for an administrator user. With these admin privileges, you retrieve the final flag stored in AWS Secrets Manager.

[Visit Scenario Page.](cloudgoat/scenarios/aws/beanstalk_secrets/README.md)  

Contributed by Tyler Ramsbey

---

### sns_secrets (Easy)
`cloudgoat create sns_secrets`

In this scenario, you start with basic access to an AWS account. You need to enumerate your privileges, discover an SNS Topic you can subscribe to, retrieve a leaked API Key, and finally use the API Key to access an API Gateway for the final flag.  

[Visit Scenario Page.](cloudgoat/scenarios/aws/sns_secrets/README.md)  

Contributed by Tyler Ramsbey

---

### iam_privesc_by_key_rotation (Easy)
`cloudgoat create iam_privesc_by_key_rotation`

Exploit insecure IAM permissions to escalate your access. Start with a role that manages other users' credentials and find a weakness in the setup to access the "admin" role. Using the admin role, retrieve the flag from Secrets Manager.

[Visit Scenario Page.](cloudgoat/scenarios/aws/iam_privesc_by_key_rotation/README.md)

Contributed by Infrasec.sh 

---

### iam_privesc_by_rollback (Easy)
`cloudgoat create iam_privesc_by_rollback`

Starting with a highly-limited IAM user, the attacker is able to review previous IAM policy versions and restore one which allows full admin privileges, resulting in a privilege escalation exploit.

[Visit Scenario Page.](cloudgoat/scenarios/aws/iam_privesc_by_rollback/README.md)

---

### lambda_privesc (Easy)
`cloudgoat create lambda_privesc`

Starting as the IAM user Chris, the attacker discovers that they can assume a role that has full Lambda access and pass role permissions. The attacker can then perform privilege escalation using these new permissions to obtain full admin privileges.

> **Note:** This scenario may require you to create some AWS resources, and because CloudGoat can only manage resources it creates, you should remove them manually before running `./cloudgoat destroy`.

[Visit Scenario Page.](cloudgoat/scenarios/aws/lambda_privesc/README.md)

---

### sqs_flag_shop (Easy)
`cloudgoat create sqs_flag_shop`

First, start with the SHOP page where you can buy FLAG. The website has a number of pages, and you can see that the source code is exposed. Attackers analyze the code to find vulnerabilities and use their privileges to purchase FLAG.

[Visit Scenario Page.](cloudgoat/scenarios/aws/sqs_flag_shop/README.md)
  
</details>

<details>
  <summary><strong>Medium</strong></summary>

### static (Medium)
`cloudgoat create static`

In this scenario, you act as an external attacker visiting a corporate portal. By analyzing the web application, you identify that it loads critical JavaScript libraries from a public S3 bucket. You must discover a misconfiguration in the bucket's permissions, perform a "Supply Chain Attack" by overwriting the library with malicious code, and wait for an internal administrator bot to log in. Your goal is to capture the bot's credentials and exfiltrate them back to the bucket.

[Visit Scenario Page.](cloudgoat/scenarios/aws/static/README.md)  

### vulnerable_cognito (Medium)
`cloudgoat create vulnerable_cognito`

In this scenario, you are presented with a signup and login page with AWS Cognito in the backend. You need to bypass restrictions and exploit misconfigurations in Amazon Cognito in order to elevate your privileges and get Cognito Identity Pool credentials.

[Visit Scenario Page.](cloudgoat/scenarios/aws/vulnerable_cognito/README.md)

Contributed by TrustOnCloud 

---
### vulnerable_lambda (Medium)
`cloudgoat create vulnerable_lambda`

In this scenario, you start as the 'bilbo' user. You will assume a role with more privileges, discover a lambda function that applies policies to users, and exploit a vulnerability in the function to escalate the privileges of the bilbo user in order to search for secrets.  

[Visit Scenario Page.](cloudgoat/scenarios/aws/vulnerable_lambda/README.md)

---

### cloud_breach_s3 (Medium)
`cloudgoat create cloud_breach_s3`

Starting as an anonymous outsider with no access or privileges, exploit a misconfigured reverse-proxy server to query the EC2 metadata service and acquire instance profile keys. Then, use those keys to discover, access, and exfiltrate sensitive data from an S3 bucket.

[Visit Scenario Page.](cloudgoat/scenarios/aws/cloud_breach_s3/README.md)

---

### iam_privesc_by_attachment (Medium)
`cloudgoat create iam_privesc_by_attachment`

Starting with a very limited set of permissions, the attacker is able to leverage the instance-profile-attachment permissions to create a new EC2 instance with significantly greater privileges than their own. With access to this new EC2 instance, the attacker gains full administrative powers within the target account and is able to accomplish the scenario's goal - deleting the cg-super-critical-security-server and paving the way for further nefarious actions.

> **Note:** This scenario may require you to create some AWS resources, and because CloudGoat can only manage resources it creates, you should remove them manually before running `./cloudgoat destroy`.

[Visit Scenario Page.](cloudgoat/scenarios/aws/iam_privesc_by_attachment/README.md)

---

### ec2_ssrf (Medium)
`cloudgoat create ec2_ssrf`

Starting as the IAM user Solus, the attacker discovers they have ReadOnly permissions to a Lambda function, where hardcoded secrets lead them to an EC2 instance running a web application that is vulnerable to server-side request forgery (SSRF). After exploiting the vulnerable app and acquiring keys from the EC2 metadata service, the attacker gains access to a private S3 bucket with a set of keys that allow them to invoke the Lambda function and complete the scenario.

[Visit Scenario Page.](cloudgoat/scenarios/aws/ec2_ssrf/README.md)

---

### ecs_takeover (Medium)
`cloudgoat create ecs_takeover`

Starting with access to the external website, the attacker needs to find a remote code execution vulnerability. By using RCE the attacker can get access to resources available to the website container. Abusing several ECS misconfigurations the attacker gains access to IAM permissions that allow them to force ECS into rescheduling the target container to a compromised instance.

[Visit Scenario Page.](cloudgoat/scenarios/aws/ecs_takeover/README.md)

---

### rds_snapshot (Medium)
`cloudgoat create rds_snapshot`

In this scenario, we start with the user 'David'. Through David, you can leverage privileges to steal credentials.
With the stolen credentials, an attacker can leverage the RDS vulnerability to access the DB and retrieve flags.

> **Note:** This scenario may require you to create some AWS resources, and because CloudGoat can only manage resources it creates, you should remove them manually before running `./cloudgoat destroy`. 

[Visit Scenario Page.](cloudgoat/scenarios/aws/rds_snapshot/README.md)

---

### glue_privesc (Medium)
`cloudgoat create glue_privesc`  

This scenario starts with a web page that uploads a CSV file and performs data visualization through the Glue service.
The attacker steals the credentials present on the webpage via a SQL injection attack and uploads a reverse shell to create a Glue Job to obtain the secret string.

> **Note:** This scenario may require you to create some AWS resources, and because CloudGoat can only manage resources it creates, you should remove them manually before running `./cloudgoat destroy`.  

[Visit Scenario Page.](cloudgoat/scenarios/aws/glue_privesc/README.md)

---

### agentcore_identity_confusion (Medium)
`cloudgoat create agentcore_identity_confusion`

In this scenario, you are provided with AWS credentials that can manage bedrock agentcore code interpreters. Your task is to leverage this to gain access to sensitive data used by other agentcore runtime agents. Figure out how to gain access to the flag stored in a bedrock knowledgebase.

> **Note:** This scenario may require you to create some AWS resources, and because CloudGoat can only manage resources it creates, you should remove them manually before running `./cloudgoat destroy`.

[Visit Scenario Page.](cloudgoat/scenarios/aws/agentcore_identity_confusion/README.md)

Contributed by Sonrai Security

---

### bedrock_agent_hijacking (Medium)
`cloudgoat create bedrock_agent_hijacking`

In this scenario, you are provided with AWS credentials that can invoke a Bedrock Agent and update lambda functions. Your task is to analyze the agent and understand how it accesses real-time information. Tap into this flow to locate and extract the flag stored in S3.

[Visit Scenario Page.](cloudgoat/scenarios/aws/bedrock_agent_hijacking/README.md)

Contributed by Sonrai Security

</details>

<details>
  <summary><strong>Hard</strong></summary>

### rce_web_app (Hard)
`cloudgoat create rce_web_app`

Starting as the IAM user Lara, the attacker explores a Load Balancer and S3 bucket for clues to vulnerabilities, leading to an RCE exploit on a vulnerable web app which exposes confidential files and culminates in access to the scenario’s goal: a highly-secured RDS database instance.

Alternatively, the attacker may start as the IAM user McDuck and enumerate S3 buckets, eventually leading to SSH keys which grant direct access to the EC2 server and the database beyond.

[Visit Scenario Page.](cloudgoat/scenarios/aws/rce_web_app/README.md)

---

### codebuild_secrets (Hard)
`cloudgoat create codebuild_secrets`

Starting as the IAM user Solo, the attacker first enumerates and explores CodeBuild projects, finding unsecured IAM keys for the IAM user Calrissian therein. Then operating as Calrissian, the attacker discovers an RDS database. Unable to access the database's contents directly, the attacker can make clever use of the RDS snapshot functionality to acquire the scenario's goal: a pair of secret strings.

Alternatively, the attacker may explore SSM parameters and find SSH keys to an EC2 instance. Using the metadata service, the attacker can acquire the EC2 instance-profile's keys and push deeper into the target environment, eventually gaining access to the original database and the scenario goal inside (a pair of secret strings) by a more circuitous route.

> **Note:** This scenario may require you to create some AWS resources, and because CloudGoat can only manage resources it creates, you should remove them manually before running `./cloudgoat destroy`.

[Visit Scenario Page.](cloudgoat/scenarios/aws/codebuild_secrets/README.md)

---

### detection_evasion (Hard)
`cloudgoat create detection_evasion`

The goal of this scenario is to read out the values for both secrets without being detected. The secrets are both stored in Secrets Manager, and their values have the following format (cg-secret-XXXXXX-XXXXXX).

This scenario is significantly different from other CloudGoat scenarios. In detection_evasion, your goals will be outlined for you more clearly, and the challenge is to complete them without triggering alarms. There is more setup involved in this scenario, and it will take longer to play (you might want/need to play it multiple times).

[Visit Scenario Page.](cloudgoat/scenarios/aws/detection_evasion/README.md)

---

### ecs_efs_attack (Hard)
`cloudgoat create ecs_efs_attack`

Starting with access to the "ruse" EC2, the user leverages the instance profile to backdoor the running ECS container. Using the backdoored container the attacker can retrieve credentials from the container metadata API. These credentials allow the attacker to start a session on any EC2 with the proper tags set. The attacker uses their permissions to change the tags on the Admin EC2 and starts a session. Once in the Admin EC2, the attacker will port scan the subnet for an open EFS to mount. Once mounted, the attacker can retrieve the flag from the elastic file system.

[Visit Scenario Page.](cloudgoat/scenarios/aws/ecs_efs_attack/README.md)

---

### ecs_privesc_evade_protection (Medium)
`cloudgoat create ecs_privesc_evade_protection`

A user begins by accessing a working web service to a container inside EC2. The attacker can exploit a web service vulnerability to get credentials from the metadata API in EC2, or to control the container. This credential allows the attacker to initiate a new container with a specific role and control it. Based on this action, make a privilege escalation, and read FLAG in S3.

> **Note:** This scenario requires Docker to be installed locally, as it builds and pushes a container image to ECR during deployment.

[Visit Scenario Page.](cloudgoat/scenarios/aws/ecs_privesc_evade_protection/README.md)

---

### secrets_in_the_cloud (Hard)
`cloudgoat create secrets_in_the_cloud`

As an IAM user with limited privileges, the attacker initiates their journey by examining AWS resources to uncover clues and hidden information. This investigation ultimately results in acquiring a role that grants access to the scenario's primary objective: retrieving the final secret from Secrets Manager.

[Visit Scenario Page.](cloudgoat/scenarios/aws/secrets_in_the_cloud/README.md)
  
</details>



## Usage Guide

The basic anatomy of a CloudGoat command is as follows:

> `cloudgoat [ command ] [ sub-command ] [ --arg-name ] [ arg-value ]`

The five main commands in CloudGoat are summarized below:

### create

`create [ scenario-name ]` deploys a scenario to the AWS account of your choosing. You can also run `create` against an existing scenario if you wish - CloudGoat will simply destroy and recreate the scenario named.

> **Tip:** you can use `/scenarios` in the name, which allows for bash's native tab-completion.

Note that the `--profile` is required for safety reasons - we don't want anyone accidentally deploying CloudGoat scenarios to a production environment - and CloudGoat will not use the system's "default" AWS CLI profiles or profiles specified as defaults via environment variables. You can, however, set this via `config aws` to avoid having to provide it every time.

### list

`list` shows some information about `all`, `undeployed`, or `deployed` scenarios, or even a lot of information about a `[ scenario-name ]` that's already deployed. You can also filter scenarios by cloud platform: `list aws` or `list azure`.

### destroy

`destroy` shuts down and deletes a `[ scenario-name ]`'s cloud resources, and then moves the scenario instance folder to `./trash` - just in case you need to recover the Terraform state file or other scenario files. You can also specify `all` instead of a scenario name to destroy all active scenarios.

> **Tip:** CloudGoat can only manage resources it creates. If you create any resources yourself in the course of a scenario, you should remove them manually before running the `destroy` command.

### config

`config` allows you to manage various aspects of your CloudGoat installation, specially the IP `whitelist`, your default AWS `profile`, and tab-completion via `argcomplete`. It's worth briefly describing what each of these sub-commands do.

#### whitelist

CloudGoat needs to know what IP addresses should be whitelisted when potentially-vulnerable resources are deployed in the cloud, and these IPs are tracked in a `./whitelist.txt` file in the base project directory. The IP address you provide for whitelisting doesn't _have_ to be in CIDR format, but CloudGoat will add a `/32` to any naked IPs you provide. Optionally, you can add the `--auto` argument, and CloudGoat will automatically make a network request, using curl to ifconfig.co to find your IP address, and then create the whitelist file with the result.

#### aws

While CloudGoat will not ever use the system's "default" AWS CLI profiles or profiles specified as defaults via environment variables, you can instruct CloudGoat to use a particular AWS profile by name using the `config aws` command. This will prompt for and save your profile's name in a `config.yml` file in the base project directory. As long as that file is present CloudGoat will use the profile name listed inside for create and destroy commands, rather than requiring the `--profile` flag. You can run the `config aws` command at any time to view the name of your CloudGoat-default profile and validate the format of the `config.yml`. You can also create `config.yml` manually, if you wish, provided that you use the correct format.

#### azure

Newer versions of the Azure provider for Terraform require the subscription ID to apply resources to. While CloudGoat uses the same credential configuration as the `az` util, CloudGoat must be told explicitly which subscription to deploy to. The configuration is done with `cloudgoat config azure`, and the subscription is stored in `config.yml` alongside the aws configuration. You can also create `config.yml` manually, if you wish, provided you use the correct format.

#### argcomplete

We really wanted to have native tab-completion in CloudGoat, but as it turns out that was somewhat difficult to do outside of a REPL. It should work reasonably well for Linux users, and those OSX users brave enough to figure out a way to upgrade their bash version to 4.2+. CloudGoat does include and support [the python library "argcomplete"](https://github.com/kislyuk/argcomplete). A brief summary of how to install argcomplete is provided below, though for more detailed steps you should refer to the official documentation at the library's [github page](https://github.com/kislyuk/argcomplete).

1. Install the argcomplete Python package using CloudGoat's requirements.txt file: `$ pip3 install -r core/python/requirements.txt`
2. In bash, run the global Python argument completion script provided by the argcomplete package: `$ activate-global-python-argcomplete`
3. Source the completion script at the location printed by the previous activation command, or restart your shell session: `$ source [ /path/to/the/completion/script ]`

For those who cannot or do not wish to configure argcomplete, CloudGoat also supports the use of directory paths as scenario names, which means tab-completion will work for scenario names. Just use `/scenario/[ scenario-name ]` or `./[ scenarioinstance-name ]` and your shell should do the rest.

### help

`help` provides contextual help about commands. `help` can come before or after the command in question, so it's always there when you need it. Below are some examples:

* `cloudgoat create help`
* `cloudgoat destroy help`
* `cloudgoat list help`
* `cloudgoat config help`

One other use of note: `cloudgoat [ scenario-name ] help` can be used to print to the console a brief summary of the scenario, as defined by the scenario's author.

## Feature Requests and Bug Reports

If you have a feature request or a bug to report, please [submit them here](https://github.com/RhinoSecurityLabs/cloudgoat/issues/new).

For bugs, please make sure to include a description sufficient to reproduce the bug you found, including tracebacks and reproduction steps, and check for other reports of your bug before filing a new bug report.

For features, much the same applies! Be specific in your request, and make sure someone else hasn't already requested the same feature.

## Contribution Guidelines

Contributions to CloudGoat are greatly appreciated. If you'd like to help make the project better, read on.

1. **Creating a New Scenario**:
   - We have provided a scenario template to help you get started quickly. The template includes the basic structure and necessary files for a CloudGoat scenario. You can find the scenario template [here](/scenarios/scenario_template).
   - **Steps to Create a New Scenario**:
     - **Copy the Template**: Copy the contents of the scenario template to a new directory named after your scenario.
     - **Modify the Template**: Replace the placeholder content in the template with the specifics of your new scenario.
     - **Test the Scenario**: Ensure that your scenario works as expected by testing it thoroughly.
2. **Coding Standards**:
   - **Code Style**: Follow the existing code style in the project. Consistency is key.
   - **Comments**: Add comments to your code where necessary to explain complex logic or important decisions.
   - **Documentation**: Update the README.md and other relevant documentation to include details about your new scenario or changes.
3. **Whitelisting**:
   - When creating or modifying scenarios, keep the following in mind:
     - **Whitelisting**: Ensure that security group rules and other access controls are configured to whitelist only the IP from the CloudGoat configuration.
     - **Review**: Double-check your configurations for any potentially vulnerable public resources before contributing (i.e. do not create vulnerable EC2s accessible to the internet). 
4. **Python Code Style**:
   - Python code in CloudGoat should generally follow Python's style conventions, favoring readability and maintainability above all.
   - Follow good git practices: use pull requests, prefer feature branches, always write clear commit messages.
   - CloudGoat uses `black` and `flake8` - Python syntax and style linters. Ensure that both `flake8` and `black` are run on all Python files in `core/python/` and on `cloudgoat.py` before committing code. `black`'s decisions take priority over `flake8`'s. Both of these are commented out in the `core/python/requirements.txt` file since normal users don't need them.
5. **Licensing**:
   - CloudGoat code should always use the BSD 3-clause license.

And lastly, thank you for contributing!


## Changelog

- **6/24/19:** CloudGoat 2.0 is released!

## Disclaimer

CloudGoat is software that comes with absolutely no warranties whatsoever. By using CloudGoat, you take full responsibility for any and all outcomes that result.