Metadata-Version: 2.5
Name: devguard-scanner
Version: 0.1.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/dev-guard
Project-URL: Documentation, https://github.com/yilmazhasan/dev-guard/tree/main/docs
Project-URL: Issues, https://github.com/yilmazhasan/dev-guard/issues
Project-URL: Changelog, https://github.com/yilmazhasan/dev-guard/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: mcp
Requires-Dist: mcp<3,>=2.3; extra == 'mcp'
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): ~/.local/share/devguard/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.

## 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
- [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).
