OffsetInspect

Un conjunto de herramientas PowerShell de memoria limitada para inspección de desplazamientos de bytes, correlación de fuentes, comparación binaria y análisis de límites de detección defensiva.

OffsetInspect responde una pregunta práctica de analista:

¿Qué contenido está presente en este desplazamiento de byte, y qué contexto fuente o binario lo rodea?

También proporciona un flujo de trabajo de límite de detección nativo de OffsetInspect inspirado en el mismo problema de analista que aborda ThreatCheck, sin incluir su fuente o binarios: localiza el prefijo de contenido más temprano que AMSI o Microsoft Defender aún detectan, valida el límite repetidamente y alimenta el desplazamiento resultante directamente al inspector de contexto. Además de ese núcleo, añade un conjunto de análisis de equipo rojo y clasificación estática: descubrimiento de múltiples regiones, escaneo de corpus, diferenciación de detecciones, correlación de desencadenantes de detección, registro de deriva, informes de compromiso, análisis de entropía, extracción de cadenas y análisis de PE/imphash, todo de solo lectura, además de un probador de robustez de firmas para uso autorizado que perturba muestras solo en memoria, y sin deshabilitar o reconfigurar la protección del punto final.

Herramienta complementaria

Para clasificación estática a escala de corpus (análisis de PE, entropía, cadenas, IOC) sin la sobrecarga de PowerShell, consulte OffsetScan

• un binario nativo en Rust con el mismo esquema de salida JSON. OffsetInspect 3.1.0+ ingiere JSON de IOC de OffsetScan directamente mediante -IocJsonPath.

Aspectos destacados

• Abre cada archivo de inspección único a través de un identificador de lectura estable y procesa todos los desplazamientos solicitados juntos.
• Utiliza un pase de transmisión de memoria limitada para el mapeo de líneas en lugar de releer el archivo completo para cada desplazamiento.
• Lee solo las ventanas de bytes solicitadas para la salida hexadecimal y la comparación.
• Mapea desplazamientos de bytes UTF-8 y UTF-16 a líneas de origen y posiciones de caracteres.
• Implementa contexto de origen anterior y siguiente mediante -ContextLines.
• Soporta contratos de salida humanos, de objeto, JSON, CSV y archivo CSV.
• Soporta planes de archivo/desplazamiento uno-a-muchos, muchos-a-uno y emparejados.
• Compara el byte objetivo contra un segundo archivo sin cargar repetidamente ese archivo.
• Añade una capa de proveedores de AMSI y Microsoft Defender implementada de forma independiente con estados explícitos de error, tiempo de espera, bloqueado e indeterminado.
• Registra un registro de auditoría por sonda (ProbeLog/ProbeCount) de cada invocación distinta al proveedor, transmitido en vivo a -Verbose, para una transcripción lista para informes del costo real del proveedor en un escaneo.
• Descubre múltiples regiones detectables de forma independiente en un archivo mediante escaneo AMSI en memoria (nada detectado se escribe en disco) y mapea cada límite a un desplazamiento absoluto.
• Escanea un corpus en una matriz de detección consolidada, diferencia las detecciones entre dos escaneos y exporta informes de compromiso en Markdown/HTML (opcionalmente alimentados por el motor nativo OffsetScan para paneles de IOC a escala de corpus).
• Correlaciona un límite de detección con el contenido que lo produjo: la sección PE, la entropía del recorrido hasta el límite y las cadenas que terminan en/cruzan el límite como contenido candidato de firma.
• Registra la detección a lo largo del tiempo (hash del archivo y la versión local de la firma de Defender) de modo que un cambio en la detectabilidad se pueda atribuir al archivo, a una actualización de la base de firmas o a un resultado no determinista del proveedor.

Comandos

¹ Estos dos comandos tienen dependencias externas opcionales: Invoke-OffsetYaraScan necesita el motor YARA (winget install VirusTotal.YARA), y Invoke-OffsetClamScan necesita ClamAV con bases de datos de firmas (winget install Cisco.ClamAV, luego freshclam). Todos los demás comandos son autocontenidos. Aquí ClamAV es un detector de un solo archivo, no un motor de búsqueda de límites - clamscan carga su base de datos completa por invocación, por lo que la bisección requeriría el demonio clamd.

² Add-OffsetDriftEntry registra en multiplataforma, pero los campos de versión de firma/motor de Defender se completan solo en Windows (mediante Get-MpComputerStatus); en otras plataformas se registran como nulos y el resto de la instantánea aún se escribe.

El núcleo de inspección de desplazamientos y todos los ayudantes de clasificación estática son multiplataforma (Windows, Linux, macOS); los proveedores de amenazas AMSI/Defender son solo Windows.

Instalación

Galería de PowerShell```powershell

Install-Module OffsetInspect -Scope CurrentUser Import-Module OffsetInspect

### Clonación del repositorio```powershell
git clone https://github.com/warpedatom/OffsetInspect.git
cd OffsetInspect
Import-Module ./module/OffsetInspect/OffsetInspect.psd1 -Force

El repositorio también incluye envoltorios CLI ligeros:```powershell ./OffsetInspect.ps1 ./OffsetThreatScan.ps1 -Engine AMSI

## Inspección de desplazamiento

### Salida legible por humanos```powershell
Invoke-OffsetInspect ./sample.bin 0x200

[No content provided for translation.]```powershell $inspectParameters = @{ FilePaths = './script.ps1' OffsetInputs = 128, 256, 512 ByteWindow = 64 ContextLines = 4 } Invoke-OffsetInspect @inspectParameters

### Objetos estructurados```powershell
$inspectParameters = @{
    FilePaths    = './script.ps1'
    OffsetInputs = 0x80, 0x100
    PassThru     = $true
}
$results = Invoke-OffsetInspect @inspectParameters

$results | Where-Object BytesDiffer

JSON y CSV```powershell

Invoke-OffsetInspect ./sample.bin 0x200 -Json Invoke-OffsetInspect ./sample.bin 0x200 -Csv Invoke-OffsetInspect ./sample.bin 0x200 -CsvPath ./artifacts/offsets.csv

El modo JSON siempre emite un array, incluso para un solo resultado.

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

Offset formats

Los valores solo numéricos sin prefijo ni sufijo se tratan intencionalmente como decimales.

Modos de codificación

La salida informa tanto BytePositionInLine como CharacterPosition. Esta distinción es importante cuando un archivo fuente contiene caracteres multibyte.

Análisis de límites de amenazas

El análisis del proveedor de amenazas es solo para Windows. El comando de inspección de desplazamiento normal sigue siendo multiplataforma.

Escaneo de texto AMSI```powershell

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

El modo texto usa `AmsiScanString`, busca prefijos de escalares Unicode sin dividir pares sustitutos, mapea el prefijo detectado a través de la codificación de origen validada, y devuelve índices de escalares Unicode, unidades de código UTF-16 y bytes del archivo de origen. Los caracteres NUL incrustados se rechazan en modo texto; use el modo de bytes sin procesar para esos archivos.

### Escaneo de bytes sin procesar de AMSI```powershell
Invoke-OffsetThreatScan ./content.bin -Engine AMSI -ScanMode RawBytes

Escaneo de Microsoft Defender```powershell

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

El proveedor Defender:

- Resuelve la ruta de la plataforma `MpCmdRun.exe` más recientemente instalada.
- Escribe prefijos en un directorio temporal único del usuario.
- Utiliza un escaneo personalizado con `-DisableRemediation`.
- Trata los tiempos de espera, errores del proveedor, salida localizada/desconocida y marcadores ambiguos como no definitivos.
- Elimina el espacio de trabajo temporal cuando finaliza el escaneo.

### Semántica de límites

Un resultado como `DetectionPrefixLength = 841` significa:

- La longitud de prefijo 840 fue clasificada como limpia/no detectada.
- La longitud de prefijo 841 fue clasificada como detectada/bloqueada.
- Las comprobaciones repetidas determinan si esa transición es estable.

No **prueba** que el byte 840 sea la firma completa, el único byte contribuyente o el rango malicioso completo. Las decisiones del antivirus pueden depender de la tokenización, el contexto circundante, el tipo de archivo, el estado del proveedor y las actualizaciones de firmas.

### Ejemplo práctico: dos motores, un archivo

Escaneando la misma muestra (PowerUp.ps1, un script público de red team, 445,954 bytes) con ambos proveedores muestra qué es un límite y hasta qué punto se puede confiar en que dos motores coincidan. AMSI en 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 en modo de bytes sin procesar, mismo archivo:```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 motores convergen en la **línea 4586** - el límite de Defender cae dentro del `it` final de `Invoke-PrivescAudit`, el de AMSI en el salto de línea que termina la misma línea, dos bytes después. Ninguno de los desplazamientos es "la firma": son el prefijo más temprano que cada proveedor seguía marcando, y la discrepancia de dos bytes es exactamente el efecto de tokenización/contexto descrito anteriormente. Defender además nombra lo que coincidió (`Trojan:Win32/Kepavll!rfn`); AMSI no informa un nombre de firma, por lo que existen `Invoke-OffsetThreatScanRegion` y `Get-OffsetDetectionTrigger` para caracterizar un golpe de AMSI.

Ambos análisis costaron 25 sondas de proveedor para un archivo de ~436 KiB - la bisección es logarítmica en el tamaño del archivo, y cada sonda se registra en `ProbeLog`.

Consulte [Diseño de escaneo de amenazas](https://github.com/warpedatom/offsetinspect/blob/HEAD/docs/THREAT-SCANNING.md) para el contrato del proveedor y la guía de interpretación, [interfaz del proveedor](https://github.com/warpedatom/offsetinspect/blob/HEAD/docs/PROVIDER-INTERFACE.md) para el contrato del escáner y cómo agregar un proveedor sin tocar el núcleo de búsqueda, [procedencia del escaneo de amenazas](https://github.com/warpedatom/offsetinspect/blob/HEAD/docs/PROVENANCE.md) para los límites de implementación y atribución, y [esquema de salida](https://github.com/warpedatom/offsetinspect/blob/HEAD/docs/OUTPUT-SCHEMA.md) para el contrato de objeto versionado.

### Informes de límites de detección

`Export-OffsetThreatReport` convierte uno o más resultados de escaneo en un informe Markdown o HTML autónomo: resumen por archivo, metadatos de proveedor/firma/motor, el registro de auditoría completo de `ProbeLog` y advertencias, para adjuntar a un informe de compromiso. Solo lee resultados y nunca reescannea, por lo que se ejecuta multiplataforma. Agregue `-IncludeIoc` para incluir un panel de indicadores hash/entropía/PE (los mismos datos que `Get-OffsetIOC`) en cada entrada del informe, y `-IncludeTrigger` para agregar un análisis de disparador de detección (ver más abajo) para cada resultado con un límite.```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 informes a escala de corpus, -IncludeIoc vuelve a escanear cada archivo en PowerShell, lo cual es lento. El motor nativo complementario OffsetScan emite JSON de IOC con esquema idéntico mucho más rápido; apunte el informe a él con -IocJsonPath y obtiene cada panel de ese JSON (recurriendo a un Get-OffsetIOC en vivo solo para archivos ausentes del mismo):```powershell offsetscan ioc ./corpus --recurse > ./ioc.json $results | Export-OffsetThreatReport -Path ./engagement.md -IocJsonPath ./ioc.json

### Escaneo por lotes / corpus

`Invoke-OffsetThreatScanBatch` expande archivos, directorios y comodines en una lista de archivos, escanea cada uno (continuando más allá de los fallos por archivo) y devuelve un resultado por archivo. `-Summary` devuelve una matriz de detección aplanada; los resultados completos se canalizan directamente al generador de informes. El escaneo del proveedor es solo para 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

Diferencia de detección / regresión

Compare-OffsetThreatResult diferencia dos resultados de escaneo - por ejemplo el mismo archivo antes y después de una actualización de definiciones de firmas - y clasifica el cambio (NewlyDetected, NoLongerDetected, BoundaryEarlier, BoundaryLater, BoundaryUnchanged, BothClean) con el delta de límite y los campos cambiados.```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

### Descubrimiento multirregión

La búsqueda de prefijo encuentra el *primer* límite de detección. `Invoke-OffsetThreatScanRegion` encuentra *múltiples* regiones detectables de forma independiente dividiendo el archivo en segmentos y escaneando cada uno de forma aislada a través de AMSI **completamente en memoria** - no se escribe nada detectado en el disco, por lo que la protección en tiempo real de Defender nunca se activa ni se reconfigura. Cada acierto se biseca dentro de su segmento para mapear el límite exacto de activación a un desplazamiento absoluto del archivo.```powershell
Invoke-OffsetThreatScanRegion ./payload.bin -SegmentCount 16 |
    Select-Object -ExpandProperty DetectedRegions |
    Format-Table SegmentIndex, StartOffset, EndOffset, AbsoluteBoundaryOffset, SignatureName

Esto reporta regiones que se activan por sí solas; puede pasar por alto firmas que solo se activan en el contexto de un archivo completo o que cruzan un límite de segmento, así que trate las regiones como pistas para confirmar con Invoke-OffsetThreatScan y validación manual. AMSI (en memoria) es el único motor compatible aquí; el escaneo de archivos de Defender requeriría escribir el contenido detectado en disco.

Correlación de activación de detección

Un límite te dice dónde cambia la detección; Get-OffsetDetectionTrigger te dice qué hay allí. Debido a que un límite de prefijo es el último byte del prefijo detectado más temprano, el contenido desencadenante es una secuencia que termina en ese desplazamiento. El comando reporta la sección PE en la que cae el límite, la entropía de la secuencia hasta él (texto plano vs empaquetado/codificado) y las cadenas extraídas que terminan en él o lo cruzan, clasificadas por proximidad — el contenido candidato de la firma — con una interpretación de una línea. Lee solo bytes y nunca vuelve a escanear, por lo que funciona multiplataforma en resultados guardados.```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 de deriva de detección

"Antes se detectaba y ahora no" tiene tres causas muy diferentes: el archivo cambió, las firmas cambiaron o el proveedor no es determinista. `Add-OffsetDriftEntry` registra instantáneas NDJSON de solo agregación: SHA-256 del archivo, estado, límite, nombre de la firma y las versiones locales de firma/motor de Defender - y `Get-OffsetDrift` lee ese historial y atribuye cada cambio a la causa correcta.```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 transición está etiquetada: un cambio de SHA-256 se lee como una modificación de archivo; un cambio de estado con el archivo sin cambios pero la versión de la firma de Defender movida se lee como deriva de firma; un cambio de estado sin ninguno de los anteriores se lee como un resultado de proveedor no determinista. El diario por defecto es %LOCALAPPDATA%\OffsetInspect\drift.ndjson; se puede sobrescribir con -JournalPath.

Prueba de robustez de firmas (solo uso autorizado)

Invoke-OffsetMutationTest responde a una pregunta de ingeniería de detección: ¿es una firma una coincidencia literal exacta frágil, o es robusta frente a ofuscación común? Dada una muestra que AMSI detecta actualmente, aplica perturbaciones estándar - inversión de mayúsculas, concatenación de literales de cadena, inserción de comentarios, inyección de espacios en blanco - y vuelve a escanear cada variante para informar qué clases neutralizan la detección. Todo sucede en memoria a través de la interfaz en proceso de AMSI; ninguna variante se escribe en disco, por lo que no se producen artefactos evasivos y la protección en tiempo real de Defender no está involucrada. El comando se niega a ejecutarse sin -AuthorizedEngagement, y está destinado únicamente a muestras que esté autorizado a probar.```powershell Invoke-OffsetMutationTest -FilePath ./flagged.ps1 -AuthorizedEngagement | Select-Object RobustnessSummary -ExpandProperty Results

Un resultado de, digamos, "frágil: neutralizado por StringConcatenation, CommentInsertion" le indica a un defensor que las claves de la firma están en un literal contiguo y deberían ampliarse; le indica a un operador autorizado lo mismo sobre la cobertura de un control.

### Correlación de telemetría

Detectar un límite te dice lo que el *motor* ve; `-CaptureTelemetry` te dice lo que el *defensor* ve. Captura una instantánea de la marca de agua alta de cada registro de telemetría de Windows accesible antes del escaneo, luego informa si la acción generó una alerta, con qué contexto y qué fuentes estaban ciegas: la pregunta de "asumir visibilidad, luego validarla", respondida con evidencia.```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 propiedad Telemetry (OffsetInspect.TelemetryCorrelation) informa:

• AlertGenerated / Alert - si se registró una detección de Microsoft Defender (evento 1116/1117) para el escaneo y su contexto (nombre de amenaza, gravedad, fuente de detección, proceso, usuario).
• CorrelationConfidence - Alta solo cuando la fuente de detección coincide con el proveedor y su proceso coincide con el host de escaneo, por lo que nunca se afirma una detección concurrente coincidente; Media solo con la fuente; Baja con ninguna.
• SourcesAccessible / SourcesUnavailable - qué registros de telemetría eran legibles y cuáles estaban ciegos (Sysmon ausente, el registro de Seguridad requiere elevación). Una brecha de visibilidad es en sí misma un hallazgo.
• Findings - conclusiones en lenguaje sencillo: una alerta con contexto completo, una alerta que carece de nombre de amenaza, sin telemetría en absoluto, o una fuente faltante.

La fuente principal es el registro operativo de Microsoft Defender, legible sin elevación; la correlación se realiza por RecordId del evento (monótono e independiente de la zona horaria). Solo para Windows e inerte a menos que se pase -CaptureTelemetry.

Ayudantes de clasificación estática

Tres comandos de análisis estático multiplataforma apoyan la clasificación de malware y se integran con el núcleo de desplazamiento:

• Get-OffsetEntropy - entropía de Shannon por ventana (bits/byte) para localizar regiones empaquetadas o cifradas; cruce referencias de las ventanas marcadas con las detecciones de Invoke-OffsetThreatScanRegion.
• Get-OffsetString - cadenas ASCII imprimibles y UTF-16LE con desplazamientos de bytes; envíe los desplazamientos a Invoke-OffsetInspect para obtener contexto.
• Get-OffsetPEInfo - máquina/bitness PE, punto de entrada, tabla de secciones, importaciones e imphash, detección de superposición añadida y tamaño de recursos, con -Offset mapeando un desplazamiento de byte a su sección (.text, .rsrc, ...). Imphash usa el MD5 estándar de library.function y se verifica idéntico byte a byte con pefile/VirusTotal - incluyendo resolución de ordinales de bibliotecas especiales, por lo que un ordinal importado de ws2_32/wsock32/oleaut32 se resuelve a su nombre de función real; cualquier otra importación ordinal se renderiza como , exactamente como lo hace pefile.

### Escaneo YARA

`Invoke-OffsetYaraScan` ejecuta reglas YARA escritas por analistas y devuelve cada coincidencia con su byte offset, complementando la vista de límites de detección de AMSI/Defender con firmas que usted controla, y no necesita antivirus instalado (solo el motor YARA, por ejemplo `winget install VirusTotal.YARA`). Los offsets se alimentan directamente al inspector.```powershell
Invoke-OffsetYaraScan ./sample.bin -RulePath ./rules/malware.yar |
    ForEach-Object { Invoke-OffsetInspect $_.File $_.Offset -ContextLines 2 }

Escaneo con ClamAV

Invoke-OffsetClamScan escanea un archivo con el motor bajo demanda de ClamAV y devuelve un resultado normalizado (Clean / Detected / Error, más el nombre de la firma). Debido a que clamscan carga toda su base de datos de firmas en cada llamada, es un detector de un solo archivo, no un motor de búsqueda de límites (eso requeriría el daemon clamd). Necesita ClamAV instalado y sus bases de datos de firmas descargadas - freshclam no se ejecutará hasta que exista un archivo de configuración:```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 apuntar a un directorio de firmas en una ubicación con permisos de escritura (no administrador), y `-ClamScanPath` si `clamscan` no está en `PATH`.

## Objetos de resultado

`Invoke-OffsetInspect -PassThru` devuelve objetos `OffsetInspect.Result` que contienen:

- Ruta de archivo canónica, tamaño del archivo, desplazamientos decimales y hexadecimales.
- Codificación solicitada y detectada.
- Número de línea, vista previa de la fuente, líneas de contexto, posición de byte y posición de carácter.
- Byte objetivo y volcado hexadecimal acotado.
- Byte de comparación opcional y estado de diferencia.
- Advertencias, duración, estado de éxito y mensaje de error.

`Invoke-OffsetThreatScan -PassThru` devuelve objetos `OffsetInspect.ThreatScanResult` que contienen:

- SHA-256 del archivo, marca de tiempo UTC del escaneo, motor, modo de escaneo, estado inicial del proveedor y metadatos del proveedor.
- Longitudes de prefijo conocidas como limpias y conocidas como detectadas.
- Límite de byte y opcionalmente de carácter.
- Estabilidad, confianza, conteo de escaneos, estados de límites repetidos y nombre de la firma cuando esté disponible.
- Un registro de auditoría `ProbeLog` de cada sonda de proveedor distinta (presentado como `ProbeCount` en la salida CSV y exportable a un transcripto JSON con `-ProbeLogPath`); consulte el [esquema de salida](https://github.com/warpedatom/offsetinspect/blob/HEAD/docs/OUTPUT-SCHEMA.md).
- Contexto `OffsetInspect.Result` anidado en el límite mapeado.

## Modelo de rendimiento

La implementación de estilo v1 releía y decodificaba un archivo completo por cada desplazamiento. La versión 2 agrupa el trabajo por archivo:```text
Previous approach: approximately O(file size × offset count)
Version 2:         approximately O(file bytes scanned once + requested windows)

El mapeo de fuentes utiliza una máquina de estados en streaming y retiene solo los descriptores de línea anterior/siguiente necesarios para los desplazamientos solicitados. Las líneas individuales extremadamente largas se muestran a través de una vista previa limitada controlada por -MaxLineBytes.

Diseño del repositorio```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

## Desarrollo

Instala las herramientas de validación fijadas:```powershell
Install-Module Pester -RequiredVersion 5.7.1 -Scope CurrentUser
Install-Module PSScriptAnalyzer -RequiredVersion 1.25.0 -Scope CurrentUser

Ejecuta el gate local completo:```powershell ./build/Test-Module.ps1

Ejecute el banco de pruebas determinista:```powershell
./benchmarks/Measure-OffsetInspect.ps1 -FileSizeMiB 64 -OffsetCount 5000

Los resultados de referencia varían según el almacenamiento, la carga del host, la edición de PowerShell y la forma del archivo. Registre esas entradas al comparar commits.

Construya un archivo de lanzamiento determinista y un archivo SHA-256:```powershell ./build/New-ReleasePackage.ps1

CI valida PowerShell 7 en Windows y Linux, Windows PowerShell 5.1, PSScriptAnalyzer, empaquetado de módulos aislados y el archivo de publicación. Los mantenedores de versiones también deben seguir la [lista de verificación de publicación](https://github.com/warpedatom/offsetinspect/blob/HEAD/docs/RELEASE-CHECKLIST.md).

## Seguridad y uso responsable

OffsetInspect está diseñado para investigación defensiva autorizada, ingeniería de detección, ingeniería inversa, análisis de malware y pruebas de seguridad. Las funciones de proveedor de amenazas analizan contenido pero no deshabilitan, eluden ni reconfiguran las protecciones de los endpoints.

`Invoke-OffsetMutationTest` genera variantes de evasión de detección para la evaluación de robustez de firmas. Opera completamente en memoria (ninguna variante se escribe en el disco) y se niega a ejecutarse sin el reconocimiento explícito de `-AuthorizedEngagement`. Úselo solo contra muestras y controles que esté autorizado a probar.

Revise [SECURITY.md](https://github.com/warpedatom/offsetinspect/blob/HEAD/SECURITY.md) antes de reportar una vulnerabilidad. No envíe muestras sensibles a través de problemas públicos de GitHub.

## Licencia

OffsetInspect se publica bajo la [Licencia MIT](https://github.com/warpedatom/offsetinspect/blob/HEAD/LICENSE).