Skip to main content

Overview

AirMDR integrates with Amazon Web Services (AWS) to enrich alerts, perform threat detection using GuardDuty, investigate logs, and extract contextual metadata from cloud resources. To support these capabilities, AirMDR requires read-only access to specific AWS services, which can be granted by following these steps:
  1. Enable AWS GuardDuty
  2. Create IAM policy
  3. Choose one of the three integration methods based on your organization’s requirements:
  4. Configure AWS in the AirMDR Integrations Dashboard
    After completing the above steps, click here to view or access all the generated AWS authentication parameters in the AWS UI Console.

AWS Setup Prerequisites

AirMDR – AWS Integration Guide

Enable AWS GuardDuty

AWS GuardDuty is mandatory for integration with AirMDR because it serves as the primary threat detection engine in your AWS environment and AirMDR relies on GuardDuty findings to perform its core security use cases.
To Enable AWS GuardDuty, refer to Getting started with GuardDuty.

Create IAM policy

To allow AirMDR to fetch telemetry data and perform read-only queries on your AWS environment, create a custom IAM policy with the following managed policies:
Creating a custom IAM policy in AWS is important when integrating with platforms like AirMDR because it allows you to define precise, least-privilege access
Expand this sections to explore the complete set of AWS IAM permissions used by AirMDR, along with how they are applied across skills, actions, and playbooks. This information is intended for reference purposes, and helpful when reviewing access scope, customizing IAM policies, or conducting security reviews.
🔹 Description:
Provides read-only access to EC2 and container metadata, enabling AirMDR to enrich alerts, assess security configurations, classify workloads by risk, and validate container deployment standards.
🔸 Input Params Used:
service_name: ec2, method_name: describe_instances
🔸 AWS Actions:
ec2:DescribeInstances
🔸 Skills Used:
general_aws_query
📎 Findings:image.pngAWS45 PnAWS46 PnAWS47 Pn
🔹 Description:
Enables AirMDR to retrieve and analyze GuardDuty findings for suspicious activity related to S3 buckets and remote IPs, supporting threat pattern detection, anomaly analysis, and automated case enrichment.
🔸 AWS Actions:
guardduty:GetFindings, guardduty:ListFindings, guardduty:GetDetector
🔸 Skills Used:
Get AWS Guardduty Findings
🔹 Description:
Provides read-only access to evaluate S3 bucket security by checking configurations, classifying data sensitivity, and validating real-world exposure risks.
🔸 Input Params Used:
service_name: s3, method_name: [get_bucket_acl, get_public_access_block, get_bucket_policy, get_bucket_tagging, list_objects_v2]
🔸 AWS Actions:
s3:GetBucketAcl, s3:GetBucketPublicAccessBlock, s3:GetBucketPolicy, s3:GetBucketTagging, s3:ListBucket
🔸 Skills Used:
general_aws_query
📎 Findings:AWS48 Pn
🔹 Description:
Grants read-only access to CloudTrail logs for reconstructing activity timelines, detecting suspicious patterns, and enriching alerts with user and process-level context.
🔸 Input Params Used:
Attribute Key: ResourceName, Attribute Value: ec2 instance id, filter_key: sourceIPAddress
🔸 AWS Actions:
cloudtrail:DescribeTrails, cloudtrail:GetTrailStatus, cloudtrail:LookupEvents
🔸 Skills Used:
Lookup AWS Cloudtrail Events
📎 Findings:AWS49 PnAWS50 PnAWS51 PnAWS52 Pn
🔹 Description:
Allows read-only access to CloudWatch logs for analyzing VPC activity, extracting alert context, and enriching investigations with time-bound log insights.
🔸 Input Params Used:
Log Group Name, Log Stream Name Prefix
🔸 AWS Actions:
logs:DescribeLogGroups, logs:DescribeLogStreams, logs:GetLogEvents, logs:FilterLogEvents
🔸 Skills Used:
Filter AWS CloudWatch Log Events
📎 Findings:AWS53 Pn
🔹 Description:
Enables validation of IAM permissions and detection of unusual user behavior, such as bulk S3 modifications, to support access risk analysis.
🔸 Input Params Used:
service_name: iam, method_name: [get_user, list_attached_user_policies, simulate_principal_policy]
🔸 AWS Actions:
iam:GetUser, iam:ListAttachedUserPolicies, iam:SimulatePrincipalPolicy, cloudtrail:LookupEvents
🔸 Skills Used:
Lookup AWS Cloudtrail Events, general_aws_query
📎 Findings:AWS54 Pn
  1. Sign in to the same AWS IAM Console created for AWS GuardDuty.
  2. Search for IAM in the top menu bar.
  3. In the IAM dashboard, click on IAM resources → Policies. AWS12 Pn
  4. Click Create policy in the top right corner. AWS13 Pn
  5. Select JSON tab in the toggle tabs and paste the following: AWS14 Pn
    User can update the Policy Permissions mentioned in the JSON as per requirement.
  6. Click Next.
  7. In the Review and create section, provide the required information for the Policy details.
    • Policy name – Provide a meaningful name like AirMDR-ReadOnlyPolicy.
    • Description (Optional) – Add a short description for this policy.
    AWS16 Pn
  8. Review your selections (Permissions defined in this policy), and if everything is correct.
    • Review Permissions – Ensure the attached policies meet your security needs.
    • Review Trust Policy – Verify the trust policy when you use cross-account access or service.
    AWS17 Pn
  9. Click Create policy.

Option 1: IAM User (Access Key Method)

  • Navigate to IAM → IAM Dashboard.
  • Click on IAM resources → User.
  • Click Create user in the top right corner. AWS18 Pn
  • Enter a User name (e.g., airmdr-integrator).
  • Click Next. AWS19 Pn
  • In the Set permissions section, select Attach policies directly.
  • Search and select AirMDR-ReadOnlyPolicy .
    Click here for detailed steps to define the AirMDR-ReadOnlyPolicy in IAM.
  • Click Next. AWS20 Pn
  • In the Review and create section, click Create user. AWS21 Pn
  • Search and select the User name (e.g., airmdr-integrator) created earlier.
  • Click on Create access key.
  • Select the Command Line Interface (CLI) Use case, and the confirmation checkbox.
  • Click Next. AWS25 Pn
  • In the set description tag - optional section, provide the required information for the Description tag value.
    • Description tag value (Optional) – Access key for AirMDR’s Use case.
  • Click Create access key. AWS27 Pn
  • On the Retrieve access keys screen, copy the:
    • Access Key ID
    • Secret Access Key
    This is the only time you can view the Access Key ID and Secret Access Key so it is recommended to Download .csv file and save it securely in the password manager or organization vault for future reference
  • Click Done.

Option 2: IAM Role (Assume Role via STS)

If you need to grant secure API access to AWS services (e.g., EC2, Lambda, or third-party applications), you must create an IAM role with the right permissions.
  • Navigate to IAM → IAM Dashboard.
  • Click on IAM resources → Roles. AWS29 Pn
  • Click on Create role in the top right corner. AWS30 Pn
  • In the Select a trusted entity → Trusted entity type section, chooseAWS Account .
  • In the An AWS account section, choose Another AWS Account.
  • Enter the AirMDR AWS Account ID: 242133657058 only as an identifier of the account that can use this role.
    Generally, the Account ID is a 12-digit Number, use only the Account ID mentioned above.
  • Select the Required external ID Options checkbox (Best practice when a third party will assume this role).
  • Provide a meaningful name for the External ID like example-external-ID.
    The ExternalIdvalue must have a minimum of 2 characters and a maximum of 1,224 characters. The value must be alphanumeric without white space. It can also include the following symbols: plus (+), equal (=), comma (,), period (.), at (@), colon (:), forward slash (/), and hyphen (-) 
    To enhance the Security:
    1. Specify an External ID, a unique identifier that the trusted account must provide when assuming the role
    2. To add an external_id:
      • Select the Require an external ID checkbox.
      • Enter the unique agreed-upon external ID value.
      • Do NOT check “Require MFA” unless the assuming account needs MFA.
  • Click Next. AWS32 Pn
  • In the Add permissions section, search and select AirMDR-ReadOnlyPolicy.
    Click here for detailed steps to define the AirMDR-ReadOnlyPolicy in IAM.
  • Click Next. AWS33 Pn
  • In the Name, review and create section.
    • Provide the required information in the Role details section for the role.
      • Role Name – Provide a meaningful name like AirMDR-Role.
      • Description (Optional) – Add a short description for this role.
      AWS34 Pn
    • Review your selections (Permissions and Policies), and if everything is correct.
      • Review Permissions – Ensure the attached policies meet your security needs.
      • Review Trust Policy – Verify the trust policy when you use cross-account access or service.
    • Click Create role.
    AWS35 Pn
  • Search and select the role (e.g., AirMDR-Role) created earlier.
  • Once the role is created, click on the role name
  • Copy and securely save the Role ARN (Amazon Resource Name):
    • Role ARN
    • External ID (entered earlier)
      Securely save and share these credentials with the AirMDR support team to allow monitoring.
  • Click Done.

