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:
- in your own repository: set
dockerfile: to its path (we suggest at some location like .oss-scanner/Dockerfile). This is the preferred option because it allows you to update the build without a pull request here; or,
- here, next to
project.yaml, as projects/<name>/Dockerfile, with no Dockerfile: key set in the project.yaml. If you would rather not add files to your repository, put it here and the scanner builds it exactly as it would an in-repo copy.
(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:
tools/validate.py checks projects/<name>/ against the rules above.tools/check <name> builds your project the way our scanner will, and opens a shell in the finished image with no network. If your tests pass in this container, our scanner will likely work with your project. tools/check --qemu <name> does the same inside virtual machines laid out like the scanner's.
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
- 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.
- We scan the project for vulnerabilities.
- 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
tools/check runs your project's Dockerfile with network access, as docker build would. With --qemu the build runs inside a virtual machine, which keeps it off your files, but it can still reach services on your computer and your local network. Only check projects you trust, or use a machine with nothing to lose.tools/check installs Claude Code into the image it builds (as the scanner does). Claude Code is covered by its own terms.
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 是 Anthropic 运营的一项服务，为注册进来的开源仓库扫描安全漏洞，在隔离的虚拟机里构建每个项目，并通过邮件把复现程序和建议补丁发给维护者。