> ## Documentation Index
> Fetch the complete documentation index at: https://docs.airmdr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AirMDR Remote Agent – Architecture & Operational

> The AirMDR Remote Agent enables secure, controlled connectivity between AirMDR and customer-managed environments. Once installed, the agent runs as a system service and facilitates data collection and task execution as required by enabled AirMDR integrations. 

### Purpose

The **AirMDR Remote Agent (RA)** is a lightweight, secure client that runs inside a customer’s private environment and enables AirMDR to collect logs and execute controlled data requests **without requiring inbound network access**.

It is designed for environments where:

* Inbound connectivity is restricted
* VPNs are not permitted
* Direct cloud-to-SIEM access is disallowed

The agent acts as a **secure bridge** between AirMDR Cloud and customer-controlled resources such as SIEMs, Windows hosts, and private infrastructure.

### Deployment Model

* Installed on:
  * A **Jump Box**, or
  * A **Windows/Linux endpoint** inside the customer network
* Operates entirely via **outbound-only connections**
* Requires **no inbound firewall rules**
* Uses **TLS-encrypted WebSocket (WSS)** over port **443**

  <Note>
    This design aligns with common enterprise security policies that prohibit inbound connections to internal systems.
  </Note>

## High-Level Architecture

### Architecture at a Glance

<img src="https://mintcdn.com/airmdr/aAHDUojjvA3EDyfT/images/RemoteAgentHLD.png?fit=max&auto=format&n=aAHDUojjvA3EDyfT&q=85&s=da635da87946bd0b2053bc4098ce096c" alt="Remote Agent HLD" width="2006" height="876" data-path="images/RemoteAgentHLD.png" />

### Core Components

#### 1. Remote Agent Client (Customer Environment)

* Written in **Go**
* Runs as a background service
* Establishes and maintains a persistent **WSS connection** to AirMDR Cloud
* Persists configuration locally (`config.json`)
* Responsible for:
  * Buffering
  * Retry logic
  * Checkpointing
  * Auto-reconnect
  * Heartbeats

#### 2. AirMDR Remote Agent Service (Cloud)

* Acts as a **WSS gateway**
* Authenticates agent connections
* Sends control commands to agents
* Tracks agent health and connectivity
* Forwards received data into AirMDR’s ingestion pipeline

## Communication & Transport Security

* **Protocol:** Secure WebSocket (WSS)
* **Port:** 443 (standard HTTPS)
* **Encryption:** TLS in transit
* **Direction:** Agent → Cloud only

### Why WebSockets?

* Maintains a persistent connection through NATs and firewalls
* Allows near-real-time command and data exchange
* Avoids polling overhead

No inbound connections are ever initiated into the customer environment.

## Data Collection Modes

The AirMDR Remote Agent supports below mentioned ingestion model.

### PULL-Based Collection (SIEM & APIs)

Used for:

* Splunk
* QRadar
* Elastic / OpenSearch
* Other TCP/HTTPS-based APIs

**Flow:**

1. AirMDR sends a `TCP_REQUEST` command to the agent
2. Agent executes the request locally against the SIEM/API
3. Results are:
   * Batched
   * Normalized
   * Returned via WSS
4. Checkpoints ensure **no duplicate data**

This approach respects SIEM API rate limits and avoids exposing SIEM endpoints externally

## Internal Agent Architecture

Inside the agent, responsibilities are clearly separated:

### Transport Layer

* WSS connect + reconnect
* Read/write loops
* Request/response correlation via `request_id`
* Message dispatching

### Command Handler

* Handles control messages such as:
  * `TCP_REQUEST`
  * `PING`

### Collector Manager

* **SIEM Collector:** Executes remote API pulls

### Local Buffer (Spooler)

* Durable queue (embedded DB)
* Stores data when offline
* Automatically drains on reconnect

### Heartbeat Manager

* Sends periodic `PING`
* Tracks connection health
* Collects basic system metrics

## Heartbeats & Health Monitoring

### Heartbeat Purpose

* Detect dropped connections
* Prevent idle timeouts
* Measure agent health

### Mechanism

* Agent sends `PING` every \~30 seconds
* Cloud responds with `PONG`
* Failure handling:
  * Reconnect if no `PONG` within 10 seconds
  * Agent marked **offline** after two missed heartbeats

Heartbeats continue even if collectors fail, allowing clear separation of **connectivity vs ingestion health**

## Reliability & Failure Handling

The Remote Agent is designed for **unreliable networks**:

* Automatic reconnect
* Disk-based buffering when offline
* Retry with backoff
* Checkpointing to avoid data loss or duplication

Temporary outages do not require manual intervention.

## Security Characteristics (Summary)

* Outbound-only traffic
* TLS-encrypted transport
* No inbound firewall rules
* No VPN required
* Credentials never leave customer environment
* Minimal local persistence
* Optional signature-verified auto-updates

These properties align with strict enterprise security and compliance requirements

## Operational Visibility

* Agent reports:
  * Online/offline status
  * Heartbeat health
  * Collector state
* Logs available via systemd / Windows service logs

## When Should a Security Engineer Use the Remote Agent?

Use the AirMDR Remote Agent when:

* SIEM or logs are not internet-exposed
* Inbound access is prohibited
* API access must originate from inside the network
* Security policy forbids VPNs or tunnels

## Summary

The AirMDR Remote Agent provides a **secure, resilient, and policy-aligned mechanism** to extend AirMDR’s detection and investigation capabilities into private environments—without weakening perimeter security.

## Support

For additional assistance:

* Contact [**AirMDR Support**](mailto:support@airmdr.com) through your designated support channel.