SecurityScout APIs

Sections

We have designed our APIs to give you access to all of the normalized IdP and MDM data that we have collected from your integrations.

These APIs are available under the Trial, ProBono, or Enterprise subscriptions.

A field can be given as a string to just search for the one value or an array to serach for any of the values in the array. e.g. {"source": ["Google Workspace", "Okta"]} will return all Google Workspace and Okta accounts.

1. Authentication

We use an X-API-KEY header to authenticate all requests API requests. This header is a combination of your tenant ID and your API key in the form of TENANT_ID:API_KEY

You can find this under Settings -> API on your tenant

It will look like: a12abcd1-1234-a3f1-a1a3-123456abc123:AKDJRISKD831K63K5K6L2KDKSL

This is to ensure you not only know which tenant you are making the API call to but that you have an API key that is valid for the tenant.

2. IdP Accounts

Normalized IdP Accounts

Get all of your accounts, normalized across your IdPs.

Optional Fields:
  • integration (e.g. "okta", "google_workspace")
  • source (e.g. "Okta", "Google Workspace")
  • user_email (e.g. "user@company.com")
  • status (e.g. "Active", "Disabled", "Suspended")
  • mfa_enabled (true, false, or Unknown)
curl -X GET 'https://app.securityscout.io/api/idp_accounts' --header "X-API-KEY: TENANT_ID:API_KEY" --header "Content-Type: application/json" --data '{"integration": ["okta", "google_workspace"], "user_email": "someone@company.com"}'
import requests

r=requests.get('https://app.securityscout.io/api/idp_accounts', headers={'X-API-KEY': 'TENANT_ID:API_KEY', 'Content-Type': 'application/json'}, json={'integration': ['okta', 'google_workspace'], 'user_email': 'someone@company.com'})

print(r.json())
{
"count": 4,
"idp_accounts": [
{
"source": "Okta",
"user_id": "19123912592295",
"user_link": "https://link.to.account/id",
"user_email": "person@company.com",
"aliases": ["person@company.tech"],
"title": "Content Marketing Manager",
"department": "Marketing",
"manager": "manager.person@company.com",
"user_name": "First Last",
"status": "ACTIVE",
"created": "2023-03-23T08:18:12",
"last_login": "2024-01-03T03:01:42",
"mfa_enabled": "true",
"mfa_options": "totp",
"roles": ["Administrator", "Reader"]
},
...
...
]
}

3. Devices

Normalized Devices

Get all of your devices, normalized across your MDMs.

Optional Fields:
  • integration (e.g. "jamf")
  • source (e.g. "Jamf")
  • name (e.g. "matt-mbp2")
  • serial_number (e.g. "N4K23KA9")
  • user_email (e.g. "person@company.com")
  • last_ip (e.g. "1.2.3.4")
curl -X GET 'https://app.securityscout.io/api/devices' --header "X-API-KEY: TENANT_ID:API_KEY" --header "Content-Type: application/json" --data '{"source": "Jamf"}'
import requests

r=requests.get('https://app.securityscout.io/api/devices', headers={'X-API-KEY':'TENANT_ID:API_KEY', 'Content-Type': 'application/json'}, json={'source': 'Jamf'})

print(r.json())
{
"count": 4,
"devices": [
{
"source": "Jamf",
"mdm": "Jamf",
"device_id": "123",
"device_link": "https://mdm.source.com/{id}",
"name": "matt-123-macbook",
"serial_number": "KWEK12122K21L",
"user_email": "person@company.com",
"make": "Apple",
"model": "Macbook Pro",
"operating_system": "macOS",
"operating_system_version": "12.0.5",
"last_enrolled": "2023-01-11T04:03:31",
"last_contact": "2024-01-21T03:01:32",
"last_sync": "2024-01-21T03:01:32",
"last_ip": "1.2.3.4",
"last_ip_epp": "1.2.3.4"
},
...
...
]
}

4. Unmanaged Devices

Unmanaged Devices

Get all of your unmanaged devices and their details.

Optional Fields:
  • serial_number (e.g. "N4K23KA9")
  • current_owner (e.g. "person@company.com")
  • make (e.g. "Apple", "Dell")
  • model (e.g. "MacBook Pro", "Latitude 5420")
  • last_owner (e.g. "person@company.com")
  • last_hostname (e.g. "matt-mbp2")
  • date_unmanaged (e.g. "2024-01-01")
  • notes (e.g. "Device was replaced with newer model")
  • last_updated (e.g. "2024-01-01T00:00:00")
  • updated_by (e.g. "admin@company.io")
  • current_status (e.g. "Decommissioned", "Sold")
  • current_location (e.g. "Warehouse", "Sold")
curl -X GET 'https://app.securityscout.io/api/devices_unmanaged' --header "X-API-KEY: TENANT_ID:API_KEY" --header "Content-Type: application/json" --data '{"make": "Apple", "model": "MacBook Pro"}'
import requests

r=requests.get('https://app.securityscout.io/api/devices_unmanaged', headers={'X-API-KEY':'TENANT_ID:API_KEY', 'Content-Type': 'application/json'}, json={'make': 'Apple', 'model': 'MacBook Pro'})

