Referência da API de gerenciamento de estoque para sensores de monitoramento OT

Artigo
12/18/2023

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

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

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

URI:/api/v1/devices/connections

GET

Parâmetros de consultas

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

Nome	Descrição	Exemplo	Obrigatório / Opcional
descobertoAntes	Numérico. Filtre os resultados que foram detetados antes de uma determinada hora, onde a hora dada é definida em milissegundos a partir da hora de Epoch e no fuso horário UTC.	`/api/v1/devices/2/connections?discoveredBefore=<epoch>`	Opcional
descobertoDepois	Numérico. Filtre os resultados que foram detetados após um determinado tempo, onde o tempo dado é definido em milissegundos a partir da hora de Epoch 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 de tempo durante o qual as conexões estavam ativas. Definido de trás para frente, em minutos, a partir 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	Description
Falha – erro	Falha na operação

Campos de resposta de sucesso

Nome	Type	Nulo / Não anulável	Lista de valores
firstDeviceId	Numérico	Não anulável	-
segundoDeviceId	Numérico	Não anulável	-
visto por último	Numérico	Não anulável	Época (UTC)
descoberto	Numérico	Não anulável	Época (UTC)
portos	Matriz numérica	Que podem ser nulos	-
protocolos	Matriz JSON	Que podem ser nulos	Campo Protocolo

Campos de protocolo

Nome	Type	Nulo / Não anulável
Designação	Cadeia (de carateres)	Não anulável
comandos	Matriz de cadeias de carateres	Que podem ser nulos

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 do dispositivo)

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

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

GET

Parâmetro Path

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

Parâmetros de consultas

Nome	Descrição	Exemplo	Obrigatório / Opcional
descobertoAntes	Numérico. Filtre os resultados que foram detetados antes de uma determinada hora, onde a hora dada é definida em milissegundos a partir da hora de Epoch e no fuso horário UTC.	`/api/v1/devices/2/connections?discoveredBefore=<epoch>`	Opcional
descobertoDepois	Numérico. Filtre os resultados que foram detetados após um determinado tempo, onde o tempo dado é definido em milissegundos a partir da hora de Epoch 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 de tempo durante o qual as conexões estavam ativas. Definido de trás para frente, em minutos, a partir 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	Description
Falha – erro	Falha na operação

Campos de resposta de sucesso

Nome	Type	Nulo / Não anulável	Lista de valores
firstDeviceId	Numérico	Não anulável	-
segundoDeviceId	Numérico	Não anulável	-
visto por último	Numérico	Não anulável	Época (UTC)
descoberto	Numérico	Não anulável	Época (UTC)
portos	Matriz numérica	Que podem ser nulos	-
protocolos	Matriz JSON	Que podem ser nulos	Campo Protocolo

Campos de protocolo

Nome	Type	Nulo / Não anulável
Designação	Cadeia (de carateres)	Não anulável
comandos	Matriz de cadeias de carateres	Que podem ser nulos

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 parâmetros de consulta fornecidos:

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 esta API para solicitar uma lista de todas as CVEs conhecidas descobertas em dispositivos na rede, classificadas por pontuação CVE decrescente.

URI:/api/v1/devices/cves

GET

Exemplo: /api/v1/devices/cves

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

Nome	Descrição	Exemplo	Obrigatório / Opcional
Início	Numérico. Determine quantos CVEs com melhor 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	Description
Falha – erro	Falha na operação

Campos de resposta de sucesso

Nome	Type	Nulo / Não anulável	Lista de valores
cveId	String	Não anulável	Um ID canônico padrão do setor para o CVE fornecido.
Endereço IP	String	Não anulável	Endereços IP
Pontuação	String	Não anulável	Uma pontuação CVE, entre 0,0 - 10,0
attackVector	String	Não anulável	`Network`, , , `Adjacent NetworkLocal`ou`Physical`
descrição	String	Não anulável	-

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 esta API para solicitar uma lista de todos os CVEs conhecidos descobertos em dispositivos na rede para um endereço IP específico.

URI:/api/v1/devices/cves

GET

Exemplo: /api/v1/devices/cves

Parâmetro Path

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

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

Nome	Descrição	Exemplo	Obrigatório / Opcional
Início	Numérico. Determine quantos CVEs com melhor 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	Description
Falha – erro	Falha na operação

Campos de resposta de sucesso

Nome	Type	Nulo / Não anulável	Lista de valores
cveId	String	Não anulável	Um ID canônico padrão do setor para o CVE fornecido.
Endereço IP	String	Não anulável	Endereços IP
Pontuação	String	Não anulável	Uma pontuação CVE, entre 0,0 - 10,0
attackVector	String	Não anulável	`Network`, , , `Adjacent NetworkLocal`ou`Physical`
descrição	String	Não anulável	-

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 parâmetros de consulta fornecidos:

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 esta API para solicitar uma lista de todos os dispositivos detetados por este sensor.

