Device Details v3.4

Last Update

07/27/2021

Authentication

YES

HTTP Method

POST

Content Type

application/json

Rate limited

YES

Requests per rate limit

10/min

Response Format

JSON

Changes

Changes compared with v3.3

• Added a policy_name into the API response

access_token

string

URL

Yes

access token which archived from OAuth authentication step

opt

int

Body

Optional

Specify a type of the ids parameter

• 0: Device ID or MAC Address

• 1: 3rd party custom ID that is linked to a device

0

ids

Array

Body

Yes

The list of Device IDs or MAC Addresses or linked IDs of devices you want to retrieve device details information. Max length is 50 devices

verbose

object

Body

Optional

Specify what information you look for

verbose.system_info

int

Body

Optional

Specify if system information are included on the response Values can be:

• 0: not include

• 1: include

1

verbose.categories

int

Body

Optional

Specify if category issues the device has are included on the response Values can be:

• 0: not include

• 1: include

0

verbose.unclassified

int

Body

Optional

Only applicable for Wins/macOS devices Specify if unclassified applications are included on the response Values can be:

• 0: not include

• 1: include

0

verbose.mobile_apps

int

Body

Optional

Only applicable for iOS/Android devices Specify if installed applications are included on the response Values can be:

• 0: not include

• 1: include

0

verbose.detected_processes

int

Body

Optional

Only applicable for Linux devices Specify if running processes are included on the response Values can be:

• 0: not include

• 1: include

0

verbose.detected_packages

int

Body

Optional

Only applicable for Linux devices Specify if installed packages are included on the response Values can be:

• 0: not include

• 1: include

0

verbose.detected_patches

int

Body

Optional

Only applicable for wins/macOS devices Specify if missing OS patches are included on the response Values can be:

• 0: not include

• 1: include

0

device_id

string

Device ID which OPSWAT Client generates unique for a device

linked_id

string

Custom ID which 3rd party can define. Need to make sure it's unique for a device

status

string

status of device. Values are:

• compliant: device is in compliance with a policy which the device is assigned to on your account

• non-compliant: device is not in compliance with a policy which the device is assigned to on your account

• exempted: device is exempted

• out_of_license_usage: device is out of token usage.

• unknown: device is not installed OPSWAT Client

• ignored: device is not installed OPSWAT Client and ignored by an administrator

• deleted: device is deleted

• not-found: device is not found

status_detail

object

status detail of device. Values are:

• agent_installed :

  • 1 : device is installed OPSWAT Client

  • 2 : device is not installed OPSWAT Client but detected by Network Discovery or Domain Controller agent

  • 3 : device is not installed OPSWAT Client but detected by Network Discovery or Domain Controller agent and ignored by an administrator

• out_of_token:

  • 0 :device is not out of token usage

  • 1 :device is out of token usage

• exempted:

  • 0: device is not exempted

  • 1: device is exempted

• pending:

  • 0: device reported to servers

  • 1: device has not been reported to servers yet

• compliant :

  • 0: device is non-compliance with policy

  • 1: device is in compliance with policy

• quarantined :

  • 0: device is not quarantined

  • 1: device is quarantined

severity

string

Severity level. Values are

• critical: device has critical issues

• warning: device has warning issues

• no-issues: device doesn't have any issues

issue

object

Issue details on the device

issue.total_issue

int

Total issues of device

issue.total_critical_issue

int

Total critical issues of device

issue.total_warning_issue

int

Total warning issues of device

categories

array<object>

Details of each posture category

categories.category_id

string

category ID which the current block stands for

categories.issue

int

Severity of the category based on the defined policy on your account. Values are:

• -1 - category is disabled

• 0 – no issues

• 1 – warning

• 2 – critical

categories.apps

array<object>

detailed products in a category

categories.apps.id

string

Product ID

categories.apps.name

string

Name of the product

categories.apps.vendor

string

Name of the product vendor

categories.apps.version

string

Product version

categories.apps.ar_id

string

App remover ID of the product

categories.apps.issue

int

Severity of the product based on the defined policy on your account Values are:

• -1 - Not an approved product

• 0 - no issues

• 1 - warning

• 2 - critical

categories.apps.health_status

array<object>

health information of the product

categories.apps.health_status.status

string

product compliance details

categories.apps.health_status.issue

int

Severity of the health_status based on the defined policy on your account Values are:

• 0 - no issues

• 1 - warning

• 2 - critical

unclassified

array<object>

Lists of unclassified products

unclassified.id

string

product ID

unclassified.name

string

product name

unclassified.vendor

string

product vendor

unclassified.version

string

product version

group_name

string

verbose.system_info = 1

group name which a device is assigned to

policy_name

string

verbose.system_info = 1

policy name which a device is assigned to

agent_type

string

verbose.system_info = 1

Type of Agent Values: managed – Managed device dc - Domain controller device

device_name

string

