Referencia de la API de administración de inventario para sensores de supervisión de OT

Artículo
06/01/2023

En este artículo se enumeran las API de administración de inventarios de dispositivos compatibles con los sensores de OT de Defender para IoT.

connections (Recuperación de la información de conexión del dispositivo)

Use esta API para solicitar una lista de todas las conexiones de dispositivos.

URI:/api/v1/devices/connections

GET

Parámetros de consulta

Defina cualquiera de los parámetros de consulta siguientes para filtrar los resultados devueltos. Si no establece los parámetros de la consulta, se devuelven todas las conexiones del dispositivo.

Nombre	Descripción	Ejemplo	Obligatorio u opcional
discoveredBefore	Numérico. Filtre los resultados que se detectaron antes de una hora determinada, donde la hora especificada se define en milisegundos desde la hora de época y en la zona horaria UTC.	`/api/v1/devices/2/connections?discoveredBefore=<epoch>`	Opcional
discoveredAfter	Numérico. Filtre los resultados que se detectaron después de una hora determinada, donde la hora especificada se define en milisegundos desde la hora de época y en la zona horaria UTC.	`/api/v1/devices/2/connections?discoveredAfter=<epoch>`	Opcional
lastActiveInMinutes	Numérico. Filtre los resultados por un período de tiempo determinado durante el cual las conexiones estaban activas. Se define hacia atrás, en minutos, desde la hora actual.	`/api/v1/devices/2/connections?lastActiveInMinutes=20`	Opcional

Tipo de respuesta: JSON

Matriz de objetos JSON que representan conexiones de dispositivo o el siguiente mensaje de error:

Message	Descripción
Error: error	Error en la operación.

Campos de respuesta correctos

Nombre	Tipo	Que admite valores NULL / No admite valores NULL	Lista de valores
firstDeviceId	Numeric	No acepta valores NULL	-
secondDeviceId	Numeric	No acepta valores NULL	-
lastSeen	Numeric	No acepta valores NULL	Tiempo (hora UTC)
discovered	Numeric	No acepta valores NULL	Tiempo (hora UTC)
ports	Matriz de números	Nullable	-
protocols	Matriz JSON	Nullable	Campo del protocolo

Campos del protocolo

Nombre	Tipo	Que admite valores NULL / No admite valores NULL
name	String	No acepta valores NULL
commands	Matriz de cadena	Nullable

Ejemplo de respuesta

[
    {
        "firstDeviceId": 171,
        "secondDeviceId": 22,
        "lastSeen": 1511281457933,
        "discovered": 1511872830000,
        "ports": [
            502
        ],
        "protocols": [
        {
            name: "modbus",
            commands: [
                "Read Coils"
            ]
        },
        {
            name: "ams",
            commands: [
                "AMS Write"
            ]
        },
        {
            name: "http",
            commands: [
            ]
        }
    ]
    },
    {
        "firstDeviceId": 171,
        "secondDeviceId": 23,
        "lastSeen": 1511281457933,
        "discovered": 1511872830000,
        "ports": [
            502
        ],
        "protocols": [
            {
                name: "s7comm",
                commands: [
                    "Download block",
                    "Upload"
                ]
            }
        ]
    }
]

Tipo: GET

API:

curl -k -H "Authorization: <AUTH_TOKEN>" https://<IP_ADDRESS>/api/v1/devices/connections

Ejemplos:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/api/v1/devices/connections

conexiones por dispositivo (Recuperar información de conexión de dispositivo específica)

Use esta API para solicitar una lista de todas las conexiones por cada dispositivo.

URI:/api/v1/devices/<deviceID>/connections

GET

Parámetro de ruta de acceso

Nombre	Descripción	Ejemplo	Obligatorio u opcional
deviceId	Obtenga conexiones para el dispositivo determinado.	`/api/v1/devices/<deviceId>/connections`	Obligatorio

Parámetros de consulta

Nombre	Descripción	Ejemplo	Obligatorio u opcional
discoveredBefore	Numérico. Filtre los resultados que se detectaron antes de una hora determinada, donde la hora especificada se define en milisegundos desde la hora de época y en la zona horaria UTC.	`/api/v1/devices/2/connections?discoveredBefore=<epoch>`	Opcional
discoveredAfter	Numérico. Filtre los resultados que se detectaron después de una hora determinada, donde la hora especificada se define en milisegundos desde la hora de época y en la zona horaria UTC.	`/api/v1/devices/2/connections?discoveredAfter=<epoch>`	Opcional
lastActiveInMinutes	Numérico. Filtre los resultados por un período de tiempo determinado durante el cual las conexiones estaban activas. Se define hacia atrás, en minutos, desde la hora actual.	`/api/v1/devices/2/connections?lastActiveInMinutes=20`	Opcional

Tipo de respuesta: JSON

Matriz de objetos JSON que representan conexiones de dispositivo o el siguiente mensaje de error:

Message	Descripción
Error: error	Error en la operación.

Campos de respuesta correctos

Nombre	Tipo	Que admite valores NULL / No admite valores NULL	Lista de valores
firstDeviceId	Numeric	No acepta valores NULL	-
secondDeviceId	Numeric	No acepta valores NULL	-
lastSeen	Numeric	No acepta valores NULL	Tiempo (hora UTC)
discovered	Numeric	No acepta valores NULL	Tiempo (hora UTC)
ports	Matriz de números	Nullable	-
protocols	Matriz JSON	Nullable	Campo del protocolo

Campos del protocolo

Nombre	Tipo	Que admite valores NULL / No admite valores NULL
name	String	No acepta valores NULL
commands	Matriz de cadena	Nullable

Ejemplo de respuesta

[
    {
        "firstDeviceId": 171,
        "secondDeviceId": 22,
        "lastSeen": 1511281457933,
        "discovered": 1511872830000,
        "ports": [
            502
        ],
        "protocols": [
        {
            name: "modbus",
            commands: [
                "Read Coils"
            ]
        },
        {
            name: "ams",
            commands: [
                "AMS Write"
            ]
        },
        {
            name: "http",
            commands: [
            ]
        }
    ]
    },
    {
        "firstDeviceId": 171,
        "secondDeviceId": 23,
        "lastSeen": 1511281457933,
        "discovered": 1511872830000,
        "ports": [
            502
        ],
        "protocols": [
            {
                name: "s7comm",
                commands: [
                    "Download block",
                    "Upload"
                ]
            }
        ]
    }
]

Tipo: GET

API:

curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/api/v1/devices/<deviceId>/connections?lastActiveInMinutes=&discoveredBefore=&discoveredAfter=

Ejemplos:

Con los parámetros de consulta especificados:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/api/v1/devices/2/connections?lastActiveInMinutes=20&discoveredBefore=1594550986000&discoveredAfter=1594550986000

cves (Recuperación de la información de los CVE)

Use esta API para solicitar una lista de todos los CVE conocidos que se detectaron en los dispositivos de la red, ordenados por puntuación de CVE descendente.

URI:/api/v1/devices/cves

GET

Ejemplo: /api/v1/devices/cves

Defina cualquiera de los parámetros de consulta siguientes para filtrar los resultados devueltos.

Nombre	Descripción	Ejemplo	Obligatorio u opcional
top	Numérico. Determine cuántos CVE de puntuación superior se deben obtener para cada dirección IP del dispositivo.	`/api/v1/devices/cves?top=50` `/api/v1/devices/<ipAddress>/cves?top=50`	Opcional. Valor predeterminado = `100`

Tipo: JSON

Matriz JSON de objetos CVE de dispositivo o el siguiente mensaje de error:

Message	Descripción
Error: error	Error en la operación.

Campos de respuesta correctos

Nombre	Tipo	Que admite valores NULL / No admite valores NULL	Lista de valores
cveId	String	No acepta valores NULL	Identificador canónico estándar del sector para el CVE específico.
ipAddress	String	No acepta valores NULL	Direcciones IP
score	String	No acepta valores NULL	Puntuación CVE, entre 0,0 y 10,0
attackVector	String	No acepta valores NULL	`Network`, `Adjacent Network`, `Local` o `Physical`
description	String	No acepta valores NULL	-

Ejemplo de respuesta

[
    {

        "cveId": "CVE-2007-0099",
        "score": "9.3",
        "ipAddress": "10.35.1.51",
        "attackVector": "NETWORK",
        "description": "Race condition in the msxml3 module in Microsoft XML Core
        Services 3.0, as used in Internet Explorer 6 and other
        applications, allows remote attackers to execute arbitrary
        code or cause a denial of service (application crash) via many
        nested tags in an XML document in an IFRAME, when synchronous
        document rendering is frequently disrupted with asynchronous
        events, as demonstrated using a JavaScript timer, which can
        trigger NULL pointer dereferences or memory corruption, aka
        \"MSXML Memory Corruption Vulnerability.\""
    },
    {
        "cveId": "CVE-2009-1547",
        "score": "9.3",
        "ipAddress": "10.35.1.51",
        "attackVector": "NETWORK",
        "description": "Unspecified vulnerability in Microsoft Internet Explorer 5.01
        SP4, 6, 6 SP1, and 7 allows remote attackers to execute
        arbitrary code via a crafted data stream header that triggers
        memory corruption, aka \"Data Stream Header Corruption
        Vulnerability.\""
    }
]

Tipo: GET

API:

curl -k -H "Authorization: <AUTH_TOKEN>" https://<IP_ADDRESS>/api/v1/devices/cves

Ejemplos:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/api/v1/devices/cves

cve por dirección IP (Recuperar información específica sobre los CVE)

Use esta API para solicitar una lista de todos los CVE conocidos que se detectaron en los dispositivos de la red para una dirección IP específica.

URI:/api/v1/devices/cves

GET

Ejemplo: /api/v1/devices/cves

Parámetro de ruta de acceso

Nombre	Descripción	Ejemplo	Obligatorio u opcional
ipAddress	Obtiene los CVE para la dirección IP especificada.	`/api/v1/devices/<ipAddress>/cves`	Obligatorio

Defina los parámetros de consulta siguientes para filtrar los resultados devueltos.

Nombre	Descripción	Ejemplo	Obligatorio u opcional
top	Numérico. Determine cuántos CVE de puntuación superior se deben obtener para cada dirección IP del dispositivo.	`/api/v1/devices/cves?top=50` `/api/v1/devices/<ipAddress>/cves?top=50`	Opcional. Valor predeterminado = `100`

Tipo: JSON

Matriz JSON de objetos CVE de dispositivo o el siguiente mensaje de error:

Message	Descripción
Error: error	Error en la operación.

Campos de respuesta correctos

Nombre	Tipo	Que admite valores NULL / No admite valores NULL	Lista de valores
cveId	String	No acepta valores NULL	Identificador canónico estándar del sector para el CVE específico.
ipAddress	String	No acepta valores NULL	Direcciones IP
score	String	No acepta valores NULL	Puntuación CVE, entre 0,0 y 10,0
attackVector	String	No acepta valores NULL	`Network`, `Adjacent Network`, `Local` o `Physical`
description	String	No acepta valores NULL	-

Ejemplo de respuesta

[
    {

        "cveId": "CVE-2007-0099",
        "score": "9.3",
        "ipAddress": "10.35.1.51",
        "attackVector": "NETWORK",
        "description": "Race condition in the msxml3 module in Microsoft XML Core
        Services 3.0, as used in Internet Explorer 6 and other
        applications, allows remote attackers to execute arbitrary
        code or cause a denial of service (application crash) via many
        nested tags in an XML document in an IFRAME, when synchronous
        document rendering is frequently disrupted with asynchronous
        events, as demonstrated using a JavaScript timer, which can
        trigger NULL pointer dereferences or memory corruption, aka
        \"MSXML Memory Corruption Vulnerability.\""
    },
    {
        "cveId": "CVE-2009-1547",
        "score": "9.3",
        "ipAddress": "10.35.1.51",
        "attackVector": "NETWORK",
        "description": "Unspecified vulnerability in Microsoft Internet Explorer 5.01
        SP4, 6, 6 SP1, and 7 allows remote attackers to execute
        arbitrary code via a crafted data stream header that triggers
        memory corruption, aka \"Data Stream Header Corruption
        Vulnerability.\""
    }
]

Tipo: GET

API:

curl -k -H "Authorization: <AUTH_TOKEN>" https://<IP_ADDRESS>/api/v1/devices/<deviceIpAddress>/cves?top=

Ejemplos:

Con los parámetros de consulta especificados:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/api/v1/devices/10.10.10.15/cves?top=50

dispositivos (Recuperación de la información de los dispositivos)

Use esta API para solicitar una lista de todos los dispositivos detectados por este sensor.

URI:api/v1/devices/

GET

Parámetro de consulta

Defina los parámetros de consulta siguientes para filtrar los resultados devueltos. Si no establece los parámetros de la consulta, se devuelven todas las conexiones del dispositivo.

Nombre	Descripción	Ejemplo	Obligatorio u opcional
autorizado	Booleano: - `true`: filtre solo por datos en dispositivos autorizados. - `false`: filtre solo por datos en dispositivos no autorizados.	`/api/v1/devices/`	Opcional

Tipo de respuesta: JSON

Matriz de objetos JSON que representan objetos de dispositivo o el siguiente mensaje de error:

Message	Descripción
Error: error	Error en la operación.

Campos de respuesta correctos

Nombre	Tipo	Que admite valores NULL / No admite valores NULL	Lista de valores
id	Numérico. Define el id. de dispositivo.	No acepta valores NULL	-
ipAddresses	Matriz JSON de cadenas.	Nullable	-
name	Cadena Define el nombre del dispositivo.	No acepta valores NULL	-
vendor	Cadena Define el proveedor del dispositivo.	Nullable	-
operatingSystem	Enumeración. Define el sistema operativo del dispositivo.	Nullable	Para obtener más información, consulte el artículo sobre los Valores de sistemas operativos compatibles.
macAddresses	Matriz JSON de cadenas.	Nullable	-
type	Cadena Define el tipo de dispositivo.	No acepta valores NULL	Puede ser `Unknown`. Para obtener más información, consulte el artículo sobre los Valores de tipos compatibles.
engineeringStation	booleano. Define si el dispositivo se define como una estación de ingeniería o no.	No acepta valores NULL	- `true`: El dispositivo es una estación de ingeniería - `false`: el dispositivo no es una estación de ingeniería.
autorizado	booleano. Define si el dispositivo se define como una estación de ingeniería o no.	No acepta valores NULL	- `true`: El dispositivo es una estación de ingeniería - `false`: el dispositivo no es una estación de ingeniería
scanner	booleano. Define si el dispositivo está autorizado o no.	No acepta valores NULL	- `true`: el dispositivo está autorizado - `false`: el dispositivo no está autorizado
Protocolos	Objeto que contiene los detalles del protocolo del dispositivo.	Nullable	Para obtener más información, consulte Microsoft Defender para IoT: protocolos IoT, OT, ICS y SCADA compatibles.
firmware	Matriz JSON de un objeto `firmware` que desafía el firmware del dispositivo.	No acepta valores NULL	Para obtener más información, consulte Campos de firmware admitidos.
hasDynamicAddress	booleano. Define si el dispositivo tiene una dirección dinámica o no.	No acepta valores NULL	- `true`: el dispositivo tiene una dirección dinámica. - `false`: el dispositivo no tiene una dirección dinámica

Valores `operatingSystem` admitidos

En esta sección se enumeran los valores admitidos para el campo de respuesta operatingSystem.

Windows 10
Windows 10 32
Windows 10 64
Windows 2000
Windows 7
Windows 7 32
Windows 7 64
Windows 8
Windows 8 32
Windows 8 64
Windows 8.1
Windows 8.1 32

Windows 8.1 64
Windows NT
Windows Server 2003
Windows Server 2003 R2
Windows Server 2008
Windows Server 2008 32
Windows Server 2008 64
Windows Server 2008 R2
Windows Server 2012
Windows Server 2012 R2
Windows Server 2016
Windows Vista

Windows Vista 32
Windows Vista 64
Windows XP
Mac OS
Mac OS X
Linux
Windows Server 2019
HP UX
Windows 11
Windows 11 32
Windows 11 64

Valores `type` admitidos

En esta sección se enumeran los valores admitidos para el campo de respuesta de tipo.

Engineering Station
PLC
Historian
HMI
Domain Controller
DB Server
Wireless Access Point
Router
Switch
Workstation
Server
IP Camera
Printer
Multicast/Broadcast
Internet
Firewall
Terminal Station
VPN Gateway
Group

IED
DCS Controller
RTU
NTP Server
Storage
Industrial Packaging System
Industrial Scale
Industrial Robot
Slot
Punch Clock
ATM
Smart TV
Game console
DVR
Door Control Panel
HVAC
Thermostat
Fire Alarm
Smart Light

Smart Switch
Fire Detector
IP Telephone
Alarm System
Alarm Siren
Smart Phone
Tablet
Wifi Pineapple
Motion Detector
Elevator
Humidity Sensor
Physical Location
Backup Server
Meter
Barcode Scanner
Uninterruptable Power Supply

Variable Frequency Drive
Robot Controller
Servo Drive
Pneumatic Device
Marquee
People Counter System
Intercom
Turnstile
I/O Adapter
Protocol Converter
KVM
Web Guiding System
Turbine
External Management
Embedded Device
Unknown

Campos admitidos para los valores de `protocols` objeto y protocolo `name`

En esta sección se enumeran los campos admitidos para el objeto protocolos en el campo de respuesta protocols.

Nombre	Tipo	Que admite valores NULL / No admite valores NULL	Lista de valores
id	Numérico. Define el identificador interno del protocolo.	No acepta valores NULL	-
name	Cadena Define el nombre del dispositivo.	No acepta valores NULL	Para obtener más información, consulte más adelante.
ipAddresses	Matriz JSON de cadenas de direcciones IP de protocolo.	No acepta valores NULL	-

Los valores siguientes se admiten como nombres de protocolo predefinidos:

Unknown
DNP3
MODBUS
C37.118
SSH
HTTP
SYSLOG
GENERIC
ICMP
DNS
GOOSE
MMS
MALFORMED
IEC-60870
OPC UA
Siemens S7
ARP
Sampled Values
EtherNet/IP

Siemens S7 Plus
Motorola MDLC
Netbios Name Service
Netbios Datagram Service
Lightweight Access Point
CAPWAP
SNMP
DTLS
TNS
Database
SRTP
RPC
OPC
DF-1
DH-485
TDS
SMB
Suitelink
ControlNet

FTP
CDP
Profinet DCP
Profinet Real-Time
LLDP
Telnet
DeltaV
BACNet
AMS
TwinCAT
Ovation ADMD
Ovation SSRPC
Ovation DPUSTAT
Port Map
STP
Telvent OASyS Tags
Mitsubishi MELSEC
Honeywell Control Data Access

ARP
Yokogawa HIS Equalize
Emerson OpenBSI
Siemens SICAM
Omron FINS
Toshiba Computer Link
Foxboro I/A
Yokogawa VNet/IP
Emerson ROC
ABB Totalflow
Siemens Process Historian Discovery
Siemens WinCC Agent
LonTalk
Common ASCII Message
CodeSys
SAIA S-Bus
MDNS
Bently Nevada

Campos de firmware admitidos

En esta sección se enumeran los campos admitidos para el objeto firmware en el campo de respuesta firmware.

Nombre	Tipo	Que admite valores NULL / No admite valores NULL	Lista de valores
address	Cadena Define la dirección IP del firmware.	No acepta valores NULL	-
moduleAddress	String. Define la dirección del módulo del firmware.	No acepta valores NULL.	-
serial	Cadena Define el número de serie del firmware.	Nullable	-
model	Cadena Define el modelo de firmware.	Nullable	-
firmwareVersion	Cadena Define la versión de firmware.	Nullable	-
additionalData	Cadena Define datos adicionales para el firmware.	Nullable	-
rack	Cadena Define el bastidor de firmware.	Nullable	-
slot	Cadena Define la ranura de firmware.	Nullable	-

Tipo: GET

curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/api/v1/devices/'

Pasos siguientes

Para obtener más información, consulte la información general de referencia de API de Defender para IoT.

Compartir vía

Referencia de la API de administración de inventario para sensores de supervisión de OT

connections (Recuperación de la información de conexión del dispositivo)

GET

Parámetros de consulta

Campos de respuesta correctos

Campos del protocolo

Ejemplo de respuesta

conexiones por dispositivo (Recuperar información de conexión de dispositivo específica)

GET

Parámetro de ruta de acceso

Parámetros de consulta

Campos de respuesta correctos

Campos del protocolo

Ejemplo de respuesta

cves (Recuperación de la información de los CVE)

GET

Campos de respuesta correctos

Ejemplo de respuesta

cve por dirección IP (Recuperar información específica sobre los CVE)

GET

Parámetro de ruta de acceso

Campos de respuesta correctos

Ejemplo de respuesta

dispositivos (Recuperación de la información de los dispositivos)

GET

Parámetro de consulta

Campos de respuesta correctos

Valores `operatingSystem` admitidos

Valores `type` admitidos

Campos admitidos para los valores de `protocols` objeto y protocolo `name`

Campos de firmware admitidos

Pasos siguientes

Comentarios

Recursos adicionales