PowerShell toolkit per l'analisi dei confini di rilevamento di AMSI/Defender e il triage statico di malware, mappa gli offset dei byte ai trigger di rilevamento, più analisi YARA, entropia, stringhe e PE/imphash. Complementare a 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
**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](https://github.com/warpedatom/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
| Comando | Scopo | Piattaforma |
|---|---|---|
| `Invoke-OffsetInspect` | Mappa gli offset di byte al contesto di origine/binario, esadecimale e confronto | Multipiattaforma |
| `Invoke-OffsetThreatScan` | Ricerca del confine di rilevamento AMSI/Defender per un file | Windows |
| `Invoke-OffsetThreatScanBatch` | Scansiona un corpus di file; `-Summary` restituisce una matrice di rilevamento | Windows |
| `Invoke-OffsetThreatScanRegion` | Scoperta multi-regione tramite AMSI in memoria (nessuna scrittura su disco) | Windows |
| `Invoke-OffsetMutationTest` | Test di robustezza delle firme: perturba un campione rilevato in memoria, segnala quali trasformazioni eludono (solo uso autorizzato) | Windows |
| `Compare-OffsetThreatResult` | Confronta due risultati di scansione (es. tra aggiornamenti delle definizioni delle firme) | Multipiattaforma |
| `Get-OffsetDetectionTrigger` | Correla un confine di rilevamento al contenuto che molto probabilmente lo ha attivato | Multipiattaforma |
| `Add-OffsetDriftEntry` | Registra un'istantanea di rilevamento (hash file + versione firma Defender) in un journal | Multipiattaforma² |
| `Get-OffsetDrift` | Spiega come è cambiata la rilevabilità di un file: modifica del file, aggiornamento firma o risultato non deterministico | Multipiattaforma |
| `Export-OffsetThreatReport` | Renderizza i risultati di scansione in un report di engagement Markdown/HTML | Multipiattaforma |
| `Invoke-OffsetYaraScan` | Confronta un file con regole YARA; restituisce hit con offset di byte | Multipiattaforma¹ |
| `Invoke-OffsetClamScan` | Scansiona un file con il motore ClamAV; risultato di rilevamento normalizzato | Multipiattaforma¹ |
| `Get-OffsetEntropy` | Entropia di Shannon per finestra per individuare regioni impacchettate/crittografate | Multipiattaforma |
| `Get-OffsetString` | Estrae stringhe ASCII/UTF-16LE con offset di byte | Multipiattaforma |
| `Get-OffsetPEInfo` | Header PE, sezioni, import/imphash, overlay, offset→sezione | Multipiattaforma |
| `Get-OffsetIOC` | Pannello indicatori consolidato: hash, entropia, PE/imphash, stringhe | Multipiattaforma |
| `Get-OffsetSignature` | Firma Authenticode: se è firmata validamente e attendibile, da chi, embedded o catalog | Windows |
¹ 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 <file> <offset>
./OffsetThreatScan.ps1 <file> -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
| Input | Interpretazione |
|---|---:|
| `512` | Decimale 512 |
| `0x200` o `0X200` | Esadecimale 0x200 |
| `200h` | Esadecimale 0x200 |
| `E1AB1` | Esadecimale senza prefisso perché contiene A-F |
I valori puramente numerici senza prefisso o suffisso sono intenzionalmente trattati come decimali.
### Modalità di codifica
| Modalità | Comportamento |
|---|---|
| `Auto` | Rileva BOM UTF-8/UTF-16; altrimenti usa UTF-8 |
| `Default` | Usa la codifica predefinita del sistema operativo host |
| `UTF8` | Mapping sorgente UTF-8 |
| `UTF16LE` | Mapping sorgente little-endian UTF-16 |
| `UTF16BE` | Mapping sorgente big-endian UTF-16 |
| `ASCII` | Mapping sorgente ASCII |
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/main/docs/THREAT-SCANNING.md) per il contratto del provider e le linee guida di interpretazione, [provider interface](https://github.com/warpedatom/offsetinspect/blob/main/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/main/docs/PROVENANCE.md) per i confini di implementazione e l'attribuzione, e [output schema](https://github.com/warpedatom/offsetinspect/blob/main/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](https://github.com/warpedatom/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 '^\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
```
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/main/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)
```
---
[Read more](https://github.com/warpedatom/offsetinspect)