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 — 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.

Comandos

¹ 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 ./OffsetThreatScan.ps1 -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

Valores apenas numéricos sem prefixo ou sufixo são tratados intencionalmente como decimais.

Modos de codificação

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/HEAD/docs/THREAT-SCANNING.md) para o contrato do provedor e orientações de interpretação, [provider interface](https://github.com/warpedatom/offsetinspect/blob/HEAD/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/HEAD/docs/PROVENANCE.md) para limites de implementação e atribuição, e [output schema](https://github.com/warpedatom/offsetinspect/blob/HEAD/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 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 , exatamente como o pefile faz.

### 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 '^\sExample\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.
- Comprimentos de prefixo conhecidos como limpos e conhecidos como detectados.
- Limite de byte e caractere opcional.
- Estabilidade, confiança, contagem de verificações, status de limite repetidos e nome da assinatura quando disponível.
- Uma trilha de auditoria `ProbeLog` de cada sonda distinta do provedor (apresentada como `ProbeCount` na saída CSV e exportável como transcrição JSON com `-ProbeLogPath`); consulte [esquema de saída](https://github.com/warpedatom/offsetinspect/blob/HEAD/docs/OUTPUT-SCHEMA.md).
- Contexto aninhado `OffsetInspect.Result` no limite mapeado.

## Modelo de desempenho

A implementação no estilo v1 relia e decodificava um arquivo completo para cada deslocamento. A Versão 2 agrupa o trabalho por arquivo:```text
Previous approach: approximately O(file size × offset count)
Version 2:         approximately O(file bytes scanned once + requested windows)

O mapeamento de origem usa uma máquina de estados de streaming e retém apenas os descritores de linha anteriores/seguintes necessários para os offsets solicitados. Linhas individuais extremamente longas são exibidas através de uma pré-visualização limitada controlada por -MaxLineBytes.

Layout do repositório```text

OffsetInspect.ps1 Thin offset-inspection CLI wrapper OffsetThreatScan.ps1 Thin threat-scan CLI wrapper module/OffsetInspect/ Complete Gallery package OffsetInspect.psd1 OffsetInspect.psm1 OffsetInspect.Format.ps1xml Public/ Private/ tests/ Pester tests benchmarks/ Reproducible performance harness build/ Validation, packaging, signing, publishing .github/workflows/ CI, dependency review, release publishing docs/ Architecture, schemas, provider design, release checklist

## Desenvolvimento

Instale as ferramentas de validação fixadas:```powershell
Install-Module Pester -RequiredVersion 5.7.1 -Scope CurrentUser
Install-Module PSScriptAnalyzer -RequiredVersion 1.25.0 -Scope CurrentUser

Execute o gate local completo:```powershell ./build/Test-Module.ps1

Execute o harness de benchmark determinístico:```powershell
./benchmarks/Measure-OffsetInspect.ps1 -FileSizeMiB 64 -OffsetCount 5000

Os resultados de benchmark variam conforme o armazenamento, a carga do host, a edição do PowerShell e o formato do arquivo. Registre essas entradas ao comparar commits.

Crie um arquivo de versão determinístico e o arquivo SHA-256:```powershell ./build/New-ReleasePackage.ps1

CI valida PowerShell 7 no Windows e Linux, Windows PowerShell 5.1, PSScriptAnalyzer, empacotamento de módulo isolado e o arquivo de lançamento. Os mantenedores do lançamento também devem seguir a [lista de verificação de lançamento](https://github.com/warpedatom/offsetinspect/blob/HEAD/docs/RELEASE-CHECKLIST.md).

## Segurança e uso responsável

O OffsetInspect é destinado a pesquisa defensiva autorizada, engenharia de detecção, engenharia reversa, análise de malware e teste de segurança. As funções de provedor de ameaças analisam conteúdo, mas não desativam, contornam ou reconfiguram as proteções do endpoint.

`Invoke-OffsetMutationTest` gera variantes de evasão de detecção para avaliação de robustez de assinaturas. Opera inteiramente em memória (nenhuma variante é gravada em disco) e se recusa a executar sem o reconhecimento explícito de `-AuthorizedEngagement`. Use-o apenas contra amostras e controles que você está autorizado a testar.

Revise [SECURITY.md](https://github.com/warpedatom/offsetinspect/blob/HEAD/SECURITY.md) antes de relatar uma vulnerabilidade. Não envie amostras confidenciais por meio de problemas públicos do GitHub.

## Licença

O OffsetInspect é distribuído sob a [Licença MIT](https://github.com/warpedatom/offsetinspect/blob/HEAD/LICENSE).