OffsetInspect

바이트 오프셋 검사, 소스 상관관계, 바이너리 비교, 방어 탐지 경계 분석을 위한 한정된 메모리(bounded-memory) PowerShell 툴킷입니다.

OffsetInspect는 실무 분석가의 질문에 답합니다:

이 바이트 오프셋에는 어떤 콘텐츠가 있으며, 그 주변에는 어떤 소스 또는 바이너리 컨텍스트가 있을까요?

또한 ThreatCheck가 다루는 동일한 분석 문제에서 영감을 얻은 OffsetInspect 고유의 탐지 경계 워크플로를 제공하되, ThreatCheck의 소스나 바이너리를 번들로 포함하지 않습니다. AMSI 또는 Microsoft Defender가 여전히 탐지하는 가장 빠른 콘텐츠 접두사를 찾아내고, 그 경계를 반복 검증한 다음, 그 결과 오프셋을 컨텍스트 검사기에 직접 전달합니다. 이 핵심 위에 다중 영역 발견, 코퍼스 스캔, 탐지 비교(diff), 탐지 트리거 상관관계, 드리프트 저널링, 참여 보고서, 엔트로피 분석, 문자열 추출, 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 전용.

명령어

¹ 이 두 명령은 선택적 외부 의존성이 있습니다: 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 갤러리```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

The input chunk is empty — no content was provided to translate. Please supply the markdown text for chunk 9 of 63.```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

오프셋 형식

접두사나 접미사가 없는 숫자로만 구성된 값은 의도적으로 10진수로 처리됩니다.

인코딩 모드

출력은 BytePositionInLine과 CharacterPosition을 모두 보고합니다. 이 구분은 소스 파일에 멀티바이트 문자가 포함된 경우 중요합니다.

위협 경계 분석

위협 공급자 분석은 Windows 전용입니다. 일반 오프셋 검사 명령은 크로스 플랫폼을 유지합니다.

AMSI 텍스트 스캔```powershell

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

텍스트 모드는 `AmsiScanString`을 사용하며, 서로게이트 쌍을 분할하지 않고 유니코드 스칼라 접두사를 검색하고, 감지된 접두사를 검증된 소스 인코딩을 통해 매핑하며, 유니코드 스칼라, UTF-16 코드 유닛, 소스 파일 바이트 인덱스를 반환합니다. 텍스트 모드에서는 포함된 NUL 문자가 거부됩니다. 해당 파일에는 raw-byte 모드를 사용하십시오.

### AMSI raw-byte 스캔```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 공급자:

- 설치된 최신 `MpCmdRun.exe` 플랫폼 경로를 확인합니다.
- 고유한 사용자 임시 디렉터리에 접두어를 기록합니다.
- `-DisableRemediation`을 사용한 사용자 지정 검사를 수행합니다.
- 시간 초과, 공급자 오류, 지역화/알 수 없는 출력 및 모호한 표시를 비확정적으로 처리합니다.
- 검사가 완료되면 임시 작업 공간을 삭제합니다.

### 경계 의미론

`DetectionPrefixLength = 841`과 같은 결과는 다음을 의미합니다.

- 접두어 길이 840은 클린/미검출로 분류되었습니다.
- 접두어 길이 841은 검출/차단으로 분류되었습니다.
- 반복 검사는 해당 전환이 안정적인지 여부를 결정합니다.

이는 바이트 840이 완전한 서명이거나, 유일한 기여 바이트이거나, 전체 악성 범위라는 것을 **증명하지는 않습니다**. 백신 판정은 토큰화, 주변 컨텍스트, 파일 형식, 공급자 상태 및 서명 업데이트에 따라 달라질 수 있습니다.

### 실제 예: 두 엔진, 하나의 파일

동일한 샘플(PowerUp.ps1, 공개 레드팀 스크립트, 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
                                                       ^

raw-byte 모드의 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의 경계는 같은 줄을 종료하는 개행 문자에 위치하며, 2바이트 뒤입니다. 두 오프셋 모두 "시그니처"가 아닙니다. 이들은 각 공급자가 여전히 탐지한 가장 이른 접두사이며, 2바이트의 차이는 앞서 설명한 토큰화/컨텍스트 효과와 정확히 일치합니다. Defender는 추가로 매칭한 대상(`Trojan:Win32/Kepavll!rfn`)의 이름을 제공합니다. AMSI는 시그니처 이름을 보고하지 않으므로, AMSI 적중을 특성화하기 위해 `Invoke-OffsetThreatScanRegion`과 `Get-OffsetDetectionTrigger`가 존재합니다.

두 스캔 모두 약 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

For corpus-scale reports, -IncludeIoc re-scans every file in PowerShell, which is slow. The companion native engine OffsetScan emits schema-identical IOC JSON far faster; point the report at it with -IocJsonPath and it sources each panel from that JSON (falling back to a live Get-OffsetIOC only for files absent from it):

For corpus-scale reports, -IncludeIoc re-scans every file in PowerShell, which is slow. The companion native engine OffsetScan emits schema-identical IOC JSON far faster; point the report at it with -IocJsonPath and it sources each panel from that JSON (falling back to a live Get-OffsetIOC only for files absent from it):```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

### 다중 영역 검색

접두사 검색은 *첫 번째* 탐지 경계를 찾습니다. `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 섹션, 경계까지의 연속 구간의 엔트로피(평문 vs 패킹/인코딩), 그리고 경계에서 끝나거나 경계에 걸쳐 있는 추출된 문자열을 근접도 순으로 정렬하여 보고합니다. 이 문자열들이 후보 시그니처 콘텐츠이며, 한 줄 해석과 함께 제공됩니다. 바이트만 읽고 다시 스캔하지 않으므로, 저장된 결과에 대해 크로스 플랫폼으로 실행됩니다.```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

### 탐지 드리프트 저널

"'이전에는 탐지되었는데 지금은 탐지되지 않는다'는 세 가지 매우 다른 원인이 있습니다: 파일이 변경되었거나, 시그니처가 변경되었거나, 제공자가 비결정적(non-deterministic)인 경우입니다. `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

The Telemetry property (OffsetInspect.TelemetryCorrelation) reports:

Telemetry 속성(OffsetInspect.TelemetryCorrelation)은 다음을 보고합니다:

• AlertGenerated / Alert - whether a Microsoft Defender detection (event 1116/1117) was logged for the scan, and its context (threat name, severity, detection source, process, user).

• AlertGenerated / Alert - 스캔에 대해 Microsoft Defender 탐지(이벤트 1116/1117)가 기록되었는지와 해당 컨텍스트(위협 이름, 심각도, 탐지 소스, 프로세스, 사용자)를 나타냅니다.

• CorrelationConfidence - High only when the detection's source matches the provider and its process matches the scanning host, so a coincidental concurrent detection is never claimed; Medium on source alone; Low on neither.

• CorrelationConfidence - 탐지 소스가 공급자와 일치 하고 해당 프로세스가 스캔 호스트와 일치하는 경우에만 High로 표시되어, 우연한 동시 탐지가 절대 주장되지 않습니다. 소스만 일치하면 Medium, 둘 다 일치하지 않으면 Low입니다.

• SourcesAccessible / SourcesUnavailable - which telemetry logs were readable and which were blind (Sysmon absent, the Security log requiring elevation). A visibility gap is itself a finding.

• SourcesAccessible / SourcesUnavailable - 읽을 수 있었던 텔레메트리 로그와 확인할 수 없었던 로그(Sysmon 부재, 상승된 권한이 필요한 Security 로그)를 나타냅니다. 가시성 공백 자체가 하나의 발견 사항입니다.

The primary source is the Microsoft Defender Operational log, readable without elevation; correlation is by event RecordId (monotonic and timezone-independent). Windows-only, and inert unless -CaptureTelemetry is passed.

기본 소스는 상승된 권한 없이 읽을 수 있는 Microsoft Defender 운영(Operational) 로그입니다. 상관 관계는 이벤트 RecordId(단조 증가, 시간대 독립적)를 기준으로 합니다. Windows 전용이며 -CaptureTelemetry가 전달되지 않으면 비활성 상태입니다.

Static triage helpers

정적 트라이지지 도우미

Three cross-platform static-analysis commands support malware triage and compose with the offset core:

세 가지 크로스 플랫폼 정적 분석 명령이 악성코드 트라이지지를 지원하며 오프셋 코어와 함께 사용할 수 있습니다:

• Get-OffsetEntropy - per-window Shannon entropy (bits/byte) to locate packed or encrypted regions; cross-reference the flagged windows with Invoke-OffsetThreatScanRegion detections.

• Get-OffsetEntropy - 패킹되거나 암호화된 영역을 찾기 위한 윈도우별 섀넌 엔트로피(비트/바이트). 플래그된 윈도우를 Invoke-OffsetThreatScanRegion 탐지와 상호 참조하십시오.

• Get-OffsetString - printable ASCII and UTF-16LE strings with byte offsets; pipe offsets into Invoke-OffsetInspect for context.

• Get-OffsetString - 바이트 오프셋이 포함된 인쇄 가능한 ASCII 및 UTF-16LE 문자열. 컨텍스트를 위해 오프셋을 Invoke-OffsetInspect로 파이프하십시오.

• Get-OffsetPEInfo - PE machine/bitness, entry point, section table, imports and imphash, appended-overlay detection, and resource size, with -Offset mapping a byte offset to its section (.text, , ...). Imphash uses the standard MD5 and is verified byte-identical to pefile/VirusTotal - including special-library ordinal resolution, so an ordinal imported from // resolves to its real function name; every other ordinal import renders , exactly as pefile does.

### 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

Use `-DatabasePath`를 사용하여 쓰기 가능한(관리자가 아닌) 위치의 서명 디렉터리를 가리키고, `clamscan`이 `PATH`에 없으면 `-ClamScanPath`를 사용하세요.

## Result objects

`Invoke-OffsetInspect -PassThru`는 다음을 포함하는 `OffsetInspect.Result` 개체를 반환합니다:

- 정규 파일 경로, 파일 크기, 10진수 및 16진수 오프셋.
- 요청된 인코딩 및 감지된 인코딩.
- 줄 번호, 소스 미리 보기, 컨텍스트 줄, 바이트 위치 및 문자 위치.
- 대상 바이트 및 제한된 16진 덤프.
- 선택적 비교 바이트 및 차이 상태.
- 경고, 지속 시간, 성공 상태 및 오류 메시지.

`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 이슈를 통해 민감한 샘플을 제출하지 마세요.

## 라이선스

OffsetInspect는 [MIT 라이선스](https://github.com/warpedatom/offsetinspect/blob/HEAD/LICENSE)에 따라 릴리스됩니다.