How it works

malware-detector doesn't reinvent detection. It runs proven engines, turns their output into a single format and applies the same rules to all of it.

        your code / package
                │
   ┌────────────┼──────────────┬─────────────────────┐
   ▼            ▼              ▼                     ▼
 Semgrep    heuristics     GuardDog            malcontent
 + rule     (packed /     (npm / PyPI         (YARA, optional
  pack     obfuscated     packages, `deps`)    --with-malcontent)
   │         lines)            │                     │
   └────────────┴──────┬───────┴─────────────────────┘
                       ▼
            normalise → suppress → collapse → rank
                       │
            human report · JSON · SARIF · exit code

The pipeline

1. Run the engines. scan runs Semgrep with the bundled rule pack plus the built-in heuristics, and malcontent if you ask for it. deps runs GuardDog on a package. More about the engines →
2. Normalise. Every engine's output becomes the same finding format: rule, severity, file, line, message, engine and snippet. Code an engine couldn't read becomes a finding too, so nothing is silently treated as clean.
3. Suppress. Your .malware-detector-ignore.json is applied to all engines in the same way.
4. Collapse. When several rules flag the same line, only the most severe finding is kept. Weak signals don't pile up into noise.
5. Rank and report. Findings are sorted worst-first and printed as text, JSON or SARIF, followed by a summary of what was scanned. The exit code reflects your --fail-on threshold.

Severity model

Severity	Meaning
CRITICAL	High-confidence malicious behaviour, e.g. a secret flowing to the network
HIGH	Strong signal, e.g. a packed/obfuscated line or a suspicious package attribute
MEDIUM	Worth a look; a capability that is often benign, e.g. shell=True

Two design choices keep the report useful:

• Low-confidence rules report at MEDIUM. You still see them by default, but --min-severity HIGH hides them in one flag.
• malcontent findings on source files are capped at MEDIUM. Its string-based signatures can't see code structure. They help catch more malware, but they can't fail a HIGH gate on their own.

Why "thin orchestrator"?

Semgrep, GuardDog and malcontent are maintained by dedicated teams and used at scale. Building on them means malware-detector gets their parsers, language support and signature updates for free, and can concentrate on what they don't provide: malware-focused rules, a single report and sensible defaults.

The engines are installed next to malware-detector and run from there, using the exact pinned versions. A different Semgrep on your PATH won't change your results.