MCP Web Audit

🚀 mcp-web-audit

A Node.js-based front-end engineering security audit tool that supports comprehensive dependency security audits for local projects and remote repositories.

🚀 Quick Start

Using npx (Recommended)

You can use it directly without installation:

# Audit a local project
npx mcp-web-audit /path/to/your/project

# Audit a remote repository
npx mcp-web-audit https://github.com/user/repo

# Specify the output file
npx mcp-web-audit /path/to/project -o ./my-audit.md

# View help
npx mcp-web-audit --help

# View version
npx mcp-web-audit --version

Global Installation

# Install globally
npm install -g mcp-web-audit

# Use the command
mcp-web-audit /path/to/your/project

Local Installation of the Development Version

# Clone the repository
git clone https://github.com/shenzhihao/mcp-web-audit.git
cd mcp-web-audit

# Install dependencies
npm install

# Test locally
node bin/cli.js /path/to/test/project

✨ Features

• 🛡️ Comprehensive Audit: Audit all direct and indirect dependencies of front-end projects.
• 🌐 Multi-source Support: Support audits for local projects and remote repositories (e.g., GitHub).
• 📊 Detailed Report: Generate an audit report in standard Markdown format.
• 🔌 MCP Integration: Provide audit services as an MCP (Model Context Protocol) server.
• ⚡ Automation: Fully automated audit process without manual intervention.
• 🚀 CLI Support: Support direct invocation via npx without installation.

📋 Audit Content

• Vulnerability Detection: Identify known security vulnerabilities in dependency packages.
• Version Analysis: Check the security and compatibility of dependency package versions.
• Dependency Chain Analysis: Conduct in-depth analysis of indirect dependency relationships.
• Risk Assessment: Classify vulnerabilities by severity (Critical, High, Moderate, Low).
• Fix Recommendations: Provide specific repair solutions and suggestions.

💻 Usage Examples

CLI Usage Instructions

Basic Usage

npx mcp-web-audit [options] <Project Path>

Parameter Description

• <Project Path>: The path of the project to be audited (local absolute path or remote repository URL).

Options

• -o, --output <File>: Specify the file path for the output report (default: ./audit-report.md).
• -h, --help: Display help information.
• -v, --version: Display version information.

Usage Examples

# Audit the current directory
npx mcp-web-audit .

# Audit a specified local project
npx mcp-web-audit /Users/username/my-project

# Audit a GitHub repository
npx mcp-web-audit https://github.com/facebook/react

# Specify the output file name
npx mcp-web-audit ./my-project -o security-report.md

# View help information
npx mcp-web-audit --help

Running as an MCP Server

node src/mcpServer.js

Programmatic Invocation

import { auditPackage } from "mcp-web-audit";

// Audit a local project
await auditPackage("/path/to/your/project", "./audit-report.md");

// Audit a remote repository
await auditPackage("https://github.com/user/repo", "./audit-report.md");

📊 Example Audit Report

The generated audit report includes the following information:

• Project Overview: Basic information such as project name and version.
• Vulnerability Summary: The number of vulnerabilities counted by severity.
• Detailed Vulnerability List: Detailed information for each vulnerability, including:
  • Vulnerability description
  • Affected packages and versions
  • Severity rating
  • Repair suggestions
  • Related links

📝 Requirements

• Node.js: >= 14.0.0
• Network: A network connection is required when auditing remote repositories.
• Disk Space: At least 100MB of free space (for temporary files).

📁 Project Structure

src/
├── audit/              # Core audit module
│   ├── currentAudit.js  # Audit of the current project
│   ├── getDepChain.js   # Dependency chain analysis
│   ├── index.js         # Main audit entry
│   ├── normalizeAuditResult.js  # Result standardization
│   ├── npmAudit.js      # NPM audit
│   └── remoteAudit.js   # Remote audit
├── common/             # Common utilities
│   └── utils.js        # Utility functions
├── entry/              # Program entry
│   └── index.js        # Main API entry
├── generateLock/       # Lock file generation
│   ├── generateLock.js # Lock file generation logic
│   └── index.js        # Module entry
├── main/               # Main program
│   └── index.js        # Main program entry
├── parseProject/       # Project parsing
│   ├── index.js        # Parsing entry
│   ├── parseLocalProject.js   # Local project parsing
│   └── parseRemoteProject.js  # Remote project parsing
├── render/             # Report rendering
│   ├── index.js        # Rendering entry
│   ├── markdown.js     # Markdown rendering
│   └── test/           # Test files
├── workDir/            # Working directory management
│   └── index.js        # Working directory operations
└── mcpServer.js        # MCP server

🔧 Technical Details

API Reference

auditPackage(projectRoot, savePath)

Audit all dependency packages of the specified project.

Parameters:

• projectRoot (string): The absolute path of the project root directory or the URL of the remote repository.
• savePath (string): The save path for the audit report.

Example:

// Local project
await auditPackage("/Users/username/my-project", "./audit.md");

// Remote repository
await auditPackage("https://github.com/facebook/react", "./react-audit.md");

Technology Stack

• Runtime Environment: Node.js (ES Modules)
• Core Dependencies:
  • @modelcontextprotocol/sdk: MCP protocol support
  • ejs: Template engine
  • zod: Data validation

Security Audit Process

1. Project Parsing: Parse the project's package.json file.
2. Dependency Analysis: Analyze all direct and indirect dependencies.
3. Lock File Generation: Generate a dependency lock file.
4. Security Scan: Conduct a security scan using npm audit.
5. Result Standardization: Standardize the audit results.
6. Report Generation: Generate an audit report in Markdown format.

🤝 Contribution Guidelines

Welcome to submit Issues and Pull Requests to help improve this project.

📄 License

ISC License

📞 Support

If you encounter any problems during use, please submit an Issue or contact the maintainer.