Kit de ferramentas PowerShell para análise de fronteira de detecção AMSI/Defender e triagem estática de malware que mapeia offsets de bytes para gatilhos de detecção, além de análise YARA, entropia, strings e PE/imphash. Complemento do OffsetScan.
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/9991/ec3b617ff761b38a1eb9296df3d62b7435bcf1684421cce77108da0b7ac12e92.png" alt="Dread Host Research" width="800">
</p>
<p align="center">
<a href="https://github.com/warpedatom/OffsetInspect/releases"><img src="https://img.shields.io/github/v/release/warpedatom/OffsetInspect" alt="Release"></a>
<a href="https://github.com/warpedatom/offsetinspect/blob/main/LICENSE"><img src="https://img.shields.io/github/license/warpedatom/OffsetInspect" alt="License"></a>
<img src="https://img.shields.io/badge/PowerShell-5.1%20%7C%207.x-5391FE" alt="PowerShell 5.1 and 7.x">
<img src="https://img.shields.io/badge/Core-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey" alt="Cross-platform core">
<img src="https://img.shields.io/badge/Threat%20Providers-Windows-0078D4" alt="Windows threat providers">
<img src="https://img.shields.io/github/actions/workflow/status/warpedatom/OffsetInspect/ci.yml?branch=main&label=CI" alt="CI">
<a href="https://github.com/warpedatom/offsetinspect/blob/main/SECURITY.md"><img src="https://img.shields.io/badge/Security-Policy-green" alt="Security policy"></a>
<a href="https://x.com/warped_atom"><img src="https://img.shields.io/badge/X-@warped__atom-000000?logo=x&logoColor=white" alt="X (Twitter): @warped_atom"></a>
</p>
# OffsetInspect
**Um kit de ferramentas PowerShell com memória limitada para inspeção de deslocamento de bytes, correlação de código-fonte, comparação binária e análise defensiva de limites de detecção.**
O OffsetInspect responde a uma pergunta prática de analista:
> Que conteúdo está presente neste deslocamento de byte, e que contexto de origem ou binário o cerca?
Ele também fornece um fluxo de trabalho de limites de detecção nativo do OffsetInspect, inspirado no mesmo problema de analista abordado pelo ThreatCheck, sem incorporar seu código-fonte ou binários: ele localiza o prefixo de conteúdo mais antigo que o AMSI ou o Microsoft Defender ainda detecta, valida o limite repetidamente e alimenta o deslocamento resultante diretamente no inspetor de contexto. Além desse núcleo, ele adiciona uma suíte de análise de red team e triagem estática — descoberta de múltiplas regiões, varredura de corpus, diff de detecção, correlação de gatilhos de detecção, registro de drifts, relatórios de engajamento, análise de entropia, extração de strings e parsing de PE/imphash — tudo somente leitura, além de um testador de robustez de assinaturas para uso autorizado que perturba amostras apenas em memória, sem nunca desabilitar ou reconfigurar a proteção de endpoints.
## Ferramenta complementar
Para triagem estática em escala de corpus (parsing de PE, entropia, strings, IOC) sem
a sobrecarga do PowerShell, veja **[OffsetScan](https://github.com/warpedatom/OffsetScan)**
— um binário Rust nativo com o mesmo esquema de saída JSON. O OffsetInspect 3.1.0+
consome o JSON de IOC do OffsetScan diretamente via `-IocJsonPath`.
---
## Destaques
- Abre cada arquivo de inspeção único por meio de um handle de leitura estável e processa todos os deslocamentos solicitados em conjunto.
- Usa uma passagem de streaming com memória limitada para mapeamento de linhas, em vez de reler o arquivo completo para cada deslocamento.
- Lê apenas as janelas de bytes solicitadas para saída hexadecimal e comparação.
- Mapeia deslocamentos de bytes UTF-8 e UTF-16 para linhas de código-fonte e posições de caracteres.
- Implementa contexto de origem anterior e posterior por meio de `-ContextLines`.
- Suporta contratos de saída humana, objeto, JSON, CSV e arquivo CSV.
- Suporta planos de arquivo/deslocamento um-para-muitos, muitos-para-um e emparelhados.
- Compara o byte alvo com um segundo arquivo sem carregar esse arquivo repetidamente.
- Adiciona uma camada de provedores AMSI e Microsoft Defender implementada de forma independente, com estados explícitos de erro, tempo limite, bloqueio e indeterminado.
- Registra uma trilha de auditoria por sonda (`ProbeLog`/`ProbeCount`) de cada invocação distinta de provedor, transmitida ao vivo para `-Verbose`, para uma transcrição pronta para relatório do custo real de provedores de uma varredura.
- Descobre múltiplas regiões independentemente detectáveis em um arquivo por meio de varredura AMSI em memória (nada detectado é gravado em disco) e mapeia cada limite para um deslocamento absoluto.
- Varre um corpus em uma matriz de detecção consolidada, faz diff de detecção entre duas varreduras e exporta relatórios de engajamento em Markdown/HTML (opcionalmente alimentados pelo JSON do motor nativo OffsetScan para painéis de IOC em escala de corpus).
- Correlaciona um limite de detecção ao conteúdo que o produziu — a seção PE, a entropia do trecho até o limite e as strings que terminam nele ou o cruzam como conteúdo candidato de assinatura.
- Registra a detecção ao longo do tempo (hash do arquivo **e** a versão local da assinatura do Defender) para que uma mudança na detectabilidade possa ser atribuída ao arquivo, a uma atualização do banco de assinaturas ou a um resultado não determinístico do provedor.
- Testa a robustez de assinaturas para engajamentos autorizados ao perturbar uma amostra detectada **em memória** (maiúsculas/minúsculas, concatenação, comentário, espaços em branco) e relata quais classes de transformação evadem — nenhuma variante é gravada em disco.
- Correlaciona uma varredura com a telemetria do Windows que ela gera (`-CaptureTelemetry`): se um alerta do Microsoft Defender foi emitido, com qual contexto, e quais fontes de telemetria ficaram cegas — codificando o princípio "assuma visibilidade, depois valide-a". Somente leitura, sem administrador, somente Windows.
- Adiciona auxiliares estáticos de triagem de malware: entropia por janela (regiões empacotadas/criptografadas), extração de strings ASCII/UTF-16LE com deslocamentos e parsing de cabeçalho/seção/importações de PE com imphash e detecção de overlay.
- Verifica a proveniência Authenticode (`Get-OffsetSignature`): usando a validação de confiança real da plataforma, informa se um arquivo é validamente assinado e confiável, quem o assinou e se é assinado incorporado ou por catálogo — um sinal de assinante que complementa o imphash e a impressão digital da cadeia de ferramentas de build (importações vs cadeia de ferramentas vs assinante). Somente Windows.
- Nunca altera exclusões do Defender, proteção em tempo real ou configuração de segurança do sistema.
- É distribuído como um pacote autocontido da PowerShell Gallery, sem dependências externas de runtime; varredura YARA e ClamAV são as únicas exceções opcionais, cada uma exigindo seu próprio motor externo.
## Comandos
| Comando | Finalidade | Plataforma |
|---|---|---|
| `Invoke-OffsetInspect` | Mapeia deslocamentos de bytes para contexto de origem/binário, hexadecimal e comparação | Multiplataforma |
| `Invoke-OffsetThreatScan` | Busca de limites de detecção AMSI/Defender para um arquivo | Windows |
| `Invoke-OffsetThreatScanBatch` | Varre um corpus de arquivos; `-Summary` retorna uma matriz de detecção | Windows |
| `Invoke-OffsetThreatScanRegion` | Descoberta de múltiplas regiões via AMSI em memória (sem gravações em disco) | Windows |
| `Invoke-OffsetMutationTest` | Teste de robustez de assinatura: perturba uma amostra detectada em memória, informa quais transformações evadem (somente uso autorizado) | Windows |
| `Compare-OffsetThreatResult` | Faz diff de dois resultados de varredura (ex.: entre atualizações de definições de assinatura) | Multiplataforma |
| `Get-OffsetDetectionTrigger` | Correlaciona um limite de detecção ao conteúdo que mais provavelmente o acionou | Multiplataforma |
| `Add-OffsetDriftEntry` | Registra um instantâneo de detecção (hash do arquivo + versão da assinatura do Defender) em um diário | Multiplataforma² |
| `Get-OffsetDrift` | Explica como a detectabilidade de um arquivo mudou: mudança de arquivo vs atualização de assinatura vs não determinístico | Multiplataforma |
| `Export-OffsetThreatReport` | Renderiza resultados de varredura em um relatório de engajamento Markdown/HTML | Multiplataforma |
| `Invoke-OffsetYaraScan` | Compara um arquivo com regras YARA; retorna correspondências com deslocamentos de bytes | Multiplataforma¹ |
| `Invoke-OffsetClamScan` | Varre um arquivo com o motor ClamAV; resultado de detecção normalizado | Multiplataforma¹ |
| `Get-OffsetEntropy` | Entropia de Shannon por janela para localizar regiões empacotadas/criptografadas | Multiplataforma |
| `Get-OffsetString` | Extrai strings ASCII/UTF-16LE com deslocamentos de bytes | Multiplataforma |
| `Get-OffsetPEInfo` | Cabeçalhos PE, seções, importações/imphash, overlay, deslocamento→seção | Multiplataforma |
| `Get-OffsetIOC` | Painel consolidado de indicadores: hashes, entropia, PE/imphash, strings | Multiplataforma |
| `Get-OffsetSignature` | Assinatura Authenticode: se é validamente assinada e confiável, por quem, incorporada vs catálogo | Windows |
¹ Estes dois comandos têm dependências externas opcionais: `Invoke-OffsetYaraScan` precisa do motor YARA (`winget install VirusTotal.YARA`), e `Invoke-OffsetClamScan` precisa do ClamAV com bancos de assinaturas (`winget install Cisco.ClamAV` e depois `freshclam`). Todos os outros comandos são autocontidos. O ClamAV é um detector de arquivo único aqui, não um motor de busca de limites — `clamscan` carrega seu banco completo a cada invocação, então a bisseção exigiria o daemon `clamd`.
² `Add-OffsetDriftEntry` registra em diário de forma multiplataforma, mas os campos de versão do motor/assinatura do Defender são preenchidos apenas no Windows (via `Get-MpComputerStatus`); em outras plataformas eles são registrados como nulos e o restante do instantâneo ainda é gravado.
O núcleo de inspeção de deslocamentos e todos os auxiliares de triagem estática são multiplataforma (Windows, Linux, macOS); os provedores de ameaças AMSI/Defender são somente Windows.
## Instalação
### PowerShell Gallery```powershell
Install-Module OffsetInspect -Scope CurrentUser
Import-Module OffsetInspect
```
### Checkout do repositório```powershell
git clone https://github.com/warpedatom/OffsetInspect.git
cd OffsetInspect
Import-Module ./module/OffsetInspect/OffsetInspect.psd1 -Force
```
O repositório também inclui wrappers CLI leves:```powershell
./OffsetInspect.ps1 <file> <offset>
./OffsetThreatScan.ps1 <file> -Engine AMSI
```
## Inspeção de offset
### Saída legível por humanos```powershell
Invoke-OffsetInspect ./sample.bin 0x200
```
Você pode encontrar instruções detalhadas de uso na documentação oficial. Certifique-se de revisar os pré-requisitos e dependências antes da instalação. Para relatar problemas ou contribuir com o projeto, consulte as diretrizes de contribuição no repositório.
A comunidade mantém o projeto ativamente, com atualizações regulares e correções de bugs. Verifique a seção de releases para obter as versões mais recentes e notas de lançamento.```powershell
$inspectParameters = @{
FilePaths = './script.ps1'
OffsetInputs = 128, 256, 512
ByteWindow = 64
ContextLines = 4
}
Invoke-OffsetInspect @inspectParameters
```
### Objetos estruturados```powershell
$inspectParameters = @{
FilePaths = './script.ps1'
OffsetInputs = 0x80, 0x100
PassThru = $true
}
$results = Invoke-OffsetInspect @inspectParameters
$results | Where-Object BytesDiffer
```
### JSON e CSV```powershell
Invoke-OffsetInspect ./sample.bin 0x200 -Json
Invoke-OffsetInspect ./sample.bin 0x200 -Csv
Invoke-OffsetInspect ./sample.bin 0x200 -CsvPath ./artifacts/offsets.csv
```
O modo JSON sempre emite um array, inclusive para um único resultado.
### Comparação binária```powershell
$compareParameters = @{
FilePaths = './before.bin'
OffsetInputs = 0x200
CompareFile = './after.bin'
PassThru = $true
}
Invoke-OffsetInspect @compareParameters
```
### Formatos de deslocamento
| Entrada | Interpretação |
|---|---:|
| `512` | Decimal 512 |
| `0x200` ou `0X200` | Hexadecimal 0x200 |
| `200h` | Hexadecimal 0x200 |
| `E1AB1` | Hexadecimal sem prefixo porque contém A-F |
Valores apenas numéricos sem prefixo ou sufixo são tratados intencionalmente como decimais.
### Modos de codificação
| Modo | Comportamento |
|---|---|
| `Auto` | Detecta BOMs UTF-8/UTF-16; caso contrário, usa UTF-8 |
| `Default` | Usa a codificação padrão do sistema operacional host |
| `UTF8` | Mapeamento de origem UTF-8 |
| `UTF16LE` | Mapeamento de origem UTF-16 little-endian |
| `UTF16BE` | Mapeamento de origem UTF-16 big-endian |
| `ASCII` | Mapeamento de origem ASCII |
A saída relata tanto `BytePositionInLine` quanto `CharacterPosition`. Essa distinção é importante quando um arquivo de origem contém caracteres multibyte.
## Análise de limites de ameaças
A análise do provedor de ameaças é exclusiva do Windows. O comando normal de inspeção de deslocamento permanece multiplataforma.
### Verificação de texto AMSI```powershell
$scanParameters = @{
FilePath = './script.ps1'
Engine = 'AMSI'
ScanMode = 'Text'
RepeatCount = 3
PassThru = $true
}
$result = Invoke-OffsetThreatScan @scanParameters
```
O modo de texto usa `AmsiScanString`, pesquisa prefixos de escalares Unicode sem dividir pares substitutos, mapeia o prefixo detectado por meio da codificação de origem validada e retorna índices de escalares Unicode, unidades de código UTF-16 e bytes do arquivo de origem. Caracteres NUL incorporados são rejeitados no modo de texto; use o modo de bytes brutos para esses arquivos.
### Varredura de bytes brutos da AMSI```powershell
Invoke-OffsetThreatScan ./content.bin -Engine AMSI -ScanMode RawBytes
```
### Verificação do Microsoft Defender```powershell
$scanParameters = @{
FilePath = './sample.bin'
Engine = 'Defender'
RepeatCount = 3
TimeoutSeconds = 45
}
Invoke-OffsetThreatScan @scanParameters
```
O provedor Defender:
- Resolve o caminho da plataforma do `MpCmdRun.exe` mais recentemente instalado.
- Grava prefixos em um diretório temporário exclusivo do usuário.
- Usa uma verificação personalizada com `-DisableRemediation`.
- Trata timeouts, erros do provedor, saída localizada/desconhecida e marcadores ambíguos como não definitivos.
- Exclui o espaço de trabalho temporário quando a verificação é concluída.
### Semântica de limite
Um resultado como `DetectionPrefixLength = 841` significa:
- O comprimento do prefixo 840 foi classificado como limpo/não detectado.
- O comprimento do prefixo 841 foi classificado como detectado/bloqueado.
- Verificações repetidas determinam se essa transição é estável.
Isso **não** prova que o byte 840 é a assinatura completa, o único byte contribuinte ou o intervalo malicioso completo. As decisões do antivírus podem depender de tokenização, contexto ao redor, tipo de arquivo, estado do provedor e atualizações de assinatura.
### Exemplo prático: dois mecanismos, um arquivo
Analisar a mesma amostra (PowerUp.ps1, um script público de red team, 445.954 bytes) com ambos os provedores mostra o que é um limite e até que ponto dois mecanismos podem ser considerados confiáveis para concordar. AMSI em modo texto:```text
Threat boundary scan: C:\Ops\Samples\PowerUp.ps1
SHA-256: 7abc87d9620aef493617a4fc1f823850f32fb26ca9ae0f3befeadb04971e0246
Engine: AMSI
Scan mode: Text
Initial status: Detected
Scans performed: 25
Provider probes: 25 (see -Verbose or the ProbeLog property for the full audit trail)
Duration: 22771.419 ms
Known clean prefix: 445953
Detected prefix: 445954
Boundary offset: 445953 (0x6CE01)
Unicode scalar index: 445953
UTF-16 code-unit idx: 445953
Stable: True
Confidence: High
Line number: 4586
Byte in line: 46
Target byte: 0A (10)
--- Source Context ---
4585 | Set-Alias Get-CurrentUserTokenGroupSid Get-ProcessTokenGroup
4586 | Set-Alias Invoke-AllChecks Invoke-PrivescAudit
^
```
Microsoft Defender em modo de bytes brutos, mesmo arquivo:```text
Engine: Defender
Scan mode: RawBytes
Initial status: Detected
Scans performed: 25
Duration: 15370.562 ms
Known clean prefix: 445951
Detected prefix: 445952
Boundary offset: 445951 (0x6CDFF)
Stable: True
Confidence: High
Signature: Trojan:Win32/Kepavll!rfn
Line number: 4586
Byte in line: 44
Target byte: 69 (105)
--- Hex Dump ---
0006CDBF 74 2D 50 72 6F 63 65 73 73 54 6F 6B 65 6E 47 72 t-ProcessTokenGr
0006CDCF 6F 75 70 0A 53 65 74 2D 41 6C 69 61 73 20 49 6E oup.Set-Alias In
0006CDDF 76 6F 6B 65 2D 41 6C 6C 43 68 65 63 6B 73 20 49 voke-AllChecks I
0006CDEF 6E 76 6F 6B 65 2D 50 72 69 76 65 73 63 41 75 64 nvoke-PrivescAud
0006CDFF 69 74 0A it.
```
Ambos os motores convergem na **linha 4586** - o limite do Defender cai dentro do `it` final de `Invoke-PrivescAudit`, o da AMSI na nova linha que termina a mesma linha, dois bytes depois. Nenhum dos deslocamentos é "a assinatura": eles são o prefixo mais antigo que cada provedor ainda sinalizou, e a divergência de dois bytes é exatamente o efeito de tokenização/contexto descrito acima. O Defender adicionalmente nomeia o que correspondeu (`Trojan:Win32/Kepavll!rfn`); a AMSI não reporta nome de assinatura, e é por isso que `Invoke-OffsetThreatScanRegion` e `Get-OffsetDetectionTrigger` existem para caracterizar uma detecção da AMSI.
Ambas as varreduras custam 25 sondagens de provedor para um arquivo de ~436 KiB - a bissecção é logarítmica no tamanho do arquivo, e cada sondagem é registrada em `ProbeLog`.
Consulte [Threat scanning design](https://github.com/warpedatom/offsetinspect/blob/main/docs/THREAT-SCANNING.md) para o contrato do provedor e orientações de interpretação, [provider interface](https://github.com/warpedatom/offsetinspect/blob/main/docs/PROVIDER-INTERFACE.md) para o contrato do scanner e como adicionar um provedor sem tocar no núcleo de busca, [threat-scanning provenance](https://github.com/warpedatom/offsetinspect/blob/main/docs/PROVENANCE.md) para limites de implementação e atribuição, e [output schema](https://github.com/warpedatom/offsetinspect/blob/main/docs/OUTPUT-SCHEMA.md) para o contrato de objeto versionado.
### Relatórios de limite de detecção
`Export-OffsetThreatReport` transforma um ou mais resultados de varredura em um relatório Markdown ou HTML autocontido - resumo por arquivo, metadados de provedor/assinatura/mecanismo, a trilha de auditoria completa do `ProbeLog` e avisos - para anexar a um relatório de engajamento. Ele lê apenas resultados e nunca re-varre, portanto é executado de forma multiplataforma. Adicione `-IncludeIoc` para incorporar um painel de indicadores hash/entropia/PE (os mesmos dados de `Get-OffsetIOC`) em cada entrada do relatório, e `-IncludeTrigger` para adicionar uma análise de gatilho de detecção (veja abaixo) para cada resultado com um limite.```powershell
Invoke-OffsetThreatScan ./sample.ps1 -Engine AMSI -ScanMode Text -PassThru |
Export-OffsetThreatReport -Path ./report.html -Format Html
# Aggregate many scans into one report, with an indicators panel and trigger analysis per file:
$results | Export-OffsetThreatReport -Path ./engagement.md -IncludeIoc -IncludeTrigger
```
Para relatórios em escala de corpus, `-IncludeIoc` re-escaneia cada arquivo no PowerShell, o que é lento. O mecanismo nativo complementar [OffsetScan](https://github.com/warpedatom/OffsetScan) emite JSON de IOC com esquema idêntico muito mais rápido; aponte o relatório para ele com `-IocJsonPath` e ele obtém cada painel desse JSON (recorrendo a um `Get-OffsetIOC` ao vivo apenas para arquivos ausentes dele):```powershell
offsetscan ioc ./corpus --recurse > ./ioc.json
$results | Export-OffsetThreatReport -Path ./engagement.md -IocJsonPath ./ioc.json
```
### Digitalização em lote / corpus
`Invoke-OffsetThreatScanBatch` expande arquivos, diretórios e curingas em uma lista de arquivos, examina cada um (continuando além de falhas por arquivo) e retorna um resultado por arquivo. `-Summary` retorna uma matriz de detecção achatada; os resultados completos são direcionados diretamente para o gerador de relatórios. A varredura de provedores é somente Windows.```powershell
Invoke-OffsetThreatScanBatch ./payloads -Recurse -Engine AMSI |
Export-OffsetThreatReport -Path ./engagement.html -Format Html
Invoke-OffsetThreatScanBatch ./samples -Summary |
Format-Table File, DetectionPrefixLength, Confidence, ProbeCount
```
### Diff de detecção / regressão
`Compare-OffsetThreatResult` compara dois resultados de varredura - por exemplo, o mesmo arquivo antes e depois de uma atualização da definição de assinatura - e classifica a mudança (`NewlyDetected`, `NoLongerDetected`, `BoundaryEarlier`, `BoundaryLater`, `BoundaryUnchanged`, `BothClean`) com o delta de limite e os campos alterados.```powershell
$before = Invoke-OffsetThreatScan ./sample.ps1 -Engine Defender -PassThru
# ... update Defender signature definitions ...
$after = Invoke-OffsetThreatScan ./sample.ps1 -Engine Defender -PassThru
Compare-OffsetThreatResult -Reference $before -Difference $after
```
### Descoberta de múltiplas regiões
A pesquisa por prefixo encontra o *primeiro* limite de detecção. `Invoke-OffsetThreatScanRegion` encontra *múltiplas* regiões independentemente detectáveis ao dividir o arquivo em segmentos e analisar cada um isoladamente por meio do AMSI **inteiramente em memória** - nada do que é detectado é gravado em disco, portanto a proteção em tempo real do Defender nunca é acionada ou reconfigurada. Cada detecção é dividida ao meio dentro do seu segmento para mapear o limite exato de acionamento para um deslocamento absoluto do arquivo.```powershell
Invoke-OffsetThreatScanRegion ./payload.bin -SegmentCount 16 |
Select-Object -ExpandProperty DetectedRegions |
Format-Table SegmentIndex, StartOffset, EndOffset, AbsoluteBoundaryOffset, SignatureName
```
Isso relata regiões que disparam por conta própria; pode perder assinaturas que só disparam no contexto do arquivo inteiro ou que cruzam um limite de segmento, portanto trate as regiões como pistas para confirmar com `Invoke-OffsetThreatScan` e validação manual. AMSI (em memória) é o único mecanismo suportado aqui - a verificação de arquivos do Defender exigiria gravar o conteúdo detectado em disco.
### Correlação de gatilho de detecção
Um limite informa *onde* a detecção muda; `Get-OffsetDetectionTrigger` informa *o que* está lá. Como um limite de prefixo é o último byte do primeiro prefixo detectado, o conteúdo acionador é uma sequência que termina nesse deslocamento. O comando informa a seção PE em que o limite se encontra, a entropia da sequência até ele (texto simples vs empacotado/codificado) e as strings extraídas que terminam nele ou o cruzam, classificadas por proximidade - o conteúdo candidato de assinatura - com uma interpretação de uma linha. Ele lê apenas bytes e nunca reescaneia, portanto é executado multiplataforma em resultados salvos.```powershell
Invoke-OffsetThreatScan ./flagged.ps1 -Engine AMSI -PassThru | Get-OffsetDetectionTrigger
# Or point it at a file and a known boundary directly:
Get-OffsetDetectionTrigger -FilePath ./sample.bin -BoundaryOffset 0x4A1 |
Select-Object Interpretation, Section, PreBoundaryEntropy -ExpandProperty CandidateStrings
```
### Diário de drift de detecção
"Foi detectado antes e agora não é" tem três causas muito diferentes: o arquivo mudou, as assinaturas mudaram ou o provedor é não determinístico. `Add-OffsetDriftEntry` registra snapshots NDJSON somente de acréscimo - SHA-256 do arquivo, status, limite, nome da assinatura e as versões locais da assinatura/mecanismo do Defender - e `Get-OffsetDrift` lê esse histórico e atribui cada mudança à causa correta.```powershell
# Record a snapshot over time (from a scan result, or directly):
Invoke-OffsetThreatScan ./sample.ps1 -Engine AMSI -PassThru | Add-OffsetDriftEntry
Add-OffsetDriftEntry -FilePath ./sample.ps1 -Status Detected -Engine AMSI -SignatureName 'Trojan:PowerShell/X'
# Later, explain what changed:
Get-OffsetDrift -FilePath ./sample.ps1 | Select-Object -ExpandProperty Transitions
```
Cada transição é rotulada: uma alteração de SHA-256 é lida como uma **modificação de arquivo**; uma alteração de status com o arquivo inalterado, mas a versão da assinatura do Defender movida, é lida como **deriva de assinatura**; uma alteração de status sem nenhum dos dois é lida como um resultado de provedor **não determinístico**. O diário usa como padrão `%LOCALAPPDATA%\OffsetInspect\drift.ndjson`; substitua-o com `-JournalPath`.
### Teste de robustez de assinatura (somente uso autorizado)
`Invoke-OffsetMutationTest` responde a uma questão de engenharia de detecção: uma assinatura é uma correspondência literal exata e frágil, ou é robusta a ofuscação comum? Dada uma amostra que o AMSI detecta atualmente, ela aplica perturbações padrão — inversão de caixa, concatenação de literais de string, inserção de comentários, injeção de espaços em branco — e reexamina cada variante para relatar quais classes neutralizam a detecção. **Tudo acontece em memória** por meio da interface em processo do AMSI; nenhuma variante é gravada em disco, portanto nenhum artefato evasivo é produzido e a proteção em tempo real do Defender não é envolvida. O comando se recusa a ser executado sem `-AuthorizedEngagement` e destina-se somente a amostras que você está autorizado a testar.```powershell
Invoke-OffsetMutationTest -FilePath ./flagged.ps1 -AuthorizedEngagement |
Select-Object RobustnessSummary -ExpandProperty Results
```
Um resultado de, digamos, "brittle: neutralized by StringConcatenation, CommentInsertion" diz a um defensor que a assinatura se baseia em um literal contíguo e deve ser ampliada; diz a um operador autorizado o mesmo sobre a cobertura de um controle.
### Correlação de telemetria
Detectar uma fronteira diz o que o *mecanismo* vê; `-CaptureTelemetry` diz o que o *defensor* vê. Ele registra o high-water mark de cada log de telemetria do Windows acessível antes da varredura e então relata se a ação gerou um alerta, com qual contexto, e quais fontes estavam cegas - a pergunta "assuma visibilidade, depois valide-a", respondida com evidências.```powershell
$r = Invoke-OffsetThreatScan ./flagged.ps1 -Engine AMSI -CaptureTelemetry -PassThru
$r.Telemetry | Format-List AlertGenerated, CorrelationConfidence, Findings
$r.Telemetry.Alert | Format-List ThreatName, SeverityName, SourceName, ProcessName, DetectionUser
```
A propriedade `Telemetry` (`OffsetInspect.TelemetryCorrelation`) relata:
- `AlertGenerated` / `Alert` - se uma detecção do Microsoft Defender (evento 1116/1117) foi registrada para o escaneamento, e seu contexto (nome da ameaça, gravidade, fonte de detecção, processo, usuário).
- `CorrelationConfidence` - **Alta** somente quando a fonte da detecção corresponde ao provedor **e** seu processo corresponde ao host de escaneamento, de modo que uma detecção concorrente coincidente nunca seja alegada; Média apenas com base na fonte; Baixa com nenhuma das duas.
- `SourcesAccessible` / `SourcesUnavailable` - quais logs de telemetria estavam legíveis e quais estavam cegos (Sysmon ausente, log de Segurança exigindo elevação). Uma lacuna de visibilidade é por si só uma descoberta.
- `Findings` - conclusões em linguagem simples: um alerta com contexto completo, um alerta sem nome de ameaça, nenhuma telemetria, ou uma fonte ausente.
A fonte primária é o log Operacional do Microsoft Defender, legível sem elevação; a correlação é pelo `RecordId` do evento (monótono e independente de fuso horário). Somente Windows, e inerte a menos que `-CaptureTelemetry` seja passado.
## Auxiliares de triagem estática
Três comandos de análise estática multiplataforma auxiliam na triagem de malware e compõem com o núcleo de offset:
- `Get-OffsetEntropy` - entropia de Shannon por janela (bits/byte) para localizar regiões empacotadas ou criptografadas; cruze as janelas sinalizadas com as detecções de `Invoke-OffsetThreatScanRegion`.
- `Get-OffsetString` - strings ASCII imprimíveis e UTF-16LE com offsets de byte; canalize offsets para `Invoke-OffsetInspect` para contexto.
- `Get-OffsetPEInfo` - máquina/bitness do PE, ponto de entrada, tabela de seções, **imports e imphash**, detecção de **overlay** anexado, e tamanho dos recursos, com `-Offset` mapeando um offset de byte para sua seção (`.text`, `.rsrc`, ...). O imphash usa o MD5 padrão `library.function` e é verificado como byte idêntico ao pefile/VirusTotal - incluindo resolução de ordinais de bibliotecas especiais, de modo que um ordinal importado de `ws2_32`/`wsock32`/`oleaut32` resolve para seu nome de função real; qualquer outro import ordinal renderiza `ordNNN`, exatamente como o pefile faz.
- `Get-OffsetIOC` - painel de indicadores em uma única execução combinando o acima: MD5/SHA-1/SHA-256 (em uma única passada), entropia geral, contagem de strings imprimíveis e máquina do PE/imphash/overlay quando aplicável.```powershell
Get-OffsetEntropy ./sample.bin -HighOnly | Select-Object -ExpandProperty Windows
Get-OffsetString ./sample.bin -MinimumLength 6 | Where-Object Value -match 'http|\.dll'
Get-OffsetPEInfo ./sample.exe | Select-Object Machine, EntryPointHex, ImpHash, ImportedDllCount, HasOverlay, OverlaySize
Get-OffsetIOC ./sample.exe | Format-List
```
### Varredura YARA
`Invoke-OffsetYaraScan` executa regras YARA criadas por analistas e retorna cada correspondência com seu offset de bytes - complementando a visão do limite de detecção do AMSI/Defender com assinaturas que você controla, e sem precisar de antivírus instalado (apenas o mecanismo YARA, ex.: `winget install VirusTotal.YARA`). Os offsets alimentam diretamente o inspetor.```powershell
Invoke-OffsetYaraScan ./sample.bin -RulePath ./rules/malware.yar |
ForEach-Object { Invoke-OffsetInspect $_.File $_.Offset -ContextLines 2 }
```
### Verificação com ClamAV
O `Invoke-OffsetClamScan` verifica um arquivo com o mecanismo on-demand do ClamAV e retorna um resultado normalizado (`Clean` / `Detected` / `Error`, além do nome da assinatura). Como o `clamscan` carrega todo o banco de assinaturas a cada chamada, ele é um detector de arquivo único, não um mecanismo de busca de limites (isso exigiria o daemon `clamd`). É necessário ter o ClamAV instalado **e** os bancos de assinaturas baixados — o `freshclam` não será executado até que um arquivo de configuração exista:```powershell
# One-time setup: create the freshclam config (remove the sample's "Example" line), then fetch databases.
Copy-Item "$env:ProgramFiles\ClamAV\conf_examples\freshclam.conf.sample" "$env:ProgramFiles\ClamAV\freshclam.conf"
(Get-Content "$env:ProgramFiles\ClamAV\freshclam.conf") -notmatch '^\s*Example\s*$' |
Set-Content "$env:ProgramFiles\ClamAV\freshclam.conf" # requires admin to write under Program Files
& "$env:ProgramFiles\ClamAV\freshclam.exe"
Invoke-OffsetClamScan ./sample.bin
```
Use `-DatabasePath` para apontar para um diretório de assinaturas em um local gravável (não administrador), e `-ClamScanPath` se `clamscan` não estiver no `PATH`.
## Objetos de resultado
`Invoke-OffsetInspect -PassThru` retorna objetos `OffsetInspect.Result` contendo:
- Caminho canônico do arquivo, tamanho do arquivo, deslocamentos decimal e hexadecimal.
- Codificação solicitada e detectada.
- Número da linha, pré-visualização da fonte, linhas de contexto, posição de byte e posição de caractere.
- Byte alvo e dump hexadecimal limitado.
- Byte de comparação opcional e estado de diferença.
- Avisos, duração, estado de sucesso e mensagem de erro.
`Invoke-OffsetThreatScan -PassThru` retorna objetos `OffsetInspect.ThreatScanResult` contendo:
- SHA-256 do arquivo, carimbo de data/hora da verificação em UTC, mecanismo, modo de verificação, status inicial do provedor e metadados do provedor.
```
---
[Read more](https://github.com/warpedatom/offsetinspect)