AirMDR Self‑Serve Integration

Introduction

The Self‑Serve Integration feature in AirMDR empowers organizational administrators and developers to create and deploy their own integrations without engineering assistance.
This module enables defining new integration providers, configuring authentication methods, building skills (custom actions), and testing them directly from the AirMDR console. With Self‑Help Integration, super‑admins can:

Add new third‑party integration providers on demand
Define authentication and connection parameters
Create reusable skills for automation workflows
Deploy and test integrations instantly inside AirMDR

Prerequisites

Role: Organization Super Admin privileges in AirMDR
Access: Integration Dashboard in the left navigation panel
Dependencies: Internet access to AirMDR GitHub integration templates (for authentication examples)
Knowledge: Basic understanding of Python and REST APIs (for writing skill code)

Workflow Summary

Step	Action	Outcome
1	Define Provider	Creates integration entry
2	Set Authentication	Configures provider credentials
3	Generate Form	Enables dynamic credential input fields based on connection parameters
4	Test Authentication	Confirms connection validity using the test_authentication() function
5	Add Skill	Defines custom logic/action (fetch, enrich, notify, etc.)
6	Generate Skill	Generates a working skill definition inside the integration
7	Deploy Integration	Makes the integration and skill available inside AirMDR
8	Add Connection	Registers live credentials (e.g., API URL, API Key) for use in playbooks
9	Use in Playbook	Deployed skill appears as selectable option in playbook step editor

Navigating to the AirMDR Integrations Dashboard

Log in to AirMDR using super‑admin credentials.
From the left navigation pane, select Integrations  → Dashboard.
Choose the desired organization from the dropdown menu.
The Organization dropdown will only appear if the current org has one or more child organizations.
If no child orgs exist, the dropdown will be hidden and the integration will apply to the current org by default.
Click the “+” icon (top‑right corner) to create a new integration provider.

Creating a New Integration Provider

Define Provider Information

Fill in the following fields:

Field	Description
Provider Name	Display name of your integration provider
Category	Choose the most relevant integration category
Logo Upload	Upload a logo image (SVG/PNG preferred)
Documentation URL	Link to external or internal provider documentation
Description	Short summary of what the integration does

Click Save Draft and Proceed to Authentication.

Configuring Authentication

In this step, define how users will authenticate with the integration provider.

Choose Authentication Type

Click View Templates to open the official AirMDR Integration Templates repository.
In the authentication_types folder, review available options:
- api_key
- base64
- basic_auth
- oauth2

Each template provides a predefined Python snippet and connection structure.

Tip: Start with the authentication model that matches your provider’s API specification.

Connection Parameters

Inside your authentication template, you must define a Connection Parameters block:

### Connection Parameters
API_URL = ConnectionParam(
    "API_URL",
    description="Base API URL (e.g. https://api.example.com)",
    input_type=InputType.URL,
)
API_KEY = ConnectionParam(
    "API_KEY",
    description="Authentication key for API access",
    input_type=InputType.SECRET,
)
### End of Connection Parameters

Guidelines

Begin with ### Connection Parameters and end with ### End of Connection Parameters.
Declare each parameter as a ConnectionParam object.
Read parameters from auth_params using ConnectionParam.read_value.

Example:

self.api_url = API_URL.read_value(auth_params)
self.api_key = API_KEY.read_value(auth_params)

🔒 Note: Type conversion is handled internally by read_value; no additional parsing is required.

Integration Class Declaration

Create a class to encapsulate your integration logic:

class MyIntegrationProvider:
    """Defines connection and authentication handling."""

The class name is automatically captured by AirMDR for registration.

Test Authentication Function

Every integration must include a test function:

def test_authentication(auth_params):
    """
    Called from the UI to verify authentication credentials.
    Returns HTTP 200 on success.
    """

The platform executes this function to confirm connection before allowing deployment.

Test and Generate Form

After defining your parameters and class, click Generate Form.
Enter your API URL and API Key (if applicable).
Click Test Authentication to validate credentials.

If successful, proceed to skill creation.

