Referência da API de gerenciamento de inventário para sensores de monitoramento de OT

Artigo
06/01/2023

Este artigo lista as APIs de gerenciamento de inventário de dispositivos com suporte para sensores OT do Defender para IoT.

conexões (Recuperar informações de conexão do dispositivo)

Use essa API para solicitar uma lista de todas as conexões de dispositivo.

URI: /api/v1/devices/connections

GET

Parâmetros de consulta

Defina qualquer um dos parâmetros de consulta a seguir para filtrar os resultados retornados. Se você não definir os parâmetros de consulta, todas as conexões de dispositivos serão retornadas.

Nome	Descrição	Exemplo	Obrigatório/Opcional
discoveredBefore	Numérico. Filtre os resultados detectados antes de um determinado horário, em que o tempo determinado é definido em milissegundos da Hora da época e no fuso horário UTC.	`/api/v1/devices/2/connections?discoveredBefore=<epoch>`	Opcional
discoveredAfter	Numérico. Filtre os resultados detectados após um determinado tempo, em que o tempo determinado é definido em milissegundos da Hora da época e no fuso horário UTC.	`/api/v1/devices/2/connections?discoveredAfter=<epoch>`	Opcional
lastActiveInMinutes	Numérico. Filtre os resultados por um determinado período durante o qual as conexões estavam ativas. Definido de modo retrospectivo, em minutos, da hora atual.	`/api/v1/devices/2/connections?lastActiveInMinutes=20`	Opcional

Tipo de resposta: JSON

Matriz de objetos JSON que representam conexões de dispositivo ou a seguinte mensagem de falha:

Mensagem	Descrição
Falha – erro	Falha na operação

Campos de resposta de êxito

Nome	Type	Anulável/Não anulável	Lista de valores
firstDeviceId	Numérico	Não permite valor nulo	-
secondDeviceId	Numérico	Não permite valor nulo	-
lastSeen	Numérico	Não permite valor nulo	Época (UTC)
discovered	Numérico	Não permite valor nulo	Época (UTC)
ports	Matriz de números	Nullable	-
protocols	Matriz JSON	Nullable	Campo de protocolo

Campos de protocolo

Nome	Type	Anulável/Não anulável
name	String	Não permite valor nulo
commands	Matriz de cadeia de caracteres	Nullable

Exemplo de resposta