print(r.json())
{
"count": 2,
"devices_unmanaged": [
{
"id": "dev-12345",
"device_type": "Laptop",
"serial_number": "N4K23KA9",
"current_owner": "person@company.com",
"current_status": "Decommissioned",
"current_location": "Warehouse",
"make": "Apple",
"model": "MacBook Pro",
"last_owner": "person@company.com",
"last_hostname": "matt-mbp2",
"date_unmanaged": "2024-01-01",
"last_updated": "2024-01-01T00:00:00",
"updated_by": "admin@company.io",
"notes": "Device was replaced with newer model"
},
...
...
]
}

4. Endpoint Protection

Normalized Endpoint Protection

Get all of your endpoint protection data, normalized across your providers.

Optional Fields:
  • source (e.g. "CrowdStrike")
  • hostname (e.g. "LAPTOP-ABC123")
  • serial_number (e.g. "ABC123XYZ")
  • last_ip (e.g. "192.168.1.100")
  • mdm_user_email (e.g. "bob@company.com")
curl -X GET 'https://app.securityscout.io/api/endpoint_protection' --header "X-API-KEY: TENANT_ID:API_KEY" --header "Content-Type: application/json" --data '{"source": "CrowdStrike", "hostname": "LAPTOP-ABC123"}'
import requests

r=requests.get('https://app.securityscout.io/api/endpoint_protection', headers={'X-API-KEY':'TENANT_ID:API_KEY', 'Content-Type': 'application/json'}, json={'source': 'CrowdStrike', 'hostname': 'LAPTOP-ABC123'})

print(r.json())
{
"count": 1,
"endpoint_protection": [
{
"source": "CrowdStrike",
"device_id": "abc123def456",
"device_link": "https://falcon.crowdstrike.com/hosts/details/abc123def456",
"hostname": "LAPTOP-ABC123",
"serial_number": "ABC123XYZ",
"last_user": "bob@company.com",
"mdm_user_email": "bob@company.com",
"first_seen": "2023-01-01T12:00:00",
"last_seen": "2023-06-15T15:30:00",
"last_ip": "10.0.0.123",
"product_type": "Workstation",
"chassis_type": "laptop",
"make": "Dell",
"model": "Latitude 5420"
},
...
...
]
}

5. Cloud IAM

Normalized Cloud IAM

Get all of your cloud IAM permissions, normalized across your cloud providers.

Optional Fields:
  • source (e.g. "AWS Identity Center", "Google Cloud", "Microsoft Azure")
  • environment_name (e.g. "my-project")
  • environment_id (e.g. "my-project")
  • environment_type (e.g. "Project", "Management Group", "Subscription")
  • member_or_principal (e.g. "person@company.com")
  • role_or_permission_set (e.g. "roles/cloudsql.client")
  • user (e.g. "bob@company.com")
curl -X GET 'https://app.securityscout.io/api/cloud_iam' --header "X-API-KEY: TENANT_ID:API_KEY" --header "Content-Type: application/json" --data '{"source": "Google Cloud"}'
import requests

r=requests.get('https://app.securityscout.io/api/cloud_iam', headers={'X-API-KEY':'TENANT_ID:API_KEY', 'Content-Type': 'application/json'}, json={'source': 'Google Cloud'})

print(r.json())
{
"count": 2,
"cloud_iam": [
{
"source": "Google Cloud",
"integration": "Google Cloud Platform",
"environment_name": "my-project",
"environment_id": "my-project",
"environment_type": "Project",
"member_or_principal_type": "USER",
"member_or_principal": "person@company.com",
"role_or_permission_set": "roles/cloudsql.client",
"inherited_from": "company.com",
"user": "bob@company.com",
"user_is_active": "true",
"iam_link": "https://console.cloud.google.com/iam-admin/iam?project=my-project",
"member_link": "",
"resource": "specific-instance",
"resource_link": "https://portal.azure.com/#@tenant.onmicrosoft.com/resource/subscriptions/ffffffff-ffff-ffff-ffff-ffffffffffff/resourceGroups/specific-instance"
},
...
...
]
}

6. Alerts

Current Alerts

Get all of your current alerts and details.

Optional Fields:
  • severity (e.g. "critical", "high", "medium", "low")
  • issue (e.g. "Device assigned to unknown user")
  • include_ignored_alerts (defaulted to "false" so that ignored alerts are not included)
curl -X GET 'https://app.securityscout.io/api/alerts' --header "X-API-KEY: TENANT_ID:API_KEY" --header "Content-Type: application/json" --data '{"severity": ["critical", "high"]}'
import requests

r=requests.get('https://app.securityscout.io/api/alerts', headers={'X-API-KEY':'TENANT_ID:API_KEY', 'Content-Type': 'application/json'}, json={'severity': 'high'})

print(r.json())
{
"count": 4,
"alerts": [
{
"severity": "high",
"issue": "Azure device is not managed",
"summary_text": "user-pc (ID: 1234) is in Azure but is not managed",
"summary_html": "user-pc (ID: 1234) is in Azure but is not managed",
"summary_slack": " is in Azure but is not managed",
"context_text": "The Dell Precision 5530 was registered 2021-06-11, last contacted the MDM 2023-11-12, and is assigned to user@company.com",
"context_html": "The Dell IPrecision 5530 was registered 2021-06-11, last contacted the MDM 2023-11-12, and is assigned to user@company.com",
"context_slack": "The Dell Precision 5530 was registered 2021-06-11, last contacted the MDM 2023-11-12, and is assigned to user@company.com"
},
...
...
]
}