OffsetInspect

一个用于字节偏移检查、源码关联、二进制比较和防御性检测边界分析的有界内存 PowerShell 工具包。

OffsetInspect 回答了一个实际的分析师问题：

在此字节偏移处存在什么内容？其周围是什么源码或二进制上下文？

它还提供了 OffsetInspect 原生的检测边界工作流，其灵感来自 ThreatCheck 所解决的同一个分析师问题，但并未捆绑其源码或二进制文件：它会定位 AMSI 或 Microsoft Defender 仍能检测到的最早内容前缀，反复验证该边界，并将得到的偏移直接送入上下文检查器。在此核心之上，它增加了红队分析与静态分诊套件——多区域发现、语料库扫描、检测差异对比、检测触发关联、漂移日志、交战报告、熵分析、字符串提取以及 PE/imphash 解析——全部为只读操作，另有一个仅供授权使用的签名稳健性测试器，仅在内存中扰动样本，且从不禁用或重新配置端点保护。

配套工具

如需在没有 PowerShell 开销的情况下进行语料库规模的静态分诊（PE 解析、熵、字符串、IOC），请参阅 OffsetScan——一个使用相同 JSON 输出模式的原生 Rust 二进制程序。OffsetInspect 3.1.0+ 可直接通过 -IocJsonPath 摄取 OffsetScan IOC JSON。

亮点

• 通过稳定的读取句柄打开每个唯一的检查文件，并一并处理所有请求的偏移。
• 使用有界内存的流式传递进行行映射，而不是为每个偏移重新读取整个文件。
• 仅读取请求的字节窗口用于十六进制输出和比较。
• 将 UTF-8 和 UTF-16 字节偏移映射到源行和字符位置。
• 通过 -ContextLines 实现前后源码上下文。
• 支持 human、object、JSON、CSV 和 CSV 文件输出约定。
• 支持一对多、多对一以及成对的文件/偏移方案。
• 在不重复加载第二个文件的情况下，将目标字节与第二个文件进行比较。
• 增加了一个独立实现的 AMSI 和 Microsoft Defender 提供程序层，具有明确的错误、超时、阻止和不确定状态。
• 记录每次不同的提供程序调用的逐探针审计跟踪（ProbeLog/ProbeCount），并实时流式输出到 -Verbose，为扫描的真实提供程序成本提供可直接用于报告的记录。
• 通过内存 AMSI 扫描发现单个文件中的多个可独立检测区域（检测到的任何内容都不会写入磁盘），并将每个边界映射到绝对偏移。
• 将语料库扫描为合并的检测矩阵，比较两次扫描之间的检测差异，并导出 Markdown/HTML 交战报告（可选由原生 OffsetScan 引擎的 JSON 提供语料库规模的 IOC 面板）。
• 将检测边界与其产生的内容关联起来——PE 节、到边界为止的运行熵，以及终止于/跨越该边界的字符串，作为候选签名内容。
• 随时间记录检测日志（文件哈希和本地 Defender 签名版本），以便将可检测性的变化归因于文件、签名数据库更新或非确定性提供程序结果。
• 通过在内存中扰动检测到的样本（大小写、串联、注释、空白）来测试授权交战的签名稳健性，并报告哪些转换类别可绕过——任何变体都不会写入磁盘。
• 将扫描与其生成的 Windows 遥测关联起来（-CaptureTelemetry）：是否触发了 Microsoft Defender 警报、带有什么上下文，以及哪些遥测源是盲区——体现了“假定可见性，然后验证它”的原则。只读、非管理员、仅限 Windows。
• 添加静态恶意软件分诊辅助功能：逐窗口熵（加壳/加密区域）、带偏移的 ASCII/UTF-16LE 字符串提取，以及带 imphash 和覆盖检测的 PE 头/节/导入解析。
• 验证 Authenticode 来源（Get-OffsetSignature）：使用平台的真实信任验证，报告文件是否有效签名且受信任、由谁签名，以及是嵌入签名还是目录签名——这是一个签名者信号，补充了 imphash 和构建工具链指纹（导入与工具链与签名者）。仅限 Windows。
• 绝不更改 Defender 排除项、实时保护或系统安全配置。
• 以自包含的 PowerShell Gallery 包形式发布，无外部运行时依赖；YARA 和 ClamAV 扫描是仅有的可选例外，各自需要独立的外部引擎。

命令