[
    {
        "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

APIs:

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

Exemplos:

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

conexões por dispositivo (recuperar informações específicas de conexão de dispositivo)

Use essa API para solicitar uma lista de todas as conexões por dispositivo.

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

GET

Parâmetro de caminho

Nome	Descrição	Exemplo	Obrigatório/Opcional
deviceId	Obtenha conexões para o dispositivo especificado.	`/api/v1/devices/<deviceId>/connections`	Obrigatório

Parâmetros de consulta

Nome	Descrição	Exemplo	Obrigatório/Opcional
discoveredBefore	Numérico. Filtre os resultados detectados antes de um determinado horário, em que o tempo determinado é definido em milissegundos da Hora da época e no fuso horário UTC.	`/api/v1/devices/2/connections?discoveredBefore=<epoch>`	Opcional
discoveredAfter	Numérico. Filtre os resultados detectados após um determinado tempo, em que o tempo determinado é definido em milissegundos da Hora da época e no fuso horário UTC.	`/api/v1/devices/2/connections?discoveredAfter=<epoch>`	Opcional
lastActiveInMinutes	Numérico. Filtre os resultados por um determinado período durante o qual as conexões estavam ativas. Definido de modo retrospectivo, em minutos, da hora atual.	`/api/v1/devices/2/connections?lastActiveInMinutes=20`	Opcional

Tipo de resposta: JSON

Matriz de objetos JSON que representam conexões de dispositivo ou a seguinte mensagem de falha:

Mensagem	Descrição
Falha – erro	Falha na operação

Campos de resposta de êxito

Nome	Type	Anulável/Não anulável	Lista de valores
firstDeviceId	Numérico	Não permite valor nulo	-
secondDeviceId	Numérico	Não permite valor nulo	-
lastSeen	Numérico	Não permite valor nulo	Época (UTC)
discovered	Numérico	Não permite valor nulo	Época (UTC)
ports	Matriz de números	Nullable	-
protocols	Matriz JSON	Nullable	Campo de protocolo

Campos de protocolo

Nome	Type	Anulável/Não anulável
name	String	Não permite valor nulo
commands	Matriz de cadeia de caracteres	Nullable

Exemplo de resposta

[
    {
        "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

APIs:

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

Exemplos:

Com determinados parâmetros de consulta:

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

cves (recuperar informações sobre CVEs)

Use essa API para solicitar uma lista de todos os CVEs conhecidos descobertos nos dispositivos na rede, classificados em ordem decrescente de pontuação de CVE.

URI: /api/v1/devices/cves

GET

Exemplo: /api/v1/devices/cves

Defina qualquer um dos parâmetros de consulta a seguir para filtrar os resultados retornados.

Nome	Descrição	Exemplo	Obrigatório/Opcional
início	Numérico. Determine quantos CVEs com a maior pontuação obter para cada endereço IP do dispositivo.	`/api/v1/devices/cves?top=50` `/api/v1/devices/<ipAddress>/cves?top=50`	Opcional. Padrão = `100`

Tipo: JSON

Matriz JSON de objetos CVE do dispositivo ou a seguinte mensagem de falha:

Mensagem	Descrição
Falha – erro	Falha na operação

Campos de resposta de êxito

Nome	Type	Anulável/Não anulável	Lista de valores
cveId	String	Não permite valor nulo	Uma ID canônica e padrão do setor para a CVE fornecida.
ipAddress	String	Não permite valor nulo	Endereços IP
score	String	Não permite valor nulo	Uma pontuação CVE, entre 0,0 e 10,0
attackVector	String	Não permite valor nulo	`Network`, `Adjacent Network`, `Local` ou `Physical`
descrição	String	Não permite valor nulo	-

Exemplo de resposta

[
    {

        "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

APIs:

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

Exemplos:

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

cves por endereço IP (recuperar informações específicas sobre CVEs)

Use essa API para solicitar uma lista de todos os CVEs conhecidos descobertos nos dispositivos na rede para um endereço IP específico.

URI: /api/v1/devices/cves

GET

Exemplo: /api/v1/devices/cves

Parâmetro de caminho

Nome	Descrição	Exemplo	Obrigatório/Opcional
ipAddress	Obtenha CVEs para o endereço IP especificado.	`/api/v1/devices/<ipAddress>/cves`	Obrigatório

Defina o parâmetro de consulta a seguir para filtrar os resultados retornados.

Nome	Descrição	Exemplo	Obrigatório/Opcional
início	Numérico. Determine quantos CVEs com a maior pontuação obter para cada endereço IP do dispositivo.	`/api/v1/devices/cves?top=50` `/api/v1/devices/<ipAddress>/cves?top=50`	Opcional. Padrão = `100`

Tipo: JSON

Matriz JSON de objetos CVE do dispositivo ou a seguinte mensagem de falha:

Mensagem	Descrição
Falha – erro	Falha na operação

Campos de resposta de êxito

Nome	Type	Anulável/Não anulável	Lista de valores
cveId	String	Não permite valor nulo	Uma ID canônica e padrão do setor para a CVE fornecida.
ipAddress	String	Não permite valor nulo	Endereços IP
score	String	Não permite valor nulo	Uma pontuação CVE, entre 0,0 e 10,0
attackVector	String	Não permite valor nulo	`Network`, `Adjacent Network`, `Local` ou `Physical`
descrição	String	Não permite valor nulo	-

Exemplo de resposta

[
    {

        "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

APIs:

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

Exemplos:

Com determinados parâmetros de consulta:

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

dispositivos (recuperar informações do dispositivo)

Use essa API para solicitar uma lista de todos os dispositivos detectados por esse sensor.

URI: api/v1/devices/

GET

Parâmetro de consulta

Defina o parâmetro de consulta a seguir para filtrar os resultados retornados. Se você não definir os parâmetros de consulta, todas as conexões de dispositivos serão retornadas.

Nome	Descrição	Exemplo	Obrigatório/Opcional
autorizado	Booliano: - `true`: filtrar somente dados em dispositivos autorizados. - `false`: filtrar somente dados em dispositivos não autorizados.	`/api/v1/devices/`	Opcional

Tipo de resposta: JSON

Matriz de objetos JSON que representam objetos de dispositivo ou a seguinte mensagem de falha:

Mensagem	Descrição
Falha – erro	Falha na operação

Campos de resposta de êxito

Nome	Type	Anulável/Não anulável	Lista de valores
id	Numérico. Define a ID do dispositivo.	Não permite valor nulo	-
ipAddresses	Matriz JSON de strings.	Nullable	-
name	Cadeia de caracteres. Define o nome do dispositivo.	Não permite valor nulo	-
vendor	Cadeia de caracteres. Define o fornecedor do dispositivo.	Nullable	-
operatingSystem	Enum. Define o sistema operacional do dispositivo.	Nullable	Para mais informações, confira Valores de sistema operacional com suporte.
macAddresses	Matriz JSON de strings.	Nullable	-
tipo	Cadeia de caracteres. Define o tipo de dispositivo.	Não permite valor nulo	Pode ser `Unknown`. Para mais informações, confira Valores de tipo com suporte.
engineeringStation	Booliano. Define se o dispositivo é definido como uma estação de engenharia ou não.	Não permite valor nulo	- `true`: Dispositivo é uma estação de engenharia - `false`: o dispositivo não é uma estação de engenharia.
autorizado	Booliano. Define se o dispositivo é definido como uma estação de engenharia ou não.	Não permite valor nulo	- `true`: Dispositivo é uma estação de engenharia - `false`: o dispositivo não é uma estação de engenharia
scanner	Booliano. Define se o dispositivo está autorizado ou não.	Não permite valor nulo	- `true`: O dispositivo está autorizado - `false`: o dispositivo não está autorizado
protocolos	Objeto que contém os detalhes do protocolo do dispositivo.	Nullable	Para obter mais informações, consulte Microsoft defender para IoT-protocolos IoT, OT, ICS e SCADA com suporte.
firmware	Matriz JSON de um objeto `firmware` que desafia o firmware do dispositivo.	Não permite valor nulo	Para mais informações, confira Campos de firmware com suporte.
hasDynamicAddress	Booliano. Define se o dispositivo tem um endereço dinâmico ou não.	Não permite valor nulo	- `true`: O dispositivo tem um endereço dinâmico - `false`: o dispositivo não tem um endereço dinâmico

Valores `operatingSystem` com suporte

Esta seção lista os valores com suporte para o campo de resposta 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` com suporte

Esta seção lista os valores com suporte para o campo de resposta 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 com suporte para os valores de objeto `protocols` e protocolo `name`

Esta seção lista os campos com suporte para o objeto protocolos no campo de resposta protocols.

Nome	Type	Anulável/Não anulável	Lista de valores
id	Numérico. Define a ID interna do protocolo.	Não permite valor nulo	-
name	Cadeia de caracteres. Define o nome do dispositivo.	Não permite valor nulo	Para obter mais informações, veja abaixo.
ipAddresses	Matriz JSON de cadeias de caracteres de endereços IP de protocolo.	Não permite valor nulo	-

Os seguintes valores têm suporte como nomes de protocolo prontos para uso:

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 com suporte

Esta seção lista os campos com suporte para o objeto firmware no campo de resposta firmware.

Nome	Type	Anulável/Não anulável	Lista de valores
address	Cadeia de caracteres. Define o endereço IP do firmware.	Não permite valor nulo	-
moduleAddress	Cadeia de caracteres. Define o endereço do módulo do firmware.	Não permite valor nulo.	-
serial	Cadeia de caracteres. Define o número de série do firmware.	Nullable	-
modelo	Cadeia de caracteres. Define o modelo de firmware.	Nullable	-
firmwareVersion	Cadeia de caracteres. Define a versão do firmware.	Nullable	-
additionalData	Cadeia de caracteres. Define dados adicionais para o firmware.	Nullable	-
rack	Cadeia de caracteres. Define o rack de firmware.	Nullable	-
slot	Cadeia de caracteres. Define o slot de firmware.	Nullable	-

Tipo: GET

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

Próximas etapas

Para obter mais informações, confira a Visão geral de referência da API do Defender para IoT.

Compartilhar via

Referência da API de gerenciamento de inventário para sensores de monitoramento de OT

conexões (Recuperar informações de conexão do dispositivo)

GET

Parâmetros de consulta

Campos de resposta de êxito

Campos de protocolo

Exemplo de resposta

conexões por dispositivo (recuperar informações específicas de conexão de dispositivo)

GET

Parâmetro de caminho

Parâmetros de consulta

Campos de resposta de êxito

Campos de protocolo

Exemplo de resposta

cves (recuperar informações sobre CVEs)

GET

Campos de resposta de êxito

Exemplo de resposta

cves por endereço IP (recuperar informações específicas sobre CVEs)

GET

Parâmetro de caminho

Campos de resposta de êxito

Exemplo de resposta

dispositivos (recuperar informações do dispositivo)

GET

Parâmetro de consulta

Campos de resposta de êxito

Valores `operatingSystem` com suporte

Valores `type` com suporte

Campos com suporte para os valores de objeto `protocols` e protocolo `name`

Campos de firmware com suporte

Próximas etapas

Comentários

Recursos adicionais