OffsetInspect

Un toolkit PowerShell a memoria limitata per l'ispezione di offset di byte, la correlazione delle sorgenti, il confronto binario e l'analisi dei confini di rilevamento difensivi.

OffsetInspect risponde a una domanda pratica dell'analista:

Quale contenuto è presente a questo offset di byte e quale contesto di origine o binario lo circonda?

Fornisce inoltre un flusso di lavoro nativo OffsetInspect per i confini di rilevamento, ispirato allo stesso problema analitico affrontato da ThreatCheck, senza includerne il codice sorgente o i binari: individua il prefisso di contenuto più antico che AMSI o Microsoft Defender rileva ancora, convalida ripetutamente il confine e inserisce l'offset risultante direttamente nell'ispettore di contesto. Oltre a questo nucleo, aggiunge una suite di analisi red-team e triage statico: scoperta multi-regione, scansione del corpus, diffing delle rilevazioni, correlazione dei trigger di rilevamento, journaling del drift, report di engagement, analisi dell'entropia, estrazione delle stringhe e parsing PE/imphash - tutto in sola lettura, più un tester di robustezza delle firme per uso autorizzato che perturba i campioni solo in memoria, senza mai disabilitare o riconfigurare la protezione degli endpoint.

Strumento complementare

Per il triage statico su scala di corpus (parsing PE, entropia, stringhe, IOC) senza overhead PowerShell, vedi OffsetScan - un binario Rust nativo con lo stesso schema di output JSON. OffsetInspect 3.1.0+ ingerisce il JSON IOC di OffsetScan direttamente tramite -IocJsonPath.

Punti salienti

• Apre ogni file di ispezione unico tramite un handle di lettura stabile ed elabora tutti gli offset richiesti insieme.
• Utilizza un passaggio di streaming a memoria limitata per il mapping delle righe invece di rileggere l'intero file per ogni offset.
• Legge solo le finestre di byte richieste per l'output esadecimale e il confronto.
• Mappa gli offset di byte UTF-8 e UTF-16 alle righe di origine e alle posizioni dei caratteri.
• Implementa il contesto di origine precedente e successivo tramite -ContextLines.
• Supporta formati di output umano, oggetto, JSON, CSV e file CSV.
• Supporta piani file/offset uno-a-molti, molti-a-uno e accoppiati.
• Confronta il byte target con un secondo file senza caricare ripetutamente quel file.
• Aggiunge un livello provider AMSI e Microsoft Defender implementato indipendentemente con stati espliciti di errore, timeout, bloccato e indeterminato.
• Registra una traccia di audit per-sonda (ProbeLog/ProbeCount) di ogni invocazione distinta del provider, trasmessa in tempo reale a -Verbose, per una trascrizione pronta per il report del costo reale del provider di una scansione.
• Scopre più regioni indipendentemente rilevabili in un file tramite scansione AMSI in memoria (nulla di rilevato viene scritto su disco) e mappa ogni confine a un offset assoluto.
• Scansiona un corpus in una matrice di rilevamento consolidata, confronta le rilevazioni tra due scansioni ed esporta report di engagement in Markdown/HTML (alimentati opzionalmente dal JSON del motore OffsetScan nativo per pannelli IOC su scala di corpus).
• Correla un confine di rilevamento al contenuto che lo ha prodotto: la sezione PE, l'entropia del tratto fino al confine e le stringhe che terminano al confine o lo attraversano come contenuto candidato per la firma.
• Registra le rilevazioni nel tempo (hash del file e versione della firma Defender locale) in modo che un cambiamento nella rilevabilità possa essere attribuito al file, a un aggiornamento del database delle firme o a un risultato non deterministico del provider.
• Testa la robustezza delle firme per engagement autorizzati perturbando un campione rilevato in memoria (maiuscole/minuscole, concatenazione, commento, spazi bianchi) e riportando quali classi di trasformazione eludono - nessuna variante viene mai scritta su disco.
• Correla una scansione con la telemetria Windows che genera (-CaptureTelemetry): se è stato generato un avviso di Microsoft Defender, con quale contesto e quali fonti di telemetria sono state cieche - codificando il principio "assumi visibilità, poi validala". Sola lettura, non amministratore, solo Windows.
• Aggiunge helper di triage statico del malware: entropia per finestra (regioni impacchettate/crittografate), estrazione di stringhe ASCII/UTF-16LE con offset e parsing di header/sezioni/import PE con imphash e rilevamento overlay.
• Verifica la provenienza Authenticode (Get-OffsetSignature): utilizzando la reale convalida della fiducia della piattaforma, segnala se un file è firmato validamente e attendibile, chi lo ha firmato e se è firmato embedded o catalog - un segnale del firmatario che completa l'imphash e l'impronta della toolchain di build (import vs toolchain vs firmatario). Solo Windows.
• Non modifica mai le esclusioni di Defender, la protezione in tempo reale o la configurazione di sicurezza del sistema.
• Viene fornito come pacchetto PowerShell Gallery autonomo senza dipendenze runtime esterne; la scansione YARA e ClamAV sono le uniche eccezioni opzionali, ciascuna richiede il proprio motore esterno.

Comandi

¹ Questi due comandi hanno dipendenze esterne opzionali: Invoke-OffsetYaraScan necessita del motore YARA (winget install VirusTotal.YARA), e Invoke-OffsetClamScan necessita di ClamAV con i database delle firme (winget install Cisco.ClamAV, poi freshclam). Ogni altro comando è autonomo. ClamAV è qui un rilevatore a file singolo, non un motore di ricerca dei confini - clamscan carica l'intero database per ogni invocazione, quindi la bisezione richiederebbe il demone clamd.

² Add-OffsetDriftEntry registra su più piattaforme, ma i campi della versione della firma/motore Defender si popolano solo su Windows (tramite Get-MpComputerStatus); altrove vengono registrati come null e il resto dell'istantanea viene comunque scritto.

Il nucleo di ispezione degli offset e tutti gli helper di triage statico sono multipiattaforma (Windows, Linux, macOS); i provider di minacce AMSI/Defender sono solo Windows.

Installazione

PowerShell Gallery```powershell

Install-Module OffsetInspect -Scope CurrentUser Import-Module OffsetInspect

### Checkout del repository```powershell
git clone https://github.com/warpedatom/OffsetInspect.git
cd OffsetInspect
Import-Module ./module/OffsetInspect/OffsetInspect.psd1 -Force

Il repository include anche dei thin CLI wrappers:```powershell ./OffsetInspect.ps1 ./OffsetThreatScan.ps1 -Engine AMSI

## Ispezione degli offset

### Output leggibile dall'uomo```powershell
Invoke-OffsetInspect ./sample.bin 0x200

CONTENUTO:```powershell $inspectParameters = @{ FilePaths = './script.ps1' OffsetInputs = 128, 256, 512 ByteWindow = 64 ContextLines = 4 } Invoke-OffsetInspect @inspectParameters

### Oggetti strutturati```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

JSON mode emette sempre un array, anche per un singolo risultato.

### Confronto binario```powershell
$compareParameters = @{
    FilePaths    = './before.bin'
    OffsetInputs = 0x200
    CompareFile  = './after.bin'
    PassThru     = $true
}
Invoke-OffsetInspect @compareParameters

Formati degli offset

I valori puramente numerici senza prefisso o suffisso sono intenzionalmente trattati come decimali.

Modalità di codifica

Il report mostra sia BytePositionInLine che CharacterPosition. Questa distinzione è importante quando un file sorgente contiene caratteri multibyte.

Analisi dei confini delle minacce

L'analisi Threat-provider è solo per Windows. Il normale comando di ispezione degli offset rimane multipiattaforma.

AMSI text scan```powershell

$scanParameters = @{ FilePath = './script.ps1' Engine = 'AMSI' ScanMode = 'Text' RepeatCount = 3 PassThru = $true } $result = Invoke-OffsetThreatScan @scanParameters

La modalità testo utilizza `AmsiScanString`, cerca prefissi di scalar Unicode senza dividere coppie di surrogate, mappa il prefisso rilevato attraverso la codifica sorgente convalidata e restituisce indici di scalar Unicode, code-unit UTF-16 e byte del file sorgente. I caratteri NUL incorporati vengono rifiutati in modalità testo; usa la modalità raw-byte per quei file.

### Scansione raw-byte AMSI```powershell
Invoke-OffsetThreatScan ./content.bin -Engine AMSI -ScanMode RawBytes

Scansione di Microsoft Defender```powershell

$scanParameters = @{ FilePath = './sample.bin' Engine = 'Defender' RepeatCount = 3 TimeoutSeconds = 45 } Invoke-OffsetThreatScan @scanParameters

Il provider Defender:

- Risolve il percorso della piattaforma `MpCmdRun.exe` più recente installato.
- Scrive i prefissi in una directory temporanea utente unica.
- Utilizza una scansione personalizzata con `-DisableRemediation`.
- Considera timeout, errori del provider, output localizzato/sconosciuto e marcatori ambigui come non definitivi.
- Elimina l'area di lavoro temporanea al termine della scansione.

### Semantica dei confini

Un risultato come `DetectionPrefixLength = 841` significa:

- La lunghezza del prefisso 840 è stata classificata come pulita/non rilevata.
- La lunghezza del prefisso 841 è stata classificata come rilevata/bloccata.
- Controlli ripetuti determinano se quella transizione è stabile.

Non **prova** che il byte 840 sia la firma completa, l'unico byte contribuente o l'intero intervallo dannoso. Le decisioni dell'antivirus possono dipendere dalla tokenizzazione, dal contesto circostante, dal tipo di file, dallo stato del provider e dagli aggiornamenti delle firme.

### Esempio pratico: due motori, un file

La scansione dello stesso campione (PowerUp.ps1, uno script pubblico di red team, 445,954 byte) con entrambi i provider mostra cos'è un confine e fino a che punto ci si può fidare che due motori concordino. AMSI in modalità testo:```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 in modalità raw-byte, stesso file:```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.

Entrambi i motori convergono sulla **linea 4586** - il confine di Defender cade all'interno del `it` finale di `Invoke-PrivescAudit`, quello di AMSI sulla nuova riga che termina la stessa linea, due byte dopo. Nessuno dei due offset è "la firma": sono il prefisso più precoce che ciascun provider ha ancora segnalato, e il disaccordo di due byte è esattamente l'effetto di tokenizzazione/contesto descritto sopra. Defender inoltre nomina ciò che ha rilevato (`Trojan:Win32/Kepavll!rfn`); AMSI non riporta alcun nome di firma, motivo per cui `Invoke-OffsetThreatScanRegion` e `Get-OffsetDetectionTrigger` esistono per caratterizzare un hit di AMSI.

Entrambe le scansioni costano 25 sonde di provider per un file di ~436 KiB - la bisezione è logaritmica nella dimensione del file, e ogni sonda è registrata in `ProbeLog`.

Vedere [Threat scanning design](https://github.com/warpedatom/offsetinspect/blob/HEAD/docs/THREAT-SCANNING.md) per il contratto del provider e le linee guida di interpretazione, [provider interface](https://github.com/warpedatom/offsetinspect/blob/HEAD/docs/PROVIDER-INTERFACE.md) per il contratto dello scanner e come aggiungere un provider senza toccare il core di ricerca, [threat-scanning provenance](https://github.com/warpedatom/offsetinspect/blob/HEAD/docs/PROVENANCE.md) per i confini di implementazione e l'attribuzione, e [output schema](https://github.com/warpedatom/offsetinspect/blob/HEAD/docs/OUTPUT-SCHEMA.md) per il contratto dell'oggetto versionato.

### Report dei confini di rilevamento

`Export-OffsetThreatReport` trasforma uno o più risultati di scansione in un report Markdown o HTML autonomo - riepilogo per file, metadati del provider/firma/motore, l'intero audit trail `ProbeLog` e avvisi - da allegare a un writeup di engagement. Legge solo i risultati e non esegue mai una nuova scansione, quindi funziona multipiattaforma. Aggiungere `-IncludeIoc` per includere un pannello di indicatori hash/entropia/PE (gli stessi dati di `Get-OffsetIOC`) in ogni voce del report, e `-IncludeTrigger` per aggiungere un'analisi del trigger di rilevamento (vedi sotto) per ogni risultato con un confine.```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

Per i report su scala di corpus, -IncludeIoc esegue una nuova scansione di ogni file in PowerShell, il che è lento. Il motore nativo complementare OffsetScan emette JSON IOC con schema identico molto più velocemente; puntare il report su di esso con -IocJsonPath e attinge ogni pannello da quel JSON (ricorrendo a un Get-OffsetIOC live solo per i file assenti da esso):```powershell offsetscan ioc ./corpus --recurse > ./ioc.json $results | Export-OffsetThreatReport -Path ./engagement.md -IocJsonPath ./ioc.json

### Scansione batch / corpus

`Invoke-OffsetThreatScanBatch` espande file, directory e wildcard in un elenco di file, scansiona ciascuno (proseguendo oltre gli errori per singolo file) e restituisce un risultato per file. `-Summary` restituisce una matrice di rilevamento appiattita; i risultati completi possono essere passati direttamente al generatore di report. La scansione dei provider è solo per 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 / regressione del rilevamento

Compare-OffsetThreatResult confronta due risultati di scansione - ad esempio lo stesso file prima e dopo un aggiornamento della definizione delle firme - e classifica il cambiamento (NewlyDetected, NoLongerDetected, BoundaryEarlier, BoundaryLater, BoundaryUnchanged, BothClean) con il delta del confine e i campi modificati.```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

### Scoperta multi-regione

La ricerca per prefisso trova il *primo* confine di rilevamento. `Invoke-OffsetThreatScanRegion` trova *multiple* regioni rilevabili indipendentemente suddividendo il file in segmenti e scansionando ciascuno in isolamento tramite AMSI **interamente in memoria** - nulla di rilevato viene scritto su disco, quindi la protezione in tempo reale di Defender non viene mai attivata o riconfigurata. Ogni rilevamento viene bisecato all'interno del proprio segmento per mappare il confine esatto di attivazione a un offset assoluto del file.```powershell
Invoke-OffsetThreatScanRegion ./payload.bin -SegmentCount 16 |
    Select-Object -ExpandProperty DetectedRegions |
    Format-Table SegmentIndex, StartOffset, EndOffset, AbsoluteBoundaryOffset, SignatureName

Questo riporta regioni che si attivano da sole; può tralasciare firme che si attivano solo in contesto di file completo o che attraversano un confine di segmento, quindi tratta le regioni come indizi da confermare con Invoke-OffsetThreatScan e validazione manuale. AMSI (in-memory) è l'unico motore supportato qui - la scansione di file di Defender richiederebbe la scrittura del contenuto rilevato su disco.

Correlazione dei trigger di rilevamento

Un confine ti dice dove il rilevamento scatta; Get-OffsetDetectionTrigger ti dice cosa c'è. Poiché un confine di prefisso è l'ultimo byte del prefisso rilevato più precoce, il contenuto scatenante è una sequenza che termina a quell'offset. Il comando riporta la sezione PE in cui cade il confine, l'entropia della sequenza fino ad esso (testo semplice vs compresso/codificato) e le stringhe estratte che terminano o sono a cavallo del confine, classificate per prossimità - il contenuto candidato della firma - con un'interpretazione in una riga. Legge solo byte e non esegue mai una nuova scansione, quindi funziona multipiattaforma sui risultati salvati.```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

### Registro del drift di rilevamento

"È stato rilevato prima e ora non lo è" ha tre cause molto diverse: il file è cambiato, le firme sono cambiate o il provider è non deterministico. `Add-OffsetDriftEntry` registra snapshot NDJSON solo append - SHA-256 del file, stato, boundary, nome della firma e le versioni locali della firma/engine di Defender - e `Get-OffsetDrift` legge quella cronologia e attribuisce ogni cambiamento alla giusta causa.```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

Ogni transizione è etichettata: una modifica SHA-256 viene letta come una modifica del file; un cambiamento di stato con file invariato ma versione della firma Defender aggiornata viene letto come deriva della firma; un cambiamento di stato con nessuna delle due viene letto come un risultato non deterministico del provider. Il journal è predefinito su %LOCALAPPDATA%\OffsetInspect\drift.ndjson; si può sovrascrivere con -JournalPath.

Test di robustezza delle firme (solo per uso autorizzato)

Invoke-OffsetMutationTest risponde a una domanda di ingegneria del rilevamento: una firma è un confronto esatto e fragile, oppure è robusta rispetto all'offuscamento comune? Dato un campione che AMSI rileva attualmente, applica perturbazioni standard – inversione di maiuscole/minuscole, concatenazione di stringhe letterali, inserimento di commenti, iniezione di spazi bianchi – e ri-esamina ogni variante per segnalare quali classi neutralizzano il rilevamento. Tutto avviene in memoria tramite l'interfaccia in-process di AMSI; nessuna variante viene scritta su disco, quindi non vengono prodotti artefatti evasivi e la protezione in tempo reale di Defender non è coinvolta. Il comando rifiuta di essere eseguito senza -AuthorizedEngagement ed è destinato solo a campioni che sei autorizzato a testare.```powershell Invoke-OffsetMutationTest -FilePath ./flagged.ps1 -AuthorizedEngagement | Select-Object RobustnessSummary -ExpandProperty Results

Un risultato di, ad esempio, "brittle: neutralizzato da StringConcatenation, CommentInsertion" dice a un difensore che le chiavi della firma si basano su un letterale contiguo e dovrebbero essere ampliate; dice a un operatore autorizzato la stessa cosa riguardo alla copertura di un controllo.

### Correlazione della telemetria

Rilevare un confine ti dice cosa vede il *motore*; `-CaptureTelemetry` ti dice cosa vede il *difensore*. Esso registra il high-water mark di ciascun log di telemetria di Windows accessibile prima della scansione, poi segnala se l'azione ha generato un avviso, con quale contesto, e quali fonti erano cieche – la domanda "presupponi la visibilità, poi validala", risposta con prove.```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

La proprietà Telemetry (OffsetInspect.TelemetryCorrelation) segnala:

• AlertGenerated / Alert - se è stato registrato un rilevamento di Microsoft Defender (evento 1116/1117) per la scansione, e il suo contesto (nome della minaccia, gravità, origine del rilevamento, processo, utente).
• CorrelationConfidence - Alta solo quando l'origine del rilevamento corrisponde al provider e il suo processo corrisponde all'host di scansione, quindi non viene mai rivendicata una rilevazione coincidente concorrente; Media solo per l'origine; Bassa per nessuno dei due.
• SourcesAccessible / SourcesUnavailable - quali log di telemetria erano leggibili e quali erano inaccessibili (Sysmon assente, il Security log richiede elevazione). Una lacuna di visibilità è di per sé un reperto.
• Findings - conclusioni in linguaggio semplice: un avviso con contesto completo, un avviso senza nome della minaccia, nessuna telemetria affatto, o una fonte mancante.

La fonte primaria è il log operativo di Microsoft Defender, leggibile senza elevazione; la correlazione avviene tramite l'evento RecordId (monotono e indipendente dal fuso orario). Solo Windows, e inerte a meno che non venga passato -CaptureTelemetry.

Helper di triage statici

Tre comandi di analisi statica multipiattaforma supportano il triage di malware e si compongono con il nucleo di offset:

• Get-OffsetEntropy - entropia di Shannon per finestra (bit/byte) per individuare regioni impaccate o crittografate; incrociare le finestre segnalate con i rilevamenti di Invoke-OffsetThreatScanRegion.
• Get-OffsetString - stringhe ASCII stampabili e UTF-16LE con offset byte; reindirizzare gli offset in Invoke-OffsetInspect per il contesto.
• Get-OffsetPEInfo - PE machine/bitness, punto di ingresso, tabella delle sezioni, import e imphash, rilevamento overlay aggiunto, e dimensione delle risorse, con -Offset che mappa un offset byte alla sua sezione (.text, .rsrc, ...). Imphash utilizza il MD5 standard library.function ed è verificato byte-per-byte identico a pefile/VirusTotal - inclusa la risoluzione ordinale per librerie speciali, quindi un ordinale importato da ws2_32/wsock32/oleaut32 viene risolto nel suo nome di funzione reale; ogni altro import ordinale rende ordNNN, esattamente come fa pefile.
• Get-OffsetIOC - pannello di indicatori one-shot che combina quanto sopra: MD5/SHA-1/SHA-256 (passaggio singolo), entropia complessiva, conteggio di stringhe stampabili, e PE machine/imphash/overlay quando applicabile.```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

### Scansione YARA

`Invoke-OffsetYaraScan` esegue regole YARA create dall'analista e restituisce ogni corrispondenza con il suo byte offset - integrando la visualizzazione dei limiti di rilevamento di AMSI/Defender con firme che controlli tu, senza necessità di antivirus installato (solo il motore YARA, ad es. `winget install VirusTotal.YARA`). Gli offset vengono alimentati direttamente nell'ispettore.```powershell
Invoke-OffsetYaraScan ./sample.bin -RulePath ./rules/malware.yar |
    ForEach-Object { Invoke-OffsetInspect $_.File $_.Offset -ContextLines 2 }

Scansione con ClamAV

Invoke-OffsetClamScan esegue la scansione di un file con il motore on-demand di ClamAV e restituisce un risultato normalizzato (Clean / Detected / Error, più il nome della firma). Poiché clamscan carica l'intero database delle firme ad ogni chiamata, si tratta di un rilevatore a file singolo, non di un motore di ricerca di confine (che richiederebbe il demone clamd). Necessita che ClamAV sia installato e che i suoi database delle firme siano scaricati – freshclam non verrà eseguito finché non esiste un file di configurazione:```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

