{"id":35118528,"url":"https://github.com/evotecit/fileinspectorx","last_synced_at":"2026-01-21T00:01:47.638Z","repository":{"id":320271135,"uuid":"1074123821","full_name":"EvotecIT/FileInspectorX","owner":"EvotecIT","description":"FileInspectorX is a library for content type detection (magic bytes + heuristics) and lightweight analysis (containers, PDFs, PE triage, text/script cues) across .NET 8, .NET Standard 2.0 and .NET Framework 4.7.2. A thin PowerShell module provides pipeline‑friendly cmdlets with reusable typed views.","archived":false,"fork":false,"pushed_at":"2025-12-27T16:03:20.000Z","size":842,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-12-29T21:34:40.213Z","etag":null,"topics":["content-analysis","detection","file-types","magic-bytes","permissions","zip"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/EvotecIT.png","metadata":{"files":{"readme":"README.MD","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"PrzemyslawKlys","custom":["https://paypal.me/PrzemyslawKlys"]}},"created_at":"2025-10-11T07:27:59.000Z","updated_at":"2025-12-27T16:01:46.000Z","dependencies_parsed_at":"2025-10-22T22:28:58.432Z","dependency_job_id":"ddc8d675-5422-4ea1-be4b-e488e6781064","html_url":"https://github.com/EvotecIT/FileInspectorX","commit_stats":null,"previous_names":["evotecit/fileinspectorx"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/EvotecIT/FileInspectorX","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EvotecIT%2FFileInspectorX","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EvotecIT%2FFileInspectorX/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EvotecIT%2FFileInspectorX/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EvotecIT%2FFileInspectorX/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EvotecIT","download_url":"https://codeload.github.com/EvotecIT/FileInspectorX/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EvotecIT%2FFileInspectorX/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28618859,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T23:49:58.628Z","status":"ssl_error","status_checked_at":"2026-01-20T23:47:29.996Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["content-analysis","detection","file-types","magic-bytes","permissions","zip"],"created_at":"2025-12-27T22:50:58.082Z","updated_at":"2026-01-21T00:01:47.632Z","avatar_url":"https://github.com/EvotecIT.png","language":"C#","funding_links":["https://github.com/sponsors/PrzemyslawKlys","https://paypal.me/PrzemyslawKlys"],"categories":[],"sub_categories":[],"readme":"\u003c!-- Badges --\u003e\n\n# FileInspectorX — Content Type Detection and Analysis for .NET and PowerShell\n\n📦 NuGet (Library)\n\n[![nuget downloads](https://img.shields.io/nuget/dt/FileInspectorX?label=nuget%20downloads)](https://www.nuget.org/packages/FileInspectorX)\n[![nuget version](https://img.shields.io/nuget/v/FileInspectorX)](https://www.nuget.org/packages/FileInspectorX)\n\n💻 PowerShell Module\n\n[![powershell gallery version](https://img.shields.io/powershellgallery/v/FileInspectorX.svg)](https://www.powershellgallery.com/packages/FileInspectorX)\n[![powershell gallery preview](https://img.shields.io/powershellgallery/vpre/FileInspectorX.svg?label=powershell%20gallery%20preview\u0026colorB=yellow)](https://www.powershellgallery.com/packages/FileInspectorX)\n[![powershell gallery platforms](https://img.shields.io/powershellgallery/p/FileInspectorX.svg)](https://www.powershellgallery.com/packages/FileInspectorX)\n[![powershell gallery downloads](https://img.shields.io/powershellgallery/dt/FileInspectorX.svg)](https://www.powershellgallery.com/packages/FileInspectorX)\n\n🛠️ Project Information\n\n[![top language](https://img.shields.io/github/languages/top/EvotecIT/FileInspectorX.svg)](https://github.com/EvotecIT/FileInspectorX)\n[![license](https://img.shields.io/github/license/EvotecIT/FileInspectorX.svg)](https://github.com/EvotecIT/FileInspectorX)\n\n👨‍💻 Author \u0026 Social\n\n[![Twitter follow](https://img.shields.io/twitter/follow/PrzemyslawKlys.svg?label=Twitter%20%40PrzemyslawKlys\u0026style=social)](https://twitter.com/PrzemyslawKlys)\n[![Blog](https://img.shields.io/badge/Blog-evotec.xyz-2A6496.svg)](https://evotec.xyz/hub)\n[![LinkedIn](https://img.shields.io/badge/LinkedIn-pklys-0077B5.svg?logo=LinkedIn)](https://www.linkedin.com/in/pklys)\n[![Threads](https://img.shields.io/badge/Threads-@PrzemyslawKlys-000000.svg?logo=Threads\u0026logoColor=White)](https://www.threads.net/@przemyslaw.klys)\n[![Discord](https://img.shields.io/discord/508328927853281280?style=flat-square\u0026label=discord%20chat)](https://evo.yt/discord)\n\n## What it's all about\n\nFileInspectorX is a library for content type detection (magic bytes + heuristics) and lightweight analysis (containers, PDFs, PE triage, text/script cues) across .NET 8, .NET Standard 2.0 and .NET Framework 4.7.2. A thin PowerShell module provides pipeline‑friendly cmdlets with reusable typed views.\n\n## Install\n\n### NuGet (Library)\n\n```bash\ndotnet add package FileInspectorX\n```\n\n### PowerShell (Module)\n\n```powershell\nInstall-Module FileInspectorX.PowerShell\n# or local build\nImport-Module .\\FileInspectorX.PowerShell\\bin\\Debug\\net8.0\\FileInspectorX.PowerShell.dll\n```\n\n## C# Quick Start\n\n```csharp\nusing FileInspectorX;\n\nvar options = new FileInspector.DetectionOptions { ComputeSha256 = true, MagicHeaderBytes = 16 };\nvar analysis = FileInspector.Analyze(path, options);\n\nConsole.WriteLine($\"{analysis.Detection?.Extension} {analysis.Detection?.MimeType} {analysis.Kind} {analysis.Flags}\");\n\n// Flatten for tabular/log display\nvar summary = SummaryView.From(path, analysis);\nvar perms   = PermissionsView.From(path, analysis.Security);\nvar sig     = SignatureView.From(path, analysis.Authenticode);\n\n// Detection only\nvar detOnly = FileInspector.Detect(path, options);\n```\n\n## C# Recipes\n\n```csharp\n// Presentation-ready report + map\nvar analysis = FileInspector.Analyze(path);\nvar report = ReportView.From(analysis);\nvar map = report.ToDictionary();\n\n// Humanize flags if you only have CSV\nstring flagsShort;\nif (!map.TryGetValue(\"AnalysisFlagsHuman\", out var human))\n{\n    map.TryGetValue(\"AnalysisFlags\", out var csv);\n    flagsShort = Legend.HumanizeFlagsCsv(csv?.ToString());\n}\nelse flagsShort = human?.ToString() ?? string.Empty;\n\n// Render a Markdown report (dependency-free)\nvar md = MarkdownRenderer.From(analysis);\n\n// Include file system metadata + flattened dictionary\nvar summary2 = FileInspector.InspectWithMetadata(path, new FileInspector.DetectionOptions { MagicHeaderBytes = 64 });\nvar metadata = summary2.Metadata;\n\n// Optional: top tokens for scripts/logs (disabled by default)\nSettings.TopTokensEnabled = true;\nSettings.TopTokensMax = 8;\nSettings.TopTokensMinLength = 4;\nSettings.TopTokensMinCount = 2;\n\n// Compare declared vs detected (with alternatives)\nvar cmp = FileInspector.CompareDeclaredDetailed(\".log\", summary2.Analysis.Detection);\nConsole.WriteLine($\"Mismatch? {cmp.Mismatch} Reason={cmp.Reason}\");\n\n// Consume typed legends directly\nforeach (var entry in Legend.GetAnalysisFlagLegend())\n    Console.WriteLine($\"{entry.Short} = {entry.Long}\");\n```\n\n## PowerShell Examples\n\n```powershell\n# Raw is default (full object)\nGet-FileInsight -Path .\\file.bin | Format-List\n\n# Opt-in compact views\nGet-FileInsight -Path .\\file.bin -View Summary | Format-Table -Auto\n\n# Other views: Summary | Detection | Permissions | Signature | Analysis | ShellProperties\nGet-FileInsight -Path .\\file.bin -View Detection | Format-Table -Auto\nGet-FileInsight -Path .\\file.bin -View Permissions | Format-Table Path,Owner,Group,ModeSymbolic,EveryoneWriteAllowed -Auto\nGet-FileInsight -Path .\\app.exe -View Signature | Format-List\nGet-FileInsight -Path .\\package.msix -View Installer | Format-Table -Auto\nGet-FileInsight -Path .\\song.mp3 -View ShellProperties | Format-Table -Auto\n\n# Exclude sections to trim work/shape\nGet-FileInsight -Path .\\file.bin -ExcludePermissions -ExcludeReferences -ExcludeShellProperties | Format-List\n\n# Back-compat: detection only\nGet-FileInsight -Path .\\file.bin -DetectOnly | Format-List\n```\n\n### PowerShell quick help\n\n```powershell\n# Discover parameters and examples\nGet-Help Get-FileInsight -Detailed\nGet-Help Get-FileInsight -Examples\n\n# Detect-only for all EXE files under the current directory\nGet-ChildItem -Filter *.exe -File -Recurse | Get-FileInsight -View Detection | Format-Table -Auto\n\n# Summarize a directory, skipping signature and installer enrichment\nGet-ChildItem -File -Recurse | Get-FileInsight -View Summary -ExcludeSignature -ExcludeInstaller | Format-Table -Auto\n```\n\n## Views\n\n- SummaryView: Path, Kind, Extension, MimeType, Confidence, Reason, Flags\n- DetectionView: Path, Extension, MimeType, Confidence, Reason, ReasonDetails, BytesInspected, Sha256Hex, MagicHeaderHex\n- AnalysisView: container/text/script/PE/Auth summaries\n- PermissionsView (Windows \u0026 Unix): Owner/Group (+ IDs), ModeOctal/ModeSymbolic, IsExecutable, Everyone/Users/Admins read/write, HasDenyEntries\n- SignatureView: Present, EnvelopeSignatureValid, ChainValid, Timestamp, signer info, FileHashMatches, SubjectCN/Org, IssuerCN/Org, IsSelfSigned\n- InstallerView: Name/Publisher/Version/Manufacturer/ProductCode for MSI; Identity/Publisher/Display for MSIX/APPX; Publisher for VSIX\n- ReferencesView: (generic) FilePath/Url/Command values found in configs (Task XML, scripts.ini), with Exists and Issues flags\n- AssessmentView: compact risk score (0–100), decision (Allow/Warn/Block/Defer), and finding codes\n  - Codes include: Package.VendorPresent/VendorUnknown/VendorAllowed, Sig.VendorAllowed/Sig.VendorUnknown, Archive.* and Pdf.* flags, etc.\n- ShellPropertiesView (Windows only): Windows shell properties (Explorer Details), e.g., Title/Authors/BPM/Initial Key, etc.\n  - IncludeEmpty enumerates the full Details property list and can be slower.\n\n## Usage Model: Raw + Views + Exclude Toggles\n\n- Default Raw\n  - The cmdlet returns the full `FileAnalysis` object by default (`-View Raw`). This is a single, rich object with Detection, Flags, Security, Authenticode/Installer, References, Assessment, Secrets summary, and more.\n\n- Views for display\n- Use `-View Summary|Detection|Analysis|Permissions|Signature|References|Assessment|Installer|ShellProperties` to get compact, tabular shapes.\n  - Every view carries `.Raw` so you can drill back into the full object without re‑invoking.\n\n- Trim work/shape with excludes\n  - `-ExcludePermissions`, `-ExcludeSignature`, `-ExcludeInstaller`, `-ExcludeReferences`, `-ExcludeContainer`, `-ExcludeAssessment`, `-ExcludeShellProperties`.\n  - In C#, use `new FileInspector.DetectionOptions { IncludePermissions = false, ... }`.\n\n```csharp\nvar lean = FileInspector.Analyze(path, new FileInspector.DetectionOptions {\n    IncludePermissions = false,\n    IncludeReferences = false,\n    IncludeShellProperties = false,\n    IncludeAuthenticode = true,\n    IncludeAssessment = true\n});\n```\n\n## API Choices: Detect vs Inspect vs Analyze\n\nPick the API based on how much work you want the library to do and how much metadata you need:\n\n- Detect(path[, options]) → ContentTypeDetectionResult\n  - Fast header-only magic/heuristics (null if unknown)\n  - Minimal I/O, ideal for bulk triage or hot loops\n  - options can still capture Sha256Hex and MagicHeaderHex\n\n- Inspect(path[, options]) → FileAnalysis (single entry point)\n  - If options.DetectOnly = true → returns a minimal FileAnalysis wrapping Detect\n  - Otherwise → performs full analysis (same as Analyze)\n\n- Analyze(path[, options]) → FileAnalysis\n  - Full analysis: container/PDF/PE/Auth/permissions/script cues/CSV estimates\n  - Returns everything Detect provides plus extra flags and metadata\n\nExamples (C#)\n\n```csharp\n// Detection only (fast)\nvar det = FileInspector.Detect(path, new FileInspector.DetectionOptions { MagicHeaderBytes = 16 });\n\n// Single entry point (detect-only)\nvar detFa = FileInspector.Inspect(path, new FileInspector.DetectionOptions { DetectOnly = true });\n\n// Full analysis\nvar full = FileInspector.Inspect(path, new FileInspector.DetectionOptions { ComputeSha256 = true });\nvar summary = full.ToSummaryView(path);\n```\n\n## Detection Ordering \u0026 Declared Extension Bias\n\nDetection runs in a stable order so downstream callers can reason about outcomes:\n\n- Magic-byte signatures and fast format checks run first (archives, executables, media, databases, etc.).\n- Container refinements (ZIP subtypes, OLE2 subtypes) run next when applicable.\n- Text/markup heuristics (JSON/XML/YAML/INI/CSV/PS/Batch/etc.) run after binary checks.\n- Plain-text fallback is last when the content looks printable.\n\nDeclared extension is used as a bias only for ambiguous/low-confidence cases:\n\n- `Detect(path)` uses the file extension as the declared value automatically.\n- `Detect(stream, options, declaredExtension)` and `Detect(ReadOnlySpan\u003cbyte\u003e, options, declaredExtension)` let you supply the declared extension to match path-based behavior.\n- Bias is applied only for ambiguous text families (e.g., cmd vs bat, admx/adml vs xml, inf vs ini, ini vs toml) and low-confidence generic text (log/txt/md/ps1/psm1/psd1). Strong magic-byte matches are not overridden.\n- `CompareDeclared` normalizes leading dots and can fall back to `GuessedExtension` when `Extension` is empty (e.g., ZIP subtypes).\n- `CompareDeclaredDetailed` returns the mismatch plus reasoning and detection alternatives (when available).\n\n## Features\n\n- Fast detection: magic bytes + heuristics (images, archives, PDFs, executables, text/markup, scripts, CSV/TSV, DMG/ISO/UDF, EVTX, ESE, RIFF/media, etc.)\n- Humanized output: friendly type labels (e.g., “Word document”, “ZIP archive”) and legend‑based flag descriptions via ReportView\n- Analysis helpers\n  - ZIP/TAR summaries (EntryCount, TopExtensions, nested archive hints)\n  - Optional deep container scan (bounded): disguised types, known tool indicators, inner signers summary (see below)\n  - PDF flags (JavaScript, OpenAction, AA, Names tree, EmbeddedFiles, ManyEmbeddedFiles)\n  - PE triage (machine/subsystem, UPX hint)\n  - Text family \u0026 CSV/TSV line estimates; generic log/schema cues (IIS W3C, Event XML, Sysmon, LDIF, AAD, MDE)\n- Script safety cues (neutral): ps:encoded, ps:iex, py:exec-b64, lua:exec, rb:eval (no raw high‑signal strings)\n- Secrets (privacy‑safe counts only): PrivateKey/JWT/KeyPattern\n- Permissions snapshot: cross‑platform owner/group + Unix modes; Windows ACL summaries (Everyone/Users/Admins read/write, deny ACEs); MOTW/ADS on Windows\n- Signatures: Authenticode summary and optional Windows policy (WinVerifyTrust) + timestamp/EKUs\n- Crypto file detection:\n  - ASCII‑armored PGP blocks (message/public key/signature)\n  - Binary OpenPGP packet header (generic, low‑confidence)\n  - DER X.509 certificate (heuristic ASN.1 OID scan)\n  - PKCS#12/PFX (ASN.1 OID scan)\n- Office \u0026 PDF flags:\n  - OOXML (Word): Remote template (OfficeRemoteTemplate), possible DDE (OfficePossibleDde)\n  - OOXML (Excel): External links (OfficeExternalLinks) and count (OfficeExternalLinksCount)\n  - PDF: XFA (PdfHasXfa), Encrypted (PdfEncrypted), ManyIncrementalUpdates (PdfManyIncrementalUpdates)\n- Citrix cues: ICA files and Receiver/Workspace configuration (XML)\n- AOT‑friendly: safe for NativeAOT\n- Name/path checks: BiDi controls, double extension, extension mismatch, suspicious whitespace\n- Archive safety: traversal/absolute paths/symlinks flags from ZIP sampling\n\n## References \u0026 Recipes\n\n\nThe library can extract generic references from common configuration files so consumers can validate what will execute or be accessed. This is domain‑agnostic and useful for many scenarios (build pipelines, endpoint hygiene, or pre‑upload checks).\n\n- Extracted kinds: FilePath, Url, Command, EnvVar, RegistryPath, Clsid.\n- Current extractors:\n  - Windows Task Scheduler Task XML: captures `\u003cExec\u003e\u003cCommand\u003e`, `\u003cArguments\u003e`, `\u003cWorkingDirectory\u003e` and `\u003cClassId\u003e` (COM handler). Flags unquoted paths, UNC usage, relative paths.\n  - GPO scripts INI (scripts.ini / psscripts.ini): captures `nCmd` and `nParameters` values, extracts paths and URLs.\n\nPowerShell\n\n```powershell\n# List references from a Task XML\nGet-FileInsight -Path .\\Task.xml -View References | Format-Table -Auto\n\n# List references in a GPO scripts.ini\nGet-FileInsight -Path .\\scripts.ini -View References | Format-Table -Auto\n```\n\nC#\n\n```csharp\nvar a = FileInspector.Analyze(path);\nforeach (var r in a.References ?? Array.Empty\u003cReference\u003e())\n{\n    Console.WriteLine($\"{r.Kind} {r.Value} exists={r.Exists} issues={r.Issues}\");\n}\n```\n\nC# (Assessment)\n\n```csharp\nvar full = FileInspector.Analyze(path);\nvar assess = FileInspector.Assess(full);\nConsole.WriteLine($\"Score={assess.Score} Decision={assess.Decision} Codes={string.Join(\" \", assess.Codes)}\");\n\n// Factors show score contributions per code (explainability)\nforeach (var kv in assess.Factors)\n{\n    Console.WriteLine($\"{kv.Key} =\u003e {kv.Value}\");\n}\n```\n\nPowerShell (Assessment)\n\n```powershell\nGet-FileInsight -Path .\\file.bin -View Assessment | Format-Table -Auto\n```\n\nThis stays generic by design. A higher‑level component (e.g., TierBridge) can layer policy (allow/warn/block) using these references and the existing Flags/SecurityFindings.\n\n## Inner Signers Inside Archives (deep scan)\n\nWhen `Settings.DeepContainerScanEnabled = true`, FileInspectorX can sample a bounded number of inner executables in ZIP archives to provide a quick signer summary without fully extracting archives. The following fields are exposed on `FileAnalysis` and surfaced via `ReportView`:\n\n- `InnerExecutablesSampled`: how many inner EXE/DLLs were sampled (bounded by `DeepContainerMaxEntries` and `DeepContainerMaxEntryBytes`).\n- `InnerSignedExecutables`: how many of those were Authenticode‑signed.\n- `InnerValidSignedExecutables`: how many had a valid chain or passed WinVerifyTrust (when available).\n- `InnerPublisherCounts`: top publishers (SignerSubjectCN) with counts.\n\nNotes:\n- This is a best‑effort, privacy‑safe summary for triage. It extracts only sampled entries to a temporary file for analysis and deletes them immediately.\n- Currently implemented for ZIP. TAR/7z/RAR can be added similarly if needed.\n\n```csharp\nvar a = FileInspector.Analyze(path);\nif (a.InnerExecutablesSampled \u003e 0)\n{\n    Console.WriteLine($\"Inner execs: {a.InnerExecutablesSampled}, signed: {a.InnerSignedExecutables}, valid: {a.InnerValidSignedExecutables}\");\n    if (a.InnerPublisherCounts != null)\n        foreach (var kv in a.InnerPublisherCounts.OrderByDescending(kv =\u003e kv.Value).Take(5))\n            Console.WriteLine($\"  {kv.Key}: {kv.Value}\");\n}\n```\n\n## Friendly Type Labels \u0026 ReportView\n\nUse `ReportView.From(FileAnalysis)` for presentation‑ready fields:\n\n- `DetectedTypeFriendly`: a human‑friendly label (e.g., “Word document”, “ZIP archive”, “X.509 certificate”).\n- `FlagsHumanShort/Long`: legend‑based humanization of flags and heuristics.\n- `AssessmentCodesHuman`: humanized assessment codes.\n\nThese are exported via `ReportView.ToDictionary()` for templating/email systems.\nExample keys: `DetectedTypeExtension`, `DetectedTypeName`, `DetectionConfidence`, `CompanyName`, `ProductName`, `FileVersion`, `AnalysisFlags`, `AnalysisFlagsHuman`, `AssessmentScore`, `AssessmentDecision`, `AssessmentCodes`, `EncryptedEntryCount`, `InnerFindings`, `TopTokens`.\n\n## Thread Safety Notes\n\n- Settings are static/global; configure once at startup.\n- Avoid concurrent mutation while detection is running; if you need runtime updates, protect changes with your own lock.\n- `DetectionScoreAdjustments` defaults to `ConcurrentDictionary`. If you replace it with a non-thread-safe dictionary, you are responsible for synchronization.\n\n## Settings Cheatsheet\n\n```csharp\n// Deep container scanning (bounded)\nSettings.DeepContainerScanEnabled = true;      // default: false\nSettings.DeepContainerMaxEntries = 64;         // sample cap\nSettings.DeepContainerMaxEntryBytes = 262144;  // per‑entry cap (256 KB)\nSettings.KnownToolNameIndicators = new[] { \"pingcastle\", \"bloodhound\" };\nSettings.KnownToolHashes = new Dictionary\u003cstring,string\u003e { /* name =\u003e lowercase sha256 */ };\n\n// Script \u0026 secrets scanning\nSettings.SecurityScanScripts = true;           // default: true\nSettings.SecretsScanEnabled = true;            // default: true\n\n// Authenticode (Windows policy optional)\nSettings.VerifyAuthenticodeWithWinTrust = true;   // default true on Windows\nSettings.VerifyAuthenticodeRevocation = false;    // default\n\n// Vendor allow hints (for assessment)\nSettings.AllowedVendors = new[] { \"Microsoft\", \"YourCompany\" };\nSettings.VendorMatchMode = VendorMatchMode.Contains; // or Exact\n```\n\n## Flags → Assessment Codes (Quick Map)\n\n\n- Archive safety\n  - ArchiveHasPathTraversal → Archive.PathTraversal (+40)\n  - ArchiveHasAbsolutePaths → Archive.AbsolutePath (+15)\n  - ArchiveHasSymlinks → Archive.Symlink (+20)\n  - ContainerContainsExecutables → Archive.ContainsExecutables (+25)\n  - ContainerContainsScripts → Archive.ContainsScripts (+20)\n  - ContainerContainsArchives → Archive.ContainsArchives (+15)\n\n- Office / OOXML\n  - HasOoxmlMacros → Office.Macros (+30)\n  - OfficeRemoteTemplate → Office.RemoteTemplate (+25)\n  - OfficePossibleDde → Office.PossibleDde (+15)\n  - OfficeExternalLinks → Office.ExternalLinks (+5) [count exposed as OfficeExternalLinksCount]\n\n- PDF\n  - PdfHasJavaScript → Pdf.JavaScript (+20)\n  - PdfHasOpenAction → Pdf.OpenAction (+15)\n  - PdfHasLaunch → Pdf.Launch (+20)\n  - PdfHasNamesTree → Pdf.NamesTree (+10)\n  - PdfHasXfa → Pdf.Xfa (+10)\n  - PdfEncrypted → Pdf.Encrypted (+10)\n  - PdfManyIncrementalUpdates → Pdf.ManyUpdates (+5)\n\n- PE hardening\n  - PeLooksPackedUpx → PE.PackerSuspect (+20)\n  - PeNoAslr → PE.NoASLR (+15)\n  - PeNoNx → PE.NoNX (+20)\n  - PeNoCfg → PE.NoCFG (+15)\n  - PeNoHighEntropyVa (x64) → PE.NoHighEntropyVA (+5)\n\n- Signatures\n  - Self‑signed → Sig.SelfSigned (+20)\n  - Chain invalid → Sig.ChainInvalid (+25)\n  - Bad envelope → Sig.BadEnvelope (+15)\n  - Vendor allowed (allowed list) → Sig.VendorAllowed (−10)\n\n- Vendor / Package\n  - Vendor present → Package.VendorPresent (0)\n  - Vendor allowed (allowed list) → Package.VendorAllowed (−15)\n  - Vendor unknown → Package.VendorUnknown (0)\n  - MSI CustomActions (EXE/Script/DLL) → Msi.CustomActionExe (+20) / Msi.CustomActionScript (+20) / Msi.CustomActionDll (+10)\n\n- Scripts \u0026 secrets (neutral categories)\n  - Script.Encoded (+25), Script.IEX (+20), Script.WebDownload (+15), Script.Reflection (+10)\n  - Secret.PrivateKey (+40), Secret.JWT (+25), Secret.KeyPattern (+15)\n\n## Assessment Pipeline (Flowchart)\n\n```mermaid\nflowchart TD\n    A[\"Input path(s)\"] --\u003e B{\"Detect (magic + heuristics)\"}\n    B --\u003e|known| C[\"ContentTypeDetectionResult\"]\n    B --\u003e|unknown| C\n\n    C --\u003e D{\"Analyze (Include* flags)\"}\n    D --\u003e D1[\"Container triage (ZIP/TAR subtype, safety, nested)\"]\n    D --\u003e D2[\"Text/Script heuristics + Secrets\"]\n    D --\u003e D3[\"Permissions / Ownership\"]\n    D --\u003e D4[\"Signatures + Installer metadata\"]\n    D --\u003e D5[\"PDF / OOXML flags\"]\n    D --\u003e D6[\"Name / Path analysis\"]\n    D --\u003e E[\"FileAnalysis\"]\n\n    E --\u003e F{\"IncludeAssessment?\"}\n    F --\u003e|Yes| G[\"Assess() Score + Codes + Factors\"]\n    F --\u003e|No| H[\"Return FileAnalysis\"]\n\n    G --\u003e I[\"Decision: Allow / Warn / Block\"]\n    I --\u003e J[[\"Views (optional)\"]]\n    H --\u003e J\n\n    subgraph Toggles\n      T1[\"IncludeContainer\"]\n      T2[\"IncludePermissions\"]\n      T3[\"IncludeAuthenticode\"]\n      T4[\"IncludeInstaller\"]\n      T5[\"IncludeReferences\"]\n      T6[\"IncludeAssessment\"]\n    end\n\n    T1 -.-\u003e D1\n    T2 -.-\u003e D3\n    T3 -.-\u003e D4\n    T4 -.-\u003e D4\n    T5 -.-\u003e D2\n    T6 -.-\u003e G\n```\n\n## Scoring Breakdown (Example)\n\n```mermaid\npie showData\n    title Example Score Composition\n    \"Archive.PathTraversal (+40)\" : 40\n    \"Office.RemoteTemplate (+25)\" : 25\n    \"Secret.PrivateKey (+40)\" : 40\n    \"Sig.VendorAllowed (−10)\" : 10\n```\n\nNotes\n- Factors in Assessment.Factors report the exact weights (negative values reduce Score).\n- Actual weights are configurable in code and may evolve; see README map above for typical values.\n\n## Sample Scenario Scores (Illustrative)\n\nGitHub's Mermaid version may not support the new `chart` directive yet, so here's a pie fallback and a simple table.\n\n```mermaid\npie showData\n    title Scenario Scores (Illustrative)\n    \"Plain PDF (0)\" : 0\n    \"PDF + JS (20)\" : 20\n    \"DOCX + Macros (30)\" : 30\n    \"DOCX + RemoteTpl (55)\" : 55\n    \"ZIP with Executable (25)\" : 25\n    \"MSI + CustomAction (50)\" : 50\n```\n\n```\nScenario                  Score\n------------------------  -----\nPlain PDF                 0\nPDF + JS                  20\nDOCX + Macros             30\nDOCX + Remote Template    55\nZIP with Executable       25\nMSI with Custom Action    50\n```\n\nThese values are illustrative only — actual scores depend on which signals are present and the configured weights.\n\n## Settings\n\n- HeaderReadBytes (default 4096)\n- DetectionReadBudgetBytes (default 1 MB)\n- SecurityScanScripts (default true)\n- VerifyAuthenticodeWithWinTrust (default true on Windows)\n- VerifyAuthenticodeRevocation (default false)\n- JS minified heuristics: JsMinifiedMinLength, JsMinifiedAvgLineThreshold, JsMinifiedDensityThreshold\n- Assessment thresholds: AssessmentWarnThreshold, AssessmentBlockThreshold\n- Vendor allow‑list: AllowedVendors (string[]), VendorMatchMode (Contains|Exact)\n - Secrets: SecretsScanEnabled (default true)\n\n## Secrets Summary (privacy‑safe)\n\nThe full object (Raw/FileAnalysis) exposes \u003ccode\u003eSecrets\u003c/code\u003e with category counts only — no values are stored:\n\n```powershell\n$fa = Get-FileInsight -Path .\\script.ps1\n$fa.Secrets | Format-List\n```\n\n```csharp\nvar fa = FileInspector.Analyze(path);\nvar s = fa.Secrets;\nConsole.WriteLine($\"privKeys={s?.PrivateKeyCount} jwt={s?.JwtLikeCount} keyPat={s?.KeyPatternCount}\");\n```\n\n## Signatures (Authenticode)\n\n- Cross‑platform\n  - Parses Authenticode PKCS#7 and extracts the content digest (SpcIndirectDataContent)\n  - Recomputes PE image digest excluding checksum and WIN_CERTIFICATE table\n  - Sets AuthenticodeInfo.FileHashMatches and FileDigestAlgorithm\n- Windows (optional)\n  - WinVerifyTrust policy verification (catalog-aware) → IsTrustedWindowsPolicy + WinTrustStatusCode\n\n## Permissions \u0026 Ownership\n\n- Unix: mode bits via .NET (UnixFileMode); owner/group names via `stat` where available\n- Windows: Owner/Group friendly names (NTAccount), ACL summaries\n  - EveryoneReadAllowed/EveryoneWriteAllowed\n  - BuiltinUsersReadAllowed/BuiltinUsersWriteAllowed\n  - AdministratorsReadAllowed/AdministratorsWriteAllowed\n  - HasDenyEntries\n\n## Platforms \u0026 AOT\n\n- .NET 8, .NET Standard 2.0, .NET Framework 4.7.2\n- NativeAOT friendly; WinVerifyTrust runs only on Windows\n\n## Build\n\n- Library: `dotnet build FileInspectorX/FileInspectorX.csproj`\n- Tests: `dotnet test`\n- PowerShell module: `dotnet build FileInspectorX.PowerShell` (then Import-Module the built DLL)\n\n## Notes\n\n- Script “security findings” are neutral codes — reduces AV triggers\n- Owner/group on Unix via `stat` when available (fields may be null; mode bits still populate)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevotecit%2Ffileinspectorx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fevotecit%2Ffileinspectorx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevotecit%2Ffileinspectorx/lists"}