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:- Enable AWS GuardDuty
- Create IAM policy
- Choose one of the three integration methods based on your organization’s requirements:
- Configure AWS in the AirMDR Integrations Dashboard
AWS Setup Prerequisites
| Step | What you need | Why it’s needed |
|---|---|---|
| 1. | AWS Account (free) | The root thing to log into the AWS Console |
| 2. | Valid Payment Method (credit/debit card) | Required even if you stay within Free Tier |
| 3. | Verified Email Address | AWS will send confirmation and alerts |
| 4. | Enable MFA (Multi-Factor Authentication) | Secure your root user (HIGHLY recommended) |
| 5. | IAM Users and Roles | Create users instead of using the root account for everything |
| 6. | Knowledge of Regions | Decide which AWS region you want to deploy resources in (e.g., us-east-1, eu-west-1) |
| 7. | AWS CLI (optional) | Install locally if you want to manage AWS from terminal |
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.
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:Understand the Purpose of AWS Permissions Used by AirMDR
Understand the Purpose of AWS Permissions Used by AirMDR
✅ AmazonEC2ReadOnlyAccess
✅ AmazonEC2ReadOnlyAccess
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:



✅ AmazonGuardDutyReadOnlyAccess
✅ AmazonGuardDutyReadOnlyAccess
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✅ AmazonS3ReadOnlyAccess
✅ AmazonS3ReadOnlyAccess
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:
✅ AWSCloudTrail_ReadOnlyAccess
✅ AWSCloudTrail_ReadOnlyAccess
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:



✅ CloudWatchReadOnlyAccess
✅ CloudWatchReadOnlyAccess
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:
✅ IAMReadOnlyAccess
✅ IAMReadOnlyAccess
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:
| Policy Name | Access Type | Importance |
|---|---|---|
AmazonGuardDutyReadOnlyAccess | Read-Only | Required |
IAMReadOnlyAccess | Read-Only | Recommended |
AmazonEC2ReadOnlyAccess | Read-Only | Optional |
AmazonS3ReadOnlyAccess | Read-Only | Optional |
AWSCloudTrailReadOnlyAccess | Read-Only | Optional |
CloudWatchReadOnlyAccess | Read-Only | Optional |
- Sign in to the same AWS IAM Console created for AWS GuardDuty.
- Search for IAM in the top menu bar.
-
In the IAM dashboard, click on IAM resources → Policies.

-
Click Create policy in the top right corner.

-
Select JSON tab in the toggle tabs and paste the following:
User can update the Policy Permissions mentioned in the JSON as per requirement. - Click Next.
-
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.

- Policy name – Provide a meaningful name like
-
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.

- Click Create policy.
Option 1: IAM User (Access Key Method)
Use this method if you prefer to authenticate via programmatic access credentials (Access Key ID and Secret Key).
Use this method if you prefer to authenticate via programmatic access credentials (Access Key ID and Secret Key).
- Navigate to IAM → IAM Dashboard.
- Click on IAM resources → User.
-
Click Create user in the top right corner.

-
Enter a User name (e.g.,
airmdr-integrator). -
Click Next.

- In the Set permissions section, select Attach policies directly.
-
Search and select
AirMDR-ReadOnlyPolicy.Click here for detailed steps to define theAirMDR-ReadOnlyPolicyin IAM. -
Click Next.

-
In the Review and create section, click Create user.

-
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.

-
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.

-
On the Retrieve access keys screen, copy the:
- ✅ Access Key ID
- ✅ Secret Access Key
- Click Done.
Option 2: IAM Role (Assume Role via STS)
Use this method if you prefer to delegate access securely using AWS Security Token Service (STS). Recommended for production and enterprise environments.
Use this method if you prefer to delegate access securely using AWS Security Token Service (STS). Recommended for production and enterprise environments.
- Navigate to IAM → IAM Dashboard.
-
Click on IAM resources → Roles.

-
Click on Create role in the top right corner.

- 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. -
Click Next.

