binary-sentinel

binary-sentinel

Static PE and ELF triage in pure JavaScript: headers, sections, entropy, imports, imphash, packer hints, capabilities and hardening checks.

binary-sentinel gives an analyst a quick first look at a Windows PE (EXE/DLL/SYS, 32- and 64-bit) or Linux/Unix ELF file without leaving the terminal or CI. The same parser can also check your own release binaries for missing hardening (ASLR, DEP/NX, CFG, PIE, RELRO, stack canaries). Samples are only ever read as bytes and are never executed or loaded.

CLI, library and GitHub Action. Node.js 18+, zero runtime dependencies, no native code.

What it extracts

PE: machine, bitness, subsystem, compile timestamp, entry point and its section, image base, DLL characteristics (ASLR, high-entropy VA, DEP, CFG, NO_SEH, AppContainer), data directories, sections (name, sizes, RWX flags, Shannon entropy, MD5), imports (including delay-load imports and ordinals), imphash (same algorithm as pefile, verified against it), exports, TLS callbacks, Rich header (entries + hash), overlay (offset, size, entropy, embedded file type), Authenticode presence, .NET (CLR) detection and the header checksum (recomputed).

ELF: class, endianness, OS ABI, type, machine, entry point, program headers (with RWX), sections and their entropy, interpreter, DT_NEEDED libraries, SONAME, RPATH/RUNPATH, dynamic imports/exports, an import hash (MD5 of sorted imported symbols), stripped state, and checksec-style hardening: PIE, NX, RELRO (none/partial/full), BIND_NOW, stack canary and FORTIFY_SOURCE.

Every file also gets its MD5/SHA1/SHA256/SHA512, overall entropy and a magic-byte type (also recognises Mach-O, ZIP, PDF, OLE, LNK, RAR, 7z, CAB, ISO, scripts…).

Mach-O, Authenticode and capability rules

binary-sentinel ./MyApp.app/Contents/MacOS/MyApp      # Mach-O (thin or universal)
binary-sentinel setup.exe                             # verifies the Authenticode signature
binary-sentinel ./samples --rules ./my-capa-rules/    # capa-style YAML rules

Capability rules use a subset of the capa rule format: api, import, export, string (exact or /regex/i), substring, section, format, os, arch, match and characteristic: embedded pe, combined with and, or, not, optional and N or more. All scopes are evaluated at file level; features that need disassembly (bytes, number, mnemonic, offset) never match. Set meta.severity to choose the finding severity.

Authenticode verification checks the image hash, the signed digest and the signer's signature (including nested signatures). It does not consult an OS trust store: a valid signature from a certificate chain you don't trust is still reported as valid, with the chain listed in JSON output (--details).

import { analyzeBuffer, verifyAuthenticode, parseMachO, loadRules } from 'binary-sentinel';
const { info, raw, summary } = analyzeBuffer(buf, 'file.exe', { rules: loadRules('./rules') });

Module formats and types

Ships ESM and CommonJS (import and require both work, via exports), with TypeScript declarations generated from the source at build time. Tests run on Node 18/20/22 in GitHub Actions (test/), including require/import checks against the packed tarball; releases are published with npm provenance.

Rules

Network, process, discovery, crypto and memory APIs are listed as capabilities in the summary but do not raise findings on their own, because almost every program uses them. IsDebuggerPresent on its own is ignored because the MSVC CRT imports it.

Profiles

• --profile triage (default): for malware triage and incoming-file screening.
• --profile hardening: for your own build artefacts. Missing ASLR/NX/RPATH safety becomes high, RELRO/canary medium, and capability findings drop to info.

Install and run

npx binary-sentinel suspicious.exe
npx binary-sentinel ./samples --format json --json triage.json   # JSON includes full headers/sections/imports
npx binary-sentinel dist/ --profile hardening --fail-on high      # CI gate for your own binaries

Library

import { parsePE, parseELF, triage, capabilities, entropy } from 'binary-sentinel';
import { readFileSync } from 'node:fs';

const pe = parsePE(readFileSync('sample.exe'));
pe.imphash; pe.sections.map((s) => [s.name, s.entropy]); pe.tlsCallbacks; pe.overlay;

const report = triage(['samples/'], { profile: 'triage' });

Configuration

Put a .binary-sentinel.json in the working directory (or pass --config <file>). Every key is optional; CLI flags override the file.

{
  "failOn": "high",
  "severity": { "packer-section": "high" },
  "allow": [
    { "rule": "packer-section", "match": "*vendor-installer.exe", "reason": "Accepted risk, ticket SEC-123", "expires": "2027-03-31" }
  ]
}

• severity changes the severity of any rule, or turns it off.
• allow suppresses findings. Each entry needs a rule (globs such as packer-* work) and a reason, and can be narrowed with target and match (a glob tested against the target, location and value). Suppressed findings are listed in the JSON report. When expires (YYYY-MM-DD) has passed, the finding comes back together with an allow-expired finding, so exceptions can't be forgotten. Entries that match nothing are reported as allow-unused (info).

Output and exit codes

• --format text|json|sarif|markdown for stdout, plus --json, --sarif and --markdown <file> to write extra copies in one run. SARIF 2.1.0 works with GitHub code scanning.
• --fail-on critical|high|medium|low|info|none (default high).
• Exit code 0: passed. 1: at least one finding at or above --fail-on. 2: usage or config error, or a target could not be checked.
• --list-rules prints every rule with its default severity.

GitHub Action

permissions:
  contents: read
  security-events: write   # only for the SARIF upload
steps:
  - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
    with: { persist-credentials: false }
  - uses: MrLouisWright/binary-sentinel@v1
    with:
      targets: 'dist/'
      fail-on: high
      sarif: binary-sentinel.sarif
  - uses: github/codeql-action/upload-sarif@v3
    if: always()
    with: { sarif_file: binary-sentinel.sarif }

Inputs: targets, fail-on, config, sarif, json, job-summary (Markdown report in the job summary, default true), args (extra CLI flags), profile. Outputs: markdown-file, exit-code.

Requirements

Node.js 18 or newer. No runtime dependencies.

Support

If this project is useful to you, you can support its development with a donation: Buy me a coffee. It helps keep these tools maintained, documented and free for everyone.

Credit (optional)

Free to use under MIT, no attribution required. If binary-sentinel helps you, a link back is appreciated:

<a href="https://louiswright.co.uk">Built with binary-sentinel by Louis Wright</a>

[![Built with binary-sentinel by Louis Wright](https://img.shields.io/badge/built%20with-binary--sentinel-blue)](https://louiswright.co.uk)

License

MIT © Louis Wright (Louis Wright)