Option 3: Multi-Account Integration using AWS StackSet Method

  1. Create IAM Role ARN from Root (Management) Account
    • Sign in to the Root AWS Account.
    • In the AWS Console Home, navigate to IAM → Roles.
    • Click on Create role in the top right corner.
    • Choose AWS Account from Trusted entity type.
    • Choose Another AWS Account from An AWS account.
    • Enter:
      • Account ID: 242133657058 (AirMDR’s AWS account)
      • Enable External ID and set a secure unique string (you’ll need this again later).
    • Assign the AWS policy: AWSOrganizationsReadOnlyAccess.
    • Click Next.
    • Provide the Role details
      • Role name: Name the role (e.g., AirMDROrgAccessRole).
      • Description: Add a short explanation of this role (Optional)
    • Click Create role.
    • After creation, open the role created (e.g., AirMDROrgAccessRole) and copy the Role ARN and root Account ID.
      • Example: This becomes your root_account_role_arn parameter.
      • Example: Your root_account_id parameter will be showcased in the arn parameter or access it from the AdministratorAccess drop-down in the top-right corner.
        The account is generally 12-digit shown on the page.This account ID also helps AirMDR know whether to ignore pulling data from the root account if needed.
  2. External ID Used in Root Account Role Trust Policy
    • This is the same External ID you configured during role creation above.
      • You can find it in IAM → Roles → [Your Role] → Trust relationships.
        Optional: If needed, edit the trust relationship and view the sts:ExternalId condition.
        Example value of External ID:
        The ExternalIdvalue must have a minimum of 2 characters and a maximum of 1,224 characters. The value must be alphanumeric without white space. It can also include the following symbols: plus (+), equal (=), comma (,), period (.), at (@), colon (:), forward slash (/), and hyphen (-) 
  3. AWS Stacksets This is the common IAM role name that you will create in every member account.
    • Sign in to the Root AWS Account.
    • In the AWS Console Home → CloudFormation.
    • In the left navigation pane of CloudFormation, select Stacksets.
    • Click on Create StackSet in the top right corner.
    • Step 1: In the Choose a template page, select the radio buttons for the respective options as mentioned below:
      • In the Permissions model → Service-managed permissions
      • In the Prerequisite - Prepare Template → Template is ready
      • In the Specify template → Upload a template file
        Use the Choose file option to upload a template file in the format of YAML provided by AirMDR support team.

        If you do not have the template file (YAML format) request it from AirMDR support team.
        Before you upload the template file (YAML format) update the sts:ExternalId with an unique value.
        The ExternalIdvalue must have a minimum of 2 characters and a maximum of 1,224 characters. The value must be alphanumeric without white space. It can also include the following symbols: plus (+), equal (=), comma (,), period (.), at (@), colon (:), forward slash (/), and hyphen (-) 
        Template file (YAML format):
        • Click Next.
      • Step 2: In the Specify StackSet details page
        • Provide a unique StackSet name (e.g., AirMDR-StackSet).
        • Provide the StackSet description (Optional)
          All the Parameters (RoleName, SSOUserAccountIdand TrustedAccountId) are updated automatically as defined in the template file (YAML format).
        • Click Next.
      • Step 3: In the Configure StackSet options page, select the radio buttons for the respective options as mentioned below:
        • In the “Execution configuration → Managed execution”, select the option Inactive (Stacksets performs one action at a time)
        • In the Capabilities, acknowledge by selecting the checkbox.
        • Click Next.
      • Step 4: In the Set deployment options page, select the radio buttons for the respective options as mentioned below:
        • In the “Add stacks to stack set”, select the option Deploy new stacks
        • In the “Deployment targets”, select the option Deployment to organisation
        • In the “Auto-deployment options → Automatic deployment”, select the option Activated
        • In the “Auto-deployment options → Account removal behaviour”, select the option Delete stacks
        • In the “Specify Regions”, choose the applicable region code (as per organizational requirements) in which you want to deploy stacks. Example: us-east-1 (This will be your region_name parameter).
        • In the “Deployment options → Region concurrency”, select the option Sequential
        • In the “Deployment options → Concurrency mode”, select the option Strict failure tolerance
        • Click Next.
      • Step 4: In the Review page:
        • Review all the Permissions, StackSet details, StackSet configuration options, Deployment Options provided
        • Click Submit.
      Upon successful completion of assigning the role name (e.g.,AirMDRReadOnlyRole), and an external ID with unique value.
      The same Role is created across all the child accounts.

      ✅ Final Summary of Collected Parameters

      Securely save and share these credentials with the AirMDR support team to allow monitoring.

