🛡️ AvaGuard - How to Use

AvaGuard provides real-time supply-chain security and package risk evaluation directly inside VS Code. It automatically guards your development environment against malicious npm, PyPI, Yarn, pnpm, and Bun packages before they are executed or installed onto your machine.

⚡ 1. Automatic Terminal Interception

AvaGuard runs automatically in the background of your VS Code workspace. You don't need to configure anything to start using it.

How it works:

1. Open any integrated terminal in VS Code (Ctrl+\`` or Cmd+``).
2. Type a standard package installation command, such as:
   • npm: npm install axios or npm i express
   • Yarn: yarn add lodash
   • pnpm: pnpm add react
   • Bun: bun add vite
   • pip: pip install requests or pip install django
3. Press Enter.

AvaGuard will instantly intercept the installation request before execution, analyze the package against real-time security advisories, and present the AvaGuard Security Modal.

🛡️ 2. Understanding the Security Modal & Safety Score

When a package command is intercepted, an interactive security panel will appear on your screen:

Key Metrics Displayed:

• Safety Score (0–100%): A multi-factor rating combining vulnerability advisories, malware signatures, typosquatting checks, popularity, and maintenance health.
• Risk Level Badge:
  • 🟢 SAFE / LOW RISK (75%–100%): Low risk, clean advisory history, active maintainers.
  • 🟡 MEDIUM RISK (50%–74%): Caution advised. May contain unmaintained code or minor advisories.
  • 🔴 HIGH / CRITICAL RISK (0%–49%): Danger alert! Known security vulnerabilities, suspicious postinstall shell commands, or typosquatting match.
• Threat Analysis Breakdown:
  • OSV.dev & CVE Vulnerabilities: Known security advisories and affected versions.
  • Typosquatting Detection: Alerts if a package name mimics popular libraries (e.g., axios-official vs axios).
  • Malicious Script Detection: Scans preinstall and postinstall scripts for remote code execution (curl, wget, eval, powershell).
  • Community & License Metrics: Weekly download volume, license compliance, and active maintainer count.

Action Controls:

• Allow & Install: Approves the package and executes the installation command in your terminal.
• Decline Installation: Cancels the installation immediately to keep your system safe.

🔍 3. Manual Package Evaluation (Command Palette)

You can inspect and evaluate any package before deciding whether to use it in your project:

1. Press Ctrl+Shift+P (or Cmd+Shift+P on macOS) to open the VS Code Command Palette.
2. Search for: AvaGuard: Check Package Safety & Install and press Enter.
3. Type the name of any package (e.g., axios, express@4.18.2, or requests).
4. AvaGuard will fetch and display the full safety analysis report.

📋 4. Viewing Security Audit History

AvaGuard logs all security decisions (Allowed, Declined, and Auto-Blocked) locally for audit compliance:

1. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P).
2. Run: AvaGuard: View Security Audit Logs.
3. A JSON viewer will open displaying your past intercepted packages, timestamps, safety scores, and decision outcomes.

⚙️ 5. Customizing AvaGuard Settings

You can adjust security sensitivity thresholds in VS Code Settings (Ctrl+, / Cmd+, -> search for AvaGuard):

• Auto Block Threshold (avaGuard.autoBlockThreshold): Packages with a Safety Score below this percentage (Default: 50%) are automatically blocked.
• Require Approval Threshold (avaGuard.requireApprovalThreshold): Packages below this rating (Default: 75%) require explicit developer approval via modal.
• Monitored Package Managers (avaGuard.supportedPackageManagers): Select which package managers to monitor (npm, yarn, pnpm, bun, pip).