Usa `-DatabasePath` per puntare a una directory di firme in una posizione scrivibile (non amministrativa), e `-ClamScanPath` se `clamscan` non è in `PATH`.

## Oggetti risultato

`Invoke-OffsetInspect -PassThru` restituisce oggetti `OffsetInspect.Result` contenenti:

- Percorso file canonico, dimensione del file, offset decimali ed esadecimali.
- Codifica richiesta e rilevata.
- Numero di riga, anteprima della sorgente, righe di contesto, posizione del byte e posizione del carattere.
- Byte target e dump esadecimale delimitato.
- Byte di confronto opzionale e stato di differenza.
- Avvisi, durata, stato di successo e messaggio di errore.

`Invoke-OffsetThreatScan -PassThru` restituisce oggetti `OffsetInspect.ThreatScanResult` contenenti:

- SHA-256 del file, timestamp della scansione UTC, motore, modalità di scansione, stato iniziale del provider e metadati del provider.
- Lunghezze dei prefissi noti puliti e noti rilevati.
- Limite del byte e limite opzionale del carattere.
- Stabilità, confidenza, conteggio scansioni, stati di limite ripetuti e nome della firma quando disponibile.
- Una traccia di audit `ProbeLog` di ogni sonda distinta del provider (esposta come `ProbeCount` nell'output CSV, ed esportabile in un trascritto JSON con `-ProbeLogPath`); vedere [schema di output](https://github.com/warpedatom/offsetinspect/blob/HEAD/docs/OUTPUT-SCHEMA.md).
- Contesto `OffsetInspect.Result` annidato al limite mappato.

## Modello di prestazioni

L'implementazione in stile v1 rileggeva e decodificava un file completo per ogni offset. La versione 2 raggruppa il lavoro per file:```text
Previous approach: approximately O(file size × offset count)
Version 2:         approximately O(file bytes scanned once + requested windows)

Il mapping delle sorgenti utilizza una macchina a stati streaming e conserva solo i descrittori di riga precedente/successiva necessari per gli offset richiesti. Le righe singole estremamente lunghe vengono visualizzate tramite un'anteprima limitata controllata da -MaxLineBytes.

Layout del repository```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

## Sviluppo

Installa gli strumenti di validazione bloccati:```powershell
Install-Module Pester -RequiredVersion 5.7.1 -Scope CurrentUser
Install-Module PSScriptAnalyzer -RequiredVersion 1.25.0 -Scope CurrentUser

Esegui il gate locale completo:```powershell ./build/Test-Module.ps1

Esegui l'harness di benchmark deterministico:```powershell
./benchmarks/Measure-OffsetInspect.ps1 -FileSizeMiB 64 -OffsetCount 5000

I risultati del benchmark variano in base all'archiviazione, al carico dell'host, all'edizione di PowerShell e alla forma del file. Registra questi input quando confronti i commit.

Crea un archivio di rilascio deterministico e un file SHA-256:```powershell ./build/New-ReleasePackage.ps1

CI convalida PowerShell 7 su Windows e Linux, Windows PowerShell 5.1, PSScriptAnalyzer, il packaging isolato del modulo e l'archivio di rilascio. I manutentori del rilascio dovrebbero anche seguire la [checklist di rilascio](https://github.com/warpedatom/offsetinspect/blob/HEAD/docs/RELEASE-CHECKLIST.md).

## Sicurezza e uso responsabile

OffsetInspect è destinato alla ricerca difensiva autorizzata, all'ingegneria del rilevamento, al reverse engineering, all'analisi malware e ai test di sicurezza. Le funzioni dei fornitori di minacce analizzano il contenuto ma non disabilitano, bypassano o riconfigurano le protezioni degli endpoint.

`Invoke-OffsetMutationTest` genera varianti di elusione del rilevamento per la valutazione della robustezza delle firme. Opera interamente in memoria (nessuna variante viene scritta su disco) e rifiuta di eseguire senza l'esplicita conferma `-AuthorizedEngagement`. Utilizzalo solo su campioni e controlli che sei autorizzato a testare.

Rivedi [SECURITY.md](https://github.com/warpedatom/offsetinspect/blob/HEAD/SECURITY.md) prima di segnalare una vulnerabilità. Non inviare campioni sensibili attraverso i problemi pubblici di GitHub.

## Licenza

OffsetInspect è rilasciato sotto la [Licenza MIT](https://github.com/warpedatom/offsetinspect/blob/HEAD/LICENSE).