Get UEBA Endpoints by Operating System

Retrieve User and Entity Behavior Analytics (UEBA) endpoint information filtered by operating system.

✅ All code examples tested: Verified against FortiAnalyzer v7.4.8, v7.6.4, v8.0.0.

Overview

This endpoint retrieves UEBA endpoint data filtered by operating system type - useful for:

• Security posture assessment by OS platform

• Identifying vulnerable OS versions requiring patches

• Compliance monitoring for specific OS platforms

• Asset inventory and management by OS type

• Risk analysis across different operating systems

• Planning OS migration or upgrade strategies

UEBA provides behavioral analytics and risk scoring for endpoints, helping security teams identify anomalous behavior and potential threats across different operating system platforms.

Endpoint Details

Method: POST URL: /jsonrpc API Path: /ueba/adom/{adom}/endpoints/ ADOM Support: Yes Requires Authentication: Yes Minimum Version: 7.4.0

Prerequisites

• UEBA feature must be enabled on FortiAnalyzer

• Endpoints must be registered and reporting to FortiAnalyzer

• Read access to UEBA data in specified ADOM

Request Format

Parameters

Parameter	Type	Required	Default	Description
adom	string	Yes	-	ADOM name (e.g., “root”)
filter	string	Yes	-	Filter expression: osname={OS_name}
limit	integer	No	1000	Maximum results to return
offset	integer	No	0	Starting position for pagination
detail-level	string	No	standard	Detail level: standard or verbose
sort-by	array	No	-	Sorting specification
time-range	object	No	-	Activity time range filter
firstseen-time-range	object	No	-	First seen time range filter

Common OS Name Values

• Windows 10

• Windows 11

• Windows Server 2019

• Windows Server 2022

• Debian

• Ubuntu

• CentOS

• Red Hat Enterprise Linux

• macOS

• iOS

• Android

Sorting Configuration

Parameter	Type	Description
└─ field	string	Field to sort by (e.g., “epid”, “risk_score”)
└─ order	string	Sort order: asc or desc

Request Example

REQUEST

{
    "method": "get",
    "params": [{
        "url": "/ueba/adom/root/endpoints/",
        "filter": "osname=Debian",
        "limit": 1000,
        "offset": 0,
        "detail-level": "standard",
        "sort-by": [{
            "field": "epid",
            "order": "asc"
        }],
        "time-range": {
            "start": "2023-10-06 13:09:00",
            "end": "2023-12-05 13:09:00"
        },
        "firstseen-time-range": {
            "start": "1970-01-01 00:00:01",
            "end": "2023-12-05 13:09:29"
        }
    }],
    "session": "{{session_id}}",
    "id": 1
}

RESPONSE

{
    "result": [{
        "data": [
            {
                "epid": 2045,
                "hostname": "debian-server-01",
                "ip": "10.0.2.50",
                "mac": "00:0c:29:4b:6f:23",
                "osname": "Debian",
                "osversion": "11.5",
                "risk_score": 25,
                "first_seen": "2023-08-20 10:15:00",
                "last_seen": "2023-12-05 11:30:00",
                "user": "admin",
                "status": "active"
            },
            {
                "epid": 2108,
                "hostname": "debian-web-02",
                "ip": "10.0.2.75",
                "mac": "00:0c:29:5c:7a:34",
                "osname": "Debian",
                "osversion": "12.0",
                "risk_score": 18,
                "first_seen": "2023-09-10 14:22:00",
                "last_seen": "2023-12-05 12:15:00",
                "user": "webadmin",
                "status": "active"
            }
        ],
        "status": {
            "code": 0,
            "message": "OK"
        }
    }]
}

Response Fields

Field	Type	Description
epid	integer	Unique endpoint identifier
hostname	string	Endpoint hostname
ip	string	IP address
mac	string	MAC address
osname	string	Operating system name
osversion	string	OS version
risk_score	integer	UEBA risk score (0-100)
first_seen	string	First seen timestamp
last_seen	string	Last activity timestamp
user	string	Associated user
status	string	Endpoint status

Complete Python Example

import json
import requests
import urllib3

urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)

def get_ueba_endpoints_by_os(session_id, adom, os_name, time_range=None, limit=1000):
    """
    Get UEBA endpoints filtered by operating system

    Args:
        session_id: Active session ID
        adom: ADOM name
        os_name: Operating system name to filter
        time_range: Optional time range dict
        limit: Maximum results (default: 1000)

    Returns:
        list: Endpoint data
    """
    url = "https://faz.example.com/jsonrpc"

    params_data = {
        "url": f"/ueba/adom/{adom}/endpoints/",
        "filter": f"osname={os_name}",
        "limit": limit,
        "offset": 0,
        "detail-level": "standard",
        "sort-by": [{
            "field": "epid",
            "order": "asc"
        }]
    }

    if time_range:
        params_data["time-range"] = time_range

    payload = {
        "method": "get",
        "params": [params_data],
        "session": session_id,
        "id": 1
    }

    response = requests.post(url, json=payload, verify=False)
    result = response.json()

    if result['result'][0]['status']['code'] == 0:
        return result['result'][0].get('data', [])
    else:
        raise Exception(f"API error: {result['result'][0]['status']['message']}")

