diff --git a/docs/content/development/contribute-documentation.md b/docs/content/development/contribute-documentation.md index f4c888ac9..9e6dc890e 100644 --- a/docs/content/development/contribute-documentation.md +++ b/docs/content/development/contribute-documentation.md @@ -2,6 +2,7 @@ title: "Contribute Documentation" date: 2020-06-17T17:31:54+03:00 draft: false +tags: ["contribute"] --- The `/docs` folder contains the Monkey Documentation site. diff --git a/docs/content/development/setup-development-environment.md b/docs/content/development/setup-development-environment.md index d965024ef..ff0d6445f 100644 --- a/docs/content/development/setup-development-environment.md +++ b/docs/content/development/setup-development-environment.md @@ -2,6 +2,7 @@ title: "Setting up a development environment" date: 2020-06-08T19:53:00+03:00 draft: false +tags: ["contribute"] --- ## Deployment scripts diff --git a/docs/content/setup/_index.md b/docs/content/setup/_index.md index 89100cde1..77a92fba5 100644 --- a/docs/content/setup/_index.md +++ b/docs/content/setup/_index.md @@ -9,7 +9,7 @@ tags = ["setup"] # Setting up Infection Monkey -Setting up Infection Monkey is really easy! First, you need to [download the Infection Monkey from our site](https://infectionmonkey.com/). +Setting up Infection Monkey is really easy! First, you need to {{% button href="https://infectionmonkey.com/" icon="fas fa-download" %}}download the Infection Monkey from our site{{% /button %}}. Once you've downloaded an installer, you can follow the relevant guide for your environment: diff --git a/docs/content/setup/aws.md b/docs/content/setup/aws.md index 48142114d..bcbfaeb75 100644 --- a/docs/content/setup/aws.md +++ b/docs/content/setup/aws.md @@ -28,6 +28,10 @@ You will be presented a login page. Use the username **monkey**, and the new EC2 ![AWS instance ID](../../images/setup/aws/aws-instance-id.png "AWS instance ID") +## Integration with AWS services + +The Monkey has built-in integrations with AWS services for better execution and reporting. See [Usage -> Integrations](../../usage/integrations) for more details. + ## Upgrading Currently there's no "upgrade-in-place" option when a new version comes out. To get the new version, you can deploy a new machine from the marketplace. If you'd like to keep your existing configuration, you can export it to a file by using the Export button and then import it to the new Monkey Island. diff --git a/docs/content/usage/accounts-and-security.md b/docs/content/usage/accounts-and-security.md index 688ea3fe7..574b07c3c 100644 --- a/docs/content/usage/accounts-and-security.md +++ b/docs/content/usage/accounts-and-security.md @@ -4,6 +4,7 @@ date: 2020-06-22T15:36:56+03:00 draft: false weight: 50 pre: " " +tags: ["usage", "password"] --- ## Security in Infection Monkey diff --git a/docs/content/usage/configuration/_index.md b/docs/content/usage/configuration/_index.md index d8cff50e7..f10d81ce1 100644 --- a/docs/content/usage/configuration/_index.md +++ b/docs/content/usage/configuration/_index.md @@ -11,6 +11,10 @@ pre: " " The Monkey is highly configurable. Nearly every part of it can be modified to turn it to a fast acting worm or into a port scanning and system information collecting machine. +{{% notice warning %}} +This section of the documentation is incomplete and under active construction. +{{% /notice %}} + See these documentation pages for information on each configuration value: {{% children description=true %}} diff --git a/docs/content/usage/configuration/basic-credentials.md b/docs/content/usage/configuration/basic-credentials.md index 10102f860..ffd6a87e4 100644 --- a/docs/content/usage/configuration/basic-credentials.md +++ b/docs/content/usage/configuration/basic-credentials.md @@ -2,7 +2,9 @@ title: "Credentials" date: 2020-06-09T12:20:08+03:00 draft: false -description: "Configure credentials that the Monkey uses for propagation" +description: "Configure credentials that the Monkey will use for propagation." --- In this screen you can feed the Monkey with “stolen” credentials for your network, simulating an attacker with inside knowledge. + +![Configure credentials](/images/usage/configruation/credentials.png "Configure credentials") diff --git a/docs/content/usage/configuration/basic-network.md b/docs/content/usage/configuration/basic-network.md index bee2a10b2..410f7a2ee 100644 --- a/docs/content/usage/configuration/basic-network.md +++ b/docs/content/usage/configuration/basic-network.md @@ -2,7 +2,7 @@ title: "Network" date: 2020-06-09T12:20:14+03:00 draft: false -description: "Configure settings related to the Monkey's network activity" +description: "Configure settings related to the Monkey's network activity." --- Here you can control multiple important settings, such as: diff --git a/docs/content/usage/getting-started.md b/docs/content/usage/getting-started.md index 0566b6b8c..d17126762 100644 --- a/docs/content/usage/getting-started.md +++ b/docs/content/usage/getting-started.md @@ -4,6 +4,7 @@ date: 2020-05-26T21:01:12+03:00 draft: false weight: 1 pre: " " +tags: ["usage"] --- ## Using the Infection Monkey @@ -27,6 +28,10 @@ To run the monkey, select one of the following options: ![Run on machine of your choice](/images/usage/getting-started/run_page_button_no_arrow.jpg "Run on machine of your choice") +{{% notice tip %}} +If you're running in an AWS cloud environment, check out [Usage -> Integrations](../../usage/integrations) for information about how Monkey integrates with AWS. +{{% /notice %}} + ### Infection Map Next, click **Infection Map** to see the Infection Monkey in action. diff --git a/docs/content/usage/integrations/_index.md b/docs/content/usage/integrations/_index.md new file mode 100644 index 000000000..a7e2157f6 --- /dev/null +++ b/docs/content/usage/integrations/_index.md @@ -0,0 +1,14 @@ +--- +title: "Integrations" +date: 2020-06-28T10:38:05+03:00 +draft: false +chapter: true +weight: 10 +pre: " " +--- + +# Integrate the Monkey with 3rd party software + +The Monkey likes working together. See these documentation pages for information on each integration the Monkey currently offers: + +{{% children description=true %}} diff --git a/docs/content/usage/integrations/aws-run-on-ec2-machine.md b/docs/content/usage/integrations/aws-run-on-ec2-machine.md new file mode 100644 index 000000000..0183dc241 --- /dev/null +++ b/docs/content/usage/integrations/aws-run-on-ec2-machine.md @@ -0,0 +1,150 @@ +--- +title: "Running the monkey on AWS EC2 instances" +date: 2020-06-28T10:44:05+03:00 +draft: false +description: "Use AWS SSM to execute Infection Monkey on your AWS instances." +tags: ["aws", "integration"] +--- + +## When to use this feature + +If your network is deployed on Amazon Web Services (with EC2 instances), and you'd like to run the Infection Monkey in order to test it, this page is for you. You can easily run the monkey on **various instances** within your network - in a secure fashion, **without** feeding the Island with any credentials or running shell commands on the machines you want to test. + +The results will be exported to AWS security hub automatically, as well. To see more information about that, see the [Infection Monkey and AWS Security Hub documentation](https://github.com/guardicore/monkey/wiki/Infection-Monkey-and-AWS-Security-Hub). + +![AWS EC2 logo](/images/usage/integrations/aws-ec2.svg?height=250px "AWS EC2 logo") + +## Setup + +Assuming your network is already set up in AWS EC2, follow these quick steps to get up and running. + +### Monkey Island deployment + +In order to run the Monkeys directly from the Monkey Island server, you need to deploy the Monkey Island server to an AWS EC2 instance in the same network which you want to test. For information about deploying the Monkey Island server, see [setup](../../../setup). + +### Setup IAM roles + +In order for the Island to successfully view your instances, you'll need to set appropriate IAM roles to your instances. You can read more about IAM roles [in Amazon's documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html), but it's not necessary in order to follow this setup. + +#### Creating a custom IAM role + +Go to the [AWS IAM roles dashboard](https://console.aws.amazon.com/iam/home?#/roles) and create a new IAM role for EC2. The role will need to have some specific permissions (see Appendix A), but you can just create a role with the `AmazonEC2RoleforSSM`, `AWSSecurityHubFullAccess` and `AmazonSSMFullAccess` pre-made permissions. In the end it should like something like this: + +![Creating a custom IAM role](/images/usage/integrations/monkey-island-aws-screenshot-3.png "Creating a custom IAM role") + +#### Applying the IAM role to an instance + +For each instance you'd like to access from the island, apply the new IAM role you've just created to the instance. For example: + +![Applying a custom IAM role](/images/usage/integrations/monkey-island-aws-screenshot-4.png "Applying a custom IAM role") + +After applying the IAM role you should see this screen: + +![Applying a custom IAM role](/images/usage/integrations/monkey-island-aws-screenshot-5.png "Applying a custom IAM role") + +**Note: after setting IAM roles, the roles might take a few minutes (up to 10 minutes sometimes) to effectively kick in.** This is how AWS works and is not related to the Monkey implementation. See [this StackOverflow thread for more details.](https://stackoverflow.com/questions/20156043/how-long-should-i-wait-after-applying-an-aws-iam-policy-before-it-is-valid) + +### Setup SSM agent + +If your EC2 instances don't have the _SSM agent_ installed, they will not be able to execute SSM commands, which means you won't see them in the AWS machines table on the monkey island. Generally speaking, most new EC2 instances ought to have SSM pre-installed; The SSM Agent is installed, by default, on Amazon Linux base AMIs dated 2017.09 and later, and on Amazon Linux 2, Ubuntu Server 16.04, and Ubuntu Server 18.04 LTS AMIs. + +See [Amazon's documentation about working with SSM agents](https://docs.aws.amazon.com/systems-manager/latest/userguide/ssm-agent.html) for more details on how to check if you have an SSM agent and how to manually install one if you don't have one. + +## Usage + +### Running the monkey + +When you run the monkey island on an AWS instance, the island detects it's running on AWS and present the following option in the _"Run Monkey"_ page, like so: + +![Running a Monkey on EC2 Instance](/images/usage/integrations/monkey-island-aws-screenshot-1.png "Running a Monkey on EC2 Instance") + +And then you can choose one of the available instances as "patient zero" like so: + +1. Click on "Run on AWS" +2. Choose the relevant Network Interface +3. Select the machines you'd like to run the Monkey on +4. Click "Run on Selected Machines", and watch the monkey go! 🐒 + +![Running a Monkey on EC2 Instance](/images/usage/integrations/monkey-island-aws-screenshot-2.png "Running a Monkey on EC2 Instance") + +## Notes + +- The machines which can use IAM roles and be listed MUST be internet connected (or you can set up a proxy for IAM). This is standard AWS practice and you can read about it (and about how to set up the required proxy machines) in AWS IAM documentation. +- You can see the monkey in [the AWS marketplace](https://aws.amazon.com/marketplace/pp/B07B3J7K6D). + +### Appendix A: Specific policy permissions required + +The IAM role will need to have, at least, the following specific permissions: + +#### For executing the Monkey on other machines - SSM + +- `"ssm:SendCommand"` +- `"ssm:DescribeInstanceInformation"` +- `"ssm:GetCommandInvocation"` + +Here's the policy of the IAM role, as a JSON object: +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "VisualEditor0", + "Effect": "Allow", + "Action": [ + "ssm:SendCommand", + "ssm:DescribeInstanceInformation", + "ssm:GetCommandInvocation" + ], + "Resource": "*" + } + ] +} +``` + +#### For exporting security findings to the Security Hub - security hub + +_Note: these can be set on the Monkey Island machine alone, since it's the only one exporting findings to the AWS secutiry hub._ + +- `"securityhub:UpdateFindings"` +- `"securityhub:BatchImportFindings"` + +Here's the policy for SecurityHub, as a JSON object: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "VisualEditor0", + "Effect": "Allow", + "Action": [ + "securityhub:UpdateFindings", + "securityhub:BatchImportFindings" + ], + "Resource": "*" + } + ] +} +``` + +The JSON object for both of the policies combined therefore is: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "VisualEditor0", + "Effect": "Allow", + "Action": [ + "ssm:SendCommand", + "ssm:DescribeInstanceInformation", + "securityhub:UpdateFindings", + "securityhub:BatchImportFindings", + "ssm:GetCommandInvocation" + ], + "Resource": "*" + } + ] +} +``` diff --git a/docs/content/usage/integrations/aws-security-hub.md b/docs/content/usage/integrations/aws-security-hub.md new file mode 100644 index 000000000..364890b3a --- /dev/null +++ b/docs/content/usage/integrations/aws-security-hub.md @@ -0,0 +1,43 @@ +--- +title: "AWS Security Hub integration" +date: 2020-06-28T10:38:12+03:00 +draft: false +description: "Correlate the Monkey's findings with the native security solutions and benchmark scores." +tags: ["aws", "integration"] +--- + +The Infection Monkey integration with the [AWS Security Hub](https://docs.aws.amazon.com/securityhub/latest/userguide/what-is-securityhub.html) allows anyone to verify and test the resilience of their AWS environment and correlate this information with the native security solutions and benchmark score. + +![AWS security hub logo](/images/usage/integrations/AWS-Security-Hub-logo.png "AWS security hub logo") + +The integration will send _all_ Infection Monkey findings (typically low tens of findings) to the security hub at the end of a Monkey breach simulation. + +## Setup + +If the correct permissions have been set on the AWS IAM role of the Monkey Island machine, then the Island will automatically export its findings to the AWS security hub. + +### Specific permissions required for security hub + +- `"securityhub:UpdateFindings"` +- `"securityhub:BatchImportFindings"` + +Note that the integration is specifically between your Monkey Island and the security hub. The Infection Monkey is an free project and there is no centralised infrastructure. + +## Integration details + +The Infection Monkey reports the following types of issues to the AWS security hub: `Software and Configuration Checks/Vulnerabilities/CVE`. + +Specifically, the Island sends findings for all vulnerabilities it finds along with generic findings on the network (such as segmentation issues). Our normalized severity is 100, while most issues we report range between 1 and 10. + +## Regions + +The Infection Monkey is usable on all public AWS instances. + +## Example + +After setting up a monkey environment in AWS and attaching the correct IAM roles to the monkey island machine, the report findings were exported to the security hub. + +1. Navigate to `Findings`. +2. Press on a specific finding to see more details and possible solutions. + +![AWS Security hub console example](images/usage/integrations/security-hub-console-example.png "AWS Security hub console example") diff --git a/docs/content/usage/scenarios.md b/docs/content/usage/scenarios.md index 48fb97178..cb65816de 100644 --- a/docs/content/usage/scenarios.md +++ b/docs/content/usage/scenarios.md @@ -3,6 +3,7 @@ title: "Scenarios" date: 2020-05-26T21:01:19+03:00 draft: true weight: 2 +tags: ["usage"] --- In this page we show how you can use the Infection Monkey to simulate breach and attack scenarios as well as to share some cool tips and tricks you can use to up your Infection Monkey game. This page is aimed at both novice and experienced Monkey users. You can also refer to [our FAQ](../../faq) for more specific questions and answers. diff --git a/docs/static/images/usage/configruation/credentials.png b/docs/static/images/usage/configruation/credentials.png new file mode 100644 index 000000000..aeaea6ce3 Binary files /dev/null and b/docs/static/images/usage/configruation/credentials.png differ diff --git a/docs/static/images/usage/integrations/AWS-Security-Hub-logo.png b/docs/static/images/usage/integrations/AWS-Security-Hub-logo.png new file mode 100644 index 000000000..44236300b Binary files /dev/null and b/docs/static/images/usage/integrations/AWS-Security-Hub-logo.png differ diff --git a/docs/static/images/usage/integrations/Amazon_Web_Services_Logo.svg.png b/docs/static/images/usage/integrations/Amazon_Web_Services_Logo.svg.png new file mode 100644 index 000000000..c76f90a8c Binary files /dev/null and b/docs/static/images/usage/integrations/Amazon_Web_Services_Logo.svg.png differ diff --git a/docs/static/images/usage/integrations/aws-ec2.svg b/docs/static/images/usage/integrations/aws-ec2.svg new file mode 100644 index 000000000..2bbf9402b --- /dev/null +++ b/docs/static/images/usage/integrations/aws-ec2.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/static/images/usage/integrations/monkey-island-aws-screenshot-1.png b/docs/static/images/usage/integrations/monkey-island-aws-screenshot-1.png new file mode 100644 index 000000000..0b1af5fae Binary files /dev/null and b/docs/static/images/usage/integrations/monkey-island-aws-screenshot-1.png differ diff --git a/docs/static/images/usage/integrations/monkey-island-aws-screenshot-2.png b/docs/static/images/usage/integrations/monkey-island-aws-screenshot-2.png new file mode 100644 index 000000000..f6442e82b Binary files /dev/null and b/docs/static/images/usage/integrations/monkey-island-aws-screenshot-2.png differ diff --git a/docs/static/images/usage/integrations/monkey-island-aws-screenshot-3.png b/docs/static/images/usage/integrations/monkey-island-aws-screenshot-3.png new file mode 100644 index 000000000..1f1ae776c Binary files /dev/null and b/docs/static/images/usage/integrations/monkey-island-aws-screenshot-3.png differ diff --git a/docs/static/images/usage/integrations/monkey-island-aws-screenshot-4.png b/docs/static/images/usage/integrations/monkey-island-aws-screenshot-4.png new file mode 100644 index 000000000..58117738c Binary files /dev/null and b/docs/static/images/usage/integrations/monkey-island-aws-screenshot-4.png differ diff --git a/docs/static/images/usage/integrations/monkey-island-aws-screenshot-5.png b/docs/static/images/usage/integrations/monkey-island-aws-screenshot-5.png new file mode 100644 index 000000000..b8bf5d3af Binary files /dev/null and b/docs/static/images/usage/integrations/monkey-island-aws-screenshot-5.png differ diff --git a/docs/static/images/usage/integrations/security-hub-console-example.png b/docs/static/images/usage/integrations/security-hub-console-example.png new file mode 100644 index 000000000..232b51b42 Binary files /dev/null and b/docs/static/images/usage/integrations/security-hub-console-example.png differ