🚀 PNPM Audit HTML

Generate beautiful HTML reports from your pnpm audit results. This tool provides a clear and concise view of vulnerabilities in your project, making it easier to track and fix issues.

✨ Features

• Easy to Use: Simple CLI commands to generate reports.
• Beautiful Reports: Generates well-structured and visually appealing HTML reports.
• Self-contained: The theme is inlined, so reports render offline and survive as CI artifacts.
• CI-ready: --fail-on <severity> gates a pipeline on the severities you care about.
• Customizable Output: Choose your output file name and location.

📋 Requirements

• pnpm: v8.0.0 or higher
• Node.js: v20 or higher

📦 Installation

To install pnpm-audit-html, follow these steps:

# Ensure you have pnpm v8+ installed
npm install -g pnpm

# Install pnpm-audit-html globally
pnpm install -g pnpm-audit-html

Or, install it as a dev dependency in your project:

pnpm add -D pnpm-audit-html

🚀 Usage

After installation, you can generate an HTML report from your pnpm audit results with a single command.

Basic Usage

pnpm-audit-html

This command will generate an HTML report in the current directory with the default name pnpm-audit-report.html.

Custom Output File

To specify a custom output file, use the -o or --output option:

pnpm-audit-html --output report.html

Example Commands

# Generate report with default file name
pnpm-audit-html

# Generate report with a custom file name
pnpm-audit-html --output security-report.html

🔧 Configuration

pnpm-audit-html uses sensible defaults for most configurations. However, you can customize the output file name and other options directly via CLI flags.

Available Options

• -o, --output <file>: Specify the output HTML file (default: pnpm-audit-report.html).
• -f, --fail-on <severity>: Exit with code 2 when vulnerabilities at or above this severity are found. One of info, low, moderate, high, critical.
• -v, --verbose: Print the full error stack when report generation fails.
• -V, --version: Output the version number.
• -h, --help: Display help for the command.

Exit Codes

• 0: The report was generated and nothing reached the --fail-on threshold.
• 1: Report generation failed (audit could not run, output could not be parsed, the file could not be written, or --fail-on got an unknown severity). Re-run with --verbose to see the stack trace.
• 2: The report was generated and vulnerabilities at or above --fail-on were found.

Without --fail-on, a successful run always exits 0, however many vulnerabilities the report contains. The two failure codes are distinct on purpose: 1 means the tool broke, 2 means the tool worked and your dependencies did not.

Gating CI

- name: Audit dependencies
  run: pnpm-audit-html --output audit.html --fail-on high

- name: Upload the report
  if: always()
  uses: actions/upload-artifact@v4
  with:
    name: audit-report
    path: audit.html

if: always() matters — on exit 2 the report is the thing you want to read, so upload it even though the step failed. The report is self-contained, so it renders straight from the downloaded artifact with no network access.

🤝 Contributing

Contributions are welcome! Feel free to open issues or submit pull requests on GitHub.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

📞 Support

If you encounter any issues or have questions, please open an issue on the GitHub repository.

🎉 Acknowledgments

Thanks to all contributors and the open-source community for making this project possible.