mamori

A read-only vulnerability scanner for your dependencies, your GitHub repositories, and the machine you run it on.

English · 日本語

mamori (守り, "protection") runs on macOS, Windows and Linux as a single file. It reads your lockfiles locally or straight from GitHub — without cloning and without write access — matches them against public vulnerability data on your machine, and always answers three questions:

1. What was scanned? Every file, package count and runtime, so you know what "no findings" covers.
2. What is wrong? Each finding with its advisory IDs, the version that fixes it, and whether it is being exploited in the wild.
3. What could not be read? Files, folders and repositories mamori could not judge. A scan with blind spots is never reported as clean.

Contents

• Quick start · Sample output · Why you can trust it
• What it checks · Install · Usage · Use in CI
• GitHub token · Exit codes · Network contacts
• FAQ · Roadmap · Contributing · License

Quick start

mamori scan                                   # this folder + the runtimes installed on this machine
mamori scan --github your-org                 # every repository of a user or organization, read-only
mamori scan --github owner/repo --format markdown --out report.md
mamori egress                                 # every host mamori may contact, and why

Sample output

A demo folder with deliberately old versions (trimmed; the full report lists all nine findings):

mamori scan report — mamori v0.1.0
Matching: local matching (public databases downloaded; your package list was not sent anywhere)

== Summary
  Findings: critical 5 / high 1 / medium 3 / low 0 / unknown 0
  Blind spots (could not read or judge): 1

== What was scanned
  [local] ~/my-app — 2 files, 5 packages
      api/requirements.txt  (PyPI, 2)
      web/package-lock.json  (npm, 3)

== Findings
  1. [critical] @tanstack/react-start 1.167.50  — local:~/my-app
     web/package-lock.json
     GHSA-qx66-fv34-fjm8, CVE-2026-102989  TanStack Router: Unauthenticated reflected XSS in TanStack Start server-function responses
     fixed in: 1.168.60
  3. [critical] brotli 1.2.0  — local:~/my-app
     api/requirements.txt
     GHSA-9v8h-qqgm-4m35, CVE-2026-111497, …  Out-of-bounds write in the Brotli decoder ("Node2Shell") also affects the PyPI Brotli package
     fixed in: 1.2.1
  4. [critical] seroval 1.5.2  — local:~/my-app
     web/package-lock.json
     GHSA-mv8w-475r-vwqw, CVE-2026-59940  seroval: `seroval.fromJSON()` Promise resolver type confusion invokes attacker-controlled methods during deserialization
     fixed in: 1.5.3
  …

== Blind spots (could not read or judge)
  - local:~/my-app:worker/package.json — dependencies are declared but there is no lockfile next to them, so the installed versions are unknown

== Patch the Planet disclosures
  Brotli decoder vulnerability (CVE-2026-111497) https://patchtheplanet.org/brotli
     checked: Google Brotli (Python binding) / findings: 1
     check by hand: Node.js, Bun, Envoy Proxy, Istio

== Network contacts
  HEAD osv-vulnerabilities.storage.googleapis.com  (2 req.)
  GET raw.githubusercontent.com  (1 req.)

The same report is available as Markdown (for issues and pull requests) and JSON (for other tools).

Why you can trust it

Promise	How it is kept
It cannot change anything on GitHub.	Every request goes through one guard (internal/egress) that refuses any method but GET/HEAD for api.github.com. Tests prove it. A token that could write is still only used to read, and mamori warns you about it.
Your code and package list stay on your machine.	By default mamori downloads the public OSV database (only when it changed) and matches locally. Nothing about your dependencies is sent anywhere. Sending package names to the OSV API is an explicit opt-in (--online).
You can see every host it talks to.	mamori egress prints the complete allow list with the reason for each host. Every report ends with the hosts actually contacted. --offline makes no network requests at all.
No telemetry, no self-update.	mamori never phones home and never replaces its own binary. Data (vulnerability databases, the Patch the Planet file) is refreshed; code is not.
"No findings" is never silent.	Unparseable files, manifests without a lockfile, missing databases, npm packages without a registry source, truncated repository listings, submodules, and repositories whose GitHub dependency graph is not reading the lockfile are all listed as blind spots, and the exit code is 3, not 0. Ignore rules in osv-scanner.toml are always named in the report.
The matching is not ours.	Version matching is done by Google's OSV-Scanner library (Apache-2.0), used as-is. mamori decides what to read and how to report it.
You can verify what you run.	Releases are built by GitHub Actions from a tagged commit, reproducibly (CGO_ENABLED=0 -trimpath -buildid=: two builds are byte-identical), with SHA256SUMS and signed build provenance.

What it checks

Lockfiles — whatever OSV-Scanner reads, including bun.lock, package-lock.json, pnpm-lock.yaml, yarn.lock, uv.lock, poetry.lock, Pipfile.lock, requirements*.txt, Cargo.lock, go.mod, Gemfile.lock, composer.lock, NuGet and Maven/Gradle lockfiles.

여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