Device

📘

Go straight to the API reference.

The device entity is the most significant building block in the Armis ecosystem.
In the context of this API, a "device" doesn't refer to a specific instance of a device (e.g., my cellphone), but rather to a device profile.

Device profile

A device profile is a term that represents devices that share similar properties, such as the same brand (e.g., Apple) or the same operating system (e.g., macOS 11).

Supported properties

Supported calculations

Related entities

The device entity can be filtered not only by its own properties (described previously), but also by the properties of its related entities.

CVE

When filtering a device by its related CVEs, it means that we consider only devices that are vulnerable to the matching CVEs.

📘

To learn more about the cve entity, see the documentation page.

Threat

When filtering a device by its related threats, it means that we consider only devices that were actually attacked by the matching threats.

📘

To learn more about the threat entity, see the documentation page.

Explorer

You can play with the device API directly in the explorer page in the management console.

Example use-cases

1. Market share of mobile phone operating systems: (explore)

/api/v1/device/_search?groupBy=osTitle&type[eq]=Mobile Phones

[
    {
        "osTitle": "iOS 15",
        "share": 0.556
    },
    {
        "osTitle": "Android 12",
        "share": 0.1302
    },
    {
        "osTitle": "iOS 14",
        "share": 0.0819
    },
    ...,
]

2. Which PLCs are the least risky? (explore)

/api/v1/device/_search?groupBy=brand&groupBy=model&calculate=avgRisk&orderBy=avgRisk:asc&type[eq]=PLCs

[
    {
        "brand": "Contemporary Control",
        "model": "SIMATIC S7-300, CPU319-3 PN/DP, 2 MB",
        "avgRisk": 2
    },
    {
        "brand": "Rockwell Automation",
        "model": "2080-LC50-24QWB",
        "avgRisk": 2
    },
    ...,
]

3. Which industry is mostly affected by the Log4Shell zero-day vulnerability? (explore)

/api/v1/device/_search?groupBy=industry&calculate=share&cve.id[eq]=CVE-2021-44228

    {
        "industry": "Manufacturing",
        "share": 0.6183
    },
    {
        "industry": "Health Care and Social Assistance",
        "share": 0.1824
    },
    ...,

Enums and lists

Some fields that are available for filtering and grouping the device entity are populated with a closed list of possible values, as described next:

Relationship between group, category, and type

When Armis detects a device type, its category and group are automatically derived according to the hierarchy type -> category -> group.
The full hierarchy tree can be seen here: