What is a Policy?

A Policy in Armis is a rule-based mechanism that monitors your environment and triggers actions when specific conditions are met. Policies can detect security threats, compliance violations, operational issues, and other events based on device properties, activities, vulnerabilities, or network connections.

Why Use the Policy API?

The Policy API allows you to programmatically access and analyze your organization's security and operational policies, enabling:

Compliance Auditing: Export all policies for compliance reporting and documentation
Policy Analysis: Analyze which policies are enabled, their severity levels, and associated MITRE ATT&CK techniques
Integration with SIEM/SOAR: Feed policy configurations into security orchestration platforms
Custom Reporting: Build custom dashboards showing policy coverage across different categories
Policy Validation: Verify that required policies are enabled and properly configured

Policy Components

Each policy consists of several key components:

Rule Type: The entity type the policy evaluates (DEVICE, ACTIVITY, VULNERABILITY, IP_CONNECTION)
ASQ Rule: The Armis Search Query expression that defines matching criteria
Actions: What happens when the policy matches (create alert, add tag, assign risk factor, etc.)
Labels: Organizational tags for filtering and categorization
MITRE ATT&CK Labels: Associated attack techniques from the MITRE ATT&CK framework

Example

You're a security analyst who needs to audit all security policies in your environment to ensure compliance with your organization's security framework. You want to export all policies, analyze their configurations, and identify which MITRE ATT&CK techniques are covered.

Step 1: List all policies

Use the API to retrieve a paginated list of all policies in your environment.

Prerequisites:

Access token with scope PERMISSION.POLICY.READ.

Send the request

import json
import requests

params = {
    "limit": 10,  # Number of policies per page (1-100)
}
access_token = "your_access_token_here"
headers = {
    "Authorization": f"Bearer {access_token}",
}

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

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

{
  "items": [
    {
      "id": 266363,
      "name": "Credentials Exposed - HTTP",
      "description": "Detects devices sending credentials over unencrypted HTTP connections.",
      "is_enabled": true,
      "rule_type": "ACTIVITY",
      "asq_rule": {
        "and": [
          "type:Credentials"
        ]
      },
      "labels": [
        "Encryption Gaps",
        "Value Pack"
      ],
      "mitre_attack_labels": null,
      "actions": [
        {
          "type": "alert",
          "params": {
            "severity": "medium",
            "title": "Credentials Exposed - HTTP",
            "description": "Credentials Exposed - HTTP",
            "type": "Security - Other",
            "endpoint": "ALL",
            "consolidation": {
              "amount": 1,
              "unit": "Days"
            }
          }
        }
      ]
    }
  ],
  "next": 266364
}

Detailed recipe

Step 2: Analyze policy data

Once you have the policy data, you can analyze it programmatically:

Example analysis script

import requests
import json
from collections import Counter

access_token = "your_access_token_here"
headers = {"Authorization": f"Bearer {access_token}"}

# Retrieve all policies with pagination
all_policies = []
after = None

while True:
    params = {"limit": 100}
    if after:
        params["after"] = after
    
    response = requests.get(
        "https://api.armis.com/v3/policies",
        params=params,
        headers=headers,
    )
    response.raise_for_status()
    data = response.json()
    
    all_policies.extend(data["items"])
    
    if not data.get("next"):
        break
    after = data["next"]

# Analyze the policies
print(f"Total policies: {len(all_policies)}")
print(f"Enabled policies: {sum(1 for p in all_policies if p.get('is_enabled'))}")

# Count by rule type
rule_types = Counter(p.get("rule_type") for p in all_policies)
print(f"\nPolicies by rule type:")
for rule_type, count in rule_types.items():
    print(f"  {rule_type}: {count}")

# Count by action type
action_types = Counter(
    action.get("type") 
    for p in all_policies 
    for action in p.get("actions", [])
)
print(f"\nPolicies by action type:")
for action_type, count in action_types.items():
    print(f"  {action_type}: {count}")

# Extract unique labels
all_labels = set()
for p in all_policies:
    if p.get("labels"):
        all_labels.update(p["labels"])
print(f"\nUnique labels ({len(all_labels)}):")
for label in sorted(all_labels):
    print(f"  - {label}")

Understanding Policy Actions

Policies can trigger various actions when their rules match:

Action Type	Description
ALERT	Create an alert with specified severity (low, medium, high, critical)
TAG	Add tags to the matching entity
CUSTOM_PROPERTY	Set a custom property value
RISK_FACTOR / CUSTOM_RISK_FACTOR	Assign a risk score
BOUNDARY	Assign the entity to a boundary
BLOCK	Block the entity (via firewall, WLC, etc.)
LINK_LAYER_SEGMENTATION / NETWORK_LAYER_SEGMENTATION	Apply network segmentation
ARMIS_SCANNER_SCAN	Trigger an Armis Smart Scanner scan
QUALYS_SCAN / NEXPOSE_SCAN / TENABLE_IO_SCAN	Trigger third-party vulnerability scans
CREATE_TICKETS / SERVICE_NOW_PUSH	Create tickets in external systems
TORQ_TRIGGER	Trigger Torq automation workflows

Understanding Rule Types

Policies evaluate different entity types based on their rule type:

Rule Type	Description
DEVICE	Evaluates device properties (e.g., OS version, manufacturer, last seen)
ACTIVITY	Evaluates network activities (e.g., credentials exposure, suspicious connections)
VULNERABILITY	Evaluates CVEs and security vulnerabilities
IP_CONNECTION	Evaluates IP-level network connections

📊
The ASQ (Armis Search Query) rule uses the same syntax as the Armis UI search functionality. You can test rules in the UI before creating policies.

🔍
Policy IDs are unique identifiers that remain constant. Use these IDs when referencing policies in integrations or automation workflows.