Step 1
Install and verify
Install package and confirm CLI availability.
pip install vyper-guard
Documentation • Vyper Guard
Implementation-aligned usage reference
This page is synchronized to DeepWiki coverage and the upstream repository command surface. It prioritizes actual CLI behavior, guardrails, and known limitations over marketing copy.
Step 2
Run first scan
Analyze one `.vy` contract with deterministic detectors.
vyper-guard analyze contract.vy
Step 3
Export artifacts
Generate CI-ready JSON and graph output.
vyper-guard stats contract.vy --graph
Overview
Vyper Guard is a static analyzer for Vyper contracts with optional advisory layers (AI triage, agent mode, explorer context, monitoring). The deterministic core remains the source of truth for verdicts and CI policy decisions.
- Single-contract static analysis via `analyze <file>`.
- 12 detector checks including compiler version advisories.
- CLI, JSON, and Markdown outputs.
- Optional remediation, explorer, and runtime workflows.
Installation
Install from PyPI and validate CLI resolution in your current environment.
installation
$ pip install vyper-guard
$ vyper-guard --version
$ vyper-guard --help
- Python requirement: >=3.10
- Optional monitor dependency:
pip install -e ".[monitor]" - Docker path: scan mounted `.vy` files using `vyper-guard analyze`.
Quick start
quick start
$ vyper-guard analyze contract.vy
$ vyper-guard analyze contract.vy --format json --output report.json
$ vyper-guard analyze contract.vy --ci --severity-threshold HIGH
$ vyper-guard stats contract.vy --graph
The `analyze` command targets a single `.vy` file path. If you want multi-file coverage in CI, invoke `analyze` per file (for example via `find`/`xargs`).
Static analysis pipeline
- 1) Source loading: load and validate non-empty `.vy` source.
- 2) AST parsing: build contract/function/state metadata.
- 3) Compiler check: evaluate pragma against known GHSA advisories.
- 4) Detector execution: run enabled detector set with smart suppression.
- 5) Score + grade: apply severity penalties, tier caps, and trust penalties.
- 6) Reporting: render CLI/JSON/Markdown output.
Metrics and graph provenance
The website intentionally mixes two metric classes, and each chart is tied to one class only.
Model-level charts
- Severity distribution (detector inventory metadata).
- Scoring penalty chart (configured deduction model).
- Risk-domain and capability charts (detector definitions).
These are not from a single contract run; they represent current analyzer design and policy.
Run-derived chart
- Example scan outcomes chart uses real CLI runs on upstream example contracts.
- Run command:
vyper-guard analyze <contract> --format json - Generator: vyper-guard 0.3.6
- Generated: 2026-04-20
| Example | Score | Grade | Findings | Severity Mix |
|---|---|---|---|---|
| docs/examples/safe_vault.vy | 80 | A | 1 | C:0 H:1 M:0 L:0 I:0 |
| docs/examples/token.vy | 57 | C | 4 | C:0 H:3 M:0 L:1 I:0 |
| docs/examples/vulnerable_vault.vy | 0 | F | 15 | C:3 H:6 M:2 L:4 I:0 |
Command reference
| Command | Purpose |
|---|---|
| vyper-guard analyze contract.vy | Run deterministic static analysis for a single contract file. |
| vyper-guard analyze contract.vy --format json --output report.json | Export machine-readable findings for CI and automation workflows. |
| vyper-guard analyze contract.vy --ai-triage --ai-triage-mode llm --allow-ai-fallback | Add advisory AI triage metadata without changing deterministic verdicts. |
| vyper-guard analyze contract.vy --fix-dry-run --max-auto-fix-tier B --fix-report remediation-report.json | Preview remediation safely and export a deterministic fix-plan report. |
| vyper-guard ast contract.vy --format json | Export parsed contract structure and metadata for machine processing. |
| vyper-guard flow contract.vy --format mermaid | Render function/call-flow summaries for architecture review. |
| vyper-guard stats contract.vy --graph | Generate structural metrics plus JSON/HTML graph artifacts. |
| vyper-guard analyze-address 0xYourContractAddress --format json | Analyze a deployed contract from explorer-verified source and metadata. |
| vyper-guard explorer 0xYourContractAddress --provider auto --format json | Fetch verified source, ABI, and contract metadata from explorer providers. |
| vyper-guard agent "Summarize top risks" --file contract.vy | Run LLM-backed advisory agent mode with optional memory and sandbox context. |
| vyper-guard monitor 0xYourContractAddress --rpc https://rpc.url | Run optional live monitoring for deployed contract behavior anomalies. |
| vyper-guard baseline 0xYourContractAddress --rpc https://rpc.url --duration 300 --output baseline.json | Create behavioral baseline data for anomaly-aware monitoring. |
| vyper-guard detectors | List detector inventory and metadata in the CLI. |
| vyper-guard benchmark ./contracts --format json --min-f1 0.70 | Run detector-quality benchmark gates on a labeled contract corpus. |
Sarvam Assist (web)
Sarvam Assist turns Vyper Guard output into structured briefs, multilingual summaries, and voice clips. The web UI sends a trimmed analyzer excerpt to Sarvam APIs and renders the response inline.
sarvam assist setup
$ export SARVAM_API_KEY="your_sarvam_api_key"
$ export SARVAM_CHAT_MODEL="sarvam-105b"
$ export SARVAM_TTS_MODEL="bulbul:v3"
- Run a command in the workbench to unlock Sarvam Assist.
- Summaries and Q&A are advisory; deterministic findings remain authoritative.
- Translations use Sarvam Text Translate; voice clips use Sarvam Text-to-Speech.
- Keep the API key in server-side environment variables only.
AI-assisted triage
AI triage is advisory-only. It cannot override deterministic findings. LLM mode is strict by default and fallback is explicit opt-in.
ai triage
$ vyper-guard analyze contract.vy --format json --ai-triage
$ vyper-guard analyze contract.vy --format json --ai-triage \
$ --ai-triage-mode llm --ai-llm-model gpt-5
$ vyper-guard analyze contract.vy --format json --ai-triage \
$ --ai-triage-mode llm --allow-ai-fallback
$ vyper-guard ai config set provider openai
$ vyper-guard ai config set model gpt-5
$ vyper-guard ai config show
- Use `--no-ai-triage` to disable triage explicitly.
- Policy metadata is included in JSON output (`ai_triage_policy`).
- Treat triage as prioritization support, not a release gate source of truth.
Remediation and fix controls
remediation
$ vyper-guard analyze contract.vy --fix
$ vyper-guard analyze contract.vy --fix --max-auto-fix-tier B
$ vyper-guard analyze contract.vy --fix-dry-run --fix-report remediation-report.json
- Tier A: safest mechanical edits.
- Tier B: moderate-risk edits, review recommended.
- Tier C: advisory/manual refactor prompts.
- Dry-run and write prompts reduce accidental file mutation risk.
Explorer and address analysis
explorer + address
$ vyper-guard explorer 0xYourContractAddress --provider auto --format json
$ vyper-guard analyze-address 0xYourContractAddress --format json
$ vyper-guard explorer config set provider auto
$ vyper-guard explorer config set network sepolia
$ vyper-guard explorer config set api-key
$ vyper-guard explorer config show
Address analysis depends on verified explorer source. Non-Vyper or unavailable source is surfaced with metadata and limitations rather than misleading static verdicts.
LLM agent mode
agent
$ vyper-guard agent "Top 3 security risks" --file contract.vy
$ vyper-guard agent "Summarize ABI attack surface" --address 0xYourContractAddress
$ vyper-guard agent "Validate this patch plan" \
$ --file contract.vy \
$ --memory-file .guardian_agent_memory.jsonl \
$ --sandbox-script tools/check_patch.py
$ vyper-guard agent-memory stats --memory-file .guardian_agent_memory.jsonl
Agent mode is strict by default; use fallback flags only when deterministic degraded output is explicitly acceptable for your workflow.
Monitoring and baseline
monitoring
$ vyper-guard monitor 0xYourContractAddress --rpc https://rpc.url
$ vyper-guard baseline 0xYourContractAddress --rpc https://rpc.url --duration 300 --output baseline.json
$ vyper-guard monitor 0xYourContractAddress --rpc https://rpc.url --baseline baseline.json
Live monitoring requires the optional monitor dependency set and is meant for runtime anomaly detection, not static-code replacement.
Detector catalog
Detector severities can be context-aware (for example, access-control-aware downgrades). The table uses the primary severity for quick taxonomy.
Total
12
Smart Suppression
7
Dynamic Severity
3
Auto-Fix Full
8
| Detector key | Severity | Confidence | Suppression | Auto-Fix | Category |
|---|---|---|---|---|---|
| missing_nonreentrant | CRITICAL | HIGH/MEDIUM | Yes | FULL | Reentrancy |
| unsafe_raw_call | HIGH | MEDIUM | Yes | FULL | External Call |
| missing_event_emission | LOW | MEDIUM | No | FULL | Code Quality |
| timestamp_dependence | LOW | MEDIUM | Yes | ADVISORY | Timestamp |
| integer_overflow | HIGH | HIGH | Yes | PARTIAL | Arithmetic |
| unprotected_selfdestruct | CRITICAL | HIGH | No | FULL | Self-Destruct |
| dangerous_delegatecall | HIGH | HIGH/MEDIUM | No | FULL | Delegate Call |
| unprotected_state_change | HIGH | HIGH | No | FULL | Access Control |
| send_in_loop | HIGH | HIGH | Yes | ADVISORY | Denial of Service |
| unchecked_subtraction | HIGH | MEDIUM | Yes | FULL | Input Validation |
| cei_violation | HIGH | HIGH | No | ADVISORY | Reentrancy |
| compiler_version_check | HIGH | HIGH | Yes | FULL | Compiler Bug |
Scoring and grade policy
Penalty model
- CRITICAL: -40 per finding (cap -50)
- HIGH: -20 per finding (cap -40)
- MEDIUM: -8 per finding (cap -20)
- LOW: -3 per finding (cap -10)
- INFO: -1 per finding (cap -5)
Detector runtime failures apply an additional trust penalty (-10 each, capped at -30).
Grade bands
- A+ (90-100): Production ready
- A (75-89): Minor fixes
- B (60-74): Review required
- C (45-59): Major fixes required
- F (0-44): Do not deploy
Recommended production minimum remains 80+.
Known limitations
DeepWiki and repository docs both emphasize that Vyper Guard is a single-layer control. It does not model protocol economics or cross-contract runtime behavior end-to-end.
- Cross-contract protocol attacks (flash loans, oracle manipulation, governance attacks) are out of scope.
- Formal verification and economic review are still required for high-value deployments.
- Smart suppression reduces false positives but cannot eliminate all edge cases.
- Exit codes are binary success/failure unless you enforce severity filtering policy in command flags/config.
Configuration
Configuration can be managed through `.guardianrc`, CLI config helpers, and environment overrides. Secure defaults are emphasized for config trust boundaries and sensitive key handling.
configuration
# AI + explorer config helpers
$ vyper-guard ai config set provider openai
$ vyper-guard ai config set model gpt-5
$ vyper-guard explorer config set provider auto
$ vyper-guard explorer config set network sepolia
$ vyper-guard explorer config set api-key
# dashboard telemetry (website runtime)
$ export PEPY_API_KEY="<your_pepy_api_key>"
# sarvam assist (website runtime)
$ export SARVAM_API_KEY="<your_sarvam_api_key>"
# trusted parent config discovery (opt-in)
$ export GUARDIAN_TRUST_PARENT_CONFIG=true
- Keep API keys in environment variables where possible.
- Use severity thresholds in config or CLI for deterministic CI policy.
- Treat config discovery outside the repo root as explicit trust opt-in.
Exit code semantics
Baseline behavior
- `0`: no findings after filters.
- `1`: one or more findings (or strict-mode failures).
Operational implication
- Use `--severity-threshold` to shape policy boundaries.
- Use JSON output for richer gate logic in CI systems.
CI/CD integration
ci pipeline
$ vyper-guard analyze contract.vy --format json --output report.json
$ vyper-guard analyze contract.vy --ci --severity-threshold HIGH
$ find contracts -name '*.vy' -print0 | xargs -0 -I{} vyper-guard analyze "{}" --ci --severity-threshold HIGH
Typical team flow: deterministic scan at commit time, optional AI triage on pull requests, and strict threshold-based gates in CI.
Production security checklist
For mainnet readiness, static analysis should be combined with testing, review, and staged deployment controls.
| Control | Minimum expectation |
|---|---|
| Static analysis | Security score target 80+ with zero unresolved critical findings. |
| Testing | Comprehensive unit/integration/fuzz coverage for core invariants. |
| Manual review | Qualified reviewer sign-off on critical/high findings and waivers. |
| Pre-mainnet rollout | Testnet soak period, monitoring alerts, staged deployment controls. |
Security notice
Vyper Guard is provided as a static analysis assistant, not a proof of exploit absence. Critical/high findings require qualified human review before production deployment.
Deterministic results and manual audit controls remain authoritative. AI and agent outputs are advisory.
Appendix
Primary upstream references: `README.md`, `docs/USAGE.md`, `docs/DETECTORS.md`, `docs/INSTALLATION.md`, and `docs/CHANGELOG.md` in the repository, plus DeepWiki generated pages for architecture, limitations, and operational summaries.