URI:api/v1/devices/

GET

Parâmetro de consulta

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

Nome	Descrição	Exemplo	Obrigatório / Opcional
autorizadas	Booleano: - `true`: Filtro para dados apenas em dispositivos autorizados. - `false`: Filtrar dados apenas 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	Description
Falha – erro	Falha na operação

Campos de resposta de sucesso

Nome	Type	Nulo / Não anulável	Lista de valores
id	Numérico. Define o ID do dispositivo.	Não anulável	-
Endereços IP	Matriz JSON de cadeias de caracteres.	Que podem ser nulos	-
Designação	String. Define o nome do dispositivo.	Não anulável	-
fornecedor	String. Define o fornecedor do dispositivo.	Que podem ser nulos	-
sistema operacional	Enum. Define o sistema operacional do dispositivo.	Que podem ser nulos	Para obter mais informações, consulte Valores do sistema operacional suportados.
macEndereços	Matriz JSON de cadeias de caracteres.	Que podem ser nulos	-
tipo	String. Define o tipo de dispositivo.	Não anulável	Pode ser `Unknown`. Para obter mais informações, consulte Valores de tipo suportados.
engineeringStation [en]	Booleano. Define se o dispositivo é definido como uma estação de engenharia ou não.	Não anulável	- `true`: O dispositivo é uma estação de engenharia - `false`: O dispositivo não é uma estação de engenharia.
autorizadas	Booleano. Define se o dispositivo é definido como uma estação de engenharia ou não.	Não anulável	- `true`: O dispositivo é uma estação de engenharia - `false`: O dispositivo não é uma estação de engenharia
scanner	Booleano. Define se o dispositivo é autorizado ou não.	Não anulável	- `true`: O dispositivo está autorizado - `false`: O dispositivo não está autorizado
protocolos	Objeto que contém os detalhes do protocolo do dispositivo.	Que podem ser nulos	Para obter mais informações, consulte Microsoft Defender for IoT - protocolos IoT, OT, ICS e SCADA suportados.
firmware	Matriz JSON de um `firmware` objeto que desafia o firmware do dispositivo.	Não anulável	Para obter mais informações, consulte Campos de firmware suportados.
hasDynamicAddress	Booleano. Define se o dispositivo tem um endereço dinâmico ou não.	Não anulável	- `true`: O dispositivo tem um endereço dinâmico - `false`: O dispositivo não tem um endereço dinâmico

Valores suportados `operatingSystem`

Esta seção lista os valores suportados 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 suportados `type`

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

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

Nome	Type	Nulo / Não anulável	Lista de valores
id	Numérico. Define a ID interna do protocolo.	Não anulável	-
Designação	String. Define o nome do dispositivo.	Não anulável	Para obter mais informações, consulte abaixo.
Endereços IP	Matriz JSON de cadeias de caracteres de endereços IP de protocolo.	Não anulável	-

Os seguintes valores são suportados 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 suportados

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

Nome	Type	Nulo / Não anulável	Lista de valores
Endereço	String. Define o endereço IP do firmware.	Não anulável	-
moduleAddress	String. Define o endereço do módulo do firmware.	Não anulável.	-
Série	String. Define o número de série do firmware.	Que podem ser nulos	-
modelo	String. Define o modelo de firmware.	Que podem ser nulos	-
firmwareVersão	String. Define a versão do firmware.	Que podem ser nulos	-
dados adicionais	String. Define dados adicionais para o firmware.	Que podem ser nulos	-
rack	String. Define o rack de firmware.	Que podem ser nulos	-
Faixa horária	String. Define o slot de firmware.	Que podem ser nulos	-

Tipo: GET

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

Próximos passos

Para obter mais informações, consulte a visão geral da referência da API do Defender for IoT.

Partilhar via

Referência da API de gerenciamento de estoque para sensores de monitoramento OT

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

GET

Parâmetros de consultas

Campos de resposta de sucesso

Campos de protocolo

Exemplo de resposta

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

GET

Parâmetro Path

Parâmetros de consultas

Campos de resposta de sucesso

Campos de protocolo

Exemplo de resposta

cves (Recuperar informações sobre CVEs)

GET

Campos de resposta de sucesso

Exemplo de resposta

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

GET

Parâmetro Path

Campos de resposta de sucesso

Exemplo de resposta

dispositivos (Recuperar informações do dispositivo)

GET

Parâmetro de consulta

Campos de resposta de sucesso

Valores suportados `operatingSystem`

Valores suportados `type`

Campos suportados para os valores de `protocols` objeto e protocolo `name`

Campos de firmware suportados

Próximos passos

Comentários

Recursos adicionais