diff --git a/docs/cnspec/cloud/aws/README.mdx b/docs/cnspec/cloud/aws/README.mdx index 79fea0c12..d7c72fea8 100644 --- a/docs/cnspec/cloud/aws/README.mdx +++ b/docs/cnspec/cloud/aws/README.mdx @@ -22,6 +22,36 @@ To analyze and explore your AWS environment with cnspec, you must have: - Your AWS credentials. To learn about creating a new access key pair, read [Creating new access keys for an IAM user](https://docs.aws.amazon.com/keyspaces/latest/devguide/access.credentials.html#create.keypair) in the AWS documentation. - Your `AWS_REGION` configured. To learn how to set your region, read [How to set environment variables](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html#envvars-set) in the AWS documentation. +### Set up AWS credentials + +To ensure your AWS credentials are set up properly so you can scan from your workstation, run this command from a terminal: + +```bash +cat ~/.aws/credentials +[default] +aws_access_key_id = AKIAIOSFODNN7EXAMPLE +aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY +aws_session_token = AQoDYXdzEJr... +``` + +If you want to use a specific profile, set `AWS_PROFILE` + +```bash +export AWS_PROFILE=PROFILENAME +``` + +For PROFILENAME, substitute the name of the profile to use. + +### Permissions required to scan an AWS account + +cnspec requires read-only access to assess the configuration of the services and resources within an AWS account. It uses the credentials for the `awscli` to authenticate with the AWS API. So it inherits the permissions granted to your AWS access keys. + +:::info + +Amazon provides the **ReadOnlyAccess** IAM profile, which grants read-only access to all AWS Services. + +::: + ### Verify with a quick AWS check To quickly confirm that cnspec has access to your AWS environment, run this test from your terminal: @@ -38,6 +68,79 @@ cnspec returns `[ok]` to indicate that the test passed, and includes the actual [ok] value: "123456789000" ``` +### Scan an AWS account with cnspec + +To scan an AWS account remotely with cnspec, enter this command in a terminal: + +```bash +cnspec scan aws +``` + +cnspec scans the account using any AWS policies you have enabled in your Mondoo account. It prints the results to `STDOUT` on the command line. It also sends the results to Mondoo Platform, which generates a report for each policy executed against the account. + +### Manage multiple AWS profiles + +If you manage multiple AWS configurations in your credentials file, you can set the `AWS_PROFILE` environment variable to specify which profile to use for each scan. For example, this credentials file has two configurations: + +```bash title='~/.aws/credentials' +[default] +aws_access_key_id=AKIAIOSFODNN7EXAMPLE +aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY + +[aws-dev-account] +aws_access_key_id=AKIAI44QH8DHBEXAMPLE +aws_secret_access_key=je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY +``` + +When you run a scan, you specify which profile to use: + +```bash title="Select AWS profile to scan" +export AWS_PROFILE=PROFILENAME +cnspec scan aws +``` + +For PROFILENAME, substitute the name of the profile to use. + +### Incognito mode + +cnspec provides an `--incognito` mode, which lets you scan your AWS account against a specific policy without sending the results back to Mondoo Platform. This can be helpful for assessing how an account will score against a policy before enabling it. + +To scan an AWS account using `incognito` mode, enter this command in a terminal: + +```bash +cnspec scan aws --incognito +``` + +## Perform agentless scans of EC2 instances + +cnspec supports remote scanning of EC2 instances without installing an agent on the instance. This lets you assess your instances on demand. You must have remote connectivity to instances, either through SSH or EC2 Instance Connect. + +### Scan an EC2 instance using EC2 Instance Connect + +import Partial from "./_aws-incl-ic.mdx"; + +{" "} + +### Scan an EC2 instance using SSH + +cnspec lets you remotely scan EC2 instances using SSH: + +```bash +cnspec scan aws ec2 instance-connect USER@HOST --identity-file PATH +``` + +| For... | Substitute... | +| ------ | --------------------------------------- | +| USER | Your user name for the AWS account | +| HOST | The instance's public IP address or DNS | +| PATH | The path to the SSH key file | + +:::info + +To learn how to retrieve credentials from a secrets manager (such as AWS Secrets Manager or SSM Parameter Store), read [Secrets Management](/platform/infra/opsys/automation/vault.md). + +::: + ## Next step You've successfully used cnspec to run your first check against your AWS account. Now you're ready to [assess your AWS environment.](/cnspec/cloud/aws/account) diff --git a/docs/platform/infra/cloud/aws/_aws-incl-ic.mdx b/docs/cnspec/cloud/aws/_aws-incl-ic.mdx similarity index 100% rename from docs/platform/infra/cloud/aws/_aws-incl-ic.mdx rename to docs/cnspec/cloud/aws/_aws-incl-ic.mdx diff --git a/docs/platform/infra/cloud/aws/aws-ebs-snapshot-scan.mdx b/docs/cnspec/cloud/aws/aws-ebs-snapshot-scan.mdx similarity index 96% rename from docs/platform/infra/cloud/aws/aws-ebs-snapshot-scan.mdx rename to docs/cnspec/cloud/aws/aws-ebs-snapshot-scan.mdx index e865e7e4d..4bfc361ce 100644 --- a/docs/platform/infra/cloud/aws/aws-ebs-snapshot-scan.mdx +++ b/docs/cnspec/cloud/aws/aws-ebs-snapshot-scan.mdx @@ -1,7 +1,7 @@ --- title: Scan an EBS Snapshot sidebar_label: Scan an EBS Snapshot -sidebar_position: 9 +sidebar_position: 55 description: This document covers the configuration and use of the Mondoo AWS Integration to scan AWS accounts and EC2 Instances --- @@ -111,8 +111,8 @@ For SNAPSHOT_ID, substitute the ID of the snapshot, for example `snap-123456b123 | To learn about... | Read... | | --------------------------- | -------------------------------------------------------------------------- | -| Scanning with AWS SSM | [Scan Using AWS Systems Manager](/platform/infra/cloud/aws/aws-ssm-scan/) | -| Scanning from a workstation | [Scan from a Workstation](/platform/infra/cloud/aws/aws-workstation-scan/) | +| Scanning with AWS SSM | [Scan Using AWS Systems Manager](/cnspec/cloud/aws/aws-ssm-scan/) | +| Scanning from a workstation | [Scan from a Workstation](/cnspec/cloud/aws/) | | Continuous AWS scanning | [Continuously Scan AWS](/platform/infra/cloud/aws/aws-integration-scan/) | | cnspec | [The cnspec documentation](/cnspec/cnspec-about/) | diff --git a/docs/platform/infra/cloud/aws/aws-ec2-ic-scan.mdx b/docs/cnspec/cloud/aws/aws-ec2-ic-scan.mdx similarity index 74% rename from docs/platform/infra/cloud/aws/aws-ec2-ic-scan.mdx rename to docs/cnspec/cloud/aws/aws-ec2-ic-scan.mdx index 044437e61..4301806f1 100644 --- a/docs/platform/infra/cloud/aws/aws-ec2-ic-scan.mdx +++ b/docs/cnspec/cloud/aws/aws-ec2-ic-scan.mdx @@ -1,7 +1,7 @@ --- title: Scan Using EC2 Instance Connect sidebar_label: Scan Using EC2 Instance Connect -sidebar_position: 8 +sidebar_position: 35 image: /img/featured_img/mondoo-aws.jpg description: This document covers the configuration and use of EC2 Instance Connect to scan EC2 instances. --- @@ -14,9 +14,9 @@ import Partial from "./_aws-incl-ic.mdx"; | To learn about... | Read... | | --------------------------- | -------------------------------------------------------------------------- | -| Scanning with AWS SSM | [Scan Using AWS Systems Manager](/platform/infra/cloud/aws/aws-ssm-scan/) | -| Scanning from a workstation | [Scan from a Workstation](/platform/infra/cloud/aws/aws-workstation-scan/) | -| Snapshot scanning | [Scan an EBS Snapshot](/platform/infra/cloud/aws/aws-ebs-snapshot-scan/) | +| Scanning with AWS SSM | [Scan Using AWS Systems Manager](/cnspec/cloud/aws/aws-ssm-scan/) | +| Scanning from a workstation | [Scan from a Workstation](/cnspec/cloud/aws/) | +| Snapshot scanning | [Scan an EBS Snapshot](/cnspec/cloud/aws/aws-ebs-snapshot-scan/) | | Continuous AWS scanning | [Continuously Scan AWS](/platform/infra/cloud/aws/aws-integration-scan/) | | cnspec | [The cnspec documentation](/cnspec/cnspec-about/) | diff --git a/docs/platform/infra/cloud/aws/aws-ssm-scan.mdx b/docs/cnspec/cloud/aws/aws-ssm-scan.mdx similarity index 98% rename from docs/platform/infra/cloud/aws/aws-ssm-scan.mdx rename to docs/cnspec/cloud/aws/aws-ssm-scan.mdx index e705362c8..827143007 100644 --- a/docs/platform/infra/cloud/aws/aws-ssm-scan.mdx +++ b/docs/cnspec/cloud/aws/aws-ssm-scan.mdx @@ -1,7 +1,7 @@ --- title: Scan Using AWS Systems Manager sidebar_label: Scan Using AWS SSM -sidebar_position: 6 +sidebar_position: 25 image: /img/featured_img/mondoo-aws.jpg description: This document covers the configuration and use of AWS Systems Manager (SSM) to scan EC2 instances without agents. --- @@ -202,7 +202,7 @@ aws ssm describe-instance-information --query "InstanceInformationList[?Instance | To learn about... | Read... | | ----------------------- | ------------------------------------------------------------------------ | -| Snapshot scanning | [Scan an EBS Snapshot](/platform/infra/cloud/aws/aws-ebs-snapshot-scan/) | +| Snapshot scanning | [Scan an EBS Snapshot](/cnspec/cloud/aws/aws-ebs-snapshot-scan/) | | Continuous AWS scanning | [Continuously Scan AWS](/platform/infra/cloud/aws/aws-integration-scan/) | | cnspec | [The cnspec documentation](/cnspec/cnspec-about/) | diff --git a/docs/platform/infra/cloud/aws/_aws-client-service.mdx b/docs/platform/infra/cloud/aws/_aws-client-service.mdx deleted file mode 100644 index 28789a822..000000000 --- a/docs/platform/infra/cloud/aws/_aws-client-service.mdx +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: AWS Instance Scanning with cnspec -sidebar_label: Scanning with cnspec -sidebar_position: 6 -description: This document covers scanning AWS instances running cnspec running as a service ---- diff --git a/docs/platform/infra/cloud/aws/aws-integration-scan.mdx b/docs/platform/infra/cloud/aws/aws-integration-scan.mdx index 926aad82a..16fa56762 100644 --- a/docs/platform/infra/cloud/aws/aws-integration-scan.mdx +++ b/docs/platform/infra/cloud/aws/aws-integration-scan.mdx @@ -2,204 +2,24 @@ title: Continuously Scan with an AWS Integration sidebar_label: Scan Continuously sidebar_position: 2 -description: This document covers the configuration and use of the Mondoo AWS Integration to scan AWS accounts and EC2 instances +description: Continuously monitor your AWS asset security with Mondoo. Choose between serverless scanning and Mondoo-hosted scanning. --- -The Mondoo AWS integration enables continuous cron-scheduled and [event-based](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-service-event.html) scanning of your AWS account and EC2 instances. +The Mondoo AWS integration lets you continuously monitor the security and compliance of your AWS account, EC2 instances, EKS clusters, EBS volumes, and more. Choose between a Mondoo-hosted integration and a serverless integration: -To learn about how an integration runs and its required permissions, read [AWS Integration FAQ](/platform/infra/cloud/aws/aws-integration-faq/). +- A [Mondoo-hosted AWS integration](/platform/infra/cloud/aws/hosted/integration-hosted/) requires no agent installed to your AWS infrastructure and incurs no AWS cost. It's easy to set up and provides a higher level of stability. You can scan individual AWS accounts only; not an entire AWS Organization. This approach requires that you give Mondoo an AWS access key and secret. -## Integrate with an entire organization or single account +- A [serverless AWS integration](/platform/infra/cloud/aws/lambda/integration-lambda/) uses an AWS Lambda function and CloudFormation to perform scheduled scans of an account or an entire AWS Organization. It doesn't require sharing AWS credentials with Mondoo. A serverless integration is more complex to set up and does incur a small AWS cost. -The Mondoo AWS integration supports scanning multiple AWS accounts. To do this, you install Mondoo across an AWS Organization using CloudFormation StackSets. All scan configuration options you choose apply to every AWS account in the AWS Organization. - -If you choose to integrate an entire Organization, be sure your AWS organization meets the requirements described in [AWS Integration Troubleshooting](/platform/infra/cloud/aws/aws-integration-troubleshooting/#requirements-for-deploying-the-mondoo-stackset-at-the-organization-level). - -You can also opt to scan a single AWS account only. Single account integrations rely on CloudFormation stacks. - -:::info -When you deploy an integration with Mondoo using a StackSet on the organizational level, the StackSet only creates an integration of the [target accounts](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacksets-concepts.html#stacksets-concepts-accts). - -The [administrator account](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacksets-concepts.html#stacksets-concepts-accts) in which the StackSet for the target accounts resides needs its own separate [single account integration](/platform/infra/cloud/aws/aws-integration-scan/#integrate-with-an-entire-organization-or-single-account). - -This is intentional and reflects the [architectural concepts of AWS StackSets](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacksets-concepts.html). -::: - -## Set up a new AWS integration - -1. Access the Integrations > Add > AWS page in one of two ways: - - - **New space setup**: After creating a new Mondoo account or creating a new space, the initial setup guide welcomes you. Select **BROWSE INTEGRATIONS** and then select **Amazon AWS**. - - ![Welcome to Mondoo Page](/img/platform/start/welcome_to_mondoo.png) - - - **INTEGRATIONS page**: In the side navigation bar, under **INTEGRATIONS**, select **Add New Integration**. Near the top of the page, select **Amazon AWS**. - - ![integration-create-image](/img/platform/infra/cloud/aws/add-aws-top.png) - -2. Select the type of integration: - - | Option | Description | - | -------------------------- | ------------------------------------------------- | - | **Organization install** | Integrate Mondoo with an entire AWS Organization. | - | **Single account install** | Integrate Mondoo with a single AWS account. | - -:::caution - -Before creating a Mondoo deployment on an AWS organization, make sure to check if the configuration of your AWS organization meets the [requirements](/platform/infra/cloud/aws/aws-integration-troubleshooting/#requirements-for-deploying-the-mondoo-stackset-at-the-organization-level). - -::: - -3. Identify the account or Organization and the region: - - | If you're integrating with... | Then... | - | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | - | An entire AWS Organization | In the **AWS Organization(s)** box, enter any name for the integration. Select the region in which you want to deploy the integration. | - | A single AWS account | In the **AWS account** box, enter your AWS account ID. Select the region in which you want to deploy the integration. | - -4. Set the account options: - - | Option | Description | - | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | - | **Schedule full scan** | Set the interval (in hours) at which to execute a full scan of the AWS account, independent of change [events](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-service-event.html). The default is 12 hours. | - | **Trigger on AWS console sign-in event** | Trigger an account scan whenever a user logs into the AWS console. | - -5. Set the EC2 options: - - ![integration-create-image](/img/platform/infra/cloud/aws/add-aws-ec2.png) - - | Option | Description | - | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | - | **Discover EC2 instances** | Include EC2 instances in asset discovery. By default, this applies across all regions. | - | **Trigger on instance state change [events](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-service-event.html)** | Trigger a scan of all EC2 instances whenever an instance changes state. | - | [**Use SSM for instance connectivity**](/docs/platform/infra/cloud/aws/aws-ssm-scan) | Use the AWS SSM service to trigger scans for EC2 instances (when it's available). | - | **Use EC2 Instance Connect for instance connectivity** | If an EC2 instance has a public IP, connect using EC2 Instance Connect. | - | **Use EBS volume scanning for instance connectivity** | Use _EBS volume scanning_ to scan the filesystems of instances that Mondoo otherwise can't reach. This includes stopped instances. | - -6. If you enable EBS volume scanning, you can customize these options: - - | Option | Description | - | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | **EBS targets per scanner** | Customize the number of targets a single scanner instance is responsible for scanning. Setting a low number (such as 5) results in faster scans, but requires AWS to create more scanner instances. Setting a high number (such as 50) reduces the number of scanner instances, but results in slower scans. The default is 20. | - | **Max ASG instances** | Set your own limit for how many instances AWS can spin up in the AutoScalingGroup to perform the filesystem scans. The default is 50. | - -7. To scan EC2 instances using SSH, enable **Use SSH for instance connectivity**. You must use the vault secret query if you use SSH. Provide this information: - - | Option | Description | - | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | **Vault type** | Specify whether to read the secret from AWS Secrets Manager or AWS SSM Parameter store. | - | **Vault secret query** | Provide the query to match vault credentials to instances. To learn how to write the query, read [Secrets Management](/platform/infra/opsys/automation/vault.md). | - -8. If desired, limit the EC2 instances that Mondoo scans: - - | Option | Description | Example | - | -------------------------- | ------------------------------------------------------------------------------ | ---------------------------------------- | - | **Filter by instance IDs** | Limit instance scanning to a subset of IDs, separated by commas. | `i-0d1f840578ca82600,i-07ae83fe5d22600a` | - | **Filter by regions** | Limit instance scanning to a subset of regions, separating values with commas. | `us-east-1,us-east-2` | - | **Filter by tags** | To Limit instance scanning to a subset of tags, separated with commas. | `Name:testname, env:test` | - -9. Set ECS, S3, and ECR options: - - ![integration-create-image](/img/platform/infra/cloud/aws/add-aws-bottom.png) - - | Option | Description | - | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | - | **Discover and scan ECS containers** | Use Amazon ECS Exec to scan Fargate containers. | - | **Trigger on S3 bucket [events](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-service-event.html)** | Trigger a scan whenever a change is made to an S3 bucket. | - | **Discover and scan ECR images** | Include ECR images in asset discovery and scan them when found. | - -10. Select the **CREATE** button. - -11. Follow the instructions to launch the AWS CloudFormation stack (for an account) or StackSet (for an Organization). - -:::caution IMPORTANT - -Selecting **Create** does not finalize the integration between Mondoo and AWS. You must launch the AWS CloudFormation stack or StackSet to complete the setup. - -::: - -## Manage an AWS integration - -You can view the status of an AWS integration, change its configuration options, and more on its integration page. - -To access an existing integration: - -1. In the [Mondoo Console](https://console.mondoo.com), [navigate](/platform/start/navigate) to the space containing the integration. - -2. In the side navigation bar, under **Integrations**, select **AWS**. - - ![integration-list-image](/img/platform/infra/cloud/aws/list.png) - -3. Select the integration you want to view or manage. - - ![integration-detail-image](/img/platform/infra/cloud/aws/integration-overview.png) - -### View an integration's status - -Mondoo shows the status at the top of the integration page, beside the integration name. - -![Mondoo AWS integration status and actions](/img/platform/infra/cloud/aws/integration-scan-now.png) - -Theses are the possible statuses for an AWS integration: - -| Status | Meaning | -| --------------- | ---------------------------------------------------------------------------------------------------------------- | -| **configuring** | Mondoo is sending the scan configuration options to the integration and the integration is saving those options. | -| **active** | The integration is active and healthy. | -| **error** | Mondoo detected an error during installation. | -| **missing** | Mondoo hasn't received a check-in from the Lambda function for over an hour. | -| **deleted** | CloudFormation for the integration has been deleted. | - -### Ping an integration - -At the top of the integration page, below the integration name, Mondoo shows the time of the last ping. - -To ping the integration now, select the ping icon (a heartbeat to the left of the **SCAN NOW** button). - -### Request a fresh scan - -To see fresh scan results, select the **SCAN NOW** button. Mondoo retrieves new scan results as soon as possible. - -### Stop all running scans - -To stop all currently running AWS scans, on the ellipsis menu of the integration page, select **Cancel Scans**. - -![Stop an AWS scan in Mondoo](/img/platform/infra/cloud/aws/cancel-scan.png) - -### Retry a failed integration setup - -If an error occurred during setup and the CloudFormation stack is now up and running but the integration is unhealthy, you can try to return it to a healthy state: Select the ellipsis to the right of the integration name and select **Retry Setup**. - -### Enable and disable policies for an AWS integration - -The **RECOMMENDED POLICIES** tab on the integration page lists policies that can help you protect your AWS environment. It shows which policies are enabled and disabled. - -![Policies for a Mondoo AWS integration](/img/platform/infra/cloud/aws/integration-policies.png) - -Use the toggle on the right side of each policy's row to enable or disable the policy. - -To learn more about policies, read [Policy as Code](/platform/security/posture/pac/). - -### Reconfigure an AWS integration - -The **CONFIGURATION** tab on the integration page shows the current settings and lets you make changes. - -![Reconfigure a Mondoo AWS integration](/img/platform/infra/cloud/aws/integration-config.png) - -To learn about individual settings, read the sections under the _Set up a new AWS integration_ section above. - -### Remove an integration - -To remove an integration, select the Remove (trash can) icon at the top of the integration page. - -![Remove an AWS Mondoo integration](/img/platform/infra/cloud/aws/integration-scan-now.png) - -A notification displays with a link to the CloudFormation Stacks list in the AWS console. Select the link and, in the AWS console, delete the stack. This removes the configured integration from Mondoo Platform and deletes the rule allowing the Mondoo AWS account to send events to the target account. - -## Learn more - -- [AWS Integration FAQ](/docs/platform/infra/cloud/aws/aws-integration-faq) - -- [AWS Integration Troubleshooting](/docs/platform/infra/cloud/aws/aws-integration-troubleshooting) +| | **Mondoo-hosted** | **Serverless** | +|:-----------------------------------------|:--------------------------------------------:|:--------------------------------------------------:| +| **Continuous AWS account scanning** | :heavy_check_mark: | :heavy_check_mark: | +| **Continuous AWS Organization scanning** | :heavy_multiplication_x: | :heavy_check_mark: | +| **Agentless** | :heavy_check_mark: | :heavy_multiplication_x: | +| **Requires an AWS Lambda function** | :heavy_multiplication_x: | :heavy_check_mark: | +| **Stability** | Highest stability; not subject to API limits | High but very large accounts can exceed API limits | +| **Complexity** | Easy | Requires installation in your environment | +| **Infrastructure cost** | No additional AWS cost | Small AWS cost | +| **Security** | Highly secure | Highest | --- diff --git a/docs/platform/infra/cloud/aws/aws-overview.mdx b/docs/platform/infra/cloud/aws/aws-overview.mdx index 88fb951cf..453e6503c 100644 --- a/docs/platform/infra/cloud/aws/aws-overview.mdx +++ b/docs/platform/infra/cloud/aws/aws-overview.mdx @@ -14,7 +14,7 @@ Mondoo offers a variety of approaches to evaluating your AWS infrastructure secu Continuously evaluate the security of your AWS accounts and resources, such as EC2 instances, so that you always have an up-to-date view of your environment's security posture. -The [Mondoo AWS Integration](/platform/infra/cloud/aws/aws-integration-scan) provides cron-scheduled and [event-based](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-service-event.html) continuous scanning of your AWS accounts and EC2 instances using a Lambda function. Deploy the integration once and always get the latest security assessments for new accounts and resources. +The [Mondoo AWS Integration](/platform/infra/cloud/aws/aws-integration-scan) provides continuous scanning of your AWS accounts. Deploy the integration once and always get the latest security assessments for new accounts and resources. ## Scan during build time @@ -22,11 +22,6 @@ The [Mondoo AWS Integration](/platform/infra/cloud/aws/aws-integration-scan) pro ## Scan during run time -Ad hoc, agentless scans are a great way to get started evaluating your AWS security with Mondoo. There's no agent to install or manage on instances in your infrastructure, so you can get started scanning in just minutes. - -- [Scan an AWS account from your workstation](/platform/infra/cloud/aws/aws-workstation-scan/): Scan your AWS accounts and instances using cnspec, the open source security scanning component of Mondoo. -- [Instance scan with AWS SSM](/platform/infra/cloud/aws/aws-ssm-scan/): Perform agentless scans of your instances using AWS Systems Manager. -- [Instance scan with EC2 Instance Connect](/platform/infra/cloud/aws/aws-ec2-ic-scan/): Use EC2 Instance Connect to assess configuration without an agent. -- [Instance scan with EBS snapshots](/platform/infra/cloud/aws/aws-ebs-snapshot-scan): To prevent impact on running instances, you can conduct a jump-host-based scan of EC2 instance EBS snapshots. +Mondoo's client, cnspec, provides many ways to [run ad hoc, agentless scans](/cnspec/cloud/aws/). --- diff --git a/docs/platform/infra/cloud/aws/aws-workstation-scan.mdx b/docs/platform/infra/cloud/aws/aws-workstation-scan.mdx deleted file mode 100644 index 34b6a7870..000000000 --- a/docs/platform/infra/cloud/aws/aws-workstation-scan.mdx +++ /dev/null @@ -1,135 +0,0 @@ ---- -title: Scan AWS Accounts and EC2 Instances from a Workstation -sidebar_label: Scan from a Workstation -sidebar_position: 7 -image: /img/featured_img/mondoo-aws.jpg -description: Perform remote, agentless scans on AWS accounts and EC2 instances with Mondoo ---- - -Use [cnspec](/cnspec/cnspec-about/), Mondoo's CLI security tool, to scan AWS accounts and EC2 instances remotely from your workstation. These fast, on-demand assessments are independent from any [native AWS integrations](/platform/infra/cloud/aws/aws-integration-scan) that run continuously within your account. - -You can: - -- [Remotely scan an AWS account](#remotely-scan-aws-accounts) using the AWS CLI config - -or - -- [Perform agentless scans of EC2 instances](#perform-agentless-scans-of-ec2-instances) using EC2 Instance Connect, SSH, or snapshot scanning - -## Remotely scan AWS accounts - -cnspec can remotely scan AWS accounts using the configuration and credentials from the AWS CLI on your workstation, which is typically located in `~/.aws/credentials`. Before you can scan an AWS account, you must have the AWS CLI [installed and configured](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) with credentials for the accounts you want to scan. - -### Set up AWS credentials - -To ensure your AWS credentials are set up properly so you can scan from your workstation, run this command from a terminal: - -```bash -cat ~/.aws/credentials -[default] -aws_access_key_id = AKIAIOSFODNN7EXAMPLE -aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY -aws_session_token = AQoDYXdzEJr... -``` - -If you want to use a specific profile, set `AWS_PROFILE` - -```bash -export AWS_PROFILE=PROFILENAME -``` - -For PROFILENAME, substitute the name of the profile to use. - -### Permissions required to scan an AWS account - -cnspec requires read-only access to assess the configuration of the services and resources within an AWS account. It uses the credentials for the `awscli` to authenticate with the AWS API. So it inherits the permissions granted to your AWS access keys. - -:::info - -Amazon provides the **ReadOnlyAccess** IAM profile, which grants read-only access to all AWS Services. - -::: - -### Scan an AWS account with cnspec - -To scan an AWS account remotely with cnspec, enter this command in a terminal: - -```bash -cnspec scan aws -``` - -cnspec scans the account using any AWS policies you have enabled in your Mondoo account. It prints the results to `STDOUT` on the command line. It also sends the results to Mondoo Platform, which generates a report for each policy executed against the account. - -### Manage multiple AWS profiles - -If you manage multiple AWS configurations in your credentials file, you can set the `AWS_PROFILE` environment variable to specify which profile to use for each scan. For example, this credentials file has two configurations: - -```bash title='~/.aws/credentials' -[default] -aws_access_key_id=AKIAIOSFODNN7EXAMPLE -aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY - -[aws-dev-account] -aws_access_key_id=AKIAI44QH8DHBEXAMPLE -aws_secret_access_key=je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY -``` - -When you run a scan, you specify which profile to use: - -```bash title="Select AWS profile to scan" -export AWS_PROFILE=PROFILENAME -cnspec scan aws -``` - -For PROFILENAME, substitute the name of the profile to use. - -### Incognito mode - -cnspec provides an `--incognito` mode, which lets you scan your AWS account against a specific policy without sending the results back to Mondoo Platform. This can be helpful for assessing how an account will score against a policy before enabling it. - -To scan an AWS account using `incognito` mode, enter this command in a terminal: - -```bash -cnspec scan aws --incognito -``` - -## Perform agentless scans of EC2 instances - -cnspec supports remote scanning of EC2 instances without installing an agent on the instance. This lets you assess your instances on demand. You must have remote connectivity to instances, either through SSH or EC2 Instance Connect. - -### Scan an EC2 instance using EC2 Instance Connect - -import Partial from "./_aws-incl-ic.mdx"; - -{" "} - -### Scan an EC2 instance using SSH - -cnspec lets you remotely scan EC2 instances using SSH: - -```bash -cnspec scan aws ec2 instance-connect USER@HOST --identity-file PATH -``` - -| For... | Substitute... | -| ------ | --------------------------------------- | -| USER | Your user name for the AWS account | -| HOST | The instance's public IP address or DNS | -| PATH | The path to the SSH key file | - -:::info - -To learn how to retrieve credentials from a secrets manager (such as AWS Secrets Manager or SSM Parameter Store), read [Secrets Management](/platform/infra/opsys/automation/vault.md). - -::: - -## Learn more - -| To learn about... | Read... | -| ----------------------- | ------------------------------------------------------------------------- | -| Scanning with AWS SSM | [Scan Using AWS Systems Manager](/platform/infra/cloud/aws/aws-ssm-scan/) | -| Snapshot scanning | [Scan an EBS Snapshot](/platform/infra/cloud/aws/aws-ebs-snapshot-scan/) | -| Continuous AWS scanning | [Continuously Scan AWS](/platform/infra/cloud/aws/aws-integration-scan/) | -| cnspec | [The cnspec documentation](/cnspec/cnspec-about/) | - ---- diff --git a/docs/platform/infra/cloud/aws/hosted/_category_.json b/docs/platform/infra/cloud/aws/hosted/_category_.json new file mode 100644 index 000000000..1100f4dac --- /dev/null +++ b/docs/platform/infra/cloud/aws/hosted/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Mondoo-Hosted", + "position": 2 +} diff --git a/docs/platform/infra/cloud/aws/hosted/integration-hosted.mdx b/docs/platform/infra/cloud/aws/hosted/integration-hosted.mdx new file mode 100644 index 000000000..fed8b1266 --- /dev/null +++ b/docs/platform/infra/cloud/aws/hosted/integration-hosted.mdx @@ -0,0 +1,120 @@ +--- +title: Continuously Scan AWS - Mondoo-Hosted Integration +sidebar_label: Scan Continuously (Hosted) +sidebar_position: 3 +description: This document covers the configuration and use of the Mondoo-hosted AWS integration to scan AWS accounts and EC2 instances +--- + +A Mondoo-hosted AWS integration provides continuous security and compliance scanning for an AWS account without installing any agents in your AWS or incurring additional AWS cost. An AWS access key gives Mondoo integration the access it needs to continuously scan your AWS account. To learn about AWS access keys, read [Managing access keys for IAM users](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) in the AWS documentation. + +:::info + +Mondoo also offers a serverless method for assessing AWS security. It provides cron-scheduled and event-based continuous scanning of your AWS accounts or your entire AWS Organization using a Lambda function. To compare the two approaches, read [Continuously Scan with an AWS Integration](/platform/infra/cloud/aws/aws-integration-scan/). + +::: + +## Set up a new AWS integration + +1. Access the Integrations > Add > AWS page in one of two ways: + + - **New space setup**: After creating a new Mondoo account or creating a new space, the initial setup guide welcomes you. Select **BROWSE INTEGRATIONS** and then select **AWS**. + + ![Welcome to Mondoo Page](/img/platform/start/welcome_to_mondoo.png) + + - **INTEGRATIONS page**: In the side navigation bar, under **INTEGRATIONS**, select **Add New Integration**. Near the top of the page, select **AWS**. + + ![AWS integration options](/img/platform/infra/cloud/aws/hosted-or-serverless.png) + +2. Select **Mondoo-Hosted**. + + ![integration-create-image](/img/platform/infra/cloud/aws/add-hosted-top.png) + +3. In the **Choose an integration name** box, type a recognizable name for this AWS asset. + +4. In a new browser tab, go to your **AWS access portal** and select the account you want to continuously scan with Mondoo. + + ![AWS access portal](/img/platform/infra/cloud/aws/awsportal.png) + +5. Select **Access keys** and scroll down to **Option 3: Use individual values in your AWS service client**. + + ![AWS access keys](/img/platform/infra/cloud/aws/option3.png) + +6. Copy the **AWS access key ID** value. + + Return to the Mondoo Console tab in your browser and, under **Enter authentication details**, paste the value in the **Access Key ID** box. + + ![AWS access keys](/img/platform/infra/cloud/aws/auth.png) + +7. In the AWS tab in your browser, copy the **AWS secret access key** value. + + Return to the Mondoo Console tab in your browser and, under **Enter authentication details**, paste the value in the **AWS secret access key** box. + +8. Select the **START SCANNING** button. + +## Manage an AWS integration + +You can view the status of an AWS integration, change its configuration options, and more on its integration page. + +To access an existing integration: + +1. In the [Mondoo Console](https://console.mondoo.com), [navigate](/platform/start/navigate) to the space containing the integration. + +2. In the side navigation bar, under **Integrations**, select **AWS**. + + ![integration-list-image](/img/platform/infra/cloud/aws/list.png) + +3. Select the integration you want to view or manage. + + ![integration-detail-image](/img/platform/infra/cloud/aws/integration-overview.png) + +### View an integration's status + +Mondoo shows the status at the top of the integration page, beside the integration name. + +![Mondoo AWS integration status and actions](/img/platform/infra/cloud/aws/integration-scan-now.png) + +Theses are the possible statuses for an AWS integration: + +| Status | Meaning | +| --------------- | ---------------------------------------------------------------------------------------------------------------- | +| **configuring** | Mondoo is sending the scan configuration options to the integration and the integration is saving those options. | +| **active** | The integration is active and healthy. | +| **error** | Mondoo detected an error during installation. | +| **missing** | Mondoo hasn't received a check-in from the Lambda function for over an hour. | +| **deleted** | CloudFormation for the integration has been deleted. | + +### Ping an integration + +At the top of the integration page, below the integration name, Mondoo shows the time of the last ping. + +To ping the integration now, select the ping icon (a heartbeat to the left of the **SCAN NOW** button). + +### Request a fresh scan + +To see fresh scan results, select the **SCAN NOW** button. Mondoo retrieves new scan results as soon as possible. + +### Enable and disable policies for an AWS integration + +The **RECOMMENDED POLICIES** tab on the integration page lists policies that can help you protect your AWS environment. It shows which policies are enabled and disabled. + +![Policies for a Mondoo AWS integration](/img/platform/infra/cloud/aws/integration-policies.png) + +Use the toggle on the right side of each policy's row to enable or disable the policy. + +To learn more about policies, read [Policy as Code](/platform/security/posture/pac/). + +### Remove an integration + +To remove an integration, select the Remove (trash can) icon at the top of the integration page. + +![Remove an AWS Mondoo integration](/img/platform/infra/cloud/aws/integration-scan-now.png) + +A notification displays with a link to the CloudFormation Stacks list in the AWS console. Select the link and, in the AWS console, delete the stack. This removes the configured integration from Mondoo Platform and deletes the rule allowing the Mondoo AWS account to send events to the target account. + +## Learn more + +- [AWS Integration FAQ](/docs/platform/infra/cloud/aws/lambda/aws-integration-faq/) + +- [AWS Integration Troubleshooting](/docs/platform/infra/cloud/aws/lambda/aws-integration-troubleshooting/) + +--- diff --git a/docs/platform/infra/cloud/aws/lambda/_category_.json b/docs/platform/infra/cloud/aws/lambda/_category_.json new file mode 100644 index 000000000..850dfbee7 --- /dev/null +++ b/docs/platform/infra/cloud/aws/lambda/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Serverless", + "position": 4 +} diff --git a/docs/platform/infra/cloud/aws/aws-integration-faq.mdx b/docs/platform/infra/cloud/aws/lambda/aws-integration-faq.mdx similarity index 88% rename from docs/platform/infra/cloud/aws/aws-integration-faq.mdx rename to docs/platform/infra/cloud/aws/lambda/aws-integration-faq.mdx index 564a63839..6c7c1a041 100644 --- a/docs/platform/infra/cloud/aws/aws-integration-faq.mdx +++ b/docs/platform/infra/cloud/aws/lambda/aws-integration-faq.mdx @@ -1,40 +1,40 @@ --- -title: AWS Integration FAQ -sidebar_label: Integration FAQ +title: AWS Serverless Integration FAQ +sidebar_label: Serverless Integration FAQ image: /img/featured_img/mondoo-aws.jpg description: This document covers how the Mondoo AWS integration works. It includes permissions and billing details. sidebar_position: 3 --- -## How does the Mondoo AWS integration work? +## How does the serverless Mondoo AWS integration work? -Mondoo Platform never has credentials to your AWS account. +With the serverless approach to integrating with AWS, Mondoo never has credentials to your AWS account. We install a Lambda function in your AWS account via the CloudFormation template, and communicate with that Lambda function over AWS EventBridge. The Lambda function communicates with Mondoo using service credentials stored in the SSM Parameter Store. -## Why does the Mondoo integration need to create resources in my AWS account? +## Why does the serverless Mondoo integration need to create resources in my AWS account? The resources created in your AWS account are used to run and schedule configuration and EC2 instance scans. Those resources are low-cost, limited to a Lambda function, SNS topic, SQS Queues, some IAM roles, EventBridge rules, and SSM parameters. If using the EBS volume scanning feature, an Autoscaling Group and launch template will also be created. -## How does the integration communicate from my AWS account to Mondoo Platform? +## How does the serverless integration communicate from my AWS account to Mondoo Platform? On CloudFormation stack creation, a short-lived token is exchanged for Mondoo credentials. Those credentials are stored in the SSM Parameter store and used by the Lambda function and SSM instances in the AWS account to communicate with Mondoo Platform over HTTPS. -## Choose to integrate an organization or an account +## Should I choose to integrate an organization or an account? If you've set up your AWS organization according to [AWS standard practices](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_tutorials_basic.html), create an organization integration for ease of use. -Before deploying, check the configuration of your AWS organization as described in [Requirements for deploying the Mondoo StackSet at the organization level](/platform/infra/cloud/aws/aws-integration-troubleshooting#requirements-for-deploying-the-mondoo-stackset-at-the-organization-level). +Before deploying, check the configuration of your AWS organization as described in [Requirements for deploying the Mondoo StackSet at the organization level](/platform/infra/cloud/aws/lambda/aws-integration-troubleshooting#requirements-for-deploying-the-mondoo-stackset-at-the-organization-level). ## What information will leave my AWS Account? Scan report results only. -## What information will Mondoo Platform store about my AWS resources? +## What information will Mondoo store about my AWS resources? Mondoo Platform stores the latest report for all scanned assets in the AWS account (the reports viewable under **Inventory**) as well as the total counts of various resources in the AWS account, displayed on the Integration detail page. -## Is the communication channel between Mondoo Platform and my AWS account secure? +## Is the communication channel between Mondoo and my AWS account secure? Yes, Mondoo communicates with your AWS account using [AWS EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-cross-account.html). The Eventbus policy and rule are created as part of the CloudFormation stack. @@ -111,9 +111,9 @@ Every time the Lambda function updates, it first reads the SHA-256 of each file When the CloudFormation stack is deleted, the lambda function receives a notification and immediately deletes all AWS resources created by Mondoo. Mondoo Platform UI will display the integration as deleted. No data will be lost in Mondoo Platform. A CloudFormation stack can be deleted and recreated multiple times. -## How much will operating the Mondoo AWS Integration cost? +## How much will operating the serverless Mondoo AWS integration cost? -Most of the costs associated with the Mondoo AWS Integration fall into the AWS Free Tier category. Over the course of a month, an example AWS integration incurred this resource usage: +Most of the costs associated with the serverless Mondoo AWS integration fall into the AWS Free Tier category. Over the course of a month, an example AWS integration incurred this resource usage: - CloudWatch PutLogs: 1GB (First 5GB per month of log data ingested is free) - CloudWatch TimedStorage: 0.16GB (First 5GB-mo per month of logs storage is free) @@ -141,7 +141,7 @@ The AWS CloudFormation JSON and Lambda zip are available as part of the Mondoo S ## Learn more -- [AWS Integration Troubleshooting](/docs/platform/infra/cloud/aws/aws-integration-troubleshooting) +- [AWS Integration Troubleshooting](/docs/platform/infra/cloud/aws/lambda/aws-integration-troubleshooting/) - [Scan Continuously with an AWS Integration](/docs/platform/infra/cloud/aws/aws-integration-scan) --- diff --git a/docs/platform/infra/cloud/aws/aws-integration-troubleshooting.mdx b/docs/platform/infra/cloud/aws/lambda/aws-integration-troubleshooting.mdx similarity index 97% rename from docs/platform/infra/cloud/aws/aws-integration-troubleshooting.mdx rename to docs/platform/infra/cloud/aws/lambda/aws-integration-troubleshooting.mdx index dcfda991e..5267e3e31 100644 --- a/docs/platform/infra/cloud/aws/aws-integration-troubleshooting.mdx +++ b/docs/platform/infra/cloud/aws/lambda/aws-integration-troubleshooting.mdx @@ -1,12 +1,12 @@ --- -title: Mondoo AWS Integration Troubleshooting -sidebar_label: Integration Troubleshooting +title: Mondoo Serverless AWS Integration Troubleshooting +sidebar_label: Serverless Integration Troubleshooting sidebar_position: 4 image: /img/featured_img/mondoo-aws.jpg description: This document covers how to debug and troubleshoot problems that may come up with the AWS Integration. --- -Troubleshoot problems that may come up deploying, running, and updating the Mondoo AWS integration. +Troubleshoot problems that may come up deploying, running, and updating the serverless Mondoo AWS integration. :::tip @@ -199,7 +199,7 @@ And of course, please contact support@mondoo.com and join us in the [Mondoo Comm ## Learn more -- [AWS Integration FAQ](/docs/platform/infra/cloud/aws/aws-integration-faq) +- [AWS Integration FAQ](/docs/platform/infra/cloud/aws/lambda/aws-integration-faq/) - [Scan Continuously with an AWS Integration](/docs/platform/infra/cloud/aws/aws-integration-scan) --- diff --git a/docs/platform/infra/cloud/aws/aws-scan-details.mdx b/docs/platform/infra/cloud/aws/lambda/aws-scan-details.mdx similarity index 87% rename from docs/platform/infra/cloud/aws/aws-scan-details.mdx rename to docs/platform/infra/cloud/aws/lambda/aws-scan-details.mdx index 4d4295cdf..7988788f6 100644 --- a/docs/platform/infra/cloud/aws/aws-scan-details.mdx +++ b/docs/platform/infra/cloud/aws/lambda/aws-scan-details.mdx @@ -1,6 +1,6 @@ --- -title: Advanced AWS Integration Details -sidebar_label: Advanced Integration Details +title: Advanced Serverless AWS Integration Details +sidebar_label: Advanced Serverless Integration Details sidebar_position: 5 image: /img/featured_img/mondoo-aws.jpg description: This document provides detailed information on how the Mondoo AWS integration works. @@ -8,13 +8,13 @@ description: This document provides detailed information on how the Mondoo AWS i :::note -This supplemental topic provides detailed information on how the Mondoo AWS integration works. It's not essential knowledge for using Mondoo. +This supplemental topic provides detailed information on how the serverless Mondoo AWS integration works. It's not essential knowledge for using Mondoo. ::: ## What is an "account scan"? -When an AWS account is integrated with a space in Mondoo Platform, Mondoo performs a configuration assessment of the AWS account by analyzing the configuration of the account (IAM settings), and discovering resources (EC2 instances, S3 buckets, RDS instances, etc) across all regions. The configuration of discovered resources are assessed according to which policies have been **ENABLED** in the **registry**. +When an AWS account is integrated with a Mondoo space, Mondoo performs a configuration assessment of the AWS account by analyzing the configuration of the account (IAM settings), and discovering resources (EC2 instances, S3 buckets, RDS instances, etc) across all regions. The configuration of discovered resources are assessed according to which policies have been **ENABLED** in the **registry**. ### Account scan schedule @@ -30,7 +30,7 @@ Additionally, on-demand scans can be triggered in **INTEGRATIONS** section by se :::info -You can also scan an AWS account by running `cnspec scan aws` from any workstation on which cnspec is installed and configured. To learn more, read [Scan AWS from your workstation](/platform/infra/cloud/aws/aws-workstation-scan/). +You can also scan an AWS account by running `cnspec scan aws` from any workstation on which cnspec is installed and configured. To learn more, read [Scan AWS from your workstation](/cnspec/cloud/aws/). ::: diff --git a/docs/platform/infra/cloud/aws/lambda/integration-lambda.mdx b/docs/platform/infra/cloud/aws/lambda/integration-lambda.mdx new file mode 100644 index 000000000..ff511a3bd --- /dev/null +++ b/docs/platform/infra/cloud/aws/lambda/integration-lambda.mdx @@ -0,0 +1,213 @@ +--- +title: Continuously Scan AWS - Serverless Integration +sidebar_label: Scan Continuously (Serverless) +sidebar_position: 1 +description: This document covers the configuration and use of the Mondoo AWS serverless integration to scan AWS accounts and EC2 instances +--- + +The Mondoo serverless AWS integration enables continuous cron-scheduled and [event-based](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-service-event.html) scanning of your AWS account or Organization. + +To learn about how an integration runs and its required permissions, read [AWS Integration FAQ](/platform/infra/cloud/aws/lambda/aws-integration-faq/). + +:::info + +Mondoo also offers a Mondoo-hosted method for assessing AWS security. It requires no agent in AWS and is easier to set up. To compare the two approaches, read [Continuously Scan with an AWS Integration](/platform/infra/cloud/aws/aws-integration-scan/). + +::: + +## Integrate with an entire organization or single account + +The serverless Mondoo AWS integration supports scanning multiple AWS accounts. To do this, you install Mondoo across an AWS Organization using CloudFormation StackSets. All scan configuration options you choose apply to every AWS account in the AWS Organization. + +:::caution IMPORTANT + +Before creating a serverless Mondoo deployment on an AWS Organization, make sure to check if the configuration of your AWS organization meets the [requirements](/platform/infra/cloud/aws/lambda/aws-integration-troubleshooting/#requirements-for-deploying-the-mondoo-stackset-at-the-organization-level). + +::: + +You can also opt to scan a single AWS account only. Single account integrations rely on CloudFormation stacks. + +:::info +When you deploy an integration with Mondoo using a StackSet on the organizational level, the StackSet only creates an integration of the [target accounts](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacksets-concepts.html#stacksets-concepts-accts). + +The [administrator account](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacksets-concepts.html#stacksets-concepts-accts) in which the StackSet for the target accounts resides needs its own separate [single account integration](/platform/infra/cloud/aws/aws-integration-scan/#integrate-with-an-entire-organization-or-single-account). + +This is intentional and reflects the [architectural concepts of AWS StackSets](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacksets-concepts.html). +::: + +## Set up a new AWS integration + +1. Access the Integrations > Add > AWS page in one of two ways: + + - **New space setup**: After creating a new Mondoo account or creating a new space, the initial setup guide welcomes you. Select **BROWSE INTEGRATIONS** and then select **AWS**. + + ![Welcome to Mondoo Page](/img/platform/start/welcome_to_mondoo.png) + + - **INTEGRATIONS page**: In the side navigation bar, under **INTEGRATIONS**, select **Add New Integration**. Near the top of the page, select **AWS**. + + ![AWS integration options](/img/platform/infra/cloud/aws/hosted-or-serverless.png) + +2. Select **Serverless**. + + ![integration-create-image](/img/platform/infra/cloud/aws/add-aws-top.png) + +3. Select the type of integration: + + | Option | Description | + | -------------------------- | ------------------------------------------------- | + | **Organization install** | Integrate Mondoo with an entire AWS Organization. | + | **Single account install** | Integrate Mondoo with a single AWS account. | + +4. Identify the account or Organization and the region: + + | If you're integrating with... | Then... | + | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | + | An entire AWS Organization | In the **AWS Organization(s)** box, enter any name for the integration. Select the region in which you want to deploy the integration. | + | A single AWS account | In the **AWS account** box, enter your AWS account ID. Select the region in which you want to deploy the integration. | + +5. Set the account options: + + | Option | Description | + | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | + | **Schedule full scan** | Set the interval (in hours) at which to execute a full scan of the AWS account, independent of change [events](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-service-event.html). The default is 12 hours. | + | **Trigger on AWS console sign-in event** | Trigger an account scan whenever a user logs into the AWS console. | + +6. Set the EC2 options: + + ![integration-create-image](/img/platform/infra/cloud/aws/add-aws-ec2.png) + + | Option | Description | + | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | + | **Discover EC2 instances** | Include EC2 instances in asset discovery. By default, this applies across all regions. | + | **Trigger on instance state change [events](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-service-event.html)** | Trigger a scan of all EC2 instances whenever an instance changes state. | + | [**Use SSM for instance connectivity**](/docs/cnspec/cloud/aws/aws-ssm-scan) | Use the AWS SSM service to trigger scans for EC2 instances (when it's available). | + | **Use EC2 Instance Connect for instance connectivity** | If an EC2 instance has a public IP, connect using EC2 Instance Connect. | + | **Use EBS volume scanning for instance connectivity** | Use _EBS volume scanning_ to scan the filesystems of instances that Mondoo otherwise can't reach. This includes stopped instances. | + +7. If you enable EBS volume scanning, you can customize these options: + + | Option | Description | + | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | + | **EBS targets per scanner** | Customize the number of targets a single scanner instance is responsible for scanning. Setting a low number (such as 5) results in faster scans, but requires AWS to create more scanner instances. Setting a high number (such as 50) reduces the number of scanner instances, but results in slower scans. The default is 20. | + | **Max ASG instances** | Set your own limit for how many instances AWS can spin up in the AutoScalingGroup to perform the filesystem scans. The default is 50. | + +8. To scan EC2 instances using SSH, enable **Use SSH for instance connectivity**. You must use the vault secret query if you use SSH. Provide this information: + + | Option | Description | + | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | + | **Vault type** | Specify whether to read the secret from AWS Secrets Manager or AWS SSM Parameter store. | + | **Vault secret query** | Provide the query to match vault credentials to instances. To learn how to write the query, read [Secrets Management](/platform/infra/opsys/automation/vault.md). | + +9. If desired, limit the EC2 instances that Mondoo scans: + + | Option | Description | Example | + | -------------------------- | ------------------------------------------------------------------------------ | ---------------------------------------- | + | **Filter by instance IDs** | Limit instance scanning to a subset of IDs, separated by commas. | `i-0d1f840578ca82600,i-07ae83fe5d22600a` | + | **Filter by regions** | Limit instance scanning to a subset of regions, separating values with commas. | `us-east-1,us-east-2` | + | **Filter by tags** | To Limit instance scanning to a subset of tags, separated with commas. | `Name:testname, env:test` | + +10. Set ECS, S3, and ECR options: + + ![integration-create-image](/img/platform/infra/cloud/aws/add-aws-bottom.png) + + | Option | Description | + | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | + | **Discover and scan ECS containers** | Use Amazon ECS Exec to scan Fargate containers. | + | **Trigger on S3 bucket [events](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-service-event.html)** | Trigger a scan whenever a change is made to an S3 bucket. | + | **Discover and scan ECR images** | Include ECR images in asset discovery and scan them when found. | + +11. Select the **START SCANNING** button. + +12. Follow the instructions to launch the AWS CloudFormation stack (for an account) or StackSet (for an Organization). + +:::caution IMPORTANT + +Selecting **Create** does not finalize the integration between Mondoo and AWS. You must launch the AWS CloudFormation stack or StackSet to complete the setup. + +::: + +## Manage an AWS integration + +You can view the status of an AWS integration, change its configuration options, and more on its integration page. + +To access an existing integration: + +1. In the [Mondoo Console](https://console.mondoo.com), [navigate](/platform/start/navigate) to the space containing the integration. + +2. In the side navigation bar, under **Integrations**, select **AWS**. + + ![integration-list-image](/img/platform/infra/cloud/aws/list.png) + +3. Select the integration you want to view or manage. + + ![integration-detail-image](/img/platform/infra/cloud/aws/integration-overview.png) + +### View an integration's status + +Mondoo shows the status at the top of the integration page, beside the integration name. + +![Mondoo AWS integration status and actions](/img/platform/infra/cloud/aws/integration-scan-now.png) + +Theses are the possible statuses for an AWS integration: + +| Status | Meaning | +| --------------- | ---------------------------------------------------------------------------------------------------------------- | +| **configuring** | Mondoo is sending the scan configuration options to the integration and the integration is saving those options. | +| **active** | The integration is active and healthy. | +| **error** | Mondoo detected an error during installation. | +| **missing** | Mondoo hasn't received a check-in from the Lambda function for over an hour. | +| **deleted** | CloudFormation for the integration has been deleted. | + +### Ping an integration + +At the top of the integration page, below the integration name, Mondoo shows the time of the last ping. + +To ping the integration now, select the ping icon (a heartbeat to the left of the **SCAN NOW** button). + +### Request a fresh scan + +To see fresh scan results, select the **SCAN NOW** button. Mondoo retrieves new scan results as soon as possible. + +### Stop all running scans + +To stop all currently running AWS scans, on the ellipsis menu of the integration page, select **Cancel Scans**. + +![Stop an AWS scan in Mondoo](/img/platform/infra/cloud/aws/cancel-scan.png) + +### Retry a failed integration setup + +If an error occurred during setup and the CloudFormation stack is now up and running but the integration is unhealthy, you can try to return it to a healthy state: Select the ellipsis to the right of the integration name and select **Retry Setup**. + +### Enable and disable policies for an AWS integration + +The **RECOMMENDED POLICIES** tab on the integration page lists policies that can help you protect your AWS environment. It shows which policies are enabled and disabled. + +![Policies for a Mondoo AWS integration](/img/platform/infra/cloud/aws/integration-policies.png) + +Use the toggle on the right side of each policy's row to enable or disable the policy. + +To learn more about policies, read [Policy as Code](/platform/security/posture/pac/). + +### Reconfigure an AWS integration + +The **CONFIGURATION** tab on the integration page shows the current settings and lets you make changes. + +![Reconfigure a Mondoo AWS integration](/img/platform/infra/cloud/aws/integration-config.png) + +To learn about individual settings, read the sections under the _Set up a new AWS integration_ section above. + +### Remove an integration + +To remove an integration, select the Remove (trash can) icon at the top of the integration page. + +![Remove an AWS Mondoo integration](/img/platform/infra/cloud/aws/integration-scan-now.png) + +A notification displays with a link to the CloudFormation Stacks list in the AWS console. Select the link and, in the AWS console, delete the stack. This removes the configured integration from Mondoo Platform and deletes the rule allowing the Mondoo AWS account to send events to the target account. + +## Learn more + +- [AWS Integration FAQ](/docs/platform/infra/cloud/aws/lambda/aws-integration-faq/) + +- [AWS Integration Troubleshooting](/docs/platform/infra/cloud/aws/lambda/aws-integration-troubleshooting/) + +--- diff --git a/docs/trouble/trouble.mdx b/docs/trouble/trouble.mdx index 059b30667..7f80392a7 100644 --- a/docs/trouble/trouble.mdx +++ b/docs/trouble/trouble.mdx @@ -16,7 +16,7 @@ If you can't find what you're looking for here, try using the search feature in ## Troubleshoot AWS integrations -If you experience issues with an AWS integration, read [Mondoo AWS Integration Troubleshooting](/platform/infra/cloud/aws/aws-integration-troubleshooting/). +If you experience issues with an AWS integration, read [Mondoo AWS Integration Troubleshooting](/platform/infra/cloud/aws/lambda/aws-integration-troubleshooting/). ## Update the Mondoo package for cnquery and cnspec diff --git a/docusaurus.config.js b/docusaurus.config.js index 721b069e0..b017c3de5 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -5,6 +5,35 @@ const { themes } = require("prism-react-renderer"); const legacyRedirects = [ // NOTE: Path / is equivalent to https://mondoo.com/docs/ // + // May 2024 reworked AWS integration stuff when we added hosted aws + { + from: "/platform/infra/cloud/aws/aws-integration-faq", + to: "/platform/infra/cloud/aws/lambda/aws-integration-faq", + }, + { + from: "/platform/infra/cloud/aws/aws-integration-troubleshooting", + to: "/platform/infra/cloud/aws/lambda/aws-integration-troubleshooting", + }, + { + from: "/platform/infra/cloud/aws/aws-scan-details", + to: "/platform/infra/cloud/aws/lambda/aws-scan-details", + }, + { + from: "/platform/infra/cloud/aws/aws-ebs-snapshot-scan", + to: "/cnspec/cloud/aws/aws-ebs-snapshot-scan", + }, + { + from: "/platform/infra/cloud/aws/aws-ec2-ic-scan", + to: "/cnspec/cloud/aws/aws-ec2-ic-scan", + }, + { + from: "/platform/infra/cloud/aws/aws-ssm-scan", + to: "/cnspec/cloud/aws/aws-ssm-scan", + }, + { + from: "/platform/infra/cloud/aws/aws-workstation-scan", + to: "/cnspec/cloud/aws", + }, // April 2024 removed separate Find Vulnerabilities subsection from Security section // part of Firewatch effort { diff --git a/releases/2022-07-12-mondoo-6.6-is-out.md b/releases/2022-07-12-mondoo-6.6-is-out.md index e42e6ac44..7ea9223d0 100644 --- a/releases/2022-07-12-mondoo-6.6-is-out.md +++ b/releases/2022-07-12-mondoo-6.6-is-out.md @@ -30,7 +30,7 @@ Get this release: [Installation Docs](/cnspec/) | [Package Downloads](https://re **Problem:** You want Mondoo to scan your AWS instances, but you want to do it without SSH credentials or an SSM agent and without directly impacting your production workloads. -**Solution:** Mondoo now supports AWS side scanning. You can scan an EC2 instance, an EC2 EBS volume, or an EC2 EBS snapshot. See the [EC2 Snapshot Scanning documentation](/platform/infra/cloud/aws/aws-ebs-snapshot-scan/) for details. +**Solution:** Mondoo now supports AWS side scanning. You can scan an EC2 instance, an EC2 EBS volume, or an EC2 EBS snapshot. See the [EC2 Snapshot Scanning documentation](/cnspec/cloud/aws/aws-ebs-snapshot-scan/) for details. ## 🧹 IMPROVEMENTS diff --git a/static/img/platform/infra/cloud/aws/add-hosted-top.png b/static/img/platform/infra/cloud/aws/add-hosted-top.png new file mode 100644 index 000000000..51f0a0ecd Binary files /dev/null and b/static/img/platform/infra/cloud/aws/add-hosted-top.png differ diff --git a/static/img/platform/infra/cloud/aws/auth.png b/static/img/platform/infra/cloud/aws/auth.png new file mode 100644 index 000000000..ee55f9758 Binary files /dev/null and b/static/img/platform/infra/cloud/aws/auth.png differ diff --git a/static/img/platform/infra/cloud/aws/awsportal.png b/static/img/platform/infra/cloud/aws/awsportal.png new file mode 100644 index 000000000..a8a1cf759 Binary files /dev/null and b/static/img/platform/infra/cloud/aws/awsportal.png differ diff --git a/static/img/platform/infra/cloud/aws/hosted-or-serverless.png b/static/img/platform/infra/cloud/aws/hosted-or-serverless.png new file mode 100644 index 000000000..33d964d86 Binary files /dev/null and b/static/img/platform/infra/cloud/aws/hosted-or-serverless.png differ diff --git a/static/img/platform/infra/cloud/aws/option3.png b/static/img/platform/infra/cloud/aws/option3.png new file mode 100644 index 000000000..6de2c3cbc Binary files /dev/null and b/static/img/platform/infra/cloud/aws/option3.png differ