refuse - Open-source server that refuses vulnerable package

项目说明

<di="center">

refuse

Self-hostable backend that powers refuse-cli to block package installs.

![CI]()
![CodeQL]()
![Container]()
![Release]()

</div>

A small HTTP service that ingests public + metadata feeds — OSV, deps.dev, CISA KEV, FIRST EPSS, GitHub Security Ad, Wolfi — into a local SQLite database and answers questions like:

The intended caller is refuse-cli — a tiny shim that wraps npm, pnpm, yarn, pip, cargo, gem, bun, go and refuses to run an install for a known-bad package. The server is also a plain REST API, so curl, a CI step, or any other client can use it.

---

Where it runs

A long-running HTTP service — pick one host:

CLI-side integrations (PATH shim, pre-commit, GitHub Actions, Docker builds) live in refuse-cli.

---

What it does

> An /mcp endpoint for MCP-aware clients is on the roadmap. REST is the canonical interface today.

---

Quickstart

1. Start the server with a persistent

2. Watch the cold-seed (~3 minutes)

The first boot streams OSV's bulk archi ecosystem in one pass — npm, PyPI, Maven, Go, crates.io, RubyGems, … plus every Debian / Ubuntu / Alpine / RHEL distro the OSV team publishes), plus KEV, EPSS, GHSA, and Wolfi in parallel. The bars show what's happening:

After this one-time bootstrap, deltas every 5 minutes are seconds-fast.

3. Wait for /readyz

Returns 503 with a pending_sources list while sources are bootstrapping, and 200 once every required source has completed at least one pass:

4. Point refuse-cli at it

Direct REST calls work too — useful for any client that doesn't want the shim:

Or browse to < for the dashboard.

---

Production deploy (compose)

See docker/docker-compose.with-key.yml for the same with comments.

---

Configuration

E is en. Defaults pick safe so docker run works without any flags.

| | Default | Purpose |
| --- | --- | --- |
| REFUSE_PORT | 8080 | HTTP listen port |
| REFUSE_DB_PATH | /data/refuse.db | SQLite file path |
| REFUSE_REQUIRE_KEY | false | Require Authorization: Bearer rfs_… on /api/v1/check/* |
| REFUSE_ADMIN_TOKEN | *(unset)* | Static bearer for admin UI + key CRUD |
| REFUSE_OS | 5 | Minutes between OS runs |
| REFUSE_DEPS_DE | 15 | Minutes between deps.dev runs |
| REFUSE_ENRICHMENT_CRON | 0 5 * * * | Cron expression for KEV/EPSS/GHSA/Wolfi |
| REFUSE_BOOTSTRAP_ON_EMPTY | true | Synchronous OSV pull on first boot if DB is empty |
| REFUSE_DISABLE_INGEST | false | Read-only mirror mode (for pre-seeded snapshots) |
| REFUSE_GITHUB_TOKEN | *(unset)* | Optional GH token, raises the GHSA-direct rate limit |
| REFUSE_CARD_CACHE_SIZE | 5000 | LRU entries for built s |
| REFUSE_CARD_CACHE_TTL_SECONDS | 600 | TTL on that LRU |
| REFUSE_LOG_LEVEL | info | debug / info / warn / error |
| REFUSE_CORS_ORIGIN | * | CORS allow-origin on /api/v1/check/* |

Full reference: docs/configuration.md.

---

API surface

| | |
| --- | --- |
| GET /healthz | Li probe |
| POST /api/v1/check/package | Single-package vuln check |
| POST /api/v1/check/batch | Many packages in parallel |
| POST /api/v1/check/lockfile | Parse + scan an entire lockfile |
| POST /api/v1/check/dockerfile | Parse + scan base image + RUN lines |
| POST /api/v1/check/workflow | Scan GitHub Actions uses: entries |
| POST /api/v1/suggest-safe- | Minimum-safe upgrade for an affected package |
| GET /api/admin/stats | DB row counts (admin token) |
| GET /api/admin/sources | Last-run / last-OK per ingest source |
| POST /api/admin/ingest/{os,enrichment} | Manual trigger |
| GET/POST/DELETE /api/keys[/:id] | API key CRUD |
| GET /ui/ | Admin dashboard for self-hosted operators |

Full schema reference: docs/api.md.

---

The refuse family

| | What it is | When to use it |
| --- | --- | --- |
| refuse (this) | Self-hostable HTTP server | You want your own backend — air-gapped, on-prem, or just because |
| refuse-cli | PATH shim that wraps npm / pip / cargo / … | You want to block installs before they happen, on a de or CI |

Both share parsers, comparators, and the OS data model.

---

How it compares

| | refuse | OS | Trivy / Grype | Dependency-Track | guarddog | npq |
| --- | --- | --- | --- | --- | --- | --- |
| OSS license | Apache-2.0 | Apache-2.0 | Apache-2.0 | Apache-2.0 | Apache-2.0 | MIT |
| Standalone server | ✅ | — | partial | ✅ | — | — |
| Install-time gate via PATH shim (with refuse-cli) | ✅ | — | — | — | — | ✅ |
| Dockerfile parsing (base image + RUN) | ✅ | — | ✅ (different mechanism) | — | — | — |
| OSV data | ✅ | ✅ | ✅ | ✅ | — | — |
| KEV / EPSS enrichment | ✅ | — | partial | ✅ | — | — |
| GitHub Actions uses: scanning | ✅ | — | partial | — | — | — |
| Heuristic malicious-package detection | partial | — | — | — | ✅ | partial |
| Single-container deploy | ✅ | n/a | ✅ | ✅ | n/a | n/a |

refuse's differentiator is install-time gating — refusing the install before it runs, rather than reporting on a tree after the fact. The CLI shim makes that gate transparent to the de or CI step. If you already run Trivy or Dependency-Track for the post-install monitoring angle, refuse composes with them: the structured refusal records (package, , reason, OSV id) drop into either pipeline.

---

Self-host walkthrough

Single de (laptop)

Anonymous mode is fine here — the server only binds to localhost.

Fleet (real domain, persistent )

Behind nginx/Caddy with TLS:

Point a DNS record at the host, terminate TLS in your reverse proxy, and rotate REFUSE_ADMIN_TOKEN periodically. Back up /sr/refuse.db with a cron cp — SQLite WAL makes a hot copy safe.

Detailed guide: docs/self-hosting.md.

---

Build from source

Repo layout:

See ARCHITECTURE.md for the deeper walkthrough.

---

Contributing

Issues, fixes, and new ecosystem matchers are welcome. See CONTRIBUTING.md. Before opening a PR:

Security

Security policy: SECURITY.md. Report pri via or GitHub private reporting.

Acknowledgments

Built on top of OSV.dev, deps.dev, the CISA KE, FIRST EPSS, GitHub Security Ad, and the Wolfi ad.

License

Apache License 2.0 © RefuseHQ.

项目信息

开发语言：TypeScript

Star 数：10

技术要点

该项目属于安全软件方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Open-source server that refuses vulnerable package installs. The backend the refuse CLI shim calls.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。