LeanIX programmatically collects information about your cloud environment using the cloud provider's API. The software that collects this information runs outside of your AWS Accounts. It assumes an AWS IAM Role in each of your AWS Accounts in order to retrieve temporary credentials that allow it to discover your cloud resources.

Get input from LeanIX

LeanIX provides you with the core information to connect your AWS environment in Self-Service. In your VSM Workspace, go to Administration > Integrations > Public Cloud Integration > Configure.

Get the Account ID

🚧

Important

LeanIX authenticates with your AWS accounts via a trusted entity. For the configuration, you need the following:

LeanIX Account ID: 843060708181

Create an external ID

A unique external ID is recommended by AWS to increase the security of your connection. At Administration > Integrations > Public Cloud Integration > Configure, click the Generate AWS external ID button - your AWS external ID will then be copied to your clipboard

Get the list of permissions for the IAM Policy

LeanIX provides the list of required permissions for the IAM policy. At Administration > Integrations > Public Cloud Integration > Configure, click the Download AWS policies button to download an IAM Policy text (JSON).

If you configure discovery for the management account of an AWS Organization, add the following permissions to the policy text:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Resource": "*",
            "Action": [
                "organizations:DescribeOrganization",
                "organizations:ListAccountsForParent",
                "organizations:ListOrganizationalUnitsForParent",
                "organizations:ListRoots",
                "organizations:ListTagsForResource"
            ]
        }
    ]
}

Create the AWS IAM Policy

Your organization likely has processes and tooling in place to create resources like IAM Roles and Policies in a set of AWS Accounts in an automated way (using, for example, AWS CloudFormation or Terraform).
We will show how to create an IAM Role with an IAM Policy using the AWS Console, to be independent of tooling. If you prefer to use CloudFormation, you can find a template in the appendix.
Create the following IAM Policy and IAM Role in each AWS Account.

1. In the AWS Console, go to Identity and Access Management (IAM) > Access Management > Policies.
2. Click the button Create policy.
3. Go to the tab JSON.
4. Paste the IAM Policy text into the editor field.

5. Click the button Next: Tags.
6. Click the button Next: Review
7. Enter a name for the IAM Policy, for example, “LeanIXCloudDiscovery”.
8. Click the button Create policy.

❗️

Periodically update the IAM Policy

The IAM Policy contains only the minimal permissions necessary to enable the capabilities of LeanIX Cloud Discovery at that point in time. Periodically check if you need to update the AWS IAM Policy to take advantage of the growing set of capabilities.

Create the AWS IAM Role

1. In your AWS Console, go to Identity and Access Management (IAM) > Access Management > Roles.
2. Click the button Create role.
3. Select Another AWS Account .
4. Enter the Account ID that was provided to you by LeanIX.
5. Under Options enable Require external ID (Best practice when a third party will assume this role).
6. Enter the External ID provided to you by LeanIX.

7. Click the button Next: Permissions.
8. Search for and select the IAM Policy that you created (for example, "LeanIXCloudDiscovery").

9. It is recommended to attach an additional IAM Policy that provides read access to the configuration of a wide range of services. This is to ensure that you do not need to update the permissions each time additional cloud services are supported. Attach the AWS-managed Policy arn:aws:iam::aws:policy/SecurityAudit (or a similar Policy) to the Role. For further information see appendix.
10. Click the button Next: Tags.
11. Click the button Next: Review
12. Enter a name for the IAM Role, for example, “LeanIXCloudDiscovery”.
13. Click the button Create role.

Configure LeanIX to discover your AWS Accounts

1. In your LeanIX VSM Workspace, go to Administration > Integrations > Public Cloud Integration > Configure.
2. Copy the following configuration into the editor field. Replace the AWS IAM Role arn with the ARN of the IAM Roles that you created in your AWS Accounts.
   You can add multiple entries in the accounts array by following the example below.

{
  "aws": {
    "accounts": [
      {
        "arn": "arn:aws:iam::123456789012:role/LeanIXCloudDiscovery"
      },
      {
        "arn": "arn:aws:iam::210987654321:role/LeanIXCloudDiscovery"
      }
    ]
  }
}

📘

Hint

You can find your Role ARN by going to IAM > Access Management > Roles and search for the role you created in the previous steps. The Role ARN is the first entry under Summary.

3. Click the button Overwrite all configurations to save your configuration.

Let LeanIX discover your cloud environment

1. In your LeanIX VSM Workspace, go to Administration > Integrations > Public Cloud Integration > Configure.
2. Click the button Scan now to start the discovery process. Wait until all scan runs show the status COMPLETED (Refresh the browser page if necessary).

You can now browse the inventory of your cloud environment.

Appendix: Permissions for LeanIX cloud discovery

The software that discovers your cloud resources runs outside of your AWS Accounts. It assumes an AWS IAM Role in each of your AWS Accounts in order to retrieve temporary credentials that allow it to discover your cloud resources.
You have full control over the permissions that LeanIX obtains and you are able to restrict them at any time for any of your AWS Accounts. On the flip side, you have to create and maintain an IAM Role and its IAM Policies in each AWS Account.

Required permissions

