AvaGuard - Real-time Dependency Security & Supply Chain Guard

AvaGuard is an open-source VS Code Extension & CLI Security Proxy designed to protect developers and organizations from malicious npm and PyPI supply-chain attacks, typosquatting, hidden install scripts, and unpatched CVE vulnerabilities before packages are installed onto your local environment.

🌟 Key Features

• 🛡️ Zero-Trust Command Interception: Intercepts npm install, yarn add, pnpm add, bun add, and pip install commands seamlessly before execution.
• 📊 Multi-Factor Safety Score (0–100%): Dynamically weighs 5 critical security metrics:
  • Vulnerability Score: Queries OSV.dev database for open CVEs & security advisories.
  • Malware & Script Analysis: Detects suspicious pre/post-install lifecycle scripts (curl, wget, eval, obfuscated binaries).
  • Typosquatting Engine: Identifies deceptive package names targeting popular libraries (expresss, reqeusts, lodas).
  • Maintenance & Quality: Evaluates maintainer counts, publication recency, and registry health.
  • Popularity & Trust: Evaluates download volume and ecosystem adoption.
• 💡 Library Usage & Implementation Guide: Automatically displays developer-friendly summaries for evaluated packages, including primary purpose, core use-cases, target ecosystems, and quick copy-paste code snippets.
• 🤖 Gemini AI Hybrid Analysis: Optional LLM-powered deep code review for zero-day package anomalies and risk synthesis.
• 🐍 Universal Package Ecosystem Support: Native support for Node.js (npm, Yarn, pnpm, Bun) and Python (pip, Poetry, Conda) package managers.
• ⚙️ Configurable VS Code Extension: Customize security policies, block thresholds, intercept rules, and preferred security providers (OSV.dev, Gemini AI Hybrid, Snyk, Socket.dev).

🚀 Quick Start & Development

Prerequisites

• Node.js: v18.x or higher
• npm: v9.x or higher

Installation

1. Clone the repository:

   git clone https://github.com/Partzhh09/AvaGuard.git
   cd AvaGuard
   

2. Install dependencies:

   npm install
   

3. Start the development server:

   npm run dev
   

   Open http://localhost:3000 in your browser to access the live AvaGuard Simulator and Extension Configurator.

4. Build for production:

   npm run build
   npm start
   

🛠️ Architecture Overview

                          [ Terminal / VS Code ]
                                     │
                     (User executes: npm / pip install)
                                     │
                                     ▼
                        [ AvaGuard Security Gate ]
                                     │
         ┌───────────────────────────┼───────────────────────────┐
         ▼                           ▼                           ▼
  [ npm / PyPI API ]           [ OSV.dev Vulnerabilities ]    [ Gemini AI Engine ]
  • Registry Metadata          • Public CVE Query             • Deep Code Review
  • Downloads & Maintainers    • Version Match               • Risk Synthesis
         │                           │                           │
         └───────────────────────────┼───────────────────────────┘
                                     │
                                     ▼
                         [ Safety Score Calculation ]
                         • 0% - 29%: CRITICAL (Blocked)
                         • 30% - 49%: HIGH (Blocked)
                         • 50% - 74%: MEDIUM (Approval Needed)
                         • 75% - 100%: SAFE (Allowed)

💻 Tech Stack

• Frontend: React 18, TypeScript, Tailwind CSS, Lucide React, Motion
• Backend: Express.js server (server.ts) with Vite Dev Middleware
• Security APIs: OSV.dev API, npm Registry API, PyPI JSON API, Google Gemini AI SDK
• Build System: Vite & esbuild

⚙️ Configuration Example (.vscode/settings.json)

{
  "avaguard.securityProvider": "gemini_hybrid",
  "avaguard.autoBlockThreshold": 50,
  "avaguard.requireApprovalThreshold": 75,
  "avaguard.interceptPackageManagers": ["npm", "yarn", "pnpm", "bun", "pip"],
  "avaguard.blockPreInstallScripts": true,
  "avaguard.checkTyposquatting": true
}

📦 How to Publish & Distribute Without Azure (Azure DevOps Free)

If you do not want to set up an Azure DevOps account or generate Azure Personal Access Tokens (PAT), you can publish and distribute your VS Code extension using any of the 3 Azure-Free methods below.

Method 1: Web Portal Upload to VS Code Marketplace (No Azure Token Required)

You do NOT need Azure DevOps PAT tokens to publish to the official VS Code Marketplace. You can build the .vsix package locally and upload it directly through the web UI using your regular GitHub or Microsoft account:

1. Install VS Code Extension CLI (vsce):

   npm install -g @vscode/vsce
   

2. Package the extension into a .vsix bundle locally:

   vsce package --no-dependencies
   

   This creates a compiled installer file: avaguard-1.0.0.vsix.

