How to Use the Command 'pnpm audit' (with Examples)

pnpm audit is a command-line tool used to scan and analyze the dependencies of a project for known vulnerabilities. It leverages a database of known security issues to ensure that the dependencies used in your project are secure. The pnpm audit command is particularly useful in maintaining the security integrity of your software by identifying and rectifying potential vulnerabilities.

Use Case 1: Identify Vulnerabilities in the Project

Code:

pnpm audit

Motivation: Running pnpm audit without any additional flags is beneficial for developers and teams who want to perform a comprehensive security check on their project’s dependencies. This command inspects all installed dependencies regardless of their type (production, development, or optional), offering a straightforward mechanism to expose any vulnerabilities in the project.

Explanation:

• pnpm: This is the package manager utility used for handling dependencies.
• audit: The specific command to initiate a security check on the dependencies within the project.

Example Output:

# Audit Report
Found 2 vulnerabilities:
  Moderate: 1
  Critical: 1

This output provides a summary of detected vulnerabilities, categorized by severity levels.

Use Case 2: Automatically Fix Vulnerabilities

Code:

pnpm audit fix

Motivation: Automatically resolving vulnerabilities is crucial for projects in active development to ensure that dependencies are promptly updated to safer versions. Using the fix flag mitigates the need for manual resolution and reduces the potential for security exploitation.

Explanation:

• fix: This argument instructs pnpm to attempt to automatically resolve vulnerabilities by updating dependencies to safer versions, if available.

Example Output:

# Fix summary
Fixed 1 out of 2 vulnerabilities
1 vulnerability could not be fixed automatically

It indicates the number of vulnerabilities successfully patched and highlights any that need manual intervention.

Use Case 3: Generate a Security Report in JSON Format

Code:

pnpm audit --json > path/to/audit-report.json

Motivation: Generating a security report in JSON is useful for integrating audit results into CI/CD pipelines or for in-depth analysis by security teams. This format allows you to programmatically handle and parse the audit results.

Explanation:

• --json: Instructs pnpm to produce the audit results in JSON format.
• >: Directs the output of the command to a specific file location.
• path/to/audit-report.json: Specifies the file path where the JSON report should be saved.

Example Output:

{
  "auditReportVersion": 2,
  "report": {
    "vulnerabilities": {
      "total": 2
    },
    "advisories": {
      "42": {
        "severity": "moderate",
        ...
      },
      "105": {
        "severity": "critical",
        ...
      }
    }
  }
}

This JSON structure provides a detailed snapshot of encountered vulnerabilities and their severities.

Use Case 4: Audit Only [D]ev Dependencies

Code:

pnpm audit --dev

Motivation: Auditing development dependencies is key for teams focused on ensuring the security of libraries and tools used in the development or testing process, separate from production environments.

Explanation:

• --dev: This flag restricts the scope of the audit to only development dependencies, ignoring production and optional ones.

Example Output:

# Dev Audit Report
No vulnerabilities found in dev dependencies

Shows a clean bill of health for development dependencies, assuring no known security issues exist in this context.

Use Case 5: Audit Only [P]roduction Dependencies

Code:

pnpm audit --prod

Motivation: Focusing an audit on production dependencies is crucial for evaluating the security posture of the actual deliverable code, excluding development-related libraries.

Explanation:

• --prod: Limits the audit operation to only include production dependencies.

Example Output:

# Production Audit Report
Found 1 critical vulnerability

Emphasizes vulnerabilities directly affecting the production environment, making it a critical aspect of pre-deployment checks.

Use Case 6: Exclude Optional Dependencies from the Audit

Code:

pnpm audit --no-optional

Motivation: Projects might rely on optional dependencies that are not critical for core functionality. Excluding them from audits can streamline the security checks, allowing focus on essential dependencies.

Explanation:

• --no-optional: Excludes optional dependencies from the audit process, concentrating on those that are mandatory.

Example Output:

# Audit Report (Excluding Optional)
Found 1 moderate vulnerability

Refines the audit results, easing the identification of issues within key dependencies.

Use Case 7: Ignore Registry Errors During the Audit Process

Code:

pnpm audit --ignore-registry-errors

Motivation: Network or registry errors should not block getting audit results. Ignoring these helps in environments where registry reliability is a concern, ensuring the audit completes.

Explanation:

• --ignore-registry-errors: Proceeds with the audit despite encountering issues connecting to the package registry.

Example Output:

# Audit Result
Ignoring registry errors - check connectivity issues
0 vulnerabilities found

Accounts for unreliable network conditions without disrupting the audit.

Use Case 8: Filter Advisories by Severity

Code:

pnpm audit --audit-level high

Motivation: Filtering advisories by severity allows teams to prioritize risk management strategies and focus on the most critical vulnerabilities first, optimizing resource allocation.

Explanation:

• --audit-level high: Directs the audit to acknowledge only issues classified as high or above in severity.

Example Output:

# High Severity Audit
No high severity vulnerabilities found

Specifically targets high-impact vulnerabilities, which are top priorities in security triage.

Conclusion:

Understanding and utilizing the pnpm audit command with its various options can greatly enhance the security posture of your software projects. By effectively identifying, addressing, and documenting vulnerabilities, developers can proactively safeguard their applications against potential security threats. Each use case offers tailored solutions to specific security scenarios, enabling efficient dependency management aligned with best practices.