Skipping Authentication (Optional)If your provider does not require authentication, select the checkbox “Skip Authentication” and continue.

Creating Skills

Skills represent the specific actions or data fetches your integration can perform within AirMDR. Click “+ Add New Skill” or “+ Create New Skill”, then provide:

Skill Name
Skill Description

Skill Code Structure

Each skill must follow the standardized AirMDR coding format.

⚙️ Order of Code Sections

Input Parameters
Output Parameters
def run_skill(input_params, auth_params):

All custom logic should reside within run_skill.

Input Parameters Section

### Input Parameters
QUERY = InputParameter(
    "QUERY",
    description="Enter search query",
    input_type=InputType.TEXT,
)
### End of Input Parameters

Guidelines

Start the section with:
### Input Parameters
End the section with:
### End of Input Parameters
Define each input using the InputParameter constructor.
Use a class-like format with assignments (do not wrap in a class definition).
❌ Do not use variable assignment outside this pattern
✅ Do not wrap in class Input:
Avoid dynamic assignments like QUERY = ... outside the defined structure.
These will not be parsed correctly by the skill loader.

Example:

### Input Parameters
QUERY = InputParameter(
    "QUERY",
    description="Query to run against the provider",
    input_type=InputType.TEXT,
)

LIMIT = InputParameter(
    "LIMIT",
    description="Maximum number of results",
    input_type=InputType.NUMBER,
)
### End of Input Parameters

🔒 Note: The parameter names (e.g., QUERY, LIMIT) must match the internal references used in your logic.

How to Access Input Values in Code You can access each input parameter inside the run_skill() function using the .read_value() method.

query = QUERY.read_value(input_params)
limit = LIMIT.read_value(input_params)

AirMDR automatically handles type validation and conversion using the InputType declaration, so you don’t need to manually convert strings or numbers.

Input Types Available

InputType	Description
`TEXT`	Free-form single line string
`TIMESTAMP`	Date-time picker for entering ISO 8601 timestamps
`NUMBER`	Integer or float input
`URL`	Field for entering a valid URL
`OAUTH_URL`	Authorization URL used to initiate OAuth2 flows
`CLIENT_ID`	OAuth2 client ID used in authentication requests
`CLIENT_SECRET`	OAuth2 client secret (secured and masked input)
`LIST`	Dropdown list with predefined selectable options
`BOOLEAN`	Toggle switch for True/False values (typically rendered as a checkbox)

🔐 Use SECRET for sensitive values like API keys or tokens.

✅ Best Practices

Use meaningful names like QUERY, HOST, or USER_ID.
Add clear description fields to improve form clarity.
Avoid redundant or unused parameters.
Group related parameters logically for better UX.

Output Parameters Section

### Output Parameters
STATUS = OutputParameter(
    name="STATUS",
    description="Status of the skill execution",
    data_type=DataType.STRING,
)
LOGS = OutputParameter(
    name="LOGS",
    description="Logs generated during execution",
    data_type=DataType.JSON,
)
### End of Output Parameters

Skill Function Definition

def run_skill(input_params, auth_params):
    """Processes user query and returns status and logs."""
    try:
        query = QUERY.read_value(input_params)
        logs = {"query": query}
        return {"STATUS": "success", "LOGS": logs}
    except Exception as e:
        return {"STATUS": "error", "LOGS": {"error": str(e)}}

Generate and Deploy Skill

Click Generate to build the skill definition.
Provide your input fields and test using Test Run.
Save draft if needed, or click Deploy Integration (top‑right corner).
Use Save to Draft frequently to prevent loss of progress.

Post‑Deployment Actions

After deployment:

The integration appears in your Integrations Dashboard.
You can clone, edit, delete, or add new skills at any time.
Search for integrations by Provider Name or Skill Name using the dashboard search bar.

🔗 Adding a Connection for a Deployed Skill in AirMDR

If an Authentication is defined for a Integration, then connection is necessary to access the skills.

When is a Connection Required?

If the integration uses auth_params like API_URL, API_KEY, TOKEN, etc.
If you’re deploying the same integration across multiple organizations