From your VSM workspace, you can always download the list of required permissions in the form of an AWS IAM Policy text as described here. This list contains only the minimum permissions needed for cloud discovery to work. These permissions are needed to describe the configuration of your cloud resources and to read your cloud costs. If you only use this policy, you will have to update its permissions frequently to take advantage of the newest LeanIX capabilities.

Avoiding frequent updates of IAM Policies

Therefore, to avoid frequent updates to the permissions, LeanIX customers may choose to use an additional IAM Policy. This is recommended if you prefer not to repeat the process to review and update the above IAM Policy every two to four weeks.
In addition to the IAM Policy with the minimally required permissions from above, attach the SecurityAudit Policy to the IAM Role. This policy is managed by AWS and contains read permissions for many services. However, it does not include all of the permissions required by LeanIX, e.g.

• ce:GetCostAndUsage
• ce:GetReservationUtilization
• sts:GetCallerIdentity
• tag:GetTagValues

Custom IAM Policies

You can always attach additional IAM Policies to the IAM Role, AWS-managed or company-specific, e.g. to use curated read permissions for selected services, or explicit deny. Obviously, this requires slightly higher effort on the customer side, as your standards need to be reconciled with LeanIX's requirements.
Make sure that IAM Policies you attach to the IAM Role used by LeanIX do not contain permissions to read data from data stores (e. g., s3:GetObject, dynamodb:GetItem, etc.).
You can also use permission boundaries to limit the permissions.

Appendix: Using an external ID when assuming an IAM Role

LeanIX cloud discovery uses an external ID when assuming the IAM Role for a customer's AWS Account. This is recommended by AWS and prevents confused deputy attacks, see this AWS blog post.
The external ID is unique per customer. The cloud discovery software generates it on-the-fly and uses it when assuming an IAM Role. Thus, the external ID not stored.
The external ID is not used by human operators.
The cloud discovery software runs in a dedicated production account, with strictly limited and monitored access.
When the customer retrieves the external ID by clicking the button "Generate AWS external ID" under Administration > Integrations > Public Cloud Integration > Configure, the external ID is generated on-the-fly and presented to the customer but not stored.

Appendix: AWS CloudFormation Template

You can use this AWS CloudFormation Template to create the IAM Role and the IAM Policy.

1. Paste the necessary permissions into the IAM Policy Statement.
2. Remove the comments < ... > to ensure proper JSON formatting.
3. Create the CloudFormation Stack, specifying the account id and the external ID provided by LeanIX as Stack Parameters.

{
  "AWSTemplateFormatVersion": "2010-09-09",
  "Parameters": {
    "AccountId": {
      "Type": "String",
      "Description": "Account Id provided by LeanIX"
    },
    "ExternalId": {
      "Type": "String",
      "Description": "External Id provided by LeanIX"
    }
  },
  "Resources": {
    "DiscoveryRole": {
      "Type": "AWS::IAM::Role",
      "Properties": {
        "AssumeRolePolicyDocument": {
          "Version": "2012-10-17",
          "Statement": [
            {
              "Effect": "Allow",
              "Principal": {
                "AWS": {
                  "Ref": "AccountId"
                }
              },
              "Action": "sts:AssumeRole",
              "Condition": {
                "StringEquals": {
                  "sts:ExternalId": {
                    "Ref": "ExternalId"
                  }
                }
              }
            }
          ]
        },
        "Description": "Role for LeanIX Cloud Discovery",
        "ManagedPolicyArns": [
          {
            "Ref": "DiscoveryPolicy"
          },
          < it is recommended to attach an additional Policy with wide-ranging read access
             like SecurityAudit so that you can take advantage of new capabilities without 
            frequently updating the Policy above. >
          "arn:aws:iam::aws:policy/SecurityAudit"
        ],
        "Path": "/",
        "RoleName": "LeanIXCloudDiscovery"
      }
    },
    "DiscoveryPolicy": {
      "Type": "AWS::IAM::ManagedPolicy",
      "Properties": {
        "Description": "Policy for LeanIX Cloud Discovery",
        "ManagedPolicyName": "LeanIXCloudDiscovery",
        "Path": "/",
        "PolicyDocument": {
          "Version": "2012-10-17",
          "Statement": [
            {
              "Effect": "Allow",
              "Resource": "*",
              "Action": [
                "ce:GetCostAndUsage",
                "ec2:DescribeInstances",
                "support:DescribeTrustedAdvisorCheckResult",
                < ...
                  paste the necessary permissions from
                  Administration > Integrationgs > Public Cloud Integration > Configure > > Download policies
                  here >
              ]
            },
            {  
              < this part only for the management account of an AWS Organization >
              "Effect": "Allow",
              "Resource": "*",
              "Action": [
                "organizations:DescribeOrganization",
                "organizations:ListAccountsForParent",
                "organizations:ListOrganizationalUnitsForParent",
                "organizations:ListRoots",
                "organizations:ListTagsForResource"
              ]
            }
          ]
        }
      }
    }
  }
}

Appendix: Cloud Spend Information

For AWS, cloud spend information is extracted for all scanned AWS Accounts automatically. In addition, for all Tag groups which are configured with a mapping to Software Artifacts in VSM, the Public Cloud integration will evaluate Cost Allocation tags setup in AWS.