Vulnerability Agent

An automated security agent that scans GitHub organization repositories for JavaScript/Node.js vulnerabilities, analyzes package usage, and creates pull requests with fixes.

🚀 Quick Install

npm install -g vulnerability-agent
vulnerability-agent --help

📚 Documentation

• Quick Start Guide - Get started in under 5 minutes
• Deployment Guide - GitHub Actions, Docker, Heroku, and more
• AI Code Changes Setup - GitHub Models, Claude, and OpenAI integration
• Teams Integration - Microsoft Teams notifications setup
• Teams Setup Guide - Detailed Teams webhook configuration
• Docker Usage Guide - Container deployment options
• Distribution Options - CLI, GitHub Action, VS Code extension
• Plugin Integration Guide - Integrate with your workflow

📖 Table of Contents

• Features
• Quick Start
• Configuration
• Usage
• Microsoft Teams Notifications
• AI-Powered Code Changes
• Distribution Options
• Architecture
• Configuration Options
• Development
• Security Considerations
• Additional Resources
• Support

Features

• 🔍 Multi-Repository Scanning: Automatically discovers and scans all repositories in a GitHub organization
• 🛡️ Vulnerability Detection: Uses npm audit, security databases, and custom vulnerability rules
• 📊 Usage Analysis: Analyzes how vulnerable packages are used throughout the codebase
• 🔧 Automated Fixes: Generates appropriate fixes including version updates and code changes
• 🤖 AI-Powered Code Changes: Uses OpenAI to intelligently transform code for breaking changes and package migrations
• 📝 Detailed PR Creation: Creates pull requests with comprehensive explanations, code diffs, and impact analysis
• 📢 Teams Notifications: Sends structured notifications to Microsoft Teams with vulnerability details, fixes, and PR links
• ⏰ Scheduled Execution: Runs periodically to ensure continuous security monitoring
• 📈 Reporting: Generates detailed reports on vulnerability status across the organization

Quick Start

Prerequisites

• Node.js 20+ and npm
• GitHub personal access token or GitHub App credentials
• Access to the target GitHub organization

Installation

Option 1: Install from npm (Recommended)

npm install -g vulnerability-agent
vulnerability-agent --help

Option 2: Clone and build from source

git clone https://github.com/vimox-shah-genea/vulnerability-agent.git
cd vulnerability-agent
npm install
cp .env.example .env
# Edit .env with your configuration
npm run build

Configuration

Create a .env file with the following variables:

# GitHub Configuration
GITHUB_TOKEN=your_github_token
GITHUB_ORG=your-organization-name
GITHUB_APP_ID=your_app_id (optional, for GitHub App)
GITHUB_APP_PRIVATE_KEY=path_to_private_key (optional, for GitHub App)

# Scanning Configuration
SCAN_SCHEDULE=0 9 * * 1  # Run every Monday at 9 AM
MAX_REPOS_PER_RUN=10
ENABLE_AUTO_PR=true

# AI-Powered Code Changes (Choose one provider)
# Option 1: GitHub Copilot (Recommended for GitHub Enterprise users)
ENABLE_GITHUB_COPILOT=true  # Uses your existing GitHub token
GITHUB_API_URL=https://api.github.com  # Or your GitHub Enterprise URL

# Option 2: Claude Sonnet (Excellent for code understanding)
ANTHROPIC_API_KEY=your_anthropic_api_key
ANTHROPIC_BASE_URL=https://api.anthropic.com  # Optional: custom endpoint

# Option 3: OpenAI GPT-4 (Fallback option)
OPENAI_API_KEY=your_openai_api_key
OPENAI_BASE_URL=https://api.openai.com/v1  # Optional: custom endpoint

# Pull Request Configuration
GROUP_BREAKING_CHANGES=false   # Set to true to separate breaking changes into different PRs
MAX_FIXES_PER_PR=100          # Maximum number of fixes per pull request

# Microsoft Teams Notifications
ENABLE_TEAMS_NOTIFICATIONS=true
TEAMS_WEBHOOK_URL=https://your-company.webhook.office.com/webhookb2/...
TEAMS_NOTIFY_HIGH_SEVERITY_ONLY=false  # Set to true to only notify for high/critical vulnerabilities
TEAMS_INCLUDE_FIX_DETAILS=true  # Include detailed fix information in notifications

