Integration Management

The Integration Management API enables you to programmatically manage third-party integrations that enrich Armis with data from external systems. Whether you're deploying integration, monitoring integration health, or automating configuration updates, these endpoints provide full control over your integration ecosystem.

Overview

Armis integrates with hundreds of third-party platforms including but not limited to:

Security Tools: CrowdStrike, Microsoft Defender, Palo Alto Networks, Check Point
Network Infrastructure: Cisco ISE, Aruba Central, Juniper Mist, Fortinet FortiGate
IT Management: ServiceNow, Microsoft Intune, Jamf, VMware
Identity Providers: Okta, Azure AD, OneLogin
Vulnerability Management: Tenable, Qualys, Rapid7

The Integration Management API allows you to:

List all configured integrations
Create new integrations programmatically
Retrieve integration details including health status and statistics
Delete integrations when they're no longer needed

Key Concepts

Integration Components

Each integration consists of:

Name: The integration type (e.g., "CrowdStrike", "Cisco ISE REST API")
Instance Name: A unique identifier for this specific configuration
Parameters: Integration-specific configuration (credentials, URLs, filters)
State: Current operational state (ACTIVE, PAUSED, etc.)
Collector/Broker: The infrastructure component handling the integration
Health State: Real-time health status (IDLE, RUNNING, ERROR)
Statistics: Execution metrics and data ingestion statistics

Health States

Integrations report real-time health status:

IDLE: Integration is configured but not currently executing
RUNNING: Integration is actively collecting data
ERROR: Integration encountered an error and requires attention
WARNING: Integration is operational but has non-critical issues

Statistics Tracking

Integration statistics provide visibility into:

Last Successful Cycle: Timestamp of most recent successful data collection
Entity Counts: Number of devices/assets discovered per entity type
Post-Filter Amounts: Items after applying filters
Sent to Armis: Total records transmitted
Unique Records: Deduplicated asset count

Common Use Cases

1. Integration Deployment

Deploy integration:

body = {
    "name": "CrowdStrike",
    "instance_name": "production-crowdstrike",
    "params": {
        "crowdstrike_base_url": "api.crowdstrike.com",
        "crowdstrike_client_id": "...",
        "crowdstrike_client_secret": "...",
        "integration_schedule": {"crontab": "0 */4 * * *"}
    },
    "state": "ACTIVE",
    "collector_id": 12345
}

response = requests.post(
    "https://tenant1.armis.com/v3/settings/integrations",
    json=body,
    headers={"Authorization": f"Bearer {access_token}"}
)

2. Integration Health Monitoring

Check integration health status:

response = requests.get(
    "https://api.armis.com/v3/settings/integrations",
    headers={"Authorization": f"Bearer {access_token}"}
)

Response includes health state and last successful cycle for each integration.

3. Automated Integration Auditing

Retrieve all integrations for compliance reporting:

response = requests.get(
    "https://api.armis.com/v3/settings/integrations",
    headers={"Authorization": f"Bearer {access_token}"},
    params={"limit": 100}
)

Use pagination to retrieve complete integration inventory.

4. Integration Statistics Analysis

Get detailed statistics for a specific integration:

integration_id = 73902
response = requests.get(
    f"https://api.armis.com/v3/settings/integrations/{integration_id}",
    headers={"Authorization": f"Bearer {access_token}"}
)

The statistics field includes cycle data and entity counts.

5. Dynamic Integration Configuration

Create integrations programmatically:

body = {
    "name": "Cisco ISE REST API",
    "instance_name": "hq-cisco-ise",
    "params": {
        "cisco_ise_hostname": "ise.company.com",
        "cisco_ise_username": "api-user",
        "cisco_ise_password": "...",
        "integration_schedule": {"crontab": "0 */6 * * *"}
    },
    "state": "ACTIVE",
    "collector_id": 12345
}

response = requests.post(
    "https://api.armis.com/v3/settings/integrations",
    json=body,
    headers={"Authorization": f"Bearer {access_token}"}
)

Required Scopes

To use the Integration Management API, your access token must include:

PERMISSION.SETTINGS.INTEGRATION.READ: List and retrieve integrations
PERMISSION.SETTINGS.INTEGRATION.MANAGE: Create and delete integrations

Best Practices

1. Secure Credential Management

Never hardcode credentials. Use environment variables or read directly from a vault:

import os

params = {
    "crowdstrike_client_id": os.environ["CROWDSTRIKE_CLIENT_ID"],
    "crowdstrike_client_secret": os.environ["CROWDSTRIKE_CLIENT_SECRET"]
}

2. Handle Pagination

Use the after field for pagination:

params = {"limit": 100, "after": "73902"}
response = requests.get(
    "https://api.armis.com/v3/settings/integrations",
    headers={"Authorization": f"Bearer {access_token}"},
    params=params
)

3. Integration Parameters

Different integrations require different parameters, for example:

CrowdStrike: crowdstrike_base_url, crowdstrike_client_id, crowdstrike_client_secret
Cisco ISE: cisco_ise_hostname, cisco_ise_username, cisco_ise_password
Aruba Central: aruba_new_central_base_url, aruba_new_central_client_id, aruba_new_central_client_secret
Microsoft Defender: mde_tenant_id, mde_client_id, mde_client_secret

Next Steps

Ready to start managing integrations? Check out these recipes: