OffsetInspect

Инструментарий PowerShell с ограниченным потреблением памяти для проверки байтовых смещений, корреляции с исходным кодом, сравнения двоичных файлов и анализа границ обнаружения в целях защиты.

OffsetInspect отвечает на практический вопрос аналитика:

Какое содержимое находится по этому байтовому смещению, и какой исходный или бинарный контекст его окружает?

Он также предоставляет собственный рабочий процесс определения границ обнаружения, вдохновлённый той же задачей аналитика, которую решает ThreatCheck, без включения в комплект его исходников или бинарников: он находит самый ранний префикс содержимого, который AMSI или Microsoft Defender всё ещё обнаруживает, многократно проверяет границу и передаёт полученное смещение напрямую инспектору контекста. Поверх этого ядра он добавляет набор для red-team анализа и статической триаж-сортировки — обнаружение нескольких регионов, сканирование корпуса, сравнение результатов обнаружения, корреляцию триггеров обнаружения, ведение журнала дрейфа, отчёты об испытаниях, энтропийный анализ, извлечение строк и парсинг PE/imphash — всё только для чтения, плюс тестер устойчивости сигнатур для авторизованного использования, который изменяет образцы только в памяти и никогда не отключает и не перенастраивает защиту конечных точек.

Сопутствующий инструмент

Для статического триажа в масштабе корпуса (парсинг PE, энтропия, строки, IOC) без накладных расходов PowerShell используйте OffsetScan — нативный бинарник на Rust с той же схемой вывода JSON. OffsetInspect 3.1.0+ принимает IOC JSON от OffsetScan напрямую через -IocJsonPath.

Возможности

• Открывает каждый уникальный проверяемый файл через стабильный дескриптор чтения и обрабатывает все запрошенные смещения совместно.
• Использует потоковый проход с ограниченной памятью для построения карты строк, вместо повторного чтения всего файла для каждого смещения.
• Считывает только запрошенные байтовые окна для hex-вывода и сравнения.
• Сопоставляет байтовые смещения UTF-8 и UTF-16 со строками исходного кода и позициями символов.
• Реализует предыдущий и последующий контекст исходного кода через -ContextLines.
• Поддерживает выходные контракты: человекочитаемый, объектный, JSON, CSV и CSV-файл.
• Поддерживает планы «один ко многим», «многие к одному» и парные планы файл/смещение.
• Сравнивает целевой байт со вторым файлом без повторной загрузки этого файла.
• Добавляет независимо реализованный слой провайдеров AMSI и Microsoft Defender с явными состояниями: ошибка, таймаут, блокировка и неопределённое состояние.
• Для каждой пробы ведёт аудит (ProbeLog/ProbeCount) каждого отдельного вызова провайдера, передаваемый в реальном времени в -Verbose, для готовой к отчёту расшифровки фактической стоимости провайдера при сканировании.
• Обнаруживает несколько независимо детектируемых областей в одном файле с помощью сканирования AMSI в памяти (ничего из обнаруженного не записывается на диск) и сопоставляет каждую границу с абсолютным смещением.
• Сканирует корпус в консолидированную матрицу обнаружений, сравнивает результаты двух сканирований и экспортирует отчёты об испытаниях в Markdown/HTML (опционально на основе JSON нативного движка OffsetScan для панелей IOC корпусного масштаба).
• Соотносит границу обнаружения с содержимым, которое её вызвало: разделом PE, энтропией фрагмента вплоть до границы и строками, заканчивающимися на границе или пересекающими её, как кандидатами в сигнатурное содержимое.
• Ведёт журнал обнаружений во времени (хэш файла и локальная версия сигнатур Defender), чтобы изменение обнаруживаемости можно было отнести к файлу, обновлению базы сигнатур или недетерминированному результату провайдера.
• Проверяет устойчивость сигнатур для авторизованных испытаний, изменяя обнаруженный образец (регистр, конкатенация, комментарий, пробелы) и сообщая, какие классы трансформаций уклоняются от обнаружения — ни один вариант никогда не записывается на диск.

Команды

¹ У этих двух команд есть опциональные внешние зависимости: Invoke-OffsetYaraScan требует движок YARA (winget install VirusTotal.YARA), а Invoke-OffsetClamScan требует ClamAV с базами сигнатур (winget install Cisco.ClamAV, затем freshclam). Все остальные команды автономны. Здесь ClamAV — детектор для одиночных файлов, а не движок поиска границ: clamscan загружает полную базу при каждом вызове, поэтому для бисекции потребовался бы демон clamd.

² Add-OffsetDriftEntry ведёт журнал кроссплатформенно, но поля версии сигнатур/движка Defender заполняются только в Windows (через Get-MpComputerStatus); в других системах они записываются как null, а остальная часть снимка всё равно сохраняется.

Ядро проверки смещений и все вспомогательные средства статической сортировки кроссплатформенны (Windows, Linux, macOS); провайдеры угроз AMSI/Defender доступны только в Windows.

Установка

PowerShell Gallery```powershell

Install-Module OffsetInspect -Scope CurrentUser Import-Module OffsetInspect

### Получение репозитория```powershell
git clone https://github.com/warpedatom/OffsetInspect.git
cd OffsetInspect
Import-Module ./module/OffsetInspect/OffsetInspect.psd1 -Force

Репозиторий также включает тонкие CLI-обёртки:```powershell ./OffsetInspect.ps1 ./OffsetThreatScan.ps1 -Engine AMSI

## Проверка смещения

### Человекочитаемый вывод```powershell
Invoke-OffsetInspect ./sample.bin 0x200

$ ls -l ~/.arduino15/packages/ATTinyCore/hardware/avr/1.5.2```powershell $inspectParameters = @{ FilePaths = './script.ps1' OffsetInputs = 128, 256, 512 ByteWindow = 64 ContextLines = 4 } Invoke-OffsetInspect @inspectParameters

### Структурированные объекты```powershell
$inspectParameters = @{
    FilePaths    = './script.ps1'
    OffsetInputs = 0x80, 0x100
    PassThru     = $true
}
$results = Invoke-OffsetInspect @inspectParameters

$results | Where-Object BytesDiffer

JSON и CSV```powershell

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

Режим JSON всегда выводит массив, в том числе для одного результата.

### Бинарное сравнение```powershell
$compareParameters = @{
    FilePaths    = './before.bin'
    OffsetInputs = 0x200
    CompareFile  = './after.bin'
    PassThru     = $true
}
Invoke-OffsetInspect @compareParameters

Форматы смещений

Числовые значения без префикса или суффикса намеренно интерпретируются как десятичные.

Режимы кодировки

В выводе указываются как BytePositionInLine, так и CharacterPosition. Это различие важно, когда исходный файл содержит многобайтовые символы.

Анализ границ угроз

Анализ через поставщика угроз доступен только в Windows. Обычная команда проверки смещений остаётся кроссплатформенной.

Сканирование текста AMSI```powershell

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

### AMSI-сканирование в режиме сырых байтов

Текстовый режим использует `AmsiScanString`, ищет префиксы, состоящие из скалярных значений Unicode, не разбивая суррогатные пары, пропускает обнаруженный префикс через проверенную кодировку источника и возвращает индексы скалярных значений Unicode, кодовых единиц UTF-16 и байтов исходного файла. Встроенные NUL-символы в текстовом режиме отклоняются; для таких файлов используйте режим сырых байтов.```powershell
Invoke-OffsetThreatScan ./content.bin -Engine AMSI -ScanMode RawBytes

Сканирование Microsoft Defender```powershell

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

Провайдер Defender:

- Определяет путь к платформе последнего установленного `MpCmdRun.exe`.
- Записывает префиксы в уникальный временный каталог пользователя.
- Использует специальное сканирование с `-DisableRemediation`.
- Рассматривает тайм-ауты, ошибки провайдера, локализованный/неизвестный вывод и неоднозначные маркеры как неопределённые.
- Удаляет временное рабочее пространство по завершении сканирования.

### Семантика границы

Результат вида `DetectionPrefixLength = 841` означает:

- Префикс длиной 840 был классифицирован как чистый/не обнаруженный.
- Префикс длиной 841 был классифицирован как обнаруженный/заблокированный.
- Повторные проверки определяют, стабилен ли этот переход.

Это **не** доказывает, что байт 840 является полной сигнатурой, единственным влияющим байтом или полным вредоносным диапазоном. Решения антивируса могут зависеть от токенизации, окружающего контекста, типа файла, состояния провайдера и обновлений сигнатур.

### Пример из практики: два движка, один файл

Сканирование одного и того же образца (PowerUp.ps1, публичный скрипт red-team, 445 954 байта) обоими провайдерами показывает, что такое граница и насколько можно доверять согласованности двух движков. AMSI в текстовом режиме:```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 в режиме raw-byte, тот же файл:```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.

Оба движка сходятся на **строке 4586** — граница обнаружения Defender попадает внутрь хвостового `it` в `Invoke-PrivescAudit`, а граница AMSI — на символ новой строки, завершающий ту же строку, двумя байтами позже. Ни одно из смещений не является «сигнатурой»: это самые ранние префиксы, которые каждый провайдер всё ещё помечает, а расхождение в два байта — ровно тот эффект токенизации/контекста, что описан выше. Defender дополнительно называет то, с чем произошло совпадение (`Trojan:Win32/Kepavll!rfn`); AMSI не сообщает имени сигнатуры, именно поэтому существуют `Invoke-OffsetThreatScanRegion` и `Get-OffsetDetectionTrigger` для характеристики срабатывания AMSI.

Оба сканирования обошлись в 25 проб провайдера для файла размером ~436 КиБ — биссекция логарифмична по размеру файла, и каждая проба фиксируется в `ProbeLog`.

См. [проектирование сканирования угроз](https://github.com/warpedatom/offsetinspect/blob/HEAD/docs/THREAT-SCANNING.md) — контракт провайдера и рекомендации по интерпретации, [интерфейс провайдера](https://github.com/warpedatom/offsetinspect/blob/HEAD/docs/PROVIDER-INTERFACE.md) — контракт сканера и о том, как добавить провайдера, не затрагивая ядро поиска, [происхождение результатов сканирования угроз](https://github.com/warpedatom/offsetinspect/blob/HEAD/docs/PROVENANCE.md) — границы реализации и атрибуцию, а также [схему выходных данных](https://github.com/warpedatom/offsetinspect/blob/HEAD/docs/OUTPUT-SCHEMA.md) — версионируемый контракт объектов.

### Отчёты о границах обнаружения

`Export-OffsetThreatReport` превращает один или несколько результатов сканирования в автономный отчёт Markdown или HTML — сводку по каждому файлу, метаданные провайдера/сигнатуры/движка, полный журнал аудита `ProbeLog` и предупреждения — для прикрепления к отчёту о тестировании. Он только читает результаты и никогда не пересканирует, поэтому работает кроссплатформенно. Добавьте `-IncludeIoc`, чтобы включить панель индикаторов хеша/энтропии/PE (те же данные, что и `Get-OffsetIOC`) в каждую запись отчёта, и `-IncludeTrigger`, чтобы добавить анализ триггера обнаружения (см. ниже) для каждого результата с границей.```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

Для отчётов корпусного масштаба -IncludeIoc повторно сканирует каждый файл в PowerShell, что медленно. Вспомогательный нативный движок OffsetScan генерирует схематически идентичный IOC JSON гораздо быстрее; укажите на него в отчёте с помощью -IocJsonPath, и он будет брать данные для каждой панели из этого JSON (возвращаясь к живому Get-OffsetIOC только для файлов, отсутствующих в нём):```powershell offsetscan ioc ./corpus --recurse > ./ioc.json $results | Export-OffsetThreatReport -Path ./engagement.md -IocJsonPath ./ioc.json

### Пакетное / корпусное сканирование

`Invoke-OffsetThreatScanBatch` раскрывает файлы, каталоги и подстановочные знаки в список файлов, сканирует каждый (продолжая работу, несмотря на сбои по отдельным файлам) и возвращает по одному результату на файл. `-Summary` возвращает сводную матрицу обнаружений; полные результаты передаются напрямую в генератор отчётов. Сканирование провайдеров доступно только в 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

Дифф обнаружения / регрессия

Compare-OffsetThreatResult сравнивает два результата сканирования — например, один и тот же файл до и после обновления сигнатур — и классифицирует изменение (NewlyDetected, NoLongerDetected, BoundaryEarlier, BoundaryLater, BoundaryUnchanged, BothClean) с указанием дельты границы и изменённых полей.```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

### Multi-region discovery

The prefix search finds the *first* detection boundary. `Invoke-OffsetThreatScanRegion` finds *multiple* independently-detectable regions by splitting the file into segments and scanning each in isolation through AMSI **entirely in memory** - nothing detected is written to disk, so Defender real-time protection is never triggered or reconfigured. Each hit is bisected within its segment to map the exact triggering boundary to an absolute file offset.

---

### Обнаружение нескольких регионов

Префиксный поиск находит *первую* границу обнаружения. `Invoke-OffsetThreatScanRegion` находит *несколько* независимо обнаруживаемых регионов, разбивая файл на сегменты и сканируя каждый по отдельности через AMSI **полностью в памяти** — ничто из обнаруженного не записывается на диск, поэтому защита в реальном времени Defender никогда не срабатывает и не перенастраивается. Каждое срабатывание бисекционно делится в пределах своего сегмента, чтобы сопоставить точную границу срабатывания с абсолютным смещением в файле.```powershell
Invoke-OffsetThreatScanRegion ./payload.bin -SegmentCount 16 |
    Select-Object -ExpandProperty DetectedRegions |
    Format-Table SegmentIndex, StartOffset, EndOffset, AbsoluteBoundaryOffset, SignatureName

Этот отчёт показывает области, которые срабатывают сами по себе; он может пропустить сигнатуры, которые срабатывают только в контексте всего файла или пересекают границу сегмента, поэтому относитесь к областям как к зацепкам, которые нужно подтверждать с помощью Invoke-OffsetThreatScan и ручной проверки. Здесь поддерживается только AMSI (в памяти) как движок — сканирование файлов Defender потребовало бы записи обнаруженного содержимого на диск.

Корреляция триггера обнаружения

Граница говорит вам, где срабатывает детект; Get-OffsetDetectionTrigger говорит, что там находится. Поскольку граница префикса — это последний байт самого раннего обнаруженного префикса, срабатывающее содержимое — это последовательность, заканчивающаяся на этом смещении. Команда сообщает секцию PE, в которую попадает граница, энтропию последовательности до неё (открытый текст против упакованного/закодированного), и извлечённые строки, заканчивающиеся на ней или пересекающие её, ранжированные по близости — содержимое кандидатной сигнатуры — с однострочной интерпретацией. Она читает только байты и никогда не пересканирует, поэтому работает кроссплатформенно на сохранённых результатах.```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

### Журнал дрейфа обнаружения

«Раньше обнаруживалось, а теперь нет» — это три совершенно разные причины: файл изменился, сигнатуры изменились или провайдер недетерминирован. `Add-OffsetDriftEntry` записывает NDJSON-снимки с добавлением в конец — SHA-256 файла, статус, граница, имя сигнатуры и локальные версии сигнатур/движка Defender, — а `Get-OffsetDrift` читает эту историю и относит каждое изменение к правильной причине.```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

Каждый переход маркируется: изменение SHA-256 интерпретируется как изменение файла; изменение статуса при неизменном файле, но с изменившейся версией сигнатур Defender интерпретируется как дрейф сигнатур; изменение статуса без того и другого интерпретируется как недетерминированный результат провайдера. Журнал по умолчанию сохраняется в %LOCALAPPDATA%\OffsetInspect\drift.ndjson; переопределить его можно с помощью -JournalPath.

Проверка устойчивости сигнатур (только при авторизованном использовании)

Invoke-OffsetMutationTest отвечает на вопрос из области детект-инжиниринга: является ли сигнатура хрупким точным совпадением с литералом или же она устойчива к распространённым методам обфускации? При наличии образца, который AMSI в настоящее время обнаруживает, команда применяет стандартные модификации — инверсию регистра, конкатенацию строковых литералов, вставку комментариев, внедрение пробелов — и повторно сканирует каждый вариант, чтобы сообщить, какие классы модификаций нейтрализуют обнаружение. Всё происходит в памяти через внутрипроцессный интерфейс AMSI; ни один вариант не записывается на диск, поэтому не создаётся эвазивных артефактов, а защита в реальном времени Defender не задействуется. Команда отказывается запускаться без -AuthorizedEngagement и предназначена только для образцов, которые вам разрешено тестировать.```powershell Invoke-OffsetMutationTest -FilePath ./flagged.ps1 -AuthorizedEngagement | Select-Object RobustnessSummary -ExpandProperty Results

Результат, скажем, "brittle: neutralized by StringConcatenation, CommentInsertion" сообщает защитнику, что сигнатура завязана на непрерывный литерал и должна быть расширена; авторизованному оператору он сообщает то же самое о покрытии контроля.

### Корреляция телеметрии

Обнаружение границы говорит вам о том, что видит *движок*; `-CaptureTelemetry` сообщает вам о том, что видит *защитник*. Он фиксирует верхнюю отметку каждого доступного журнала телеметрии Windows до сканирования, а затем сообщает, вызвало ли действие оповещение, с каким контекстом и какие источники были слепыми - вопрос «предполагай видимость, затем проверяй её», на который дан ответ с доказательствами.```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

Свойство Telemetry (OffsetInspect.TelemetryCorrelation) сообщает:

• AlertGenerated / Alert — была ли зарегистрирована для сканирования детекция Microsoft Defender (событие 1116/1117) и её контекст (имя угрозы, уровень серьезности, источник детекции, процесс, пользователь).
• CorrelationConfidence — High только когда источник детекции совпадает с провайдером и её процесс совпадает с хостом сканирования, так что случайная совпавшая по времени детекция никогда не заявляется; Medium — только по источнику; Low — если не совпадает ни то, ни другое.
• SourcesAccessible / SourcesUnavailable — какие журналы телеметрии были читаемы, а какие недоступны (Sysmon отсутствует, журнал безопасности требует повышения привилегий). Пробел видимости сам по себе является находкой.
• Findings — выводы на простом языке: оповещение с полным контекстом, оповещение без имени угрозы, полное отсутствие телеметрии или отсутствующий источник.

Основной источник — журнал операций Microsoft Defender, читаемый без повышения привилегий; корреляция осуществляется по RecordId события (монотонный и не зависящий от часового пояса). Только для Windows и неактивен, если не передан -CaptureTelemetry.

Статические вспомогательные команды для триажа

Три кроссплатформенных команды статического анализа поддерживают триаж вредоносных программ и сочетаются с ядром поиска по смещениям:

• Get-OffsetEntropy — для каждого окна энтропия Шеннона (бит/байт) для поиска упакованных или зашифрованных областей; сверяйте отмеченные окна с детекциями Invoke-OffsetThreatScanRegion.
• Get-OffsetString — печатные строки ASCII и UTF-16LE со смещениями в байтах; передавайте смещения в Invoke-OffsetInspect для контекста.
• Get-OffsetPEInfo — машинный тип/разрядность PE, точка входа, таблица секций, импорты и imphash, определение дописанного оверлея и размер ресурсов, с -Offset, сопоставляющим байтовое смещение с его секцией (.text, .rsrc, ...). Imphash использует стандартный MD5 в формате library.function и побайтово совпадает с pefile/VirusTotal — включая разрешение ординалов из специальных библиотек, поэтому ординал, импортированный из ws2_32/wsock32/oleaut32, разрешается в реальное имя функции; все остальные ординарные импорты отображаются как , точно как в pefile.

### YARA-сканирование

`Invoke-OffsetYaraScan` выполняет YARA-правила, написанные аналитиком, и возвращает каждое совпадение с его байтовым смещением — дополняя картину границ обнаружения AMSI/Defender сигнатурами, которыми вы управляете, и не требуя установленного антивируса (только YARA-движок, например, `winget install VirusTotal.YARA`). Смещения напрямую передаются в инспектор.```powershell
Invoke-OffsetYaraScan ./sample.bin -RulePath ./rules/malware.yar |
    ForEach-Object { Invoke-OffsetInspect $_.File $_.Offset -ContextLines 2 }

Сканирование ClamAV

Invoke-OffsetClamScan сканирует файл с помощью движка ClamAV по требованию и возвращает нормализованный результат (Clean / Detected / Error, а также имя сигнатуры). Поскольку clamscan загружает полную базу сигнатур при каждом вызове, это детектор одиночных файлов, а не движок поиска по границам (для этого потребовался бы демон clamd). Ему требуется установленный ClamAV и загруженные базы сигнатур - freshclam не запустится, пока не будет существовать файл конфигурации:```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

Используйте `-DatabasePath`, чтобы указать каталог сигнатур в доступном для записи месте (без прав администратора), и `-ClamScanPath`, если `clamscan` отсутствует в `PATH`.

## Объекты результатов

`Invoke-OffsetInspect -PassThru` возвращает объекты `OffsetInspect.Result`, содержащие:

- Канонический путь к файлу, размер файла, десятичные и шестнадцатеричные смещения.
- Запрошенную и обнаруженную кодировки.
- Номер строки, предпросмотр исходного текста, строки контекста, позицию байта и позицию символа.
- Целевой байт и ограниченный hex-дамп.
- Необязательный сравниваемый байт и состояние расхождения.
- Предупреждения, длительность, состояние успеха и сообщение об ошибке.

`Invoke-OffsetThreatScan -PassThru` возвращает объекты `OffsetInspect.ThreatScanResult`, содержащие:

- SHA-256 файла, UTC-временную метку сканирования, движок, режим сканирования, исходный статус провайдера и метаданные провайдера.
- Длины префиксов заведомо чистых и заведомо обнаруженных объектов.
- Границу по байтам и, опционально, по символам.
- Стабильность, уверенность, количество сканирований, повторяющиеся статусы границ и имя сигнатуры, если доступно.
- Аудиторский след `ProbeLog` для каждого отдельного запроса к провайдеру (отображается как `ProbeCount` в CSV-выводе и может быть экспортирован в JSON-транскрипт с помощью `-ProbeLogPath`); см. [схему вывода](https://github.com/warpedatom/offsetinspect/blob/HEAD/docs/OUTPUT-SCHEMA.md).
- Вложенный контекст `OffsetInspect.Result` на сопоставленной границе.

## Модель производительности

Реализация в стиле v1 перечитывала и декодировала полный файл для каждого смещения. Версия 2 группирует работу по файлам:```text
Previous approach: approximately O(file size × offset count)
Version 2:         approximately O(file bytes scanned once + requested windows)

Сопоставление исходного кода использует потоковый конечный автомат и сохраняет только дескрипторы предыдущих/последующих строк, необходимые для запрошенных смещений. Чрезвычайно длинные отдельные строки отображаются через ограниченный предпросмотр, управляемый -MaxLineBytes.

Структура репозитория```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

## Разработка

Установите закреплённые инструменты валидации:```powershell
Install-Module Pester -RequiredVersion 5.7.1 -Scope CurrentUser
Install-Module PSScriptAnalyzer -RequiredVersion 1.25.0 -Scope CurrentUser

Запустите полную локальную проверку:```powershell ./build/Test-Module.ps1

Запустите детерминированный испытательный стенд:```powershell
./benchmarks/Measure-OffsetInspect.ps1 -FileSizeMiB 64 -OffsetCount 5000

Результаты бенчмарков зависят от хранилища, нагрузки на хост, редакции PowerShell и формы файла. Записывайте эти входные данные при сравнении коммитов.

Соберите детерминированный архив релиза и файл SHA-256:```powershell ./build/New-ReleasePackage.ps1

CI проверяет PowerShell 7 в Windows и Linux, Windows PowerShell 5.1, PSScriptAnalyzer, изолированную упаковку модулей и архив релиза. Сопровождающие выпуск также должны следовать [списку проверок релиза](https://github.com/warpedatom/offsetinspect/blob/HEAD/docs/RELEASE-CHECKLIST.md).

## Безопасность и ответственное использование

OffsetInspect предназначен для авторизованных оборонительных исследований, разработки детектирования, реверс-инжиниринга, анализа вредоносных программ и тестирования безопасности. Функции, предоставляющие информацию об угрозах, анализируют содержимое, но не отключают, не обходят и не перенастраивают защиту конечных точек.

`Invoke-OffsetMutationTest` создаёт варианты обхода детектирования для оценки устойчивости сигнатур. Он работает полностью в памяти (ни один вариант не записывается на диск) и отказывается запускаться без явного подтверждения `-AuthorizedEngagement`. Используйте его только с образцами и контрольными объектами, которые вам разрешено тестировать.

Ознакомьтесь с [SECURITY.md](https://github.com/warpedatom/offsetinspect/blob/HEAD/SECURITY.md) перед сообщением об уязвимости. Не отправляйте конфиденциальные образцы через публичные GitHub issues.

## Лицензия

OffsetInspect распространяется под [лицензией MIT](https://github.com/warpedatom/offsetinspect/blob/HEAD/LICENSE).