Módulo WMI

O módulo wmi fornece funções para interagir com o Windows Management Instrumentation (WMI), permitindo consultar informações do sistema, hardware, software e configurações em máquinas Windows remotas ou locais. Este módulo suporta tanto a execução cross-platform (usando o utilitário wmic) quanto a execução nativa no Windows (usando a API COM).
Funções Disponíveis
1. wmi.buildwql(instance_id, table, fields)
Constrói uma consulta WQL (WMI Query Language) a partir de parâmetros simplificados.
Parâmetros:

instance_id (string opcional): Identificador de instância no formato "Tabela|Campo|Valor"

table (string opcional): Nome da tabela WMI (usado quando não há instance_id)

fields (tabela): Lista de campos a serem selecionados
Retorno:

string: Consulta WQL formatada
Exceções:
Lança erro se nenhum dos parâmetros instance_id ou table for fornecido
Lança erro se instance_id estiver em formato inválido
Exemplos:
-- Consulta simples a uma tabela
local wql1 = wmi.buildwql(nil, "Win32_OperatingSystem", {"Caption", "Version", "BuildNumber"})
-- Resultado: "select Caption,Version,BuildNumber from Win32_OperatingSystem"

-- Consulta a uma instância específica
local wql2 = wmi.buildwql("Win32_Process|Name|explorer.exe", nil, {"ProcessId", "WorkingSetSize"})
-- Resultado: "select ProcessId,WorkingSetSize from Win32_Process where Name = \"explorer.exe\""

-- Consulta com múltiplos campos
local wql3 = wmi.buildwql(nil, "Win32_LogicalDisk", {"DeviceID", "Size", "FreeSpace", "FileSystem"})
-- Resultado: "select DeviceID,Size,FreeSpace,FileSystem from Win32_LogicalDisk"

2. wmi.exec(config, wql, namespace)
Executa uma consulta WMI usando o utilitário wmic
Parâmetros:

config (tabela): Configuração de conexão contendo:

net.address (string): Endereço IP ou hostname do alvo

wmi.username (string): Nome de usuário para autenticação

wmi.password (string): Senha para autenticação

wmi.timeout (número opcional, padrão: 10): Timeout em segundos

wql (string): Consulta WQL a ser executada

namespace (string opcional): Namespace WMI (padrão: "root\cimv2")
Retorno:

tabela: Array de resultados, onde cada elemento é uma tabela com pares campo-valor
Nota: Em vez de criar manualmente uma tabela de configuração, você pode usar a tabela global params que já contém todos os campos necessários (net.address, wmi.username, wmi.password, etc.). Esta tabela é automaticamente disponibilizada pelo sistema quando o script é executado no contexto de um dispositivo gerenciado.
Exemplo usando params:
-- A tabela 'device' já contém as credenciais e endereço do dispositivo alvo
local success, results = pcall(function()
 return wmi.exec(params, wql, "root\\cimv2")
end)

Exemplo prático:
-- Consulta simplificada usando a tabela device
local wql = "select Caption,Version from Win32_OperatingSystem"
local results = wmi.exec(device, wql)

-- Para consultas locais no próprio dispositivo
if device["net.address"] == "127.0.0.1" or device["net.address"] == "localhost" then
 -- Pode-se usar exec_native para melhor performance
 if wmi.exec_native then
 results = wmi.exec_native(device, wql)
 end
end

Exceções:
Lança erro se a conexão falhar
Lança erro "Timeout" se a consulta exceder o tempo limite
Lança erro se o utilitário wmic retornar código de erro
Exemplos:
-- Configuração básica
local config = {
 ["net.address"] = "192.168.1.100",
 ["wmi.username"] = "Administrator",
 ["wmi.password"] = "senha123",
 ["wmi.timeout"] = 15
}

-- Consulta informações do sistema operacional
local wql = "select Caption,Version,BuildNumber,OSArchitecture from Win32_OperatingSystem"
local success, results = pcall(function()
 return wmi.exec(config, wql, "root\\cimv2")
end)

if success then
 for _, row in ipairs(results) do
 print("Sistema: " .. row.Caption)
 print("Versão: " .. row.Version)
 print("Build: " .. row.BuildNumber)
 print("Arquitetura: " .. row.OSArchitecture)
 end