¹ 这两个命令有可选的外部依赖：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

## Offset inspection

### Human-readable output```powershell
Invoke-OffsetInspect ./sample.bin 0x200

• SecuSphere - SecuSphere是一个全面、高效的DevSecOps平台，贯穿整个SDLC。SecuSphere通过在一个统一的框架内集成开发、安全与运维，从根本上转变了组织保护软件系统安全的方式。该平台对整个SDLC进行集中管理，包括漏洞管理、安全测试、合规以及DevSecOps工作流，将设计、架构、实施及防护融为一体，从而以前所未有的方式提升运营效率与安全标准。

• Cobra - Cobra是一个能够通过输入路径列表，自动为特定路径生成定制字典的Golang工具，用于模糊测试。Cobra是一个用于生成定制字典的灵活模糊测试工具，它通过CLI路径或文件中的路径列表进行输入。它会自动扫描路径内的关键词，并匹配相关扩展生成输出，从而构建字典。

• Vigilant - Vigilant是一个用于检测Web应用程序的变更、监控其内容完整性、抓取屏幕截图并进行全文搜索的工具。

• Tantiny - Tantiny是一款基于Tantivy的最小化全文搜索Ruby库。Tantiny是一个受Tantivy和SQLite架构研究启发的Ruby gem包。Tantiny允许你在Ruby/Ruby on Rails环境中使用全文搜索功能。不同于使用FFI或为Tantivy做C绑定，它利用了Tantivy的Ruby绑定。

• Kali Linux Tools - 一键式Kali Linux工具安装，实现自动化安装，为渗透测试人员节省时间。该项目旨在自动化执行这些任务，为渗透测试人员提供一种快速简便的方式来安装Kali Linux上使用的工具。

• Whitewidow - Whitewidow是一个开源的自动化SQL漏洞扫描工具，能够处理文件列表，并可以在Google上轻松搜索潜在的易受攻击网站。

• Megatron - Megatron是（相对）安全地管理AWS账户权限的最简单方法。

• Webkiller - 输入你的目标域名，让工具通过分析Whois信息、DNS记录、HTTP头部、SSL/TLS证书等方式为你完成所有渗透测试。```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

Text mode uses `AmsiScanString`, searches Unicode-scalar prefixes without splitting surrogate pairs, maps the detected prefix through the validated source encoding, and returns Unicode-scalar, UTF-16 code-unit, and source-file byte indexes. Embedded NUL characters are rejected in text mode; use raw-byte mode for those files.

### AMSI raw-byte scan

文本模式使用 `AmsiScanString`，在不拆分代理对的情况下搜索 Unicode 标量前缀，将检测到的前缀通过已验证的源编码进行映射，并返回 Unicode 标量、UTF-16 代码单元和源文件字节索引。文本模式会拒绝嵌入式 NUL 字符；对于此类文件，请使用原始字节模式。

### AMSI 原始字节扫描```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

The Defender provider:

- Resolves the newest installed `MpCmdRun.exe` platform path.
- Writes prefixes to a unique user temporary directory.
- Uses a custom scan with `-DisableRemediation`.
- Treats timeouts, provider errors, localized/unknown output, and ambiguous markers as non-definitive.
- Deletes the temporary workspace when scanning completes.

### Boundary semantics

A result such as `DetectionPrefixLength = 841` means:

- Prefix length 840 was classified as clean/not detected.
- Prefix length 841 was classified as detected/blocked.
- Repeated checks determine whether that transition is stable.

It does **not** prove that byte 840 is the complete signature, the only contributing byte, or the full malicious range. Antivirus decisions may depend on tokenization, surrounding context, file type, provider state, and signature updates.

### Worked example: two engines, one file

Scanning the same sample (PowerUp.ps1, a public red-team script, 445,954 bytes) with both providers shows what a boundary is and how far two engines can be trusted to agree. AMSI in text mode:```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，同一文件：```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 的边界落在 `Invoke-PrivescAudit` 尾部 `it` 的内部，而 AMSI 的边界落在终止同一行的换行符上，晚两个字节。这两个偏移都不是“签名”：它们是每个提供程序仍会标记的最早前缀，而这两个字节的差异正是上文所述的标记化/上下文效应。Defender 还会指明其匹配的内容（`Trojan:Win32/Kepavll!rfn`）；AMSI 不报告签名名称，这正是 `Invoke-OffsetThreatScanRegion` 和 `Get-OffsetDetectionTrigger` 存在的原因，用于描述 AMSI 命中。

两次扫描对一个约 436 KiB 的文件进行了 25 次提供程序探测 - 二分查找与文件大小呈对数关系，每次探测都会记录在 `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 能以快得多的速度生成 schema 相同的 IOC JSON；使用 -IocJsonPath 让报告指向该 JSON，即可让每个面板都从该 JSON 中获取数据（仅对其中缺失的文件回退到实时的 Get-OffsetIOC）：```powershell offsetscan ioc ./corpus --recurse > ./ioc.json $results | Export-OffsetThreatReport -Path ./engagement.md -IocJsonPath ./ioc.json

### 批量 / 语料库扫描

`Invoke-OffsetThreatScanBatch` 将文件、目录和通配符展开为文件列表，逐个扫描（即使单个文件失败也会继续），并为每个文件返回一个结果。`-Summary` 返回扁平化的检测矩阵；完整结果可直接通过管道送入报告生成器。Provider 扫描仅适用于 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

### 多区域发现

前缀搜索会找到*第一个*检测边界。`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 缺失，Security 日志需要提升权限）。可见性缺口本身就是一个发现。
• Findings - 用简明语言给出的结论：具有完整上下文的告警、缺少威胁名称的告警、完全没有遥测，或缺少来源。

主要来源是 Microsoft Defender Operational 日志，无需提升权限即可读取；关联依据是事件的 RecordId（单调且与时区无关）。仅限 Windows，且除非传入 -CaptureTelemetry，否则不生效。

静态分流辅助工具

三个跨平台静态分析命令支持恶意软件分流，并与偏移核心组合使用：

• Get-OffsetEntropy - 逐窗口计算香农熵（位/字节），用于定位加壳或加密区域；将标记的窗口与 Invoke-OffsetThreatScanRegion 检测结果交叉对照。
• Get-OffsetString - 提取带有字节偏移的可打印 ASCII 和 UTF-16LE 字符串；可将偏移通过管道传递给 Invoke-OffsetInspect 以获取上下文。
• Get-OffsetPEInfo - PE 机器类型/位数、入口点、节表、导入和 imphash、追加的 overlay 检测，以及资源大小；使用 -Offset 可将字节偏移映射到其所属节（.text、.rsrc、...）。Imphash 使用标准的 library.function MD5，并已验证与 pefile/VirusTotal 逐字节一致——包括特殊库的序号解析，因此从 ws2_32/wsock32/oleaut32 导入的序号会解析为真实函数名；其他所有序号导入均呈现为 ordNNN，与 pefile 的行为完全一致。
• Get-OffsetIOC - 一次性指标面板，综合以上功能：MD5/SHA-1/SHA-256（单遍）、整体熵、可打印字符串数量，以及适用的 PE 机器类型/imphash/overlay。```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

### 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` 指向可写（非管理员）位置的签名目录；如果 `clamscan` 不在 `PATH` 中，则使用 `-ClamScanPath`。

## 结果对象

`Invoke-OffsetInspect -PassThru` 返回 `OffsetInspect.Result` 对象，其中包含：

- 规范文件路径、文件大小、十进制和十六进制偏移量。
- 请求的编码与检测到的编码。
- 行号、源预览、上下文行、字节位置和字符位置。
- 目标字节及有界十六进制转储。
- 可选的比较字节和差异状态。
- 警告、持续时间、成功状态和错误消息。

`Invoke-OffsetThreatScan -PassThru` 返回 `OffsetInspect.ThreatScanResult` 对象，其中包含：

- 文件 SHA-256、UTC 扫描时间戳、引擎、扫描模式、初始提供商状态和提供商元数据。
- 已知干净和已知检测的前缀长度。
- 字节边界及可选的字符边界。
- 稳定性、置信度、扫描次数、重复边界状态，以及可用时的签名名称。
- 一个 `ProbeLog` 审计跟踪，记录每个不同的提供商探测（在 CSV 输出中显示为 `ProbeCount`，并可通过 `-ProbeLogPath` 导出为 JSON 记录）；请参阅 [输出模式](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 在 Windows 和 Linux 上验证 PowerShell 7、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 issue 提交敏感样本。

## 许可证

OffsetInspect 根据 [MIT 许可证](https://github.com/warpedatom/offsetinspect/blob/HEAD/LICENSE) 发布。