3. Upload to Marketplace Web Portal:

   • Go to VS Code Marketplace Publisher Management Portal.
   • Sign in with your GitHub or Microsoft account.
   • Click + New Extension -> select Visual Studio Code.
   • Drag and drop your avaguard-1.0.0.vsix file.
   • Click Upload. Your extension is verified and published globally!

Method 2: Publish to Open VSX Registry (open-vsx.org)

Open VSX is an open-source, vendor-neutral marketplace for VS Code extensions used by VSCodium, Eclipse Theia, Gitpod, and GitHub Codespaces.

1. Create an account on Open VSX:

   • Go to open-vsx.org and click Sign In (via GitHub).
   • Go to your Profile Settings and generate an Access Token.

2. Install ovsx CLI tool:

   npm install -g ovsx
   

3. Package & Publish:

   # Package locally
   vsce package
   
   # Publish to Open VSX Registry
   ovsx publish avaguard-1.0.0.vsix -t <YOUR_OPEN_VSX_ACCESS_TOKEN>
   

Method 3: Direct .vsix File Distribution (GitHub Releases / Self-Hosted)

For internal teams, private projects, or direct open-source distribution without any marketplace registry:

1. Build the .vsix installer:

   vsce package
   

2. Share via GitHub Releases or Website:

   • Create a new Release on your GitHub repository.
   • Attach avaguard-1.0.0.vsix as a release asset.

3. How Users Install the .vsix file:

   • Via Terminal:

     code --install-extension avaguard-1.0.0.vsix
     

   • Via VS Code GUI:
     1. Open VS Code and press Ctrl+Shift+X (or Cmd+Shift+X on macOS) to open the Extensions view.
     2. Click the ... (More Actions) menu icon in the top-right corner of the Extensions panel.
     3. Select Install from VSIX...
     4. Select avaguard-1.0.0.vsix. Done!

📦 Traditional CLI Publishing to Visual Studio Code Marketplace (With Azure PAT)

Follow this step-by-step guide to package and publish the AvaGuard extension using the automated vsce CLI workflow:

Step 1: Install the VS Code Extension Manager (vsce)

vsce is the official Command-Line Tool for packaging and publishing VS Code extensions.

npm install -g @vscode/vsce

Step 2: Create a Publisher Account & Personal Access Token (PAT)

1. Create an Azure DevOps Personal Access Token (PAT):

   • Go to Azure DevOps Portal and log in with your Microsoft account.
   • Click the User Settings (gear icon) in the top-right corner -> Personal Access Tokens.
   • Click + New Token.
   • Set Organization to All accessible organizations.
   • Set Scopes to Custom defined -> click Show all scopes -> scroll down to Marketplace and select Manage.
   • Click Create and copy your generated token safely (you won't be able to view it again).

2. Create a Publisher ID on VS Code Marketplace:

   • Go to the Visual Studio Marketplace Management Portal.
   • Click + Create publisher.
   • Enter your unique Publisher ID (e.g., avaguard-sec), Display Name, and Contact Email.

Step 3: Configure package.json for Publishing

Ensure your package.json includes required extension manifest attributes:

{
  "name": "avaguard",
  "displayName": "AvaGuard",
  "description": "Real-time dependency security & supply-chain attack guard for npm and pip packages in VS Code.",
  "version": "1.0.0",
  "publisher": "ParthChotaliya",
  "author": "Parth Chotaliya",
  "icon": "assets/icon.png",
  "engines": {
    "vscode": "^1.85.0"
  },
  "categories": [
    "Security",
    "Linters",
    "Other"
  ],
  "keywords": [
    "security",
    "dependency",
    "npm",
    "pip",
    "supply-chain",
    "vulnerability",
    "avaguard"
  ],
  "repository": {
    "type": "git",
    "url": "https://github.com/Partzhh09/AvaGuard.git"
  },
  "license": "MIT"
}

Step 4: Login to Publisher via vsce

In your terminal, execute:

vsce login ParthChotaliya

When prompted, paste the Personal Access Token (PAT) created in Step 2.

Step 5: Build & Package the Extension (.vsix)

Before installing or publishing, you must generate the .vsix installer file.

1. Install dependencies on your local machine:

   npm install
   

2. Package the extension into a .vsix file:

   npx @vscode/vsce package --no-dependencies
   

   This creates avaguard-1.0.0.vsix in your current folder.

3. Install the generated .vsix into VS Code:

   code --install-extension avaguard-1.0.0.vsix
   

Step 6: Publish to the VS Code Marketplace

Once verified, publish directly to the public marketplace:

# Publish current version
vsce publish

# Or auto-bump version and publish
vsce publish patch   # 1.0.0 -> 1.0.1
vsce publish minor   # 1.0.0 -> 1.1.0
vsce publish major   # 1.0.0 -> 2.0.0

Alternative Manual Upload: You can also manually drag-and-drop the generated avaguard-1.0.0.vsix file at marketplace.visualstudio.com/manage under your Publisher account.

📄 License

This project is released under the MIT License.