What is a Collector?

A Collector is a component that enables Armis to discover and monitor devices within your network infrastructure. Collectors come in various image types (OVA, QCOW2, VHD, etc.) depending on your virtualization platform or operating system.

Why Use the Collector API?

The Collector API allows you to programmatically retrieve the necessary details to download and deploy collector images, enabling:

• Automated Infrastructure Deployment: Script the deployment of collectors across multiple sites or environments
• CI/CD Integration: Incorporate collector deployment into your infrastructure-as-code workflows
• Secure Credential Management: Retrieve image passwords programmatically without manual intervention
• Multi-Platform Support: Access different image types for various virtualization platforms

Example

You're managing a large enterprise with multiple data centers and need to deploy Armis collectors programmatically. Rather than manually downloading images and managing credentials, you can use the API to automate the entire process.

Step 1: Retrieve collector image details

Use the API to get the download URL, image type, password, and URL expiration details for your chosen collector image.

Prerequisites:

1. Access token with scope PERMISSION.SETTINGS.COLLECTOR.READ.

Send the request

import json
import requests

params = {
    "image_type": "OVA",  # Options: OVA, QCOW2, VHD, VHDX, DEB, RPM, etc.
}
headers = {
    "Authorization": "Bearer <access_token>",
}

response = requests.get(
    "https://api.armis.com/v3/collectors/_image",
    params=params,
    headers=headers,
)

response.raise_for_status()
image_details = response.json()
print(json.dumps(image_details, indent=2))

{
  "image_password": "secure_password_123",
  "image_type": "OVA",
  "url": "https://presigned-url.s3.amazonaws.com/collector-image.ova?signature=...",
  "url_expiration_date": "2025-12-18T00:00:00Z"
}

Detailed recipe

Step 2: Download and deploy the image

Once you have the image details, you can:

1. Download the image using the presigned URL (valid until the expiration date)
2. Deploy the image to your virtualization platform (VMware, Hyper-V, KVM, etc.)
3. Configure the collector using the provided image password

Example download script

import requests

# Use the details from Step 1
image_url = image_details["url"]
image_password = image_details["image_password"]
image_type = image_details["image_type"]

# Download the image
with requests.get(image_url, stream=True) as r:
    r.raise_for_status()
    with open(f"armis-collector.{image_type.lower()}", "wb") as f:
        for chunk in r.iter_content(chunk_size=8192):
            f.write(chunk)

print(f"Image downloaded successfully!")
print(f"Image password: {image_password}")

Supported Image Types

The API supports various image types for different platforms:

• OVA: VMware ESXi/vSphere
• QCOW2: KVM/OpenStack
• VHD/VHDX: Microsoft Hyper-V
• DEB: Debian-based Linux distributions
• RPM: Red Hat-based Linux distributions
• DARWIN_AMD64_BROKER/DARWIN_ARM64_BROKER: macOS collectors
• LINUX_AMD64_BROKER/LINUX_ARM64_BROKER: Linux broker collectors
• WINDOWS_BROKER: Windows broker collectors

⏰

Download URLs are time-limited. Make sure to download the image before the expiration date specified in the response.

🔐

Store the image password securely. You'll need it to access and configure the collector after deployment.