-
In the Add permissions section, search and select
AirMDR-ReadOnlyPolicy.Click here for detailed steps to define theAirMDR-ReadOnlyPolicyin IAM. -
Click Next.

-
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.

- Role Name – Provide a meaningful name like
-
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.

-
Provide the required information in the Role details section for the role.
-
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)
- Click Done.
Option 3: Multi-Account Integration using AWS StackSet Method
For organizations managing multiple accounts under an AWS Organization, AirMDR supports Stackset-style delegated access via a root account.
For organizations managing multiple accounts under an AWS Organization, AirMDR supports Stackset-style delegated access via a root account.
-
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).
- Account ID:
- 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)
- Role name: Name the role (e.g.,
- 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_arnparameter. -
Example: Your
root_account_idparameter will be showcased in thearnparameter 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.
-
Example: This becomes your
-
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.
Example value of External ID:Optional: If needed, edit the trust relationship and view the
sts:ExternalIdcondition.
-
You can find it in IAM → Roles → [Your Role] → Trust relationships.
- This is the same External ID you configured during role creation above.
-
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
Before you upload the template file (YAML format) update the
sts:ExternalIdwith an unique value. 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,SSOUserAccountIdandTrustedAccountId) are updated automatically as defined in the template file (YAML format). - Click Next.
-
Provide a unique StackSet name (e.g.,
-
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 yourregion_nameparameter). - 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
Parameter Example Value arnarn:aws:iam::123456789012:role/AirMDROrgAccessRoleexternal_idairmdr-stackset-unique-id-xyzroot_account_id123456789012cross_account_role_nameAirMDRReadOnlyRolecross_account_external_idairmdr-member-role-external-idregion_nameus-east-1Securely 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)
| Credential | How to Get It (UI Path) |
|---|---|
| Access Key ID | IAM → Users → Select user → Security credentials tab → Scroll to Access keys section |
| Secret Access Key | Shown only once during Access Key creation. If lost, delete and create a new access key under “Access keys” |
| Role ARN | IAM → Roles → Click on created role (e.g., AirMDROrgAccessRole) → Copy ARN from top section |
| External ID | IAM → Roles → Select role → Trust relationships → View or edit policy to see sts:ExternalId |
| Region Name | Top-right corner of AWS Console (e.g., us-east-1, ap-south-1) or in the region dropdown in any service page |
| Root Account ID | Click account name (top-right) → My Account → Find 12-digit Account ID under “Account settings” |
| Cross Account Role Name | IAM → Roles (in member account) → Name of role created (e.g., AirMDRReadOnlyRole) |
| Cross Account External ID | IAM → Roles (in member account) → Select role → Trust relationships → Check for sts:ExternalId value |
Skills Provided by this Integration
Skills encapsulate the logic, authentication, parameterization, and external API handling required to perform a task—whether it's data retrieval, transformation, enrichment, or action.
Skills encapsulate the logic, authentication, parameterization, and external API handling required to perform a task—whether it's data retrieval, transformation, enrichment, or action.
| Skill ID | Purpose | Permissions Required |
|---|---|---|
| Lookup AWS CloudTrail Events | Retrieve events from AWS CloudTrail. Use this skill to monitor and audit account activity across your AWS infrastructure, ensuring compliance and security. \ For example, you can track changes made to specific AWS resources or by certain users. | AWSCloudTrail_ReadOnlyAccess |
| Filter AWS CloudWatch Log Events | Filter and retrieve logs from specified AWS CloudWatch LogGroups and LogStreams based on various parameters such as time range and filter patterns. This skill is useful for analyzing and debugging application behavior by examining log data. The output includes detailed log event information such as timestamps, messages, and event IDs. | CloudWatchLogsReadOnlyAccess |
| Get AWS Guard Duty Findings | Retrieve detailed security incident findings from AWS GuardDuty. Use this skill to analyze potential threats and vulnerabilities detected by GuardDuty, helping you maintain the security and integrity of your AWS environments. The output includes comprehensive details about each finding, such as severity, type, and involved resources. | AmazonGuardDutyReadOnlyAccess |
| Get AWS SecurityHub Findings | Retrieve detailed findings from AWS SecurityHub based on specified filters. Use this skill to analyze security alerts and vulnerabilities detected in your AWS environment. You can filter findings by attributes such as account name or resource application name to focus on specific areas of interest. | AWSSecurityHubReadOnlyAccess |
| Get AWS CloudWatch Log Events | Retrieve log events from specified AWS CloudWatch LogGroups and LogStreams. Use this skill to monitor, troubleshoot, and audit activities within your AWS environment by accessing detailed log data. The output includes log event details such as timestamp, message content, and ingestion time. | CloudWatchLogsReadOnlyAccess |
| Execute AWS Athena Query | Use this skill to execute SQL queries in AWS Athena, allowing you to analyze large-scale data directly in S3. This is useful for data analysis and reporting purposes. The output includes detailed query results and execution metadata. | AmazonAthenaFullAccess |
| Get AWS Caller Permissions | Check if the AWS caller has the required permissions specified in the input policies list. This skill helps verify IAM permissions before performing actions that require specific AWS permissions. | |
| Update AWS SecurityHub Finding Status | Update the workflow status of a specific finding in AWS SecurityHub. This skill allows you to change the status of security findings to track their investigation and resolution progress. | |
| general_aws_query | Execute AWS service commands across different services using Boto3 python client. | AmazonEC2ReadOnlyAccess |
| Execute OpenSearch Query | Execute search queries against AWS OpenSearch domains. Use this skill to search and retrieve documents from specified OpenSearch indices using custom query DSL. The output includes the complete search response with matching documents and metadata. | AmazonOpenSearchServiceReadOnlyAccess AmazonOpenSearchIngestionReadOnlyAccess |
Configure AWS in the AirMDR Integrations Dashboard
-
Navigate to AirMDR, provide the credentials, and click Login.