# Logging
LOG_LEVEL=info

Usage

If installed from npm:

# Run a one-time scan
vulnerability-agent scan --org your-organization

# Show help and available commands
vulnerability-agent --help

# Scan with specific configuration
vulnerability-agent scan --org my-org --auto-fix --teams-notify

If running from source:

# Run a one-time scan
npm run scan

# Start the scheduled agent
npm start

# Run in development mode with hot reload
npm run dev

# Run tests
npm test

Microsoft Teams Notifications

The vulnerability agent can send detailed notifications to Microsoft Teams channels when vulnerabilities are discovered. Notifications include:

Per-Repository Notifications

• Repository name and vulnerability summary
• List of vulnerable packages with severity levels
• Generated fixes and recommended actions
• Links to created pull requests
• Color-coded cards based on severity (red for critical, orange for high, yellow for moderate)

Organization Summary Notifications

• Total repositories scanned
• Overall vulnerability statistics by severity
• Top most vulnerable repositories
• Total fixes generated across the organization

Setup Teams Notifications

1. Create a Teams Webhook:

   • In your Teams channel, click "..." → "Connectors" → "Incoming Webhook"
   • Configure the webhook and copy the URL

2. Configure Environment Variables:

   ENABLE_TEAMS_NOTIFICATIONS=true
   TEAMS_WEBHOOK_URL=https://your-company.webhook.office.com/webhookb2/...
   TEAMS_NOTIFY_HIGH_SEVERITY_ONLY=false
   TEAMS_INCLUDE_FIX_DETAILS=true

3. Notification Triggers:

   • After each repository scan (if vulnerabilities found)
   • At the end of organization-wide scans (summary)
   • When pull requests are created for fixes

Testing Teams Configuration

Use the built-in test command to verify your Teams setup:

# Check configuration status
npx vulnerability-agent test-teams

# Send a test notification
npx vulnerability-agent test-teams --send-test

Troubleshooting Teams Integration

Common Issues:

1. "Teams notifications are not enabled"

   • Set ENABLE_TEAMS_NOTIFICATIONS=true

2. "Invalid Teams webhook URL format detected"

   • Verify the webhook URL is complete and from Microsoft Teams
   • Regenerate the webhook if necessary

3. "Teams webhook failed: 404"

   • The webhook URL is invalid or expired
   • Check if the webhook connector is still active in Teams

4. "No notifications received"

   • Verify webhook URL configuration
   • Check Teams channel permissions
   • Use --send-test flag to test connectivity

For detailed setup instructions, see TEAMS_SETUP_GUIDE.md.

AI-Powered Code Changes 🤖

The vulnerability agent can use multiple AI providers to intelligently transform application code when package updates require breaking changes or API migrations. GitHub Copilot integration is recommended for GitHub Enterprise users.

Supported AI Providers

1. GitHub Copilot (Recommended) 🥇

• Perfect for GitHub Enterprise users - uses your existing GitHub token
• Context-aware: Has access to latest package documentation
• Security-focused: Follows GitHub's security best practices
• Enterprise-ready: Works with GitHub Enterprise environments
• Cost-effective: Included with your GitHub Copilot subscription

ENABLE_GITHUB_COPILOT=true
GITHUB_TOKEN=your_existing_github_token  # Same token you're already using

2. Claude Sonnet 3.5 🧠

• Excellent code understanding: Superior at analyzing complex code structures
• Detailed reasoning: Provides comprehensive explanations for transformations
• Safety-focused: Considers edge cases and potential side effects
• Latest model: claude-3-5-sonnet-20241022

ANTHROPIC_API_KEY=your_anthropic_api_key

3. OpenAI GPT-4 🔧

• Reliable fallback: Well-tested for code transformations
• Broad support: Handles many programming languages and frameworks
• Custom endpoints: Supports Azure OpenAI and other providers

OPENAI_API_KEY=your_openai_api_key

How It Works

1. Code Analysis: Scans your repository to find files that use vulnerable packages
2. Context Understanding: Reads the actual code to understand how packages are used
3. AI Generation: Uses OpenAI GPT-4 to generate appropriate code transformations
4. Smart Application: Applies changes with fuzzy matching and validation
5. PR Integration: Includes all code changes in the generated pull requests

