malware-detector-py 0.1.0rc2

Multi-language malware detector that orchestrates AST/taint and supply-chain engines into one report.

malware-detector

A generic, multi-language malware detector for JavaScript, TypeScript, Python, and PHP, tuned to minimize false negatives. It is a thin orchestrator over existing detection engines (Semgrep/Opengrep for AST + taint analysis, GuardDog for supply-chain metadata, malcontent for release diffing), normalizing their findings into one report with a single suppression model.

Install

One command (recommended):

uv tool install malware-detector-py
# or
pipx install malware-detector-py

This pulls the core engine stack (Semgrep + GuardDog) in one step. The optional diff mode also needs malcontent, a standalone Go binary: brew install malcontent.

Requires Python >=3.10,<3.14 (3.13 recommended). See docs/installation.md for the full dependency model, development setup, and install gotchas.

Usage

Scan source files or directories:

malware-detector scan path/to/code            # human report
malware-detector scan src tests               # multiple paths
malware-detector scan . --json                # JSON output
malware-detector scan . --sarif > out.sarif   # SARIF for CI / code scanning
malware-detector scan . --min-severity HIGH   # hide low-confidence findings
malware-detector scan . --explain             # show engine + matched line

Scan a package for supply-chain risk (via GuardDog; npm/PyPI auto-detected):

malware-detector deps ./path/to/package

Incremental scans for git hooks:

malware-detector scan --staged                # pre-commit: staged files only
malware-detector scan --changed               # pre-push: changed vs HEAD + untracked

Exit codes: 0 clean, 1 findings (at/above --fail-on), 2 usage error, 3 engine error. Suppress accepted findings with a .malware-detector-ignore.json at the repo root (match by path, ruleId, and/or line).

As a pre-commit hook

Add to your .pre-commit-config.yaml (requires Python <3.14, see installation):

repos:
  - repo: https://github.com/<owner>/malware-detector
    rev: v0.0.1
    hooks:
      - id: malware-detector

In Docker (offline / CI)

docker build -t malware-detector .
docker run --rm -v "$PWD:/scan:ro" malware-detector scan .
docker run --rm -v "$PWD:/scan:ro" malware-detector deps .

The image bundles the core engines (Semgrep + GuardDog). --with-malcontent needs the mal Go binary, which is not bundled.

Development

make install   # editable install + dev tools
make check     # format check + lint + type-check + tests