- Navigate to the AirMDR Integrations Dashboard in the left navigation pane and select Integrations.
-
Use the search option, enter the keyword “Amazon Web Services”, select the Connections tab, and click the + Create icon.

-
Enter an unique name to the Instance (e.g.,
your org name-AWS) to easily identify the user connection by AirMDR. -
AirMDR supports multiple authentication methods for integrating with your AWS environment:
-
IAM User (Access Key Method)
To Integrate and authenticate the credentials generated through IAM User (Access Key Method)
- In the Authentication Details → DO IT YOURSELF
- 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 userThis key is generated when creating the Access Key for the user.
-
- In the Step. 5 enter the region name.
region_name: AWS region to be used for integration (e.g.,us-east-1)
- Click the “Create” button to save the integration configuration.
- Click the “Authenticate” button to validate the credentials and authorize the connection.
-
IAM Role (Assume Role Method)
To Integrate and authenticate the credentials generated through IAM Role (Assume Role Method)
- In the Authentication Details → DO IT YOURSELF
- In the Step. 3 provide the values: Required Fields in the Authentication Details field params:
role_arn: ARN of the IAM role to assumeexternal_id: External ID configured in the IAM role’s trust policy
- In the Step. 5 enter the region name.
region_name: AWS region to be used for integration (e.g.,us-east-1)
- Click the “Create” button to save the integration configuration.
- Click the “Authenticate” button to validate the credentials and authorize the connection.
-
Multi-Account Integration using AWS Stackset Method
To Integrate and authenticate the credentials generated through AWS Stackset Method
- In the Authentication Details → DO IT YOURSELF
- 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 accountsroot_account_external_id: External ID in the root account role’s trust policyroot_account_id: Account ID of the root/management accountcross_account_role_name: Name of the IAM role created in all member accountscross_account_external_id: External ID configured in member accounts’ trust policies
- In the Step. 5 enter the region name.
region_name: AWS region to be used for integration (e.g.,us-east-1)
- Click the “Create” button to save the integration configuration.
- Click the “Authenticate” button to validate the credentials and authorize the connection.
-
IAM User (Access Key Method)