Supported Transformations

• Version Updates: Adapts code for breaking changes in major version updates
• Package Migrations: Converts from deprecated packages to modern alternatives (e.g., moment → date-fns)
• API Changes: Updates function calls, imports, and usage patterns
• Security Fixes: Applies code-level security improvements

Example Code Changes

When updating lodash from 4.17.20 to 4.17.21 to fix a prototype pollution vulnerability:

// Before (vulnerable)
const template = _.template('<%= user %>');

// After (secure)
const template = _.template('<%= user %>', { sourceURL: '' });

When migrating from moment to date-fns:

// Before
import moment from 'moment';
const formatted = moment().format('YYYY-MM-DD');

// After
import { format } from 'date-fns';
const formatted = format(new Date(), 'yyyy-MM-dd');

Configuration

For GitHub Enterprise Users (Recommended)

# Use your existing GitHub Copilot access
ENABLE_GITHUB_COPILOT=true
GITHUB_TOKEN=your_github_token  # Same token used for repository access

For Claude Sonnet Users

# Get API key from https://console.anthropic.com/
ANTHROPIC_API_KEY=your_anthropic_api_key

For OpenAI Users

# Traditional OpenAI setup
OPENAI_API_KEY=your_openai_api_key

Provider Selection Priority

1. GitHub Copilot (if ENABLE_GITHUB_COPILOT=true and GITHUB_TOKEN is set)
2. Claude Sonnet (if ANTHROPIC_API_KEY is set)
3. OpenAI GPT-4 (if OPENAI_API_KEY is set)
4. Rule-based fallback (if no AI provider is configured)

GitHub Enterprise Integration Benefits

Since you're already using GitHub Enterprise and GitHub Copilot:

✅ No additional API costs - uses your existing Copilot subscription
✅ Single sign-on - uses your existing GitHub token
✅ Enterprise security - stays within your GitHub environment
✅ Latest documentation - Copilot has access to current package docs
✅ Security best practices - aligned with GitHub's security standards
✅ Compliance-ready - meets enterprise security requirements

Fallback Behavior

• No API Key: Falls back to rule-based transformations for common packages
• API Errors: Uses predefined transformation patterns as backup
• Confidence Scoring: Only applies high-confidence changes automatically

Pull Request Integration

All code changes are included in the generated PRs with:

• File-by-file breakdown of what changed and why
• Diff views showing before/after code
• Explanation of each transformation
• Testing recommendations for affected functionality

Sample Teams Notification

When vulnerabilities are found, you'll receive a Teams notification like this:

🛡️ Security Vulnerabilities Found
frontend-app - 3 vulnerabilities detected

Repository: frontend-app
Total Vulnerabilities: 3
Severity Breakdown: 🚨 Critical: 1 | 🔴 High: 1 | 🟡 Moderate: 1
Fixes Generated: 3
Pull Requests Created: 2

📦 Vulnerable Packages & Fixes
• lodash (4.17.20) - Prototype Pollution | Fix: Update to 4.17.21
• axios (0.21.0) - Server-Side Request Forgery | Fix: Update to 0.21.4
• express (4.16.4) - Denial of Service | Fix: Update to 4.18.2

🔀 Pull Requests Created
• Pull Request #123 (https://github.com/org/frontend-app/pull/123)
• Pull Request #124 (https://github.com/org/frontend-app/pull/124)

Distribution Options

The vulnerability agent is available in multiple formats to fit different workflows:

🎯 GitHub Action (Recommended for CI/CD)

Perfect for automated security checks in your CI/CD pipeline:

- name: Vulnerability Agent Scan
  uses: vimox-shah-genea/vulnerability-agent@v1
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    ai-provider: 'github-models'
    auto-create-prs: 'true'

🔐 GitHub Actions Secrets Setup

Configure these secrets in your repository settings (Settings > Secrets and variables > Actions):

Required Secrets:

• ORGANIZATION_NAME - Your GitHub organization name (⚠️ Note: Cannot be named GITHUB_ORG due to GitHub restrictions)

Optional Secrets (for Teams notifications):