verbose.system_info = 1

Hostname of the device. It will get "<private>" value if it's a non-collectible to each fields which related to privacy.

nick_name

string

verbose.system_info = 1

a nickname for the device which an administrator can update on the console

device_type

string

verbose.system_info = 1

The type of the device

agent_version

string

verbose.system_info = 1

Version of an agent installed on the device

oesis_version

string

verbose.system_info = 1

SDK version which the agent is running

enrolled_at

string

verbose.system_info = 1

Timestamp in GMT format when a device enrolled to an account

last_seen

string

verbose.system_info = 1

The last timestamp in GMT format when the agent reports data to the Cloud

last_reboot

string

verbose.system_info = 1

The last timestamp in GMT format when device reboots

public_ip

string

verbose.system_info = 1

public IP of the device in the last report

country

string

verbose.system_info = 1

Region where the device IP geographically represents

user_identity

string

verbose.system_info = 1

Custom user identity information. This is only available if the account enables "Enforce users enter custom information" on Advanced Setting tab on Global Settings

user_info

object

verbose.system_info = 1

User information block

user_info.username

string

username who currently logs in. This field will be remove if it's set as privacy

user_info.domain

string

Currently logged in user domain

remediation_link

string

verbose.system_info = 1

remediation page URL of the given device

os_info

object

verbose.system_info = 1

Operation system information

os_info.family

string

OS family

os_info.name

string

OS name

os_info.vendor

string

OS vendor

os_info.version

string

OS version

os_info.service_pack_version

string

OS Service Pack Version

os_info.architecture

string

OS architecture

os_info.os_language

string

OS language

os_info.user_password_set

int

If user password is set on OS, 1 is set, 0 is not set

network_info

array<object>

verbose.system_info = 1

Network adapter information block

network_info.description

string

network card description

network_info.mac

string

Media Access Control (MAC) address of the network adapter.. This field will be remove if it's a non-collectible to each fields which related to privacy.

network_info.ipv4

string

IPv4 addresses associated with the network adapter. This field will be remove if it's a non-collectible to each fields which related to privacy.

network_info.ipv6

string

IPv6 addresses associated with the network adapter. This field will be remove if it's a non-collectible to each fields which related to privacy.

network_info.subnet_mask

string

the subnet mask associated with the current network adapter.

network_info.media_state

string

network card state

network_info.dhcp_enabled

string

DHCP enabled state of installed network adapter.

network_info.dhcp_obtained

string

(Optional)The timestamp in GMT format when the lease was obtained for the IP address assigned to the computer by the DHCP server.

network_info.dhcp_expires

string

(Optional)The expiration timestamp in GMT format for a leased IP address that was assigned to the computer by the DHCP server.

network_info.dhcp_server

string

(Optional)IP address of the dynamic host configuration protocol (DHCP) server.

network_info.adapter_enabled

string

Indicates whether the adapter is enabled or not.

network_info.default_gateway

string

(Optional)Array of IP addresses of default gateways that the computer system uses.

network_info.dns_addresses

array<string>

(Optional)Array of server IP addresses to be used in querying for DNS servers.

link_user

object

verbose.system_info = 1

User is linked by admin (editable)

link_user.username

string

Username is linked to device by admin

link_user.group

string

Group is linked to device by admin

mobile_apps

array<object>

Only applicable for iOS/Android devices Lists of applications installed on the device

mobile_apps.name

string

application name

mobile_apps.vendor

string

application vendor

mobile_apps.community_rate

string

rating from community

mobile_apps.community_reviewer

string

number of community reviewers who reviewed the application

detected_processes

object

Only applicable for Linux devices Details about running processes on the device when the device reports data to your account

detected_processes.total

int

number of running processes on the device when the device reports data to your account

detected_processes.processes

array<object>

Lists of running processes on the device when the device reports data to your account with details

detected_packages

object

Only applicable for Linux devices Details about packages installed on the device when the device reports data to your account

detected_packages.total

int

number of packages installed on the device when the device reports data to your account

detected_packages.packages

array<object>

Lists of packages installed on the device when the device reports data to your account

detected_patches

object

Only applicable for Windows/macOS devices Details about missing patches on the device when the device reports data to your account

detected_patches.timestamp

string

timestamp in GMT format when the device reports data to your account

detected_patches.total

int

Total missing patches on the device when the device reports data to your account

detected_patches.patches

array<object>

Lists of missing patches on the device when the device reports data to your account

detected_patches.patches.category

string

The category of a missing patch: 'security_update', 'update_rollup', 'critical_update', 'update', 'driver', 'service_pack', 'unknown'.

detected_patches.patches.titles

string

The title of a missing patch.

detected_patches.patches.description

string

The description of a missing patch.

detected_patches.patches.product

string

The product missing this patch.

detected_patches.patches.vendor

string

(optional) The vendor of the product missing this patch

detected_patches.patches.severity

string

The severity of a missing patch: 'low', 'moderate', 'important', 'critical', 'unknown'.

detected_patches.patches.kb_name

string

(optional)The knowledge base article id of a missing patch. May duplicate security_update_id on some platforms.

detected_patches.patches.release_date

string

A timestamp in GMT format when a patch is released

infection

object

Details on threat detection

infection.metascan

object

Only applicable for Windows/macOS/Linux devices Infection information block which is detected by Metadefender Cloud

infection.metascan.last_scan

string

The last timestamp a device reports Statement of Threat

infection.metascan.total

int

Total infections which is detected by Metadefender Cloud

infection.metascan.issue

int

Status of Daily Metadefender Cloud anti-malware scan based on a device policy on your account Values are:

• -1 – category is disabled

• 0 – category doesnot have issues

• 1 – category has issues

• 2 – category has critical issues

infection.metascan.threats

array<object>

Lists of found threats

infection.metascan.threats.critical

int

Critical status of the threat Values are:

• 0 – not critical

• 1 – critical

infection.metascan.threats.scan_time

string

timestamp when found the threat

infection.metascan.threats.file

string

File was found the threat

infection.metascan.threats.hash

string

hash of the file

infection.metascan.threats.threat_name

string

Threat name

infection.metascan.threats.details

array<object>

threat details on each engine which detected the threat

infection.metascan.threats.details.threat_name

string

Threat name which detected on a specific engine

infection.metascan.threats.details.av_name

string

engine name

infection.antivirus

object

Only applicable for Windows/macOS devices Repeated threat details detected by local anti-malware applications

infection.antivirus.total

int

Total repeated threats which are detected by local anti-malware applications

infection.antivirus.issue

int

Status of repeated threats based on a device policy on your account Values are:

• -1 – category is disabled

• 0 – category doesnot have issues

• 1 – category has issues

• 2 – category has critical issues

infection.antivirus.threats

array<object>

Lists of repeated threats

infection.antivirus.threats.critical

int

Critical status of the threat Values are:

• 0 – not critical

• 1 – critical

infection.antivirus.threats.scan_time

string

Last timestamp when the threat was detected

infection.antivirus.threats.repeat

int

Number of times the threat was detected

infection.antivirus.threats.file

string

File was detected as a threat

infection.antivirus.threats.hash

string

hash of the file

infection.antivirus.threats.threat_name

string

threat name

infection.antivirus.threats.product_name

string

product name which detected the threat

infection.antivirus.threats.product_vendor

string

vendor name

infection.antivirus.threats.product_version

string

product version

infection.antivirus.threats.severity

string

threat severity

infection.antivirus.threats.action

string

The type of remediation ( unknown, cleaned, deleted, quarantined)

infection.antivirus.threats.existing

int

to indicate if an infected file still exists on the system.

• 0 : not existing

• 1 : existing

infection.ip_scanning

object

Only applicable for LINUX/MOBILE devices Details of daily scan for suspicious IP connections

infection.ip_scanning.total

int

Total of suspicious IPs

infection.ip_scanning.issue

int

Status of the suspicious IP based on a device policy on your account Values are:

• -1 – category is disabled

• 0 – category doesnot have issues

• 1 – category has issues

infection.ip_scanning.threats

array<object>

Lists of suspicious IPs

infection.ip_scanning.threats.geo_info

object

An object represents the geolocation of the suspicious IP

infection.ip_scanning.threats.geo_info.country_code

string

Region name of the network address (e.g., San Paulo)

infection.ip_scanning.threats.geo_info.city

string

Country name of the network address (e.g., Brazil)

infection.ip_scanning.threats.geo_info.country_name

string

Country name of the network address (e.g., BR)

infection.ip_scanning.threats.geo_info.region_name

string

Region code of the network address (e.g., 27)

infection.ip_scanning.threats.geo_info.region_code

string

City name of the network address (e.g., San Paulo)

infection.ip_scanning.threats.network_address

string

IP address of the suspicious IP

infection.ip_scanning.threats.status

string

indicates the scanning object is clear, dirty or in-progress

infection.ip_scanning.threats.total_source

int

number of total source

infection.ip_scanning.threats.threats

array<object>

details of IP connections

infection.ip_scanning.threats.threats.assessment

string

Type of threat detected

infection.ip_scanning.threats.threats.confident

string

Represents the reliability of the detection based on several factors. The higher the score, the more reliable the result.

infection.ip_scanning.threats.threats.source_name

string

Source of the feed, usually the domain where the feed is from (e.g., example.com)

v.3

Device Details v3.3

v3.2

Device Details v3.2

v3.1

Device Details v3.1

v3.0

Device Details v3.0

v2.6

Device Details v2.6

v2.5

Device Details v2.5

v2.4

Device Details v2.4

v2.3

Device Details v2.3

v2.2

Device Details v2.2

v2.1

Device Details v2.1