Metadata-Version: 2.4
Name: malware-detector-py
Version: 0.1.0rc2
Summary: Multi-language malware detector that orchestrates AST/taint and supply-chain engines into one report.
Author: Wael BEN ZID EL GUEBSI
License-Expression: MIT
Keywords: malware,security,semgrep,static-analysis,supply-chain
Requires-Python: <3.14,>=3.10
Requires-Dist: guarddog<4,>=3.0
Requires-Dist: semgrep==1.121.0
Requires-Dist: setuptools<81
Provides-Extra: dev
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# 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):

```sh
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](docs/installation.md)
for the full dependency model, development setup, and install gotchas.

## Usage

Scan source files or directories:

```sh
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):

```sh
malware-detector deps ./path/to/package
```

Incremental scans for git hooks:

```sh
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):

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

### In Docker (offline / CI)

```sh
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

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