Where to find the generated AWS Authentication Parameters in the Console (UI Steps)

Skills Provided by this Integration

To view the details of Input Parameters and Output for the respective skills
  • Go to AirMDR → AWS Integration page.
  • Select the Skills tab and click on the required listed skills.

Configure AWS in the AirMDR Integrations Dashboard

  1. Navigate to AirMDR, provide the credentials, and click Login.
  2. Navigate to the AirMDR Integrations Dashboard in the left navigation pane and select Integrations.
  3. Use the search option, enter the keyword “Amazon Web Services”, select the Connections tab, and click the + Create icon. images/AWS1.png
  4. Enter an unique name to the Instance (e.g., your org name-AWS) to easily identify the user connection by AirMDR.
  5. AirMDR supports multiple authentication methods for integrating with your AWS environment:
    • IAM User (Access Key Method)
      1. In the Authentication Details → DO IT YOURSELF
      2. Go to Step. 2 and provide the values: Required Fields in the Authentication Details field params:
        • access_key: Access Key ID of the IAM user
        • secret_key: Secret Access Key associated with the IAM user
          This key is generated when creating the Access Key for the user.
      3. In the Step. 5 enter the region name.
        • region_name: AWS region to be used for integration (e.g., us-east-1)
      4. Click the “Create” button to save the integration configuration.
      5. Click the “Authenticate” button to validate the credentials and authorize the connection.
    • IAM Role (Assume Role Method)
      1. In the Authentication Details → DO IT YOURSELF
      2. In the Step. 3 provide the values: Required Fields in the Authentication Details field params:
        • role_arn: ARN of the IAM role to assume
        • external_id: External ID configured in the IAM role’s trust policy
      3. In the Step. 5 enter the region name.
        • region_name: AWS region to be used for integration (e.g., us-east-1)
      4. Click the “Create” button to save the integration configuration.
      5. Click the “Authenticate” button to validate the credentials and authorize the connection.
    • Multi-Account Integration using AWS Stackset Method
      1. In the Authentication Details → DO IT YOURSELF
      2. In the Step. 4 provide the values: Required Fields in the Authentication Details field params:
        • root_account_role_arn: ARN of the IAM role in the root account used to list accounts
        • root_account_external_id: External ID in the root account role’s trust policy
        • root_account_id: Account ID of the root/management account
        • cross_account_role_name: Name of the IAM role created in all member accounts
        • cross_account_external_id: External ID configured in member accounts’ trust policies
      3. In the Step. 5 enter the region name.
        • region_name: AWS region to be used for integration (e.g., us-east-1)
      4. Click the “Create” button to save the integration configuration.
      5. Click the “Authenticate” button to validate the credentials and authorize the connection.