Vyper Guard

Static security analyzer for Vyper smart contracts.

Vyper Guard scans .vy sources, runs a focused detector suite, and emits structured security reports for auditors, developers, and security teams. It is designed for fast local analysis with optional compiler-backed semantics and verification workflows.

Website: https://vyper-web.vercel.app

What's new in 0.6.0

Vyper Guard 0.6.0 is a precision and trust release for professional security workflows:

• Lower-noise analysis: improved call-target, mutability, timestamp, arithmetic, access-control, and legacy Vyper reasoning reduces avoidable findings on production contracts.
• Clearer trust signals: reports now identify semantic-engine provenance, detector maturity, degraded analysis, protocol assumptions, and reviewed audit attribution.
• Safer remediation: compiler-backed validation blocks writes when a generated patch does not validate, while governed baseline acceptances require ownership and rationale.
• Audit-focused output: concise terminal triage highlights actionable candidates while JSON, Markdown, SARIF, and HTML retain the full evidence set.
• Reproducible quality evidence: pinned production-contract corpora, detector quality gates, and an evidence-backed Curve DAO benchmark make current coverage and limitations explicit.
• CI-ready distribution: a reusable GitHub Action generates SARIF for code-scanning and regression workflows.

See the changelog for the complete release notes.

Who it is for

• Auditors and auditing companies
• Protocol and dApp developers
• Security and engineering teams

Primary use cases

• Pre-audit security scans
• CI security gates and regression checks
• Learning and reviewing Vyper security patterns

Features

• Vyper-focused static analysis for .vy contracts
• 22 built-in detectors with explicit supported, beta, and experimental maturity labels
• Always-on compiler advisories (compiler_version_check)
• Multiple report formats: CLI, JSON, Markdown, SARIF, HTML
• Verification workflows for unit and fuzz tests (verify, test, fuzz)
• Baseline suppression and baseline-diff for CI stability
• Optional remediation mode with tiered auto-fix controls
• Optional compiler-backed semantic mode (install vyper extra)
• Compiler semantics can also use a vyper executable on PATH, with engine, version, and fallback provenance in reports
• CFG-aware CEI analysis plus cyclomatic complexity metrics in reports and stats
• Project-wide graph for directory scans (imports, interfaces, call/state maps)
• Explorer and on-chain analysis workflows (explorer, analyze-address)
• Deterministic priority scoring with governance notes and explicit fallback controls (--allow-ai-fallback)

Installation

Python 3.10+ is required.

pip install vyper-guard

Optional extras:

pip install vyper-guard[vyper]       # compiler-backed semantics
pip install vyper-guard[monitor]     # on-chain monitoring (web3 + aiohttp)
pip install vyper-guard[remediation] # GitHub remediation support
pip install vyper-guard[all]         # all optional features

Verify:

vyper-guard --version

Quickstart

Analyze a contract:

vyper-guard analyze contract.vy

For the lower-noise supported and beta profile:

vyper-guard analyze contract.vy --detectors recommended

--detectors all preserves the complete legacy detector set, including experimental rules. Detector maturity describes validation evidence, not issue severity.

Verify static analysis plus tests:

vyper-guard verify contract.vy --unit-cmd "pytest -q"

Generate a machine-readable report:

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

Generate a SARIF report for code scanning:

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

Generate an HTML report:

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

Command guide (when to use)

Core commands

Verification (unit + fuzz)

Use verify for a single report that includes static findings plus unit/fuzz results. Use test or fuzz to run them independently.

vyper-guard verify contract.vy --unit-cmd "pytest -q"
vyper-guard fuzz contract.vy --fuzz-cmd "your-fuzz-command"

You can also set defaults via environment variables:

export GUARDIAN_UNIT_CMD="pytest -q"
export GUARDIAN_FUZZ_CMD="your-fuzz-command"

Configuration

Configuration is loaded in this order:

1. CLI flags
2. Environment variables
3. .guardianrc in the current directory (or .guardianrc.yaml, .guardianrc.yml)
4. ~/.guardianrc

Create a starter config:

vyper-guard init

Example verification config:

verification:
  unit_command: ["pytest", "-q"]
  fuzz_command: ["your-fuzz-command"]
  timeout_seconds: 600
  max_output_chars: 20000

Explorer and LLM keys are read from environment variables:

export GUARDIAN_EXPLORER_API_KEY="..."
export GUARDIAN_LLM_API_KEY="..."

Output formats

Use --format and --output for structured reports:

vyper-guard analyze contract.vy --format json --output report.json
vyper-guard analyze contract.vy --format sarif --output report.sarif
vyper-guard analyze contract.vy --format html --output report.html

Supported formats: cli, json, markdown, sarif, html.

Security scoring

Each run produces a backward-compatible heuristic risk indicator from 0 to 100 and a grade. It measures detected heuristic risk, not contract safety or deployment readiness. Structured reports also include analysis_trust with compiler coverage, detector maturity, degradation reasons, and limitations.

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. unchecked_send
4. missing_event_emission
5. timestamp_dependence
6. integer_overflow
7. unprotected_selfdestruct
8. dangerous_delegatecall
9. unprotected_state_change
10. send_in_loop
11. unchecked_subtraction
12. cei_violation
13. tx_origin_auth
14. missing_zero_address_check
15. weak_randomness
16. locked_ether
17. shadowed_state_variable
18. missing_input_validation
19. unsafe_assembly
20. missing_return_value
21. division_before_multiplication
22. incorrect_erc20_return

Compiler advisories are always evaluated and reported as compiler_version_check findings.

Remediation

Use remediation mode for guided fixes:

vyper-guard analyze contract.vy --fix

Limit remediation scope by risk tier:

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

Dry-run remediation:

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.