Armis Centrix

📘

TL;DR

To integrate Armis Centrix with Query:

• Retrieve your Armis tenant base URL and create an API Secret Token.
• Configure an Armis Centrix Connector.
• Use Query Search to parallelize searches and surface details about devices, users, and vulnerabilities for incident response (IR), threat hunting, investigations, and other security and observability use cases.

Overview

Armis Centrix™, the cyber exposure management platform, is powered by the Armis AI-driven Asset Intelligence Engine, which sees, secures, protects and manages billions of assets around the world in real time. Armis Centrix™ seamlessly connects with existing data sources to see, secure, protect, and manage all physical and virtual assets – from the ground to the cloud – ensuring the entire attack surface is both defended and managed in real time.

Armis connects with several SASEs, Vulnerability Management platforms, EDRs, IdPs, its own agents, and other security and IT point solutions to built a full asset inventory of users, devices, and their vulnerabilities to help security and observability teams. Armis Centrix's policy engine allows administrators to configure rules around creating alerts for a lack of coverage, tie users to devices (and vice versa), override vulnerability severities, track remediation, and more.

All federated searches have their searches and results expressed in the terms of the Query Data Model (QDM), which is based on the Open Cybersecurity Schema Framework (OCSF). Each API source is normalized into a specific QDM/OCSF Event Class to standardize and normalize the data for increased situational awareness, ease of aggregation of filtering, and easy pivoting.

❗️

Important Note Regarding Vulnerabilities

You must have a valid Armis Centrix for Vulnerability Prioritization and Remediation (ViPR) License to retrieve ANY vulnerability data.

The Armis Centrix Connector is designed to properly route requests and generate ASQ/AQL on the user's behalf depending on the information required. For instance, searching for a Device by MAC Address is only supported via the /devices API Endpoint but not as an AQL/ASQ Filter, so the Connector will plan, route, and execute queries that are known to work to the proper endpoints. Using the Connector, you can quickly locate which Users use which Devices or vice versa, you can pivot on the User Email to unlock insights stored in other Connectors such as in authentication and authorization logs from Auth0 or Token activity in Google Workspaces Reports. Likewise, searching on hostnames or IP addresses for Devices can unlock similar insights from logging sources stored in SIEMs, Lakes, Lakehouses, Warehouses, and XDRs onboarded as Query Federated Search Connectors.

🤓

Some details on searches

AQL/ASQ does not support filtering on every single key within the payloads from Devices, Users, and/or Vulnerabilities. In fact, some keys are not supported at all which may make pivoting or searching for specific deep-nested attributes impossible to fulfill.

Query brings back no more than 5000 results per API, this is the natural page limit within the Armis API.

The payload for Vulnerabilities differs on whether you use the search endpoint to retrieve vulnerabilities or use the vulnerability-match API. If you use Event-based searches to retrieve Vulnerabilities, then the former is used, if you search on the Resource UID of a device the latter is used.

The vulnerability-match API does not support IP address, Site (Geo Location), MAC address, nor hostname-based searches. If you want vulnerability details you must pivot-search or submit a new search on the device.uid Attribute.

Prerequisites

To connect Armis Centrix with Query Federated Search you'll need to retrieve your URL and authorization (auth) token. If you do not have an auth token, you will need to create one.

1. To retrieve your URL, refer to the URL of your Armis instance, typically the scheme will be https://<company_or_tenant_name>.armis.com

2. To create a new Auth Token and retrieve the Secret Key navigate to Settings -> API Management and select Create. After creation, you'll have the opportunity to copy the secret key, or select Show to show it again as shown below (FIG. 1).

   

To learn how to configure an Armis Centrix Connector, proceed to the next section.

👍

On NHI security

NHI - or, Non-Human Identities - such as your Armis Centrix client secret are extremely sensitive. Query securely stores the Client Secret in a dedicated AWS Secrets Manager Secret per Connector per Tenant.

While this requires you to configure Connectors per Armis Centrix and continue to enter in your credentials, every copy is stored as securely as each other with minimum necessary permissions that only allows the specific piece of serverless infrastructure to retrieve the secret, it is never cached or persisted outside of the Secret.

Setting up the Armis Centrix Connector

Use the following steps to create a new Query Federated Search Connector for Armis Centrix.

1. Navigate to the Connectors page, select Add Connector, and selectArmis Centrix from the IT Service Management category as shown below (FIG. 2). You can also search for Armis Centrix using the search bar in the Add Connector page.

   

2. In the Configure Connector tab, add the following detail as shown below (FIG. 3):

   1. Connector Alias Name: The human-readable name you want to give to this connector, you can provide the name...

   2. Default Login: Leave the default value: Default Login.

   3. URL: detail, copied in Step 1 of the Prerequisites section.

   4. API Secret: detail, copied in Step 2 of the Prerequisites section.

      

3. Select Save to save and activate the Connector.

4. Select Test Connection from the bottom-right of the connection pane to ensure that your Armis Centrix API secret can be exchanged for an access key, that you are properly licensed for ViPR, and that you have scopes and can reach all of your endpoints via your provided URL.

You will now see Armis Centrix added as an available Connector within the Query Search and Query Summary Insights UI.

Querying Armis Centrix Connectors

Within the Query Search UI, all Connectors are enabled by default. To check that your specified Connector(s) for Armis Centrix are enabled, navigate to the IT Service Management section of the Selected Connectors dropdown and ensure that your specified Armis Centrix Connector(s) are are selected (denoted by a checkbox) before running your searches as shown below (FIG. 4).

Entity-based Search

The Armis Centrix Connector is a static schema Connector which means that all normalization and search translation is completely defined by the Query team. Refer back to the Introduction section and refer to the table to learn which Entities map against which Armis Centrix API Endpoint. For instance, you can lookup Device IDs in Armis using the Resource UID Entity, or use the User UID Entity to lookup User IDs.

In the Federated Search console, select the search dropdown, ensure the Entities radio button is selected and search for your desired Entity as shown below (FIG. 5). For instance, you can search for for specific Site locations of Devices with the Country (Geo Location) Entity or search for vulnerabilities in your environment by the CVE ID, these results can be further correlated against other different Query Connectors.

After selecting an Entity, most allow you to specify an Operator. This allows you to perform simple equality searches or to perform more generalized searches using Contains, Starts With, or Ends With Operators. Only equality is supported within both the URI parameters and AQL/ASQ, so the other operators will be emulated based on over-fetching data and may not work correctly.

When you search for multiple values that may be present across different Connectors, the Query Federated Search query planner inspects the Configure Schema metadata to ensure searches are sent to the appropriate Connectors, this operates more as a collated window function within Query and not as an expensive SQL join.

Additionally, you can specify case-sensitivity for the entire search criteria. An example of a multi-value CVE search that uses the equals operator and toggled case-sensitivity is shown below (FIG. 6).

Event-based Search

Event-based searches allow you to broadly search across the entirety of results from a downstream API, or, search for very specific results based on filters. Refer back to the Introduction section and refer to the table to learn which Events map to the Armis Centrix Connector.

In the Federated Search console, select the search dropdown, ensure the Events radio button is selected and search for your desired Event as shown below (FIG. 7), in this case select the Discovery category to find the Device Inventory Info Event Class. You can also search across all Connectors normalized to Device Inventory Info such as Jamf, Microsoft Intune, Crowdstrike, or other data lake or SIEM resources mapped to Device Inventory Info such as asset data from ITSM and CAASM reports, and otherwise.

Searching from the Event will pull a sample (up to 2500) of all matching events per Connectors that are mapped to it. For more specific filtering within an Event, you can choose one or more conditions to refine a search. Selecting the plus-sign (+) dropdown next to the Event menu allows you to choose from any specific OCSF/QDM attribute in the event.

For instance, when searching for HTTP Activity events, you can specify a specific mobile device hostname by filtering for Device --> Hostname as shown below (FIG. 8).

When adding two or more Conditions, you can further change the behavior by specifying ANY or ALL quantifiers over the filters for greater levels of specificity or more narrow-but-generalized searches, respectively, as shown below (FIG. 9). In this case a multiple values were used to search for Non-Compliant devices (that are reporting as compromised) that checked in the last 30 days and are running an Android OS.

Resources

Refer to your Armis Centrix API PDF guide for information on creating credentials.

Troubleshooting Steps

• Ensure the proper URL of your Armis instance is used, and that it is a URL and not just the hostname.
• Ensure that the Secret Key for your Auth Token is correct.
• Ensure that you are licensed for Centrix and for ViPR.
• Ensure that you have data in your Armis instance that can be retrieved from upstream tools.

If you have exhausted the above Troubleshooting list, please contact your designated Query Sales Engineer or Customer Success Manager. If you are using a free tenant, please contact Query Customer Success via the Support email in the Help section, or via Intercom within your tenant.