• ENABLE_TEAMS_NOTIFICATIONS - Set to true to enable Teams notifications
• TEAMS_WEBHOOK_URL - Your Teams webhook URL
• TEAMS_NOTIFY_HIGH_SEVERITY_ONLY - Set to true to only notify for high/critical vulnerabilities
• TEAMS_INCLUDE_FIX_DETAILS - Set to true to include detailed fix information

📖 See Deployment Guide for complete setup instructions

🖥️ CLI Tool

Install globally and use anywhere:

npm install -g vulnerability-agent
vulnerability-agent scan --org my-organization --auto-fix

🐳 Docker Container

Run in containerized environments:

docker-compose up -d
# or
docker run -e GITHUB_TOKEN=xxx vulnerability-agent

📖 See Docker Usage Guide for container deployment options

🔌 VS Code Extension

IDE integration for developers (manifest ready in vscode-extension/):

• Scan workspace for vulnerabilities
• Apply AI-powered fixes directly in editor
• View security insights in Problems panel

📖 See Distribution Options for all available formats

Architecture

Core Components

1. Repository Scanner (src/github/repository-scanner.ts)

   • Discovers repositories in the organization
   • Filters for JavaScript/Node.js projects
   • Manages scanning queue and rate limiting

2. Vulnerability Detector (src/scanners/vulnerability-detector.ts)

   • Integrates with npm audit
   • Checks against security databases (GitHub Advisory, npm)
   • Applies custom vulnerability rules

3. Usage Analyzer (src/analyzers/package-usage-analyzer.ts)

   • Analyzes how packages are imported and used
   • Identifies dead code and unused dependencies
   • Determines impact of vulnerability fixes

4. Fix Generator (src/fixers/automated-fixer.ts)

   • Generates version updates
   • Creates code patches when needed
   • Validates fixes don't break functionality

5. PR Manager (src/github/pr-manager.ts)

   • Creates detailed pull requests
   • Includes vulnerability explanations and fix rationale
   • Manages PR lifecycle (updates, closes obsolete PRs)

Workflow

1. Discovery: Scan organization for repositories with package.json
2. Analysis: For each repository:
   • Clone/fetch latest code
   • Run vulnerability scans
   • Analyze package usage
   • Identify required fixes
3. Fix Generation: Create appropriate fixes based on vulnerability type and usage
4. PR Creation: Generate pull request with:
   • Vulnerability details and severity
   • Fix explanation and rationale
   • Testing recommendations
   • Links to security advisories

Configuration Options

Scanning Rules

Configure scanning behavior in config/scan-rules.json:

{
	"severityThreshold": "moderate",
	"excludePackages": ["package-name"],
	"autoFixTypes": ["version-update", "dependency-removal"],
	"requireManualReview": ["major-version-updates"]
}

PR Templates

Customize PR content in templates/pr-template.md.

Development

Project Structure

src/
├── core/           # Core business logic
├── github/         # GitHub API integration
├── scanners/       # Vulnerability scanning modules
├── analyzers/      # Code and usage analysis
├── fixers/         # Automated fix generation
├── utils/          # Utility functions
└── types/          # TypeScript type definitions

tests/              # Test files
config/             # Configuration files
templates/          # PR and report templates

Contributing

1. Fork the repository
2. Create a feature branch
3. Write tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

Security Considerations

• All GitHub tokens are stored securely
• Rate limiting prevents API abuse
• Fixes are validated before PR creation
• Sensitive data is never logged or exposed

License

MIT License - see LICENSE file for details.

📚 Additional Resources

Setup & Deployment Guides

• Quick Start Guide - Get running in 5 minutes
• Deployment Options - GitHub Actions, Docker, Cloud platforms
• Docker Usage - Container deployment and Kubernetes

Integration Guides

• AI Code Changes - GitHub Models, Claude Sonnet, OpenAI setup
• Teams Integration - Microsoft Teams notifications
• Plugin Integration - CLI, VS Code, GitHub Action

Development & Advanced Usage

• Distribution Options - All available formats and publishing
• Enhancement Summary - Latest features and improvements
• JavaScript Conversion - Convert from TypeScript to JavaScript

Examples

• examples/ directory contains working examples for:
  • AI code changes integration
  • Teams notifications setup
  • GitHub Copilot demonstration

Support

For issues and questions, please open an issue on GitHub or contact the development team.