Overview

The Armis Alert Management API allows you to retrieve detailed information about security alerts detected in your environment. Each alert provides comprehensive context including severity, status, affected devices, and MITRE ATT&CK framework mappings.

Use Cases

Security Monitoring: Retrieve alert details for security operations and incident response
Alert Enrichment: Obtain comprehensive alert context including affected devices and connections
Compliance Reporting: Track and report on security alerts with MITRE ATT&CK mappings
Automated Response: Integrate alert data into your security orchestration workflows

Getting Started

Prerequisites

To use the Alert Management API, you'll need:

An active Armis API access token with the PERMISSION.ALERT.READ scope
The alert ID you want to retrieve

Required Scope

PERMISSION.ALERT.READ - Required to read alert information

Retrieving an Alert

To retrieve a specific alert, use the GET /alerts/{alert_id} endpoint.

Example Request

curl -X 'GET' \
  'https://api.armis.com/v3/alerts/12345' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <access_token>'

{
  "id": 12345,
  "severity": "HIGH",
  "type": "SYSTEM_POLICY_VIOLATION",
  "status": "OPEN",
  "activity_timestamp": "2026-06-15T10:30:00Z",
  "title": "Unauthorized Network Connection Detected",
  "classification": "Network.UnauthorizedConnection",
  "policy_id": 789,
  "affected_devices_count": 1,
  "mitre_attack_labels": [
    {
      "matrix": "ENTERPRISE",
      "tactic": "Command and Control",
      "technique": "T1071",
      "sub_technique": "T1071.001"
    }
  ],
  "status_change_time": "2026-06-15T11:00:00Z",
  "last_alert_update_time": "2026-06-15T11:30:00Z",
  "description": "A device attempted to establish a connection to an unauthorized external IP address.",
  "activity_uuids": ["550e8400-e29b-41d4-a716-446655440000"],
  "device_ids": [98765],
  "connection_ids": [55555],
  "source_endpoints": [
    {
      "id": 98765,
      "name": "mfg-printer-08",
      "ipv4_addresses": ["10.0.4.18"],
      "mac_addresses": ["00:1A:2B:3C:4D:5E"],
      "risk_level": 8,
      "business_impact": "HIGH",
      "data_sources": ["network", "agent"],
      "boundary_names": ["Manufacturing"],
      "site_name": "Boston HQ"
    }
  ],
  "destination_endpoints": [
    {
      "id": "203.0.113.42",
      "name": "203.0.113.42",
      "ipv4_address": "203.0.113.42"
    }
  ]
}

Recipe

Understanding Alert Properties

Alert Severity

Alerts can have one of four severity levels:

LOW - Low-risk security event
MEDIUM - Moderate security risk
HIGH - High-risk security event requiring attention
CRITICAL - Critical security issue requiring immediate action

Alert Status

Alerts progress through various statuses:

UNHANDLED - Alert has not been reviewed
OPEN - Alert is under investigation
RESOLVED - Alert has been addressed
IGNORED - Alert has been dismissed
SUPPRESSED - Alert is temporarily suppressed by policy

Alert Types

Alerts are categorized by how they were raised:

SYSTEM_POLICY_VIOLATION - Violation of Armis system policy
USER_POLICY_VIOLATION - Violation of custom user-defined policy
ANOMALY_DETECTION - Detected behavioral anomaly

Business Impact

Devices in alerts can have a business impact classification:

CRITICAL - Critical business function
HIGH - High business importance
UNASSIGNED - No business impact assigned

MITRE ATT&CK Mappings

Alerts may include MITRE ATT&CK framework annotations that provide standardized threat intelligence context:

Matrix: The MITRE ATT&CK matrix family (ENTERPRISE, ICS, MOBILE)
Tactic: High-level adversary objective (e.g., "Initial Access", "Command and Control")
Technique: Specific technique ID (e.g., "T1071")
Sub-technique: More specific sub-technique (e.g., "T1071.001")

These mappings help security teams understand the attack patterns and prioritize response actions.

Endpoint Information

Alerts contain detailed information about source and destination endpoints:

Device Endpoints

For persistent devices tracked in Armis, the alert includes:

Device ID and name
IP and MAC addresses
Risk level (0-100)
Business impact classification
Data sources
Associated boundaries and sites

IP Address Endpoints

For ephemeral or external IP addresses:

IP address (serves as both ID and display name)
IPv4 format specification