Refuse

Product Introduction

1. Definition: Refuse is an open-source, self-hostable security shim and command-line interface (CLI) that acts as an intermediary layer for 19+ package managers (including npm, pip, cargo, gem, go). Its core technical category is supply chain security tooling or a package install interceptor.
2. Core Value Proposition: Refuse exists to enforce dependency security by preemptively blocking the installation of packages with known vulnerabilities (CVEs) and malicious code. It provides a critical "fail-fast" security gate for developers, AI coding agents, and continuous integration (CI) pipelines before vulnerable code reaches the local disk or production environment.

Main Features

1. Universal CLI Shim: A single binary wraps common package managers, intercepting every install command typed by a user, AI agent, or CI script. This "shim" architecture requires minimal integration—users simply replace their standard npm install or pip install with refuse install. The implementation involves modifying the system's PATH to prioritize Refuse's managed binaries.
2. Real-Time Vulnerability & Malware Blocking: By checking packages against a live feed of 362,000+ advisories from sources like GitHub Advisory Database, OSV, and OS-specific databases, Refuse refuses installs of packages flagged with CVEs or malicious activity. It provides immediate feedback, showing the refused package and version, and often suggests a safe alternative version using the refuse fix command.
3. Flexible Backend Architecture: Refuse supports two operational modes for its advisory database: a hosted SaaS (mcp.refuse.dev) for zero-infrastructure ease of use with a free tier, and a self-hostable Docker container (ghcr.io/refusehq/refuse:latest) for air-gapped environments or strict data control requirements, using a SQLite database locally.
4. Broad Ecosystem & Context Support: The tool scans not just direct language packages (PyPI, npm, RubyGems, Cargo, Go, Composer, Maven, NuGet, Hex), but also extends to container security (scanning apt, apk, dnf commands in Dockerfiles), CI/CD security (checking GitHub Actions workflows), and OS-level dependencies for distros like Debian, Ubuntu, Alpine, and Red Hat.
5. AI Agent & Model Security Benchmarking: A unique feature highlighted is the "Most Refused" dashboard, which demonstrates Refuse's value by tracking and displaying instances where frontier AI models (like GPT-5.5, Gemini 3.1, Claude Opus) recommended or attempted to install packages with known, severe vulnerabilities (e.g., .template RCE in lodash, decompression bombs in urllib3, SSRF in axios), proving its necessity as a safety layer for autonomous coding agents.

Problems Solved

1. Pain Point: It addresses the critical supply chain attack vector and the risk of vulnerable dependencies in software development. Developers and automated tools (like AI agents) often install packages without real-time vetting, inadvertently introducing known critical vulnerabilities, malicious code, or compromised packages into projects, which can lead to data breaches, system compromise, or operational failure.
2. Target Audience: Software Developers (using any of the 19+ supported package managers), DevOps/SRE Engineers securing CI/CD pipelines and container builds, Security Teams looking for shift-left tooling, and Users of AI Coding Assistants (e.g., Claude, Cursor, GitHub Copilot) who need to validate and sanitize the packages these tools suggest.
3. Use Cases:
   • Local Development: A developer's npm install is automatically checked before writing to node_modules, preventing a vulnerable React component from being added.
   • CI/CD Pipeline: A GitHub Actions workflow uses refuse install to ensure every dependency in a Docker image build is scanned against advisories before being baked into the image layer.
   • AI-Assisted Development: When an AI coding agent suggests pip install package-x, the developer's Refuse shim intercepts it, blocks a known malicious package, and suggests a safe fork or version.
   • Container Security: The refuse scan command (or integrated install) catches vulnerable apt-get install commands within a Dockerfile, securing the OS-level dependencies of a container.

Unique Advantages

1. Differentiation: Unlike traditional Software Composition Analysis (SCA) tools that scan a project manifest after installation, Refuse operates as a pre-execution interceptor. It is a proactive, real-time gatekeeper that stops vulnerable packages before they hit the disk. Its open-source, self-hosted option offers full control over advisory data and network traffic, a key advantage over many proprietary SCA SaaS solutions.
2. Key Innovation: Its primary innovation is the seamless, universal shim architecture combined with a focus on securing the AI agent workflow. By positioning itself at the command-line level where both humans and AI agents operate, it creates a single, auditable security checkpoint for all package acquisition activities, regardless of the actor. This proactive interception model is uniquely suited to the age of AI-assisted and AI-driven development.

Frequently Asked Questions (FAQ)

1. What exactly does Refuse do that npm audit doesn't? Refuse performs real-time, pre-install blocking based on a broad, multi-source advisory feed, including malicious package detections that npm audit may not cover. While npm audit reports known vulnerabilities after packages are in your project, Refuse prevents them from ever being installed in the first place, offering a more proactive defense.

2. Which package managers does Refuse support? Refuse supports 19 package managers and contexts. The core language-level managers are npm, pnpm, yarn, bun, npx, pip, pip3, uv, poetry, pipenv, pdm, pipx, cargo, gem, bundle, go, composer, and dotnet. It also extends support to Dockerfile commands (apt, apk, dnf), GitHub Actions, and specific Linux distributions for OS-level packages.

3. How does Refuse work with AI coding agents like Claude or Cursor? Once Refuse's CLI shim is installed and configured in your shell, it automatically intercepts any install command executed in that shell environment, including those generated by AI coding assistants. When an AI agent runs a command like npm install vulnerable-package, Refuse steps in, blocks the install if it's unsafe, and logs the intervention.

4. Can I self-host Refuse, and is it free? Yes, Refuse is fully open-source (Apache-2.0) and can be self-hosted for free forever using a single Docker container command. The self-hosted version uses a local SQLite database and fetches the same advisory feed, ensuring no data leaves your network. The optional hosted SaaS tier is also free up to 100k scans per 30 days.

5. What happens when Refuse blocks a package? Does it break my install? When Refuse blocks a package, it terminates the install command and displays an error message explaining the reason (e.g., a specific CVE or "Malicious" tag). It typically suggests a safe alternative version. To proceed, you can either use the suggested safe version (e.g., via $(refuse fix npm package@version)) or, if you've assessed the risk, temporarily bypass the check using the underlying package manager's native command directly.