OffsetInspect

Un ensemble d'outils PowerShell à mémoire bornée pour l'inspection des offsets d'octets, la corrélation source, la comparaison binaire et l'analyse défensive des limites de détection.

OffsetInspect répond à une question pratique d'analyste :

Quel contenu est présent à cet offset d'octets, et quel contexte source ou binaire l'entoure ?

Il fournit également un flux de travail de limites de détection natif d'OffsetInspect, inspiré du même problème d'analyste traité par ThreatCheck, sans inclure son code source ni ses binaires : il localise le préfixe de contenu le plus court qu'AMSI ou Microsoft Defender détecte encore, valide la limite à plusieurs reprises, et transmet directement l'offset obtenu à l'inspecteur de contexte. Par-dessus ce cœur, il ajoute une suite d'analyse red team et de tri statique - découverte multi-régions, analyse de corpus, diff de détection, corrélation de déclencheurs de détection, journalisation des dérives, rapports d'engagement, analyse d'entropie, extraction de chaînes et analyse PE/imphash - le tout en lecture seule, plus un testeur de robustesse des signatures pour usage autorisé qui modifie les échantillons uniquement en mémoire, et sans jamais désactiver ni reconfigurer la protection des points de terminaison.

Outil complémentaire

Pour le tri statique à l'échelle d'un corpus (analyse PE, entropie, chaînes, IOC) sans la surcharge de PowerShell, voir OffsetScan - un binaire Rust natif avec le même schéma de sortie JSON. OffsetInspect 3.1.0+ ingère directement le JSON IOC d'OffsetScan via -IocJsonPath.

Points forts

• Ouvre chaque fichier d'inspection unique via un handle de lecture stable et traite tous les offsets demandés ensemble.
• Utilise une passe de streaming à mémoire bornée pour le mappage des lignes au lieu de relire le fichier complet pour chaque offset.
• Ne lit que les fenêtres d'octets demandées pour la sortie hexadécimale et la comparaison.
• Mappe les offsets d'octets UTF-8 et UTF-16 vers les lignes source et les positions de caractères.
• Implémente le contexte source précédent et suivant via -ContextLines.
• Prend en charge les contrats de sortie humain, objet, JSON, CSV et fichier CSV.
• Prend en charge les plans fichier/offset un-à-plusieurs, plusieurs-à-un et appariés.
• Compare l'octet cible à un second fichier sans recharger ce fichier à plusieurs reprises.
• Ajoute une couche de fournisseurs AMSI et Microsoft Defender implémentée indépendamment, avec des états explicites d'erreur, de dépassement de délai, de blocage et indéterminé.
• Enregistre une piste d'audit par sonde (ProbeLog/ProbeCount) de chaque invocation distincte de fournisseur, diffusée en direct vers -Verbose, pour une transcription prête pour les rapports du coût réel en fournisseurs d'une analyse.
• Découvre plusieurs régions indépendamment détectables dans un même fichier via l'analyse AMSI en mémoire (aucun élément détecté n'est écrit sur le disque) et mappe chaque limite à un offset absolu.
• Analyse un corpus en une matrice de détection consolidée, compare la détection entre deux analyses et exporte des rapports d'engagement Markdown/HTML (éventuellement alimentés par le JSON du moteur natif OffsetScan pour les panneaux IOC à l'échelle du corpus).
• Corrèle une limite de détection au contenu qui l'a produite - la section PE, l'entropie de la séquence jusqu'à la limite, et les chaînes se terminant à/chevauchant cette limite comme contenu de signature candidat.
• Journalise la détection dans le temps (empreinte du fichier et version locale de la signature Defender) afin qu'un changement de détectabilité puisse être attribué au fichier, à une mise à jour de la base de signatures, ou à un résultat non déterministe du fournisseur.

Commandes

¹ Ces deux commandes ont des dépendances externes facultatives : Invoke-OffsetYaraScan nécessite le moteur YARA (winget install VirusTotal.YARA), et Invoke-OffsetClamScan nécessite ClamAV avec les bases de signatures (winget install Cisco.ClamAV, puis freshclam). Toutes les autres commandes sont autonomes. ClamAV est ici un détecteur mono-fichier, pas un moteur de recherche de limites - clamscan charge sa base complète à chaque invocation, la bissection nécessiterait donc le démon clamd.

² Add-OffsetDriftEntry journalise sur toutes les plateformes, mais les champs de version de signature/moteur Defender ne sont renseignés que sur Windows (via Get-MpComputerStatus) ; ailleurs, ils sont enregistrés comme null et le reste de l'instantané est quand même écrit.

Le cœur d'inspection des offsets et tous les assistants de tri statique sont multi-plateforme (Windows, Linux, macOS) ; les fournisseurs de menaces AMSI/Defender sont réservés à Windows.

Installation

PowerShell Gallery```powershell

Install-Module OffsetInspect -Scope CurrentUser Import-Module OffsetInspect

### Extraction du dépôt```powershell
git clone https://github.com/warpedatom/OffsetInspect.git
cd OffsetInspect
Import-Module ./module/OffsetInspect/OffsetInspect.psd1 -Force

Le dépôt inclut également des wrappers CLI légers :```powershell ./OffsetInspect.ps1 ./OffsetThreatScan.ps1 -Engine AMSI

## Inspection des offsets

### Sortie lisible par l'humain```powershell
Invoke-OffsetInspect ./sample.bin 0x200

• Skanda - Skanda est un outil complet de découverte d’actifs de cybersécurité et d’analyse de vulnérabilités, balayant l’ensemble de la chaîne d’attaque (cyber kill chain) à l’aide des meilleurs outils open source pour des résultats rapides et précis.```powershell $inspectParameters = @{ FilePaths = './script.ps1' OffsetInputs = 128, 256, 512 ByteWindow = 64 ContextLines = 4 } Invoke-OffsetInspect @inspectParameters

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

$results | Where-Object BytesDiffer

JSON et CSV```powershell

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

Le mode JSON émet toujours un tableau, y compris pour un résultat unique.

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

Formats d'offset

Les valeurs uniquement numériques, sans préfixe ni suffixe, sont intentionnellement traitées comme décimales.

Modes d'encodage

La sortie indique à la fois BytePositionInLine et CharacterPosition. Cette distinction importe lorsqu'un fichier source contient des caractères multioctets.

Analyse de la limite de menace

L'analyse des fournisseurs de menaces est réservée à Windows. La commande normale d'inspection des offsets reste multiplateforme.

Scan texte AMSI```powershell

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

Le mode texte utilise `AmsiScanString`, recherche les préfixes de scalaires Unicode sans diviser les paires de substituts, mappe le préfixe détecté via l'encodage source validé, et renvoie les index de scalaires Unicode, d'unités de code UTF-16 et d'octets du fichier source. Les caractères NUL intégrés sont rejetés en mode texte ; utilisez le mode octets bruts pour ces fichiers.

### Analyse AMSI en octets bruts```powershell
Invoke-OffsetThreatScan ./content.bin -Engine AMSI -ScanMode RawBytes

Analyse Microsoft Defender```powershell

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

Le fournisseur Defender :

- Résout le chemin de plateforme du `MpCmdRun.exe` le plus récemment installé.
- Écrit les préfixes dans un répertoire temporaire utilisateur unique.
- Utilise une analyse personnalisée avec `-DisableRemediation`.
- Traite les délais d'attente, les erreurs du fournisseur, les sorties localisées/inconnues et les marqueurs ambigus comme non définitifs.
- Supprime l'espace de travail temporaire à la fin de l'analyse.

### Sémantique des limites

Un résultat tel que `DetectionPrefixLength = 841` signifie :

- La longueur de préfixe 840 a été classée comme propre/non détectée.
- La longueur de préfixe 841 a été classée comme détectée/bloquée.
- Des vérifications répétées déterminent si cette transition est stable.

Cela ne prouve **pas** que l'octet 840 est la signature complète, le seul octet contributif, ou la plage malveillante complète. Les décisions de l'antivirus peuvent dépendre de la tokenisation, du contexte environnant, du type de fichier, de l'état du fournisseur et des mises à jour de signatures.

### Exemple concret : deux moteurs, un fichier

L'analyse du même échantillon (PowerUp.ps1, un script public de red team, 445,954 octets) avec les deux fournisseurs montre ce qu'est une limite et dans quelle mesure deux moteurs peuvent être considérés comme concordants. AMSI en mode texte :```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 mode raw-byte, même fichier :```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.

Les deux moteurs convergent sur la **ligne 4586** - la limite de Defender tombe à l'intérieur du `it` final de `Invoke-PrivescAudit`, celle d'AMSI sur le saut de ligne qui termine la même ligne, deux octets plus loin. Aucun des deux décalages n'est « la signature » : il s'agit des préfixes les plus courts que chaque fournisseur a encore signalés, et l'écart de deux octets correspond exactement à l'effet de tokenisation/contexte décrit plus haut. Defender nomme en outre ce qu'il a détecté (`Trojan:Win32/Kepavll!rfn`) ; AMSI ne rapporte pas de nom de signature, c'est pourquoi `Invoke-OffsetThreatScanRegion` et `Get-OffsetDetectionTrigger` existent pour caractériser une détection AMSI.

Les deux analyses nécessitent 25 sondes de fournisseur pour un fichier d'environ 436 KiB - la bissection est logarithmique en fonction de la taille du fichier, et chaque sonde est enregistrée dans `ProbeLog`.

Voir [Conception de l'analyse des menaces](https://github.com/warpedatom/offsetinspect/blob/HEAD/docs/THREAT-SCANNING.md) pour le contrat de fournisseur et les conseils d'interprétation, [interface de fournisseur](https://github.com/warpedatom/offsetinspect/blob/HEAD/docs/PROVIDER-INTERFACE.md) pour le contrat de l'analyseur et la manière d'ajouter un fournisseur sans toucher au cœur de la recherche, [provenance de l'analyse des menaces](https://github.com/warpedatom/offsetinspect/blob/HEAD/docs/PROVENANCE.md) pour les limites d'implémentation et l'attribution, et [schéma de sortie](https://github.com/warpedatom/offsetinspect/blob/HEAD/docs/OUTPUT-SCHEMA.md) pour le contrat d'objet versionné.

### Rapports de limites de détection

`Export-OffsetThreatReport` transforme un ou plusieurs résultats d'analyse en un rapport Markdown ou HTML autonome - résumé par fichier, métadonnées de fournisseur/signature/moteur, piste d'audit complète de `ProbeLog` et avertissements - à joindre à un rapport de mission. Il ne lit que les résultats et ne relance jamais d'analyse : il fonctionne donc sur toutes les plateformes. Ajoutez `-IncludeIoc` pour intégrer un panneau d'indicateurs hash/entropie/PE (les mêmes données que `Get-OffsetIOC`) dans chaque entrée du rapport, et `-IncludeTrigger` pour ajouter une analyse du déclencheur de détection (voir ci-dessous) pour chaque résultat comportant une limite.```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

Pour les rapports à l'échelle du corpus, -IncludeIoc réanalyse chaque fichier dans PowerShell, ce qui est lent. Le moteur natif compagnon OffsetScan émet des JSON d'IOC au schéma identique bien plus rapidement ; pointez le rapport dessus avec -IocJsonPath et il alimente chaque panneau à partir de ce JSON (en recourant à un Get-OffsetIOC en direct uniquement pour les fichiers qui en sont absents) :```powershell offsetscan ioc ./corpus --recurse > ./ioc.json $results | Export-OffsetThreatReport -Path ./engagement.md -IocJsonPath ./ioc.json

### Analyse par lots / corpus

`Invoke-OffsetThreatScanBatch` développe les fichiers, répertoires et caractères génériques en une liste de fichiers, analyse chacun d'eux (en poursuivant malgré les échecs par fichier), et renvoie un résultat par fichier. `-Summary` renvoie une matrice de détection aplatie ; les résultats complets sont directement acheminés vers le générateur de rapports. L'analyse par fournisseur est réservée à Windows.```powershell
Invoke-OffsetThreatScanBatch ./payloads -Recurse -Engine AMSI |
    Export-OffsetThreatReport -Path ./engagement.html -Format Html

Invoke-OffsetThreatScanBatch ./samples -Summary |
    Format-Table File, DetectionPrefixLength, Confidence, ProbeCount

Diff de détection / régression

Compare-OffsetThreatResult compare deux résultats d'analyse - par exemple le même fichier avant et après une mise à jour de définition de signature - et classe le changement (NewlyDetected, NoLongerDetected, BoundaryEarlier, BoundaryLater, BoundaryUnchanged, BothClean) avec le delta de limite et les champs modifiés.```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

### Découverte multi-région

La recherche par préfixe trouve la *première* limite de détection. `Invoke-OffsetThreatScanRegion` trouve *plusieurs* régions indépendamment détectables en divisant le fichier en segments et en analysant chacun isolément via AMSI **entièrement en mémoire** - rien de détecté n'est écrit sur le disque, de sorte que la protection en temps réel de Defender n'est jamais déclenchée ni reconfigurée. Chaque correspondance est bissectée dans son segment pour cartographier la limite de déclenchement exacte jusqu'à un décalage de fichier absolu.```powershell
Invoke-OffsetThreatScanRegion ./payload.bin -SegmentCount 16 |
    Select-Object -ExpandProperty DetectedRegions |
    Format-Table SegmentIndex, StartOffset, EndOffset, AbsoluteBoundaryOffset, SignatureName

Cette commande signale les régions qui se déclenchent seules ; elle peut manquer des signatures qui ne se déclenchent qu'en contexte de fichier complet ou qui chevauchent une limite de segment. Traitez donc ces régions comme des pistes à confirmer avec Invoke-OffsetThreatScan et une validation manuelle. AMSI (en mémoire) est le seul moteur pris en charge ici - l'analyse de fichiers Defender nécessiterait d'écrire le contenu détecté sur le disque.

Corrélation des déclencheurs de détection

Une limite vous indique où la détection bascule ; Get-OffsetDetectionTrigger vous indique ce qui s'y trouve. Comme une limite de préfixe est le dernier octet du préfixe détecté le plus tôt, le contenu déclencheur est une séquence se terminant à cet offset. La commande signale la section PE dans laquelle se situe la limite, l'entropie de la séquence jusqu'à cette limite (texte brut vs compressé/encodé), et les chaînes extraites se terminant à cette limite ou la chevauchant, classées par proximité - le contenu de signature candidat - avec une interprétation en une ligne. Elle ne lit que des octets et ne réanalyse jamais, elle s'exécute donc de manière multiplateforme sur des résultats enregistrés.```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

### Journal de dérive de détection

« Il était détecté avant et maintenant il ne l'est plus » a trois causes très différentes : le fichier a changé, les signatures ont changé, ou le fournisseur est non déterministe. `Add-OffsetDriftEntry` enregistre des instantanés NDJSON en ajout seul - SHA-256 du fichier, statut, limite, nom de signature, et les versions locales de la signature/du moteur Defender - et `Get-OffsetDrift` lit cet historique et attribue chaque changement à la cause appropriée.```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

Chaque transition est étiquetée : un changement de SHA-256 est lu comme une modification de fichier ; un changement de statut avec fichier inchangé mais la version de signature Defender ayant changé est lu comme une dérive de signature ; un changement de statut sans aucun des deux est lu comme un résultat de fournisseur non déterministe. Le journal utilise par défaut %LOCALAPPDATA%\OffsetInspect\drift.ndjson ; remplacez-le avec -JournalPath.

Test de robustesse des signatures (utilisation autorisée uniquement)

Invoke-OffsetMutationTest répond à une question d'ingénierie de détection : une signature est-elle une correspondance littérale exacte et fragile, ou est-elle robuste à l'obfuscation courante ? Étant donné un échantillon qu'AMSI détecte actuellement, il applique des perturbations standard - inversion de casse, concaténation de littéraux de chaîne, insertion de commentaires, injection d'espaces blancs - et re-scanne chaque variante pour rapporter quelles classes neutralisent la détection. Tout se passe en mémoire via l'interface in-process d'AMSI ; aucune variante n'est écrite sur le disque, donc aucun artefact d'évasion n'est produit et la protection en temps réel de Defender n'est pas impliquée. La commande refuse de s'exécuter sans -AuthorizedEngagement, et n'est destinée qu'à des échantillons que vous êtes autorisé à tester.```powershell Invoke-OffsetMutationTest -FilePath ./flagged.ps1 -AuthorizedEngagement | Select-Object RobustnessSummary -ExpandProperty Results

Un résultat, disons, "fragile: neutralisé par StringConcatenation, CommentInsertion" indique à un défenseur que la signature repose sur un littéral contigu et devrait être élargie ; il indique à un opérateur autorisé la même chose à propos de la couverture d'un contrôle.

### Corrélation de télémétrie

Détecter une limite vous indique ce que voit le *moteur* ; `-CaptureTelemetry` vous indique ce que voit le *défenseur*. Il prend un instantané du niveau maximal de chaque journal de télémétrie Windows accessible avant l'analyse, puis indique si l'action a déclenché une alerte, avec quel contexte, et quelles sources étaient aveugles - la question "supposer la visibilité, puis la valider", à laquelle il répond avec des preuves.```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 propriété Telemetry (OffsetInspect.TelemetryCorrelation) rapporte :

• AlertGenerated / Alert - si une détection Microsoft Defender (événement 1116/1117) a été journalisée pour l'analyse, et son contexte (nom de la menace, gravité, source de détection, processus, utilisateur).
• CorrelationConfidence - Élevée uniquement lorsque la source de détection correspond au fournisseur et que le processus de détection correspond à l'hôte d'analyse, afin qu'une détection concurrente fortuite ne soit jamais présentée comme corrélée ; Moyenne sur la source seule ; Faible sur aucun des deux.
• SourcesAccessible / SourcesUnavailable - quels journaux de télémétrie étaient lisibles et lesquels étaient aveugles (Sysmon absent, journal Sécurité nécessitant une élévation). Un manque de visibilité est en soi un constat.
• Findings - conclusions en langage clair : une alerte avec contexte complet, une alerte sans nom de menace, aucune télémétrie du tout, ou une source manquante.

La source principale est le journal opérationnel Microsoft Defender, lisible sans élévation de privilèges ; la corrélation se fait par RecordId d'événement (monotone et indépendant du fuseau horaire). Réservé à Windows, et inactif sauf si -CaptureTelemetry est spécifié.

Outils d'aide au triage statique

Trois commandes d'analyse statique multiplateformes prennent en charge le triage de malwares et s'intègrent au noyau offset :

• Get-OffsetEntropy - entropie de Shannon par fenêtre (bits/octet) pour localiser les régions packées ou chiffrées ; recoupez les fenêtres signalées avec les détections de Invoke-OffsetThreatScanRegion.
• Get-OffsetString - chaînes ASCII imprimables et UTF-16LE avec décalages d'octets ; envoyez les décalages par pipeline vers Invoke-OffsetInspect pour obtenir le contexte.
• Get-OffsetPEInfo - type de machine et bitness PE, point d'entrée, table des sections, imports et imphash, détection d'overlay ajouté, et taille des ressources, avec -Offset mappant un décalage d'octets vers sa section (.text, .rsrc, ...). L'imphash utilise le MD5 standard library.function et est vérifié comme étant octet pour octet identique à pefile/VirusTotal - y compris la résolution des ordinaux pour les bibliothèques spéciales, ainsi un ordinal importé depuis ws2_32/wsock32/ se résout en son véritable nom de fonction ; tout autre import ordinal s'affiche comme , exactement comme pefile.

### Analyse YARA

`Invoke-OffsetYaraScan` exécute les règles YARA rédigées par l'analyste et renvoie chaque correspondance avec son décalage d'octet - complétant la vue de la limite de détection AMSI/Defender avec des signatures que vous contrôlez, et ne nécessitant aucun antivirus installé (seul le moteur YARA est nécessaire, par ex. `winget install VirusTotal.YARA`). Les décalages sont directement transmis à l'inspecteur.```powershell
Invoke-OffsetYaraScan ./sample.bin -RulePath ./rules/malware.yar |
    ForEach-Object { Invoke-OffsetInspect $_.File $_.Offset -ContextLines 2 }

Analyse ClamAV

Invoke-OffsetClamScan analyse un fichier avec le moteur à la demande de ClamAV et renvoie un résultat normalisé (Clean / Detected / Error, plus le nom de la signature). Comme clamscan charge sa base de signatures complète à chaque appel, c'est un détecteur de fichier unique, pas un moteur de recherche de limites (ce qui nécessiterait le démon clamd). Il nécessite que ClamAV soit installé et que ses bases de signatures soient téléchargées - freshclam ne s'exécutera pas tant qu'un fichier de configuration n'existera pas :```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

Utilisez `-DatabasePath` pour pointer vers un répertoire de signatures dans un emplacement accessible en écriture (non administrateur), et `-ClamScanPath` si `clamscan` n'est pas dans `PATH`.

## Objets de résultat

`Invoke-OffsetInspect -PassThru` retourne des objets `OffsetInspect.Result` contenant :

- Chemin de fichier canonique, taille du fichier, décalages décimal et hexadécimal.
- Encodage demandé et détecté.
- Numéro de ligne, aperçu de la source, lignes de contexte, position d'octet et position de caractère.
- Octet cible et hexdump borné.
- Octet de comparaison optionnel et état de différence.
- Avertissements, durée, état de succès et message d'erreur.

`Invoke-OffsetThreatScan -PassThru` retourne des objets `OffsetInspect.ThreatScanResult` contenant :

- SHA-256 du fichier, horodatage UTC de l'analyse, moteur, mode d'analyse, état initial du fournisseur et métadonnées du fournisseur.
- Longueurs des préfixes connus sains et connus détectés.
- Limite d'octet et limite de caractère optionnelle.
- Stabilité, confiance, nombre d'analyses, statuts de limite répétés et nom de la signature lorsqu'il est disponible.
- Une piste d'audit `ProbeLog` de chaque sonde de fournisseur distincte (exposée sous la forme de `ProbeCount` dans la sortie CSV, et exportable vers une transcription JSON avec `-ProbeLogPath`) ; voir [schéma de sortie](https://github.com/warpedatom/offsetinspect/blob/HEAD/docs/OUTPUT-SCHEMA.md).
- Contexte `OffsetInspect.Result` imbriqué à la limite mappée.

## Modèle de performance

L'implémentation de style v1 relisait et décodait un fichier complet pour chaque décalage. La version 2 regroupe le travail par fichier :```text
Previous approach: approximately O(file size × offset count)
Version 2:         approximately O(file bytes scanned once + requested windows)

Le mappage des sources utilise une machine à états de streaming et ne conserve que les descripteurs de lignes précédentes/suivantes requis pour les décalages demandés. Les lignes individuelles extrêmement longues sont affichées via un aperçu borné contrôlé par -MaxLineBytes.

Structure du dépôt```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

## Développement

Installez les outils de validation épinglés :```powershell
Install-Module Pester -RequiredVersion 5.7.1 -Scope CurrentUser
Install-Module PSScriptAnalyzer -RequiredVersion 1.25.0 -Scope CurrentUser

Exécutez la validation locale complète :```powershell ./build/Test-Module.ps1

Exécutez le harnais de benchmark déterministe:```powershell
./benchmarks/Measure-OffsetInspect.ps1 -FileSizeMiB 64 -OffsetCount 5000

Les résultats de benchmark varient selon le stockage, la charge de l'hôte, l'édition de PowerShell et la forme des fichiers. Enregistrez ces entrées lors de la comparaison des commits.

Créez une archive de version déterministe et un fichier SHA-256 :```powershell ./build/New-ReleasePackage.ps1

CI valide PowerShell 7 sur Windows et Linux, Windows PowerShell 5.1, PSScriptAnalyzer, le packaging de module isolé et l'archive de publication. Les mainteneurs de version devraient également suivre la [liste de contrôle de publication](https://github.com/warpedatom/offsetinspect/blob/HEAD/docs/RELEASE-CHECKLIST.md).

## Sécurité et usage responsable

OffsetInspect est destiné à la recherche défensive autorisée, à l'ingénierie de détection, au reverse engineering, à l'analyse de malwares et aux tests de sécurité. Les fonctions fournisseurs de menaces analysent le contenu mais ne désactivent, ne contournent ni ne reconfigurent les protections des points de terminaison.

`Invoke-OffsetMutationTest` génère des variantes d'évasion de détection pour l'évaluation de la robustesse des signatures. Il fonctionne entièrement en mémoire (aucune variante n'est écrite sur le disque) et refuse de s'exécuter sans la confirmation explicite `-AuthorizedEngagement`. Utilisez-le uniquement sur des échantillons et des contrôles que vous êtes autorisé à tester.

Consultez [SECURITY.md](https://github.com/warpedatom/offsetinspect/blob/HEAD/SECURITY.md) avant de signaler une vulnérabilité. Ne soumettez pas d'échantillons sensibles via les issues GitHub publiques.

## Licence

OffsetInspect est publié sous la [licence MIT](https://github.com/warpedatom/offsetinspect/blob/HEAD/LICENSE).