Add a Connection in AirMDR

Go to Integrations Dashboard

Login to the AirMDR console as a Super Admin.
From the left navigation pane, click on Integrations.
Locate your deployed integration by Provider Name or Skill Name using the dashboard search bar.

Open the Provider

Click on the name of the deployed integration.
You will see the list of associated skills and connections (if any).
Click on the “+ New Connection” button (top-right of the Connections section).

Fill in Connection Parameters & Save the Connection

You will now be prompted to provide required fields that were defined in your Connection Parameters block during integration setup. Mandatory Fields may include:
- Instance
- Description
- Email
- Token
- Instance Url
Click Save.

Using the Connection in a Playbook

Now that the connection is added:

Go to Playbook Manager
Create or edit a playbook
Add a new step and select your deployed skill
In the skill configuration, choose the connection you just created from the dropdown.
If the skill doesn’t appear, ensure that the integration is published, the skill is generated, and a connection is added.

Best Practices

Create one connection per environment (e.g., staging, production).
Use clear, scoped names for each connection.
Periodically revalidate connections if using expiring tokens (e.g., OAuth2).
Maintain a connection for each org if using shared integrations across multiple tenants.

Notes & Recommendations

Use unique provider names to avoid duplication across organizations.
Follow AirMDR’s Python syntax and regex structure for parameter sections.
Always validate credentials using the Test Authentication option before deployment.
For non‑standard providers, use the “Skip Authentication” option carefully — security teams should review before enabling.
Maintain all integration code under version control (GitHub/Bitbucket) for compliance traceability.

Troubleshooting

Issue	Possible Cause	Resolution
Authentication test fails	Incorrect API URL or Key	Re‑enter valid credentials and re‑test
Skill not executing	Missing `run_skill` function or improper input mapping	Verify skill code structure and input names
Integration not visible	Draft not deployed	Click Deploy Integration to make it active
Incorrect parameter mapping	Mismatched input names	Check parameter spelling and case sensitivity

Support

For further assistance, reach out to AirMDR Support

Getting Started

Integrations

API Reference

AirMDR Product Suite

AirMDR Self‑Serve Integration

Introduction

Prerequisites

Workflow Summary

Navigating to the AirMDR Integrations Dashboard

Creating a New Integration Provider

Configuring Authentication

Choose Authentication Type

Connection Parameters

Integration Class Declaration

Test Authentication Function

Test and Generate Form

Creating Skills

Skill Code Structure

Generate and Deploy Skill

Post‑Deployment Actions

🔗 Adding a Connection for a Deployed Skill in AirMDR

Add a Connection in AirMDR

Using the Connection in a Playbook

Best Practices

Notes & Recommendations

Troubleshooting

Support

Getting Started

Integrations

API Reference

AirMDR Product Suite

​Introduction

​Prerequisites

​Workflow Summary

​Navigating to the AirMDR Integrations Dashboard

​Creating a New Integration Provider

​Configuring Authentication

​Choose Authentication Type

​Connection Parameters

​Integration Class Declaration

​Test Authentication Function

​Test and Generate Form

​Creating Skills

​Skill Code Structure

​Generate and Deploy Skill

​Post‑Deployment Actions

​🔗 Adding a Connection for a Deployed Skill in AirMDR

​Add a Connection in AirMDR

​Using the Connection in a Playbook

​Best Practices

​Notes & Recommendations

​Troubleshooting

​Support

Introduction

Prerequisites

Workflow Summary

Navigating to the AirMDR Integrations Dashboard

Creating a New Integration Provider

Configuring Authentication

Choose Authentication Type

Connection Parameters

Integration Class Declaration

Test Authentication Function

Test and Generate Form

Creating Skills

Skill Code Structure

Generate and Deploy Skill

Post‑Deployment Actions

🔗 Adding a Connection for a Deployed Skill in AirMDR

Add a Connection in AirMDR

Using the Connection in a Playbook

Best Practices

Notes & Recommendations

Troubleshooting

Support