ARP Management

The ARP Management API enables you to upload user-defined ARP (Address Resolution Protocol) records to help Armis correlate devices across different network segments. By providing IP-to-MAC address mappings, you can enhance device identification and tracking in complex network environments.

Overview

ARP records map IP addresses to MAC addresses, which is essential for:

Device Correlation: Help Armis identify when the same device appears with different IP addresses
Network Segmentation: Distinguish devices across overlapping IP ranges in different network segments
Enhanced Visibility: Provide additional context for device identification

The ARP Management API allows you to:

Upload CSV files containing IP/MAC mappings
Set expiration dates for ARP records
Associate records with specific network segments
Track upload statistics (accepted records, duplicates)

Key Concepts

ARP Upload Components

When uploading ARP records, you provide:

CSV File Content (per row):

IP Address: IPv4 address (IPv6 is not currently supported)
MAC Address: Physical address of the network interface

Upload Parameters (apply to all rows):
3. Network ID: Identifier for the logical network segment
4. Expiration: UTC timestamp when the records should expire

Network Segmentation

The network_id field is crucial when dealing with overlapping IP ranges across different network segments. It ensures that MAC-to-IP bindings are resolved within the correct network context. For example, if you have multiple networks that all use the 10.0.0.0/8 private IP space, the network ID helps Armis distinguish which network a specific binding belongs to.

File Format

ARP records must be provided as a CSV file with the following format:

ip,mac
10.19.96.21,00:11:22:33:44:55
10.19.96.29,AA:BB:CC:DD:EE:FF
10.200.5.46,11:22:33:44:55:66

Requirements:

Header row must include columns ip and mac
Maximum file size: 10 MB (10485760 bytes)
IPv4 addresses only (IPv6 not supported)
Blank rows are ignored
Duplicate rows (same IP/MAC combination) are automatically skipped

Processing

When you upload ARP records:

The file is validated as a whole - any error rejects the entire upload
Records are accepted for processing asynchronously
The response provides immediate statistics, but records may not be queryable yet
If a partial save occurs, re-uploading the same file is safe and idempotent

Common Use Cases

1. Upload ARP Records

Upload ARP records from a CSV file:

import requests
from datetime import datetime, timedelta

# Calculate expiration (30 days from now)
expiration = (datetime.utcnow() + timedelta(days=30)).isoformat() + "Z"

with open("arp_data.csv", "rb") as csv_file:
    files = {
        "file": ("arp_data.csv", csv_file, "text/csv")
    }
    data = {
        "expiration": expiration,
        "network_id": "L_621732956900298999"
    }
    
    response = requests.post(
        "https://api.armis.com/v3/arps",
        files=files,
        data=data,
        headers={"Authorization": f"Bearer {access_token}"}
    )

The CSV file (arp_data.csv) should contain:

ip,mac
10.19.96.21,00:11:22:33:44:55
10.19.96.29,AA:BB:CC:DD:EE:FF
10.200.5.46,11:22:33:44:55:66

Response codes:

202: Success - records accepted for processing
400: Invalid file format or content
413: File exceeds 10 MB limit
502: Save failed - retry the upload (safe and idempotent)

Required Scopes

To use the ARP Management API, your access token must include:

PERMISSION.DEVICE.MANAGE: Required to upload ARP records

Best Practices

1. Set Appropriate Expiration Times

Choose expiration times based on your network's DHCP lease duration and device mobility:

from datetime import datetime, timedelta

# For networks with frequent IP changes (e.g., guest networks)
short_expiration = (datetime.utcnow() + timedelta(days=7)).isoformat() + "Z"

# For stable corporate networks
long_expiration = (datetime.utcnow() + timedelta(days=30)).isoformat() + "Z"

The maximum expiration is 30 days from the current time.

2. Validate CSV Format Before Upload

Ensure your CSV follows the required format:

import csv

def validate_arp_csv(file_path):
    """Validate ARP CSV format before upload"""
    with open(file_path, "r") as f:
        reader = csv.DictReader(f)
        
        # Check headers
        if reader.fieldnames != ["ip", "mac"]:
            raise ValueError("CSV must have 'ip' and 'mac' columns")
        
        # Validate each row
        for i, row in enumerate(reader, start=2):
            if not row["ip"] or not row["mac"]:
                raise ValueError(f"Line {i}: Missing ip or mac value")

validate_arp_csv("arp_data.csv")

3. Retry Failed Uploads

If a 502 error occurs, the upload may have been partially applied. Re-uploading is safe:

import time

def upload_with_retry(files, data, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(
            "https://api.armis.com/v3/arps",
            files=files,
            data=data,
            headers=headers
        )
        
        if response.status_code == 202:
            return response.json()
        elif response.status_code == 502 and attempt < max_retries - 1:
            time.sleep(2 ** attempt)
        else:
            response.raise_for_status()

Error Handling

Common Error Responses

400 Bad Request: The file format is invalid

{
  "message": "Invalid ARP record.",
  "line": 4,
  "column": "ip",
  "value": "2001:db8::1",
  "error": "IPv6 addresses are not supported; only IPv4."
}

413 Payload Too Large: File exceeds 10 MB

{
  "message": "The file must be at most 10485760 bytes."
}

502 Bad Gateway: Save operation failed

Re-upload the file. The operation is idempotent, so re-uploading is safe.

Next Steps

Ready to start managing ARP records? Check out this recipe: