Metadata-Version: 2.4
Name: vyper-guard
Version: 0.3.9
Summary: Real-time vulnerability monitoring and auto-remediation for Vyper smart contracts
Project-URL: Homepage, https://github.com/preethamak/vyper
Project-URL: Website, https://vyper-web.vercel.app
Project-URL: Repository, https://github.com/preethamak/vyper
Project-URL: Issues, https://github.com/preethamak/vyper/issues
Project-URL: Documentation, https://github.com/preethamak/vyper/tree/main/docs
Author: Preetham AK
License: MIT
License-File: LICENSE
Keywords: blockchain,security,smart-contracts,static-analysis,vulnerability-scanner,vyper
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Testing
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.31.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.9.0
Provides-Extra: all
Requires-Dist: aiohttp>=3.9.0; extra == 'all'
Requires-Dist: pygithub>=2.0.0; extra == 'all'
Requires-Dist: vyper>=0.4.0; extra == 'all'
Requires-Dist: web3>=6.0.0; extra == 'all'
Provides-Extra: monitor
Requires-Dist: aiohttp>=3.9.0; extra == 'monitor'
Requires-Dist: web3>=6.0.0; extra == 'monitor'
Provides-Extra: remediation
Requires-Dist: pygithub>=2.0.0; extra == 'remediation'
Provides-Extra: vyper
Requires-Dist: vyper>=0.4.0; extra == 'vyper'
Description-Content-Type: text/markdown

# Vyper Guard

Vyper Guard is a static security analyzer for Vyper smart contracts. It helps teams detect common vulnerability patterns, review security posture before deployment, and generate structured reports for engineering and CI workflows.

## Highlights

- Native Vyper-focused static analysis
- 12 built-in detectors across reentrancy, access control, external call safety, arithmetic risks, and compiler advisories
- Multiple report formats: CLI, JSON, Markdown, SARIF, and HTML
- Optional baseline suppression and baseline-diff workflows for CI stability
- Optional remediation mode with tiered auto-fix controls
- Optional compiler-backed semantic mode (requires `vyper` extra)
- Explorer and on-chain analysis workflows (`explorer`, `analyze-address`)
- AI advisory triage support with explicit fallback control (`--allow-ai-fallback`)

## What is New in v0.3.9

- Added semantic mode selection (`--semantic-mode`) with `source` (default) and `compiler` options
- Compiler-backed semantic extraction via the Vyper AST when available, with safe fallback to source mode
- Semantic mode configuration in `.guardianrc` and env override (`GUARDIAN_SEMANTIC_MODE`)
- Coverage metadata aligned with runtime detector catalog for report integrity

## Installation

```bash
pip install vyper-guard
```

Verify:

```bash
vyper-guard --version
```

Optional compiler-backed semantic mode:

```bash
pip install vyper-guard[vyper]
```

## Quick Start

Analyze a contract:

```bash
vyper-guard analyze contract.vy
```

Generate a machine-readable report:

```bash
vyper-guard analyze contract.vy --format json --output report.json
```

Generate a SARIF report for code scanning:

```bash
vyper-guard analyze contract.vy --format sarif --output report.sarif
```

Generate an HTML report:

```bash
vyper-guard analyze contract.vy --format html --output report.html
```

## Core Commands

| Command | Purpose |
|---|---|
| `analyze <file_or_dir>` | Analyze a single contract or directory of contracts |
| `scan <file_or_dir>` | Alias for `analyze` |
| `ast <file>` | Structural AST-oriented contract output |
| `flow <file>` | Function/call-flow visualization data |
| `fix <file>` | Remediation workflow |
| `stats <file>` | Contract metrics and graph artifacts |
| `diff <before> <after>` | Compare security posture between revisions |
| `explorer <address>` | Fetch verified source and ABI metadata |
| `analyze-address <address>` | Analyze explorer-fetched contract source |
| `detectors` | List detector catalog with severity/category |
| `benchmark [dir]` | Detector quality benchmark run |
| `baseline <address>` | Build monitor baseline profile |
| `monitor <address>` | Runtime monitoring and alerts |
| `help` | Full command catalog and usage hints |

## Security Scoring

Each run produces a score from 0 to 100 and a grade.

Base score is 100 with severity-based deductions:

- CRITICAL: -40 points (capped at -50)
- HIGH: -20 points (capped at -40)
- MEDIUM: -8 points (capped at -20)
- LOW: -3 points (capped at -10)
- INFO: -1 point (capped at -5)

Additional trust penalty:

- Detector runtime failures: -10 each (capped at -30)

## Detector Catalog

1. `missing_nonreentrant`
2. `unsafe_raw_call`
3. `missing_event_emission`
4. `timestamp_dependence`
5. `integer_overflow`
6. `unprotected_selfdestruct`
7. `dangerous_delegatecall`
8. `unprotected_state_change`
9. `send_in_loop`
10. `unchecked_subtraction`
11. `cei_violation`
12. `compiler_version_check`

## Remediation

Use remediation mode for guided fixes:

```bash
vyper-guard analyze contract.vy --fix
```

Limit remediation scope by risk tier:

```bash
vyper-guard analyze contract.vy --fix --max-auto-fix-tier B
```

Dry-run remediation:

```bash
vyper-guard analyze contract.vy --fix-dry-run --fix-report remediation-report.json
```

## License

MIT. See LICENSE.

## Disclaimer

Vyper Guard is a static analysis aid and does not guarantee absence of vulnerabilities. Use it together with manual review, testnet validation, and professional audits for high-value deployments.
