oss-scanner README

The project's README from github.com/anthropics/oss-scanner. As one markdown file: README.md.

OSS Scanner

OSS Scanner is a service by Anthropic to scan critical open-source repositories for security vulnerabilities. Learn more about the service at red.anthropic.com/oss-scanner.

Note, use of this tool is subject to the terms and conditions outlined in the OSS Scanner terms.

How to sign up

Enroll an open-source project by opening a pull request that adds one directory:

projects/<name>

Our security scanner builds your project in an isolated VM, then analyses it with no Internet access and emails what it finds to primary_contact (and any CCs), each with a reproducer and a proposed patch where available. Reports are model-generated and are not reviewed by a human. Because of this we do not place a 90-day disclosure period on these findings and will not make them public. Project owners should provide project.yaml (to configure the scanner), a Dockerfile (stating how to build the project), and optionally a threat_model.md (providing project-specific threat modeling).

project.yaml

Start from templates/project.yaml:

repo: https://github.com/example/project    # required: the git repository to scan; add #branch to pin one
primary_contact: [email protected]       # required: reports and build problems go here (one address)
auto_ccs:                                   # optional: more addresses on every mail
  - [email protected]
homepage: https://example.org               # optional
disabled: false                             # optional: true pauses reports without removing the enrolment
dockerfile: .oss-scanner/Dockerfile         # required unless a Dockerfile sits in this repo next to your project.yaml
threat_model: .oss-scanner/threat_model.md  # optional; also supports placing the file in this repository

repo and primary_contact are always required. dockerfile is required unless you keep your Dockerfile next to project.yaml (see below). Others are optional.

The email addresses in project.yaml are public. Use addresses you are happy to see published, such as a security alias.

To receive reports encrypted, add your armored OpenPGP public key. Reports then go to primary_contact only; pgp cannot be combined with auto_ccs:

pgp: |
  -----BEGIN PGP PUBLIC KEY BLOCK-----
  mQINBF...
  -----END PGP PUBLIC KEY BLOCK-----

You must provide a Dockerfile, in exactly one of two places:

(The threat model works the same way. Set the threat_model field for its location in your repository, or place it here at projects/<name>/threat_model.md.)

The purpose of the Dockerfile is to set up your environment, install every dependency, and build the project. Initial project setup runs with network access enabled, but the security audit after it runs without Internet access. Anything the build or the tests need must be fetched during the initial Dockerfile setup. We recommend checking that your tests pass inside the built image.

The threat_model.md (optional but strongly recommended) file allows you to provide the scanner with documentation on your intended security goals. We have found it is most useful to provide guidance for how you rate the severity of reports (e.g., do you consider post-auth SQLi high or critical? are buffer overflows without demonstrated exploits capped at high? when is stored XSS medium, high, and critical?) This file can also state what the project does, where untrusted input enters, which components matter and which are out of scope, how you would like reports and patches to look, or anything else you think important or useful.

We suggest you run two commands before opening a pull request:

These tools need your host to have installed git, Docker, and Python 3 with PyYAML (pip install pyyaml); --qemu needs Linux on x86-64 with QEMU instead of Docker.

What happens after the merge

  1. The scanner imports the project, builds it online in an isolated VM, then moves the VM to a network with no Internet access for scanning. If the build fails, we will email primary_contact with an error message.
  2. We scan the project for vulnerabilities.
  3. Findings are emailed to primary_contact and any additional CCs with reproduction steps and a proposed patch where available.

You can edit your project at any time with a PR. To unenroll your project, set the disabled field to true to pause reports or remove projects/\<name\>/ to withdraw the project entirely.

Security considerations

Learn more

Please visit red.anthropic.com/oss-scanner.

Maintenance status: this repository is actively maintained by Anthropic. We review and merge enrollment pull requests (changes under projects/<name>/) only; we do not accept other contributions, including changes to tools/ or templates/. See CONTRIBUTING.md for how to enroll, SECURITY.md to report a vulnerability in this repository, and CODE_OF_CONDUCT.md.

oss-scanner (anthropics/oss-scanner)

Searching Database…

1K ·GitHub
Oss-scanner
What is this?OSS Scanner is a service run by Anthropic that scans enrolled open-source repositories for security vulnerabilities, building each project in an isolated VM and emailing the maintainer a reproducer plus a proposed patch for anything it finds.
Is this a tool I run myself, or do I just enroll my project with Anthropic?It's neither a local app nor a library you run — you enroll your project by opening a pull request against this repo, and Anthropic's own infrastructure then builds and scans it.
How do I enroll my project in the scanner?Open a PR adding a projects/ / directory that contains a project.yaml (based on templates/project.yaml) with your repo and primarycontact, plus a Dockerfile that builds your project, and optionally a threatmodel.md.
What do I need locally to test my enrollment before opening the PR?tools/validate.py and tools/check require git, Docker, and Python 3 with PyYAML installed; the --qemu variant needs Linux on x86-64 with QEMU instead of Docker.
Are the vulnerability reports reviewed by a person before I see them?No — reports are model-generated and not reviewed by a human, which is also why Anthropic doesn't hold them to a 90-day disclosure window or publish the findings.
Does the scanner have internet access while examining my code?Only during the initial build — the project is built online in an isolated VM, and that VM is then moved to a network with no internet access before the actual vulnerability scan runs.
What role does Claude Code play in the scanning process?tools/check installs Claude Code into the build image exactly as the live scanner does, since Claude Code is the engine that analyzes the offline build and drafts the proposed patch.
Can I keep my Dockerfile in my own project repo instead of this one?Yes, and it's the preferred setup — just point dockerfile: at its path in your own repo so you can update the build without ever opening a PR here.
How do I stop receiving reports from the scanner?Set disabled: true in your project.yaml to pause reports, or delete your projects/ / folder entirely to withdraw your project from the service.
What are similar projects?osv-scanner, VulnHunter, defending-code-reference-harness, nuclei, Cybermes, codex-security, shannon, 0
Which topics is it in?ai-security-tool, qemu, security-audit, dockerfile, sandboxing, devsecops, vulnerability-scanner, vulnerability, github, security-tools, anthropic, claude-code
Creator
anthropics
Size
1.1 MB
Stars
1K
Updated
CommitOct 16
Age
9d
Commits · 90 Days