
If you maintain a small software project, a security researcher should not have to guess whether to open a public issue, send a message on social media, or contact a hosting provider. A short vulnerability disclosure policy gives them a private route, tells them what is in scope, and sets expectations for what happens next.
The policy does not need to promise a security team or a fix by a particular date. It does need a contact channel someone checks, a clear boundary for reports, and a process you can keep up with.
A policy and security.txt do different jobs
A vulnerability disclosure policy is the human-readable guide: which project or service is covered, how to report a possible flaw, what testing is acceptable, and how you will communicate. For a GitHub project, a SECURITY.md file is a practical place to publish it.
The security.txt format defined by RFC 9116 helps researchers find that guidance. It points to a contact method and, optionally, a policy page or encryption key. It is a discovery mechanism, not a complete response process or a guarantee that a report will be reviewed.
You can publish the policy without security.txt, but adding both makes the route easier to find. Keep their contact and policy links consistent.
1. Define exactly what is in scope
Name the product, repository, and versions you can support. If the project has a live service, list the specific domains or applications that you control. Say whether the policy covers the source code, deployed service, or both.
Be explicit about exclusions. A vendor's hosting platform, payment service, dependencies, customer installations, and unrelated domains are not automatically yours to authorize for testing. If a service belongs to a provider, use that provider's disclosure policy unless you have permission to include it.
Avoid vague statements such as “all our systems” if you cannot identify or authorize every system. A narrow, accurate scope is more useful than a broad promise you cannot honor. The CISA vulnerability disclosure policy template is a useful checklist for thinking about scope and reporting, but it was written for US federal agencies; it is not legal boilerplate for every project.
2. Choose a private channel you can monitor
Use one clear primary route, such as a dedicated security email address or private reporting form. Assign someone to check it, and arrange a backup if that person is unavailable. Test the address before publishing it, including spam filtering and account recovery.
For a public GitHub repository, an owner or administrator can enable GitHub's private vulnerability reporting. Researchers can then use the repository's private reporting form instead of posting details in an issue. Keep a second route available for people who cannot use GitHub.
Do not direct vulnerability reports to a public issue tracker, discussion board, or ordinary support form unless it can keep the report private. Do not ask researchers to include passwords, API keys, customer records, or other people's private data. If a report contains sensitive information, restrict access to the people who need it and avoid copying it into general team chat.
3. Set safe, realistic testing boundaries
Tell researchers which activities are acceptable and which are not. For a small project, ask them to avoid actions that could interrupt a live service, access another person's data, change or delete data, or test a third-party system. If testing reveals sensitive information or an impact beyond the intended scope, ask them to stop and contact you privately.
Be careful with legal promises. Publishing a policy does not automatically grant permission to test every related system, and it does not create a universal legal safe harbor. Do not copy legal language from another organization or promise immunity without confirming that you have authority to make that commitment. Ask qualified counsel to review any authorization or legal assurance you plan to publish.
4. Explain what to include and when you will reply
Request enough information to assess a report without encouraging unnecessary data collection. Useful details include the affected project and version, a concise description of the behavior, the potential impact, and steps that reproduce it in a test environment. Ask the reporter to redact secrets and personal information.
Set a response target that matches your capacity. For example, a solo maintainer might aim to acknowledge a report within five business days and send an update if investigation takes longer. That is a practical commitment, not a deadline imposed by RFC 9116. If you cannot meet a target, say so and provide a new update date rather than going silent.
Explain the stages a reporter can expect:
- You acknowledge receipt and confirm that the report reached the right person.
- You assess whether the affected project is in scope and ask focused follow-up questions if needed.
- You investigate and decide on mitigation, a fix, or another response.
- You coordinate release and public details with the reporter where appropriate.
Do not promise that every report will be accepted as a vulnerability, that a fix will be available by a fixed date, or that a reward will be paid unless you have decided to offer one and can support the promise.
5. Publish the policy in the right places
Add a SECURITY.md policy to the repository and keep it close to the project documentation. GitHub's guide to adding a security policy explains how to set one up and list the supported versions of a project.
If you operate a web domain, publish security.txt at the domain's /.well-known/security.txt path over HTTPS. RFC 9116 requires the Contact and Expires fields. Contact gives a URI such as a mailto: address or HTTPS reporting page; Expires is a date and time in the RFC 3339 format. The RFC recommends choosing an expiration less than a year away so old contact details are not treated as current.
You can also include a Policy field linking to the full disclosure policy, an Encryption field pointing to a public key, or Preferred-Languages for languages your team can support. Keep each field on its own line. Serve the file as plain text with UTF-8 over HTTPS, and set a calendar reminder to renew it before it expires.
The file applies to the domain from which it is retrieved; it does not automatically cover a parent domain, subdomains, or every product you own. State any additional product or service scope in the policy itself. A root-level /security.txt can be used for legacy compatibility, but the /.well-known/security.txt location is the one to use.
6. Check the reporting path after publication
Before announcing the policy, verify the live links and contact route:
- Open the repository's security policy while signed out or in a private browser window.
- Visit the
/.well-known/security.txtURL over HTTPS and confirm it returns the current plain-text file. - Check that the contact mailbox or form reaches its owner and that a backup can access it.
- If you use GitHub private reporting, confirm the repository setting is enabled and the reporting option is available.
- Review the scope, supported versions, and
Expiresdate whenever you release a major version or change domains.
A policy that points to an unattended mailbox is worse than a shorter policy with a route you actually monitor. For a broader plan to handle a confirmed compromise or exposed data, see our guide to security incident response for small web applications. A vulnerability report is not the same as an incident, but either can require prompt, careful communication.