Project Vulnerability Check

Have you ever needed to quickly determine if a project has known vulnerabilities without downloading the entire repository, installing a tool-chain, and doing it all in a single click? Project Vulnerability Check is a lightweight PowerShell GUI application that scans Maven and NPM package files for vulnerabilities and generates detailed, color-coded HTML reports.

Table of Contents

• Features
• Prerequisites
• Installation
• Usage
• How It Works
• Report Details
• Customization
• Known Issues
• Troubleshooting
• Disclaimer
• Contributing
• License

Features

• User-Friendly Interface: Intuitive PowerShell GUI for ease of use.
• Multi-Platform Support: Scans both Maven (pom.xml) and NPM (package.json) projects.
• Color-Coded Reports:
  • Green: Safe packages
  • Orange: Packages with moderate vulnerabilities
  • Red: Packages with critical vulnerabilities
• Detailed HTML Reports:
  • Summary statistics, package details, and vulnerability descriptions
  • Direct links to CVE pages and security advisories
• Minimal Dependencies: Designed to run with minimal external dependencies, ensuring portability.
• Easily Extensible: The scanning logic can be extended to support additional package types or vulnerability databases.

Prerequisites

• Operating System: Windows
• Environment: PowerShell (with administrative rights recommended for certain operations)
• Internet Connection: Required for querying the GitHub Advisory API and other vulnerability databases

Installation

1. Download the Script:

   • Download the main PowerShell script file: PackageVulnerabilityScannerV2.ps1

2. Obtain a GitHub Token:

   • Generate a GitHub Personal Access Token (PAT) with the necessary scopes (see GitHub Documentation for details).

3. Run the Script:

   • Open PowerShell (preferably as Administrator) and execute:

     powershell -ExecutionPolicy Bypass -File .\PackageVulnerabilityScannerV2.ps1 -GitHubToken <your token>

Usage

1. Launch the Application:
   Start the PowerShell GUI.

2. Select a Dependency File:
   Click "Browse" to choose either a pom.xml or package.json file.

3. Set the Output Directory:
   Specify the output directory for the generated HTML reports (default: Documents\VulnerabilityReports).

4. Run the Scan:
   Click "Scan Packages" to initiate the vulnerability scan.

5. View the Report:
   Once the scan is complete, the HTML report will automatically open in your default web browser.

How It Works

The application leverages PowerShell's UI and REST capabilities to efficiently perform vulnerability scans:

1. User Interface:
   The script provides a graphical interface for file selection and settings configuration.

2. Scanning Process:

   • Parsing: Reads and parses dependency files (pom.xml or package.json).
   • Querying: Calls public vulnerability databases and the GitHub Advisory API.
   • Analysis: Matches dependencies against known vulnerabilities.
   • Reporting: Generates detailed HTML reports with color-coded summaries and direct links to CVE pages.

Report Details

The generated HTML reports include:

• Summary Statistics: Overview of safe and vulnerable packages.
• Package Information: Detailed version data for each package.
• Vulnerability Breakdown: Expandable sections listing each vulnerability, along with CVSS scores.
• Direct CVE Links: Quick access to detailed vulnerability information on CVE pages.
• Visual Cues: Color-coded indicators to facilitate quick risk assessments.

Customization

Feel free to tailor the application to your needs by:

• Modifying the HTML template for custom report styling.
• Extending the scanning logic to integrate additional vulnerability databases.
• Adding organization-specific vulnerability rules or processing logic.
• Extending it to other project types (e.g. Python's requirements.txt)

Known Issues

• Version Comparison:
  The current semver comparison implementation is basic and may not correctly handle complex version ranges (e.g., "< 1.6.0" or "3.4.5, < 4.0.0-rc1"), thus incorrectly matching the version or plainly skipping the dependency.

• GitHub Token Dependency:
  The -GitHubToken parameter is now essential. Due to recent GitHub policy changes, non-token access may result in a 403 error.

• Parsing Artifacts:
  Some response parsing issues may lead to unexpected symbols in vulnerability descriptions.

• Unsupported Complex POM files:
  The script does not account for parametrized POMs or externally linked files (e.g. composed POMs)

Troubleshooting

If you encounter issues during the scan:

1. GitHub Token:
   Ensure you pass a valid GitHub token when running the script.

2. File Format:
   Verify that the pom.xml or package.json files are correctly formatted (you can use online validators).

3. Internet Access:
   Confirm that your system has access to the required online vulnerability databases.

4. Permissions:
   Run PowerShell as an administrator to avoid permission issues.

5. Debugging:
   Check UI logs and console warnings for any error messages during execution and user the -Verbose flag for extended error information.

Note: The parsing logic is based on current file format conventions as of the day of publication.

Contributing

Contributions to improve this project are welcome! Please follow these steps:

1. Fork the Repository: Create your own fork and clone it locally.
2. Create a Feature Branch: Develop your changes on a separate branch.
3. Commit and Push: Ensure your commits are clear and descriptive.
4. Submit a Pull Request: Provide a detailed description of your changes and submit a PR.

For any major changes, please open an issue first to discuss what you would like to change. Please note that due to time constraints, there's no warranty that your PR will be accepted.

License

This project is open source and licensed under the MIT License.

Author

The Project Vulnerability Check is developed and maintained by Rodrigo Morteo.

All contributions and modifications are subject to the terms of the MIT License.

Please include proper attribution when using or modifying this code.

Disclaimer

THIS SCRIPT IS PROVIDED "AS IS" AND WITHOUT ANY WARRANTY, EXPRESS OR IMPLIED. USE IT AT YOUR OWN RISK. THE AUTHOR MAKES NO REPRESENTATIONS OR WARRANTIES THAT THIS SCRIPT IS SUITABLE FOR YOUR PROJECT, ENVIRONMENT, OR SITUATION. THERE IS NO WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.

BY USING THIS SCRIPT, YOU ACKNOWLEDGE THAT IT IS YOUR SOLE RESPONSIBILITY TO VERIFY THAT IT MEETS YOUR NEEDS AND IS COMPATIBLE WITH YOUR SYSTEM. THE SCRIPT IS PROVIDED WITHOUT ANY SUPPORT, MAINTENANCE, OR LIABILITY ON THE PART OF THE AUTHOR. UNDER NO CIRCUMSTANCES SHALL THE AUTHOR BE HELD LIABLE FOPR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER, EVEN IF THE AUTHOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, ARISING OUT OF OR IN CONNECTION WITH THE USE OR ABUSE OF THIS SCRIPT.

FURTHERMORE, YOU ARE RESPONSIBLE FOR ENSURING THAT YOUR USE OF THIS SCRIPT DOES NOT VIOLATE ANY LAWS OR CAUSE HARM, SUCH AS UNINTENTIONAL DDOS ATTACKS OR OTHER DAMAGE TO THE API PROVIDER OR INTERNET INFRASTRUCTURE. PLEASE USE THIS SCRIPT CAREFULLY, RESPONSIBLY, AND IN ACCORDANCE WITH ALL APPLICABLE LAWS.