# Example: Get all Debian endpoints
endpoints = get_ueba_endpoints_by_os(
    session_id="your_session_id",
    adom="root",
    os_name="Debian",
    time_range={
        "start": "2023-10-06 13:09:00",
        "end": "2023-12-05 13:09:00"
    }
)

# Display results
print(f"Found {len(endpoints)} Debian endpoints:\n")
for ep in endpoints:
    print(f"  {ep['hostname']} ({ep['ip']})")
    print(f"    OS Version: {ep['osversion']}")
    print(f"    Risk Score: {ep['risk_score']}")
    print(f"    Last Seen: {ep['last_seen']}")
    print()

Use Cases

Vulnerability Assessment by OS

# Identify all Windows 10 endpoints for patching
win10_endpoints = get_ueba_endpoints_by_os(
    session_id=session,
    adom="root",
    os_name="Windows 10"
)

high_risk = [ep for ep in win10_endpoints if ep['risk_score'] > 60]
print(f"High-risk Windows 10 endpoints: {len(high_risk)}")

for ep in high_risk:
    print(f"  {ep['hostname']} - Risk: {ep['risk_score']}")

OS Migration Planning

# Get all endpoints running legacy OS versions
legacy_os = ["Windows 7", "Windows Server 2008", "Ubuntu 16.04"]
endpoints_to_migrate = []

for os_name in legacy_os:
    endpoints = get_ueba_endpoints_by_os(
        session_id=session,
        adom="root",
        os_name=os_name
    )
    endpoints_to_migrate.extend(endpoints)

print(f"Total endpoints requiring migration: {len(endpoints_to_migrate)}")

# Generate migration report
for ep in endpoints_to_migrate:
    print(f"{ep['hostname']}: {ep['osname']} {ep['osversion']} -> Upgrade Required")

Compliance Reporting

# Check compliance: All servers must run approved OS versions
approved_server_os = ["Windows Server 2019", "Windows Server 2022", "Ubuntu 22.04", "Debian"]

server_endpoints = get_ueba_endpoints_by_os(
    session_id=session,
    adom="root",
    os_name="Windows Server 2016"  # Non-compliant version
)

if server_endpoints:
    print("⚠️ COMPLIANCE ALERT: Non-compliant OS detected")
    for ep in server_endpoints:
        print(f"  {ep['hostname']} running {ep['osname']} {ep['osversion']}")

Security Posture by Platform

# Analyze risk scores by OS platform
os_platforms = ["Windows 10", "Windows 11", "macOS", "Ubuntu", "Debian"]
risk_by_os = {}

for os_name in os_platforms:
    endpoints = get_ueba_endpoints_by_os(
        session_id=session,
        adom="root",
        os_name=os_name
    )

    if endpoints:
        avg_risk = sum(ep['risk_score'] for ep in endpoints) / len(endpoints)
        risk_by_os[os_name] = {
            'count': len(endpoints),
            'avg_risk': round(avg_risk, 2)
        }

# Display results
print("Security Posture by OS Platform:")
for os_name, data in sorted(risk_by_os.items(), key=lambda x: x[1]['avg_risk'], reverse=True):
    print(f"  {os_name}: {data['count']} endpoints, Avg Risk: {data['avg_risk']}")

Error Handling

ERROR RESPONSE

{
    "result": [{
        "status": {
            "code": -2,
            "message": "No data available"
        }
    }]
}

Common causes:

• No endpoints with specified OS name

• UEBA not enabled

• No data for specified time range

• Incorrect OS name format

• Insufficient permissions

Best Practices

💡 Tip: Use exact OS names as they appear in FortiAnalyzer. OS names are case-sensitive.

💡 Tip: Combine with risk_score sorting to prioritize high-risk endpoints for remediation.

⚠️ Warning: Legacy OS versions (Windows 7, Server 2008) pose significant security risks and should be upgraded.

💡 Tip: Regular OS inventory helps identify unauthorized or non-compliant systems.

Related Endpoints

• Get UEBA Endpoints by ID - Query specific endpoint

• Get Devices - List all managed devices

---

Last Updated: 2025-11-09 API Version: 7.6.4+