Finding a security vulnerability, whether in an open-source library, a website, or a product you use, comes with a responsibility: report it in a way that gets it fixed without putting users at risk. Beginners often either stay silent because they are unsure how, or post it publicly and accidentally hand attackers a roadmap. There is a well-established middle path called responsible disclosure. That holds whether you found a bug in a small CLI tool or a Next.js security vulnerability affecting a framework millions of production apps depend on. This guide walks you through it step by step, so your first report is a helpful one.
What you will accomplish
You will confirm your finding is real, locate the correct private channel to report it, write a report a maintainer can act on quickly, and coordinate a sensible disclosure timeline.
Prerequisites
- A vulnerability you believe you have found, with steps that reproduce it.
- A terminal for a couple of quick lookups.
- Patience, since good disclosure is a conversation, not a single message.
Step 1: Confirm it is real and reproducible
Before contacting anyone, make sure you can trigger the issue reliably. A report that says "I think something might be wrong" wastes everyone's time. Write down the exact steps, the affected version, and what you observed versus what should happen. If you cannot reproduce it twice in a row, keep investigating before reporting.
Step 2: Find the official reporting channel
Never post a vulnerability in a public issue tracker or social media first. Look for a private channel instead. Many projects publish one in a standard location:
curl -s https://example.com/.well-known/security.txt
Also check the repository for a SECURITY.md file, which usually names a contact address and disclosure policy. In order of preference, use a dedicated security email, a private advisory form such as GitHub Security Advisories, or an official bug bounty platform. A Next.js security vulnerability, for example, is typically reported through GitHub Security Advisories on the framework's own repository — the same private-advisory route described above.
Step 3: Encrypt sensitive details if a key is provided
If the project publishes a PGP key, use it to encrypt your report so the details are not readable in transit. A typical flow:
gpg --import project-security-key.asc
gpg --encrypt --armor --recipient security@example.com report.txt
If no key is provided, a plain email to the official address is fine. Do not let perfect encryption become an excuse to delay a report.
Step 4: Write a clear, actionable report
A good report is short and specific. Include, in order:
- A one-line summary of the vulnerability and its impact.
- The affected component and exact version.
- Numbered steps to reproduce it.
- What an attacker could achieve, in plain terms.
- Any suggested fix, if you have one.
Avoid dramatic language and avoid demands. Maintainers act faster on a calm, precise report than on an alarming vague one.
Step 5: Agree on a disclosure timeline
Responsible disclosure means giving the maintainer reasonable time to fix the issue before it becomes public. A common convention is 90 days, though smaller projects may need a gentle nudge and more patience. State clearly that you intend to coordinate and will not disclose publicly until a fix is available or the agreed window passes.
Step 6: If you are the one receiving reports, be ready
The flip side of reporting is receiving. If you maintain a project, make it easy for people to reach you privately by adding a SECURITY.md:
printf "# Security Policy\n\nReport vulnerabilities to security@yourproject.dev.\n" > SECURITY.md
git add SECURITY.md && git commit -m "docs: add security policy"
A clear policy turns a stranger's goodwill into a fixed bug instead of a public surprise.
How to know it worked
- You reported through a private, official channel, not a public post.
- Your report reproduces the issue and states its impact in plain language.
- You received an acknowledgment, or you have a documented timeline for following up.
- Nothing about the vulnerability is public until a fix exists or the agreed window closes.
If a maintainer can read your report and start fixing without asking you basic questions, you did it right.
Next steps
- Follow up politely if you hear nothing after a reasonable period, then escalate to a coordinating body such as a CERT if needed.
- Request a CVE identifier once a fix is planned, so the issue is tracked publicly and permanently.
- Add a security policy to your own projects so you are on the receiving end gracefully.
- Learn the vocabulary of advisories and identifiers in the concepts library.
If you found the issue in a dependency rather than your own code, understanding how it is tracked and scored helps you write a stronger report; read about software composition analysis to see how known vulnerabilities are cataloged. Teams that manage inbound reports at scale can compare workflows on the pricing page. To practice writing clear, professional reports, work through the guided material in the Safeguard Academy.
Frequently Asked Questions
Why should not I just post the vulnerability publicly? Because until a fix exists, a public post gives attackers everything they need while leaving users defenseless. Responsible disclosure reports the issue privately first, gives the maintainer reasonable time to patch, and only then goes public. This protects the very users you are trying to help.
What if the project has no security contact at all?
Check for a security.txt file, a SECURITY.md, and the maintainer's profile before concluding there is none. If you genuinely cannot find a private channel, a coordinating organization such as a national CERT can act as an intermediary, receiving your report and relaying it responsibly to the project.
What should a good vulnerability report contain? A one-line impact summary, the affected component and exact version, numbered reproduction steps, a plain-language description of what an attacker could do, and any fix you can suggest. Keep the tone calm and factual, since a precise, unemotional report gets acted on faster than an alarming vague one.
What is a CVE and do I need one? A CVE is a public identifier that uniquely tracks a specific vulnerability so everyone refers to it the same way. You do not need one to report the issue, but once a fix is planned, requesting a CVE, usually through the project or a coordinating authority, makes the vulnerability trackable and helps downstream users know they are affected.
Want a clearer picture of the vulnerabilities in your own projects before you report or receive one? Sign up at app.safeguard.sh/register, and build your fundamentals in the Safeguard Academy.