Extracting Device Information

API endpoints in this page

Search assets that match certain criteria

Many companies rely on Armis as their single source of truth for asset information. It's therefore critical to provide third-party vendors with the ability to retrieve device data through our API.

The API provides two primary methods for extracting device information: filtering by identifiers or by the last time assets were detected. Let's explore both approaches.

Filtering by Identifiers

Assets can have multiple identifiers, with the most common being:

Internal asset ID - Generated by Armis when an asset is first discovered
IPv4 or IPv6 addresses
MAC addresses
Serial numbers

The API allows you to filter using any of these identifiers, which is particularly valuable when your unique identifier differs from the internal asset ID.

Example: Searching by IPv4 Address

In this example, we'll retrieve the device ID and display string for assets based on their IPv4 addresses. Note that some IPv4 addresses may be associated with multiple assets.

You can search assets using any of the following identifiers by specifying the asset_id_source field:

ASSET_ID
IPV4_ADDRESS
IPV6_ADDRESS
MAC_ADDRESS
SERIAL_NUMBER

Prerequisites

Access token with the following scopes:

PERMISSION.DEVICE.READ
PERMISSION.PII.DEVICE
FULL_VISIBILITY

Send the Request

import json
import requests

body = {
    "asset_type": "DEVICE",
    "fields": [
        "device_id",
        "display",
    ],
    "filter": {
        "filter_criteria": "ASSET_ID",
        "asset_id_source": "IPV4_ADDRESS",
        "asset_ids": [
            "10.19.96.21",
            "10.19.96.29",
            "10.200.5.46",
        ],
    },
}
access_token = "your_access_token_here"
headers = {
    "Authorization": f"Bearer {access_token}",
}

response = requests.post(
    "https://api.armis.com/v3/assets/_search",
    json=body,
    headers=headers,
)

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

{
  "items": [
    {
      "asset_id": "10.19.96.29",
      "fields": {
        "device_id": 8,
        "display": "81002f4a_634"
      }
    },
    {
      "asset_id": "10.19.96.21",
      "fields": {
        "device_id": 9,
        "display": "372f8790_692"
      }
    },
    {
      "asset_id": "10.200.5.46",
      "fields": {
        "device_id": 10,
        "display": "8831 Conference Phone"
      }
    },
    {
      "asset_id": "10.19.96.21",
      "fields": {
        "device_id": 53,
        "display": "0349e74a_a42"
      }
    }
  ],
  "next": null
}

Detailed recipe

Search devices by IPv4 addresses

Open Recipe

Filtering by Last Seen Timestamp

The Armis platform records a timestamp whenever an asset is detected. This enables you to filter assets based on:

Assets seen after a specific date
Assets seen within the last X seconds

Example: Recently Active Devices

In this example, we'll search for assets that have been active within the last 24 hours.

Prerequisites

Access token with the following scopes:

PERMISSION.DEVICE.READ
PERMISSION.PII.DEVICE
FULL_VISIBILITY

Send the Request

import json
import requests

body = {
    "asset_type": "DEVICE",
    "fields": [
        "device_id",
        "brand",
        "tags",
    ],
    "filter": {
        "filter_criteria": "LAST_SEEN",
        "last_seen_seconds": 86400,  # 24 hours in seconds
    },
}
access_token = "your_access_token_here"
headers = {
    "Authorization": f"Bearer {access_token}",
}

response = requests.post(
    "https://api.armis.com/v3/assets/_search",
    json=body,
    headers=headers,
)

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

{
  "items": [
    {
      "asset_id": 1,
      "fields": {
        "device_id": 1,
        "brand": "Hewlett Packard",
        "tags": [
          "Access Point",
          "Managed"
        ]
      }
    },
    {
      "asset_id": 2,
      "fields": {
        "device_id": 2,
        "brand": null,
        "tags": [
          "Insecure Traffic and Behavior",
          "Deprecated SW/HW"
        ]
      }
    },
    {
      "asset_id": 3,
      "fields": {
        "device_id": 3,
        "brand": "Polycom",
        "tags": [
          "Insecure Traffic and Behavior",
          "Deprecated SW/HW"
        ]
      }
    },
    {
      "asset_id": 4,
      "fields": {
        "device_id": 4,
        "brand": "Cisco",
        "tags": null
      }
    },
    {
      "asset_id": 5,
      "fields": {
        "device_id": 5,
        "brand": null,
        "tags": [
          "Insecure Traffic and Behavior",
          "Deprecated SW/HW",
          "Misconfigurations",
          "Unprotected Sensitive Data",
          "Insecure Credentials and Access Control",
          "External to Internal Traffic"
        ]
      }
    },
    {
      "asset_id": 6,
      "fields": {
        "device_id": 6,
        "brand": null,
        "tags": null
      }
    },
    {
      "asset_id": 7,
      "fields": {
        "device_id": 7,
        "brand": null,
        "tags": [
          "Insecure Traffic and Behavior",
          "Deprecated SW/HW"
        ]
      }
    },
    {
      "asset_id": 8,
      "fields": {
        "device_id": 8,
        "brand": null,
        "tags": [
          "Insecure Traffic and Behavior",
          "Deprecated SW/HW"
        ]
      }
    },
    {
      "asset_id": 9,
      "fields": {
        "device_id": 9,
        "brand": null,
        "tags": [
          "Insecure Traffic and Behavior",
          "Deprecated SW/HW"
        ]
      }
    },
    {
      "asset_id": 10,
      "fields": {
        "device_id": 10,
        "brand": "Yamaha",
        "tags": [
          "Critical asset at risk"
        ]
      }
    }
  ],
  "next": 10
}

Detailed Recipe

Search recently seen devices

Open Recipe