Metadata-Version: 2.5
Name: devguard-scanner
Version: 0.4.0
Summary: Scan untrusted code repositories for malware before you open, install, or run them. Files are analyzed as data and never executed.
Project-URL: Homepage, https://github.com/yilmazhasan/devguard-scanner
Project-URL: Documentation, https://github.com/yilmazhasan/devguard-scanner/tree/main/docs
Project-URL: Issues, https://github.com/yilmazhasan/devguard-scanner/issues
Project-URL: Changelog, https://github.com/yilmazhasan/devguard-scanner/blob/main/CHANGELOG.md
Author: yilmazhasan
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: devsecops,malware,mcp,scanner,security,supply-chain,vscode
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.12
Requires-Dist: pydantic<3,>=2.7
Requires-Dist: pyyaml<7,>=6.0.1
Provides-Extra: anthropic
Requires-Dist: anthropic<2,>=1.0; extra == 'anthropic'
Provides-Extra: api
Requires-Dist: fastapi<1,>=0.115; extra == 'api'
Requires-Dist: uvicorn<1,>=0.30; extra == 'api'
Provides-Extra: mcp
Requires-Dist: mcp<3,>=2.3; extra == 'mcp'
Provides-Extra: mongodb
Requires-Dist: pymongo<5,>=4.8; extra == 'mongodb'
Provides-Extra: openai
Requires-Dist: openai<4,>=1.50; extra == 'openai'
Description-Content-Type: text/markdown

# DevGuard

Scan a repository for malware **before** you open it in your IDE, install its dependencies, or run it.

Malicious repositories (fake job-interview tasks, poisoned forks, hijacked packages) rarely wait for you to run
`main.py`. They run automatically: a VS Code task on folder open, an npm `postinstall` script, a git hook, an AI
assistant hook, a loader hidden in `tailwind.config.js`. DevGuard finds those triggers, follows them to the code
they run, and tells you whether it is safe to proceed. It reads files as data and **never executes anything**.

## Install

```bash
pipx install devguard-scanner        # or: uv tool install devguard-scanner
```

## Use

```bash
devguard scan path/to/repo
```

```text
DevGuard scan complete
Target:   interview-task
Verdict:  BLOCK | Do not open, install, or run this project. Strong indicators of malicious behavior were found.
Findings: 5 (1 critical, 2 high, 1 medium, 1 low)
  - [critical] Automatic trigger reaches dangerous code (package.json:5)
  - [high] Browser profile data targeted (lib/collect.js:7)
  - [high] Cryptocurrency wallet data targeted (lib/collect.js:10)
Report (md): ~/devguard-scanner/reports/interview-task-1a2b3c4d/latest/report.md
```

| Verdict | Meaning |
|---|---|
| `block` | Do not open, install, or run it. |
| `review` | Read the report first. |
| `indicators` | Weak signals only, often benign. |
| `no-indicators` | Nothing found by the enabled checks (not a guarantee). |

Exit code `1` means findings at or above `--fail-on` (default `high`), so it works as a CI gate.

## Scan a GitHub repository without cloning it

```bash
devguard scan https://github.com/owner/repo          # add --ref BRANCH|TAG|SHA
```

The repository is downloaded into a temporary directory, scanned, and deleted. `git` is never run, so clone-time
exploits and hooks cannot trigger, and the files never sit in a folder your IDE could open. Private repositories
work with your own token (`GH_TOKEN`, `GITHUB_TOKEN`, or `DEVGUARD_GITHUB_TOKEN`).

## No install: hosted API or Docker

```bash
# hosted API (public repositories), Swagger UI at https://devguard-scanner.vercel.app/docs
curl -s 'https://devguard-scanner.vercel.app/v1/scans/github/owner/repo?format=md'

# one-off scan in a throwaway container
docker run --rm ghcr.io/yilmazhasan/devguard-scanner scan https://github.com/owner/repo --stdout md

# self-hosted API, plus local scans of anything you copy into ~/devguard-scanner-data (mounted read-only)
docker compose up -d
```

See the [API guide](docs/api.md) and the [Docker guide](docs/docker.md). Optional AI explanations work with
your own provider key; the server never stores it.

## More

- [Getting started](docs/getting-started.md): options, reports, exit codes
- [AI investigation](docs/ai.md): optional explanations from Claude, OpenAI, Gemini, or a local model
- [Provider plugins](docs/plugins.md): connect any LLM with a small Python file
- [MCP server](docs/mcp.md): let Claude Code, Cursor, or Copilot check a repo before acting on it
- [HTTP API](docs/api.md) · [Docker](docs/docker.md): scan without installing, or self-host
- [CI and pre-commit](docs/ci.md) · [Configuration](docs/configuration.md) · [How it works](docs/how-it-works.md)
- [Contributing](CONTRIBUTING.md) · [Security policy](SECURITY.md)

Licensed under [Apache-2.0](LICENSE).
