Technical documentation and operational usage

Architecture

The execution model is intentionally layered: input normalization, deterministic detector pass, semantic verification, optional AI interpretation, and report synthesis. This keeps core findings reproducible while allowing richer human-readable audit context.

Analysis lifecycle

1. 1) Input validation: verifies source exists and rejects empty/comment-only files.
2. 2) Deterministic analysis: detector patterns + AST/semantic contextual checks.
3. 3) Risk synthesis: severity distribution, score, and deploy recommendation.
4. 4) Report rendering: CLI / JSON / Markdown outputs for local and CI usage.

This staged model ensures the same source yields stable baseline findings while still allowing optional augmentation layers to improve reviewer velocity and report quality.

Command reference

Recommended baseline commands for teams are `analyze`, `analyze --ai`, `fix --fix-dry-run`, `stats --graph`, and `analyze-address` for post-deploy checks.

Detector taxonomy

Detector inventory grouped by category and operational intent.

AI-Assisted audit

AI mode augments deterministic findings. It should be treated as a triage and explanation layer, not as a replacement for deterministic checks or formal audit review.

• Use AI mode for prioritization and report readability.
• Keep deterministic severity thresholds as the enforcement baseline.
• Store AI-assisted reports for audit traceability in CI artifacts.

AST and flow views

Structural views improve reviewer understanding of contract layout, function interactions, and potential high-risk control paths.

AST output is suited for machine processing and tooling integration, while flow summaries are suited for reviewer cognition and architecture walkthroughs.

Remediation workflow (`fix`)

• Tier A: low-risk candidates.
• Tier B: medium-risk, review-required.
• Tier C: high-risk/architectural, mostly advisory.

Teams should require human approval for Tier B and Tier C classes and retain fix-plan artifacts in pull request metadata to preserve review transparency.

Explorer + address analysis

Address-based mode is intended for post-deployment visibility and incident response workflows, especially when source and ABI are verified through explorer providers.

Output formats

Configuration

Core configuration surfaces include AI provider/model settings, explorer provider credentials, output defaults, and CI severity thresholds.

Scoring & grade policy

Severity caps prevent a single class from over-dominating score impact and preserve a more balanced security posture interpretation across multiple risk dimensions.

Backward compatibility

Existing workflows based on analyze [path] remain valid. Newer features such as AI layering, explorer integration, and fix policy controls are additive and can be introduced incrementally.

• Legacy single-file usage remains supported.
• Folder-level recursive analysis remains compatible.
• Structured output flags are optional and backwards-safe.

CI/CD

Recommended CI pattern: generate machine-readable report, evaluate threshold policy, publish report artifact, and fail fast on disallowed severities.

Team workflow guide

A practical team pattern is to run deterministic scans at commit time, run full AI-assisted triage on pull requests, and enforce severity thresholds in CI before merge. This approach keeps developer feedback fast while preserving strict release controls for security-critical changes.

For audit-heavy repositories, teams typically pair `analyze --format json` with markdown reports. JSON outputs are consumed by quality gates, while markdown artifacts are attached to pull requests for reviewer clarity and discussion.

• Pre-commit: local deterministic scan to catch immediate issues.
• Pull request: AI-assisted triage and fix-plan generation.
• Release branch: threshold-based CI gating and archived reports.

Policy and governance

Security governance should define acceptable risk by severity and environment. A common policy is zero tolerated critical findings in all environments, and zero high findings for production deploys. Medium and low findings may be allowed with explicit waivers and remediation timelines.

Waiver records should include detector key, rationale, owner, expiry date, and mitigation status. This creates auditability and prevents permanent drift from baseline security posture.

Troubleshooting

• Command not found: activate virtual environment and verify path.
• AI not running: confirm API key/provider in vyper-guard ai config show.
• Explorer fails: verify address and provider/API key config.
• Empty source rejected: expected for empty/comment-only files.
• Unexpected CI pass/fail: verify severity threshold values and report path handling.
• Low signal/no findings: ensure target path includes `.vy` contracts and non-empty source.

Frequently asked questions

Appendix

This page is a product-level operational reference derived from available Vyper Guard metadata, command references, and detector/scoring model representation in the project context. For upstream implementation details and release notes, use the linked repository and package pages.

Continue exploring