GitHub Packages · MIT · Node ≥ 18
Turn a suspicious file into a structured malware triage report (Markdown, HTML or JSON) using static analysis only.
Static malware triage report generator: hashes, file type, entropy, PE/ELF internals, Office macros and auto-exec, PDF actions, LNK, RTF, archives, scripts and HTML smuggling, IOCs, ATT&CK mapping, a verdict and a YARA starter rule, as Markdown, HTML or JSON. Never executes samples. Zero deps.
1 Point the @mrlouiswright scope at GitHub Packages in .npmrc
@mrlouiswright:registry=https://npm.pkg.github.com2 Install
npm i -D @mrlouiswright/malware-report-sentinelPublished to GitHub Packages, not npmjs.com. GitHub Packages needs a GitHub token with read:packages to install, even for public packages: add //npm.pkg.github.com/:_authToken=${GITHUB_TOKEN} to .npmrc or run npm login --registry=https://npm.pkg.github.com.
$ npx malware-report-sentinel invoice-macro.docmmalware-report-sentinel — 1 target(s) invoice-macro.docm type: zip size: 817 sha256: 2e462acf04ce532166731456962695f0310ceddc263981b7d10b38f2690973a9 verdict: malicious (62/100) CRITICAL invoice-macro.docm Auto-executing macro: AutoOpen [office-autoexec-macro] ↳ fix: Do not enable content. Extract and review the macro with olevba in an isolated lab. HIGH invoice-macro.docm Macro keywords: Shell, CreateObject, powershell [office-macro-suspicious] LOW invoice-macro.docm 2 network indicator(s): hxxp[://]payload[.]badhost[.]ru/a[.]ps1, payload[.]badhost[.]ru [network-indicators] 1 critical, 1 high, 1 low✖ Failing (fail-on: high).
Drop in a phishing attachment, a dropper or an odd binary and malware-report-sentinel produces the report an analyst would otherwise write by hand: sample details and hashes, a verdict and risk score, findings, format-specific internals (PE/ELF, VBA macros, PDF keywords, archive contents, shortcut targets, decoded PowerShell), embedded objects analysed recursively, defanged IOCs, a MITRE ATT&CK mapping, a starter YARA rule and recommendations, with TLP marking, analyst and case fields.
Samples are never executed, opened, rendered or uploaded. Everything is parsed from bytes in pure JavaScript. CLI, library and GitHub Action. Node.js 18+, zero runtime dependencies.
Full header, section, entropy, import, imphash, Rich header, overlay and TLS parsing; packer hints (UPX, ASPack, VMProtect, Themida…), RWX sections, entry-point anomalies, injection APIs, capability mapping, hardening (shares its engine with binary-sentinel)
vbaProject.bin extraction and MS-OVBA decompression of macro source, auto-exec entry points (AutoOpen, Document_Open, Workbook_Open, ActiveX _Painted/_GotFocus…), suspicious macro keywords (Shell, CreateObject, XMLHTTP, ADODB.Stream, Declare … Lib, Chr() chains), remote template injection (external attachedTemplate/oleObject relationships), DDE fields, embedded OLE/ActiveX
VBA project detection and macro source recovery, Ole10Native objects, DDE
\objdata/\objupdate OLE objects, Equation Editor CLSID (CVE-2017-11882 family), hex-encoded payloads decoded and scanned
/JavaScript, /JS, /OpenAction, /AA, /Launch, /EmbeddedFile, /URI, /AcroForm, /XFA, /SubmitForm, /ObjStm, /Encrypt and hex-escaped name obfuscation (/J#61vaScript)
StringData parsing (arguments, working dir, icon); shells, script hosts and LOLBins; padded arguments
Entry listing, encrypted entries, executables/scripts inside, double extensions; nested executables and documents analysed recursively (decompression capped at 64 MB)
-EncodedCommand (decoded), FromBase64String/Gzip, download cradles (IEX + DownloadString, curl \| sh), LOLBins (certutil, mshta, regsvr32, rundll32, bitsadmin, wmic, schtasks, msbuild…), obfuscation (char codes, reversal, concatenation, eval, escape characters), AMSI/Defender tampering, shadow-copy deletion; Base64 blobs decoded and scanned for payloads
# Example
npx malware-report-sentinel invoice.docm --report invoice-report.md --html invoice-report.html --tlp AMBER --analyst "Louis Wright" --case IR-2026-042# one report covering many samples
npx malware-report-sentinel ./quarantine -f report > triage.md# Example
npx malware-report-sentinel sample.exe --yara sample.yar --json sample.jsonpermissions:
contents: read
security-events: write # only for the SARIF upload
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
with: { persist-credentials: false }
- uses: MrLouisWright/malware-report-sentinel@v1
with:
targets: 'quarantine/'
fail-on: high
sarif: malware-report-sentinel.sarif
- uses: github/codeql-action/upload-sarif@v3
if: always()
with: { sarif_file: malware-report-sentinel.sarif }| Flag | Description |
|---|---|
| Report | |
--report <file> | Write the full Markdown malware report |
--html <file> | Write the report as standalone HTML |
--yara <file> | Write the starter YARA rule(s) |
--title <text> | Report title |
--analyst <name> | Analyst name |
--case <id> | Case / ticket reference |
--tlp <level> | CLEAR | GREEN | AMBER | AMBER+STRICT | RED |
--benign <list> | Domains to leave out of the IOC list |
-f report | Print the Markdown report to stdout |
| Policy and output | |
-c, --config <file> | JSON config (default .malware-report-sentinel.json if present) |
-f, --format <fmt> | text (default) | json | sarif | markdown |
--json/--sarif/--markdown <file> | Also write that format to a file |
--fail-on <sev> | critical | high | medium | low | info | none (default high) |
--list-rules | Print rules and default severities |
--no-color | Disable colours |
Full reference, config file format and API in the README.
Support this project
I build free, open-source tools that help developers ship safer websites. Every coffee helps keep them maintained, documented and free for everyone.
Buy me a coffee (opens Stripe in a new tab)Secure checkout by Stripe
