npm-audit-fix

Automated dependency security scanning, patching, testing, and Pull Request creation for Node.js/npm projects.

npm-audit-fix automates the repetitive process of identifying known vulnerabilities in npm dependencies, applying available patch updates, verifying the project with its test suite, and creating a GitHub Pull Request with the changes.

The goal is simple: find vulnerable dependencies → apply safe updates → run tests → create a PR.

---

✨ Features

• 🔍 Automated Security Audit Runs npm audit --json to identify known vulnerabilities.

• 📦 Dependency Patching Updates vulnerable dependencies to available patched versions.

• 🧪 Test Verification Runs the target project's native npm test command after dependency updates.

• 🌿 Automatic Git Branching Creates a dedicated branch for security fixes.

• 💾 Automatic Commits Commits updated dependency files with a descriptive commit message.

• 🚀 Automatic Push Pushes the security-fix branch to GitHub.

• 🔀 Automatic Pull Requests Creates a GitHub Pull Request containing the updated packages and vulnerability information.

• 🔄 Retry Workflow If tests fail, the repository state is preserved so fixes can be made manually before resuming the process.

• 🛡️ Safe Failure Handling The tool stops when dependency installation or tests fail instead of automatically creating a PR with unverified changes.

---

🔄 How It Works

                 ┌─────────────────────┐
                 │  GitHub Repository  │
                 └──────────┬──────────┘
                            │
                            ▼
                 ┌─────────────────────┐
                 │   Clone Repository  │
                 └──────────┬──────────┘
                            │
                            ▼
                 ┌─────────────────────┐
                 │     npm audit       │
                 │  Find vulnerabilities│
                 └──────────┬──────────┘
                            │
                            ▼
                 ┌─────────────────────┐
                 │ Update Dependencies │
                 │   to patched versions│
                 └──────────┬──────────┘
                            │
                            ▼
                 ┌─────────────────────┐
                 │    npm install      │
                 └──────────┬──────────┘
                            │
                            ▼
                 ┌─────────────────────┐
                 │      npm test       │
                 └──────────┬──────────┘
                            │
                    ┌───────┴───────┐
                    │               │
                  FAIL             PASS
                    │               │
                    ▼               ▼
             Manual Fix       Commit Changes
                    │               │
                    │               ▼
                    └──────────► Push Branch
                                    │
                                    ▼
                            Create GitHub PR

Process

1. Clone the target GitHub repository.
2. Create a dedicated security-fix branch.
3. Run npm audit --json.
4. Identify vulnerabilities with available patches.
5. Update affected dependencies.
6. Run npm install.
7. Run the project's npm test script.
8. If tests pass, commit the changes.
9. Push the branch to GitHub.
10. Create a Pull Request containing the security updates.

---

🛠️ Requirements

Before using npm-audit-fix, make sure you have:

• Python 3.8+
• Node.js
• npm
• Git
• A GitHub Personal Access Token
• A target GitHub repository containing a package.json

The target project must use npm.

---

📥 Installation

1. Clone the project

git clone https://github.com/faisalalidoka-stack/npm-audit-fix.git
cd npm-audit-fix

2. Install Python dependencies

pip install -r requirements.txt

3. Install the CLI

You can optionally install the project as a command-line application:

pip install -e .

After installation, the following command becomes available:

npm-audit-fix

---

🔐 Configuration

The tool requires a GitHub Personal Access Token.

Option 1 — .env file

Copy the example environment file:

cp .env.example .env

Then add your token:

GITHUB_TOKEN=your_github_personal_access_token

Never commit your .env file or expose your GitHub token publicly.

GitHub Token Permissions

The token must have sufficient permissions to:

• Access the target repository
• Clone the repository
• Push a new branch
• Create Pull Requests

For private repositories, the token needs appropriate repository access.

---

🚀 Usage

Basic usage

npm-audit-fix https://github.com/owner/repository

For example:

npm-audit-fix https://github.com/faisalalidoka-stack/example-project

---

Custom branch name

You can specify the branch that will contain the security fixes:

npm-audit-fix https://github.com/owner/repository --branch fix/security-updates

---

Provide the token directly

Instead of using .env, you can provide the token through the CLI:

npm-audit-fix https://github.com/owner/repository --token YOUR_GITHUB_TOKEN

Using an environment variable or .env file is generally preferable so that the token is not exposed in shell history.

---

Retry after test failures

If dependency updates cause the project's tests to fail, the tool preserves the modified repository so you can investigate and fix the problem manually.

After fixing the issue, resume the workflow with:

npm-audit-fix https://github.com/owner/repository --retry

The retry workflow resumes from the testing stage and can continue to commit, push, and create the Pull Request once the tests pass.

---

📋 Example

Suppose a project contains:

{
  "dependencies": {
    "lodash": "^4.17.15"
  }
}

and npm audit reports a vulnerability with an available patched version.

The tool may produce a workflow similar to:

Step 1: Cloning repository
✓ Repository cloned

Step 2: Creating branch
✓ Created branch: fix/vulnerabilities-20260822-132500

Step 3: Scanning for vulnerabilities
✓ Found vulnerabilities with available patches

Step 4: Updating dependencies
✓ Updated lodash

Step 5: Running tests
✓ All tests passed

Step 6: Committing changes
✓ Changes committed

Step 7: Pushing branch
✓ Branch pushed to GitHub

Step 8: Creating pull request
✓ Pull Request created

The resulting Pull Request contains information about:

• Updated packages
• Previous and new versions
• Vulnerability severity
• Security advisories
• Test status

---

🧪 Testing

The tool automatically detects whether the target project contains an npm test script.

If package.json contains:

{
  "scripts": {
    "test": "..."
  }
}

the tool executes:

npm test

If no test script exists, testing is skipped and the workflow continues.

When tests fail

The tool does not automatically create the Pull Request.

Instead, it:

1. Displays the test output.
2. Preserves the modified repository.
3. Allows the developer to manually investigate the failure.
4. Allows the workflow to be resumed with --retry.

This prevents unverified dependency changes from being automatically submitted.

---

📁 Project Structure

npm-audit-fix/
│
├── cli.py
├── main.py
├── config.py
│
├── scanner.py
├── updater.py
├── test_runner.py
│
├── git_operations.py
├── github_manager.py
├── pr_creator.py
│
├── requirements.txt
├── pyproject.toml
├── .env.example
├── .gitignore
└── README.md

Core modules

---

⚠️ Limitations

npm-audit-fix is intentionally conservative, but there are some limitations:

• Only npm projects are supported.
• Yarn, pnpm, and other package managers are not currently supported.
• Only vulnerabilities with available patches are targeted.
• Dependency updates can still introduce unexpected behavior.
• The tool does not automatically modify application code to accommodate dependency changes.
• Projects without an npm test script cannot have their tests verified.
• Patch releases are generally expected to be safe, but no dependency update is completely risk-free.
• Pull Requests should always be reviewed by a developer before merging.

---

🐛 Troubleshooting

GITHUB_TOKEN environment variable is required

Make sure you have either:

GITHUB_TOKEN=your_token_here

in your .env file, or provide the token using:

npm-audit-fix https://github.com/owner/repository --token YOUR_TOKEN

---

npm audit failed

Check that:

• Node.js is installed.
• npm is installed.
• The target repository contains a valid package.json.
• The repository can successfully install its dependencies.

Try:

node --version
npm --version

---

npm install failed

The target repository may already contain dependency problems.

Try cloning the repository manually and running:

npm install

to investigate the issue.

---

Tests failed

Review the test output displayed by the tool.

After fixing the issue manually, resume with:

npm-audit-fix https://github.com/owner/repository --retry

---

Pull Request creation failed

Check that:

• Your GitHub token is valid.
• The token has sufficient repository permissions.
• The security-fix branch was successfully pushed.
• You have permission to create Pull Requests in the target repository.

---

🤝 Contributing

Contributions are welcome.

If you would like to improve npm-audit-fix:

1. Fork the repository.
2. Create a feature branch.
3. Make your changes.
4. Test your changes.
5. Submit a Pull Request.

git checkout -b feature/my-improvement

---

🔒 Security

Because this tool works with GitHub credentials and modifies repositories, security should be taken seriously.

Never:

• Commit your GitHub token.
• Add .env to version control.
• Share tokens in screenshots or logs.
• Hard-code credentials into the source code.

Always review automatically generated Pull Requests before merging them.

---

📄 License

This project is licensed under the MIT License.

See the LICENSE file for details.

---

⚠️ Disclaimer

npm-audit-fix is provided as-is for automating dependency vulnerability remediation.

Automated dependency updates can occasionally introduce compatibility issues or unexpected behavior. Always review generated Pull Requests and run your project's complete test suite before merging security updates into production.