else
 print("Erro na consulta WMI: " .. results)
end

-- Consulta processos em execução
local process_wql = "select Name,ProcessId,WorkingSetSize,CommandLine from Win32_Process"
local process_results = wmi.exec(config, process_wql)

-- Consulta discos lógicos
local disk_wql = [[
select DeviceID,Size,FreeSpace,FileSystem
from Win32_LogicalDisk
where DriveType = 3
]]
local disk_results = wmi.exec(config, disk_wql, nil) -- namespace padrão

3. wmi.exec_native(config, wql, namespace) (Apenas no agente Windows)
Executa uma consulta WMI usando a API nativa do Windows (COM). Esta função está disponível apenas em sistemas Windows e oferece melhor performance e integração.
Parâmetros:

config (tabela): Configuração de conexão (ignorada na execução local)

wql (string): Consulta WQL a ser executada

namespace (string opcional): Namespace WMI
Retorno:

tabela: Array de resultados, onde cada elemento é uma tabela com pares campo-valor
Exceções:
Lança erro se a API COM falhar
Lança erro se a consulta for inválida
Exemplos:
-- Apenas funciona em Windows
if wmi.exec_native then
 -- Consulta local (config é ignorado)
 local config = nil -- Deixar vazio para consultas do agente
 local wql = "select Name,Manufacturer,Model from Win32_ComputerSystem"

 local success, results = pcall(function()
 return wmi.exec_native(config, wql)
 end)

 if success and #results > 0 then
 local computer = results[1]
 print("Computador: " .. computer.Name)
 print("Fabricante: " .. computer.Manufacturer)
 print("Modelo: " .. computer.Model)
 end
end

Informações Adicionais
1. Suporte Cross-Platform
A função exec usa o utilitário wmic que funciona em sistemas Linux
Permite consultar máquinas Windows remotamente
Esta funcionalidade é legada, pois versões mais recentes do Windows não permitem conexões WMI remotas.
2. Execução Nativa no Windows
A função exec_native oferece melhor performance em sistemas Windows
Não requer autenticação para consultas locais
Usa a API COM do Windows diretamente
3. Timeout Configurável
Timeout padrão de 10 segundos
Configurável via parâmetro wmi.timeout na configuração
Melhores Práticas
1. Otimização de Consultas
-- RUIM: Seleciona todas as colunas
local bad_wql = "select * from Win32_Process"

-- BOM: Seleciona apenas colunas necessárias
local good_wql = "select Name,ProcessId,WorkingSetSize from Win32_Process"

-- MELHOR: Adiciona filtros para reduzir resultados
local best_wql = [[
select Name,ProcessId,WorkingSetSize
from Win32_Process
where WorkingSetSize > 10485760 -- > 10MB
]]

4. wmi.exec(config, wql, namespace, replace_backslash)
Versão estendida da função exec com suporte a timeout e opção para substituir barras invertidas.
Parâmetros:

config (tabela): Configuração de conexão

wql (string): Consulta WQL a ser executada

namespace (string, opcional): Namespace WMI (usa wmi._namespace ou params.wmiNamespace se não especificado)

replace_backslash (booleano, opcional): Se true, substitui \ por \\ na WQL (padrão: true)
Retorno:

tabela: Resultados da consulta WMI
Comportamento:
Suporta execução via probe WMI quando params["wmi.type"] == 0

Para localhost (127.0.0.1), usa execução nativa
Exemplo de Uso:
-- Executar com timeout configurado
-- params.wmiTimeout = 10 (10 segundos)

local config = {
 address = "192.168.1.100",
 username = "administrator",
 password = "senha123"
}

local wql = "select Name, ProcessId, WorkingSetSize from Win32_Process"
local results = wmi.exec(config, wql, "root\\cimv2")

for _, process in ipairs(results) do
 print(string.format("Processo: %s (PID: %d, Memória: %d bytes)",
 process.Name, process.ProcessId, process.WorkingSetSize))
end

5. wmi.query(wmiobj, ...)
Consulta simplificada a uma tabela WMI sem instância específica.
Parâmetros:

wmiobj (string): Nome da tabela WMI

... (strings): Campos a serem selecionados (pode incluir namespace=...)
Retorno:

qualquer tipo: Valor único se apenas um campo for selecionado, tabela se múltiplos campos
Comportamento:
Constrói WQL automaticamente com wmi.buildwql

Armazena resultado internamente para uso com prev e lapsed

Suporta especificação de namespace via namespace= no início dos campos
Exemplo de Uso:
-- Consultar informações do sistema operacional
local os_name = wmi.query("Win32_OperatingSystem", "Caption")
print("Sistema Operacional:", os_name)

-- Consultar múltiplos campos
local disk_info = wmi.query("Win32_LogicalDisk", "DeviceID", "Size", "FreeSpace")
for _, disk in ipairs(disk_info) do
 local used_percent = 100 - (disk.FreeSpace / disk.Size * 100)
 print(string.format("Disco %s: %.1f%% usado", disk.DeviceID, used_percent))
end

-- Consultar com namespace específico
local cluster_info = wmi.query("MSCluster_Cluster", "namespace=root\\MSCluster", "Name", "State")

6. wmi.queryinst(...)
Consulta WMI para instância específica definida em params.InstanceId.
Parâmetros:

... (strings): Campos a serem selecionados (pode incluir namespace=...)
Retorno:

qualquer tipo: Valor único se apenas um campo for selecionado, tabela se múltiplos campos
Comportamento:
Usa params.InstanceId para construir consulta de instância
Lança erro se instância não for encontrada
Armazena resultado em _mem_store para uso com prev e lapsed

Exemplo de Uso:
-- params.InstanceId = "Win32_Process|Name|explorer.exe"

-- Consultar informações do processo explorer.exe
local pid = wmi.queryinst("ProcessId")
local memory = wmi.queryinst("WorkingSetSize")

print(string.format("Explorer.exe - PID: %d, Memória: %d bytes", pid, memory))

-- Consultar múltiplos campos
local process_info = wmi.queryinst("ProcessId", "WorkingSetSize", "ThreadCount", "Priority")

7. wmi.prev(wmiobj, ...)
Obtém o valor anterior de uma consulta WMI.
Parâmetros:

wmiobj (string): Nome da tabela WMI

... (strings): Campos da consulta original
Retorno:

qualquer tipo: Valor anterior armazenado
Comportamento:
Reconstrói a WQL original
Busca valor em store.get("wmi.value." .. wql)

Retorna valor único se consulta original retornou único valor
Exemplo de Uso:
-- Obter valor atual
local current_memory = wmi.query("Win32_OperatingSystem", "TotalVisibleMemorySize")

-- Obter valor anterior
local previous_memory = wmi.prev("Win32_OperatingSystem", "TotalVisibleMemorySize")

-- Calcular diferença
local memory_diff = current_memory - previous_memory
print("Variação de memória:", memory_diff, "bytes")

8. wmi.previnst(...)
Obtém o valor anterior de uma consulta WMI de instância.
Parâmetros:

... (strings): Campos da consulta original
Retorno:

qualquer tipo: Valor anterior armazenado
Exemplo de Uso:
-- params.InstanceId = "Win32_Process|Name|svchost.exe"

-- Obter uso atual de CPU
local current_cpu = wmi.queryinst("PercentProcessorTime")

-- Obter uso anterior
local previous_cpu = wmi.previnst("PercentProcessorTime")

-- Calcular variação
local cpu_change = current_cpu - previous_cpu
print("Variação no uso de CPU:", cpu_change, "%")

9. wmi.lapsed(wmiobj, ...)
Obtém o tempo decorrido desde a última consulta WMI.
Parâmetros:

wmiobj (string): Nome da tabela WMI

... (strings): Campos da consulta original
Retorno:

número: Tempo em segundos desde última consulta
Exemplo de Uso:
-- Calcular taxa de transferência de disco
local current_reads = wmi.query("Win32_PerfRawData_PerfDisk_LogicalDisk", "DiskReadBytesPerSec")
local previous_reads = wmi.prev("Win32_PerfRawData_PerfDisk_LogicalDisk", "DiskReadBytesPerSec")
local time_elapsed = wmi.lapsed("Win32_PerfRawData_PerfDisk_LogicalDisk", "DiskReadBytesPerSec")

local read_rate = (current_reads - previous_reads) / time_elapsed
print("Taxa de leitura de disco:", read_rate, "bytes/segundo")

10. wmi.lapsedinst(...)
Obtém o tempo decorrido desde a última consulta WMI de instância.
Parâmetros:

... (strings): Campos da consulta original
Retorno:

número: Tempo em segundos desde última consulta
Exemplo de Uso:
-- params.InstanceId = "Win32_PerfRawData_PerfDisk_LogicalDisk|Name|C:"

-- Calcular taxa de escrita para disco C:
local current_writes = wmi.queryinst("DiskWriteBytesPerSec")
local previous_writes = wmi.previnst("DiskWriteBytesPerSec")
local time_elapsed = wmi.lapsedinst("DiskWriteBytesPerSec")

local write_rate = (current_writes - previous_writes) / time_elapsed
print("Taxa de escrita no disco C:", write_rate, "bytes/segundo")

11. wmi.diff(typ, lhs, rhs)
Calcula a diferença entre dois valores WMI, tratando rollover de contadores.
Parâmetros:

typ (número): Tipo do contador (32 ou 64 bits)

lhs (número): Valor atual

rhs (número): Valor anterior
Retorno:

número: Diferença entre os valores
Comportamento:
Usa a mesma implementação que snmp.diff

Trata rollover de contadores de 32 e 64 bits
Sinaliza RepeatPrevValue se a diferença for negativa
Exemplo de Uso:
-- Calcular diferença para contador de 64 bits
local current_bytes = wmi.queryinst("DiskReadBytesPerSec")
local prev_bytes = wmi.previnst("DiskReadBytesPerSec")
local bytes_diff = wmi.diff(64, current_bytes, prev_bytes)

print("Bytes lidos desde última leitura:", bytes_diff)

Exemplos Completos
Monitoramento de Processo Específico:
-- Configurar instância para monitorar processo específico
-- params.InstanceId = "Win32_PerfRawData_PerfProc_Process|Name|chrome.exe"

-- Obter métricas atuais
local cpu_usage = wmi.queryinst("PercentProcessorTime")
local memory_usage = wmi.queryinst("WorkingSetPrivate")
local thread_count = wmi.queryinst("ThreadCount")

-- Calcular variações
local prev_cpu = wmi.previnst("PercentProcessorTime")
local prev_memory = wmi.previnst("WorkingSetPrivate")
local time_elapsed = wmi.lapsedinst("PercentProcessorTime")

local cpu_delta = wmi.diff(32, cpu_usage, prev_cpu)
local memory_delta = memory_usage - prev_memory

print(string.format("Chrome.exe - CPU: %d%%, Memória: %d bytes, Threads: %d",
 cpu_delta / time_elapsed, memory_delta, thread_count))

Inventário de Hardware com Cache:
-- Função para obter informações de hardware com cache
local function get_hardware_info()
 local cache_key = "hardware_info_" .. params.device.address
 local cached = cache.get(cache_key)

 if cached then
 return cached
 end

 -- Coletar informações diversas
 local hardware_info = {
 os = wmi.query("Win32_OperatingSystem", "Caption", "Version", "BuildNumber"),
 cpu = wmi.query("Win32_Processor", "Name", "NumberOfCores", "MaxClockSpeed"),
 memory = wmi.query("Win32_ComputerSystem", "TotalPhysicalMemory"),
 disks = wmi.query("Win32_LogicalDisk", "DeviceID", "Size", "FreeSpace", "FileSystem")
 }

 -- Armazenar em cache por 1 hora
 cache.put(cache_key, hardware_info, 3600)

 return hardware_info
end

-- Usar informações em cache
local info = get_hardware_info()
print("Sistema:", info.os.Caption, info.os.Version)
print("Processador:", info.cpu.Name, "(" .. info.cpu.NumberOfCores .. " núcleos)")
print("Memória total:", info.memory / (1024*1024*1024), "GB")