BinSkim is a binary static analysis tool that checks compiler, linker, and other security-relevant characteristics of Windows Portable Executable (PE), Linux ELF, and macOS Mach-O files. Results use the Static Analysis Results Interchange Format (SARIF).
Download the Microsoft.CodeAnalysis.BinSkim NuGet package and select the executable for the platform where BinSkim will run. See Install BinSkim for the package layout and supported runtime identifiers.
The examples assume the selected executable is available as BinSkim on PATH. Analyze a binary and write the results to a SARIF file:
BinSkim analyze path-to-binary --output results.sarifRun BinSkim analyze --help for the authoritative command-line reference.
| Document | Purpose |
|---|---|
| User guide | Installation, analysis workflows, rule selection, symbols, SARIF output, and automation guidance |
| Rule reference | Generated descriptions and messages for every BinSkim rule |
| Troubleshooting | Common analysis failures and rule-specific remediation |
| Release history | Changes included in each release |
| Rule contributions | End-to-end workflow for adding or changing a rule |
Build the solution from the repository root:
dotnet build src/BinSkim.sln -c ReleaseOn Windows, BuildAndTest.cmd restores and builds the solution, runs tests, creates platform packages and NuGet packages, and regenerates docs\BinSkimRules.md.
On Linux and macOS, BuildAndTest.sh runs the test suite. It does not perform the packaging and generated-documentation steps from the Windows script.
Use the rule contribution guide for rule changes. For other changes, open or locate a relevant GitHub issue and keep the implementation focused on that scenario.
Builds that deploy Windows x64 DIA download Microsoft.VisualCpp.DIA.SDK from
the public Visual Studio Stable distribution. The version, immutable download URL
and SHA-256 hashes of the VSIX and native DLL are pinned in
src\Directory.Packages.props. MSBuild caches and verifies the SDK in each
project's intermediate directory before deploying only msdia140.dll. A clean
build needs access to download.visualstudio.microsoft.com; it does not need
Visual Studio or COM registration. Non-Windows builds do not download the SDK
unless publishing for win-x64. The SDK contains no managed Dia2Lib.dll, so
the existing interop assembly and managed TraceEvent dependency are unchanged. See
the runtime notices for provenance and licensing.
The C# tests validate the pinned SDK DLL by default. On Windows x64, run the same tests against a trusted candidate DLL with the standard .NET test runner:
dotnet test src\BinSkim.sln -c Release --environment "BINSKIM_DIA_CANDIDATE=C:\candidate\msdia140.dll"Test-only native-library resolution selects the candidate for BinaryParsers'
in-process DIA calls without replacing build outputs or changing the production
loader. The xUnit tests check compiler options, function security flags, source
checksums, Source Link streams, segments and section contributions, including
classic-PDB/MSFZ equivalence. No PowerShell wrapper or second test framework is
required. This checks BinSkim's exercised contracts, not every DIA SDK interface
or binary compatibility of a replacement managed Dia2Lib.dll.
SymsrvTests
exercise DIA/symsrv using self-contained symbol stores on Windows. No external
network or credentials are required.
dotnet test src\Test.UnitTests.BinaryParsers\Test.UnitTests.BinaryParsers.csproj -c Release --filter FullyQualifiedName~SymsrvTests --blame-hang --blame-hang-timeout 180sSymbolServerIntegrationTests
cover real servers and require Windows with permitted outbound HTTPS.
Local runs exclude Category=LiveSymbolServer by default; explicit filters
select live cases. Windows CI runs the public case (Requires=Network) inside
Build and Test, excluding private cases (Requires=PrivateSymbolServer).
Linux CI excludes live cases.
Run the public case with:
dotnet test src\Test.FunctionalTests.BinSkim.Driver\Test.FunctionalTests.BinSkim.Driver.csproj -c Release --filter "Category=LiveSymbolServer&Requires!=PrivateSymbolServer" --logger trx --blame-hang --blame-hang-timeout 180sRun private cases only on a protected, network-enabled Windows agent with an authorized managed/workload identity or another approved authorization method. The agent must configure the native symbol client's credential provider. Select private cases with:
dotnet test src\Test.FunctionalTests.BinSkim.Driver\Test.FunctionalTests.BinSkim.Driver.csproj -c Release --filter "Requires=PrivateSymbolServer" --logger trx --blame-hang --blame-hang-timeout 180sSet BINSKIM_SYMBOL_SERVER_TEST_CONFIG to a protected runtime JSON file.
Each array entry supplies Name (a non-sensitive alias), ServerUrl (HTTPS, no
user information or query string), and BinaryPath (a controlled PE whose full
PDB is on that server). Missing or empty configuration fails a selected test
rather than skipping it. Do not commit this file, private endpoints, customer
binaries or credentials/tokens.
Public access and HTTP 401/403 rejection do not prove private authentication.
For native upgrades, compare baseline and candidate builds in fresh test
processes, retaining TRX results and native version/hash diagnostics. Use
--no-build after deploying a candidate to preserve its test output. Private
authentication, proxies and the supported Windows-image matrix need separate
integration/canary coverage.
Do not report security vulnerabilities through public GitHub issues. Follow the instructions in SECURITY.md.
BinSkim is licensed under the MIT License.