Make the security reporting channel reachable, and make SECURITY.md agree with itself #481

Summary

SECURITY.md names security@docs.plus as the only way to report a vulnerability. That address very likely cannot receive mail. On 2026-10-14, dig MX docs.plus returned nothing on both 1.1.1.1 and 8.8.8.8, and port 25 on the docs.plus A host was closed. The same address is in apps/webapp/public/.well-known/security.txt and apps/webapp/src/pages/terms.tsx. GitHub private vulnerability reporting is already on for this repo, so it can be the first channel now. The file also has two smaller errors, and the README never links it.

• Severity: High. A reporter who follows the policy reaches no one.
• Area: SECURITY.md, apps/webapp/public/.well-known/security.txt, apps/webapp/src/pages/terms.tsx, README.md
• Source: docs and README review of 2026-10-14. Five review agents each covered one docs area. A separate agent then checked each finding against the code and tried to refute it. Every item below survived that check. "Checked" lists the evidence.

Items

1. SECURITY.md names security@docs.plus as the only reporting channel, but that address very likely cannot receive mail.

• Where: SECURITY.md:21
• Severity: high
• Checked: SECURITY.md:19-21 sends reporters only to "security@docs.plus". dig MX docs.plus returns no MX record, only the SOA. dig TXT docs.plus is also empty. Mail then falls back to the docs.plus A record. A port-25 probe (nc -z -w5 docs.plus 25) fails with exit 1, so no SMTP server answers there. A reporter's mail will bounce or be lost. That misleads readers about security support, so high is the right severity. gh api repos/docs-plus/docs.plus/private-vulnerability-reporting returns {"enabled":true}, but no tracked .md file links to security/advisories. The same address appears in apps/webapp/public/.well-known/security.txt:2, apps/webapp/src/pages/terms.tsx:12 and CHANGELOG.md:889. This is not a settled decision. AGENTS.md:162 only says SECURITY.md routes reports to security@docs.plus. It does not rule on whether that mailbox receives mail. So keep the address and fix delivery. Do not replace the address without a maintainer ruling. Leave CHANGELOG.md:889 alone, because it is history. One caveat: some outside mail setup could still exist, but with no MX record and port 25 closed, standard mail delivery fails.
• Fix: In SECURITY.md under "How to Report", add GitHub's private reporting link as the first channel: "Use GitHub private vulnerability reporting: https://github.com/docs-plus/docs.plus/security/advisories/new". Keep the email line after it. In security.txt, add Contact: https://github.com/docs-plus/docs.plus/security/advisories/new above the mailto: line. RFC 9116 reads Contact lines in order of preference. As a separate ops step, the maintainer adds an MX record or mail forward for security@docs.plus and sends a test mail. Do not change the address in SECURITY.md, security.txt or terms.tsx unless the maintainer rules that it should change.

2. SECURITY.md gives two different timelines for critical issues.

• Where: SECURITY.md:37
• Severity: medium
• Checked: SECURITY.md has a conflict. Line 35 says "acknowledge receipt of your report within 48 hours". Line 36 says "assess the vulnerability within 7 days". Line 37 says "release a fix within 30 days for critical issues". The table header at line 107 is "Response Time", and line 109 says "Critical | 24 hours". If "Response Time" means first reply, Critical (24 hours) differs from the 48-hour acknowledgment. High is 7 days, which is later than that 48-hour promise. If it means fix time, Critical at 24 hours contradicts "30 days for critical issues". No reading makes the two sections agree. No other tracked doc defines these times; git grep finds them only in SECURITY.md. This is not a settled decision, and a small text fix resolves it. Severity stays medium. A reporter is misled about the security support promise. Nobody loses data, and no step fails.
• Fix: Make one section the single source for the times. Rename the header at SECURITY.md:107 from "Response Time" to "Target fix time". Change :37 to "Resolution: We aim to release a fix within the target time for its severity in the Severity Classification table below." Keep :35 (48-hour acknowledgment) and :36 (7-day assessment) as they are. The maintainer must confirm that the table values are real fix commitments, especially Critical at 24 hours. If they are not, change the values in the table rather than the wording at :37.

3. The Supported Versions table skips the 1.x line that was really released.

• Where: SECURITY.md:9
• Severity: low
• Checked: The claim holds. SECURITY.md:5-9 lists three rows: "2.x (webapp + hocuspocus)", "latest (npm extensions)" and "< 1.0 | ❌". git tag shows v1.8.7, v1.8.12 and v1.8.18, and no tag below 1.0. CHANGELOG.md:899 says "docs.plus 1.x was an Etherpad fork. Its last tag is v1.8.18... That code is not reachable from main." The 1.x line is real and unsupported, but the table never names it. The "< 1.0" row points at versions that never existed. The table also lists no 2.0.0-alpha or beta line. Covering every older line with one row is the smallest fix. The cost is small: few readers still run the Etherpad fork, and the gap only implies 1.x support. So the severity stays low. This is not one of the settled decisions.
• Fix: In SECURITY.md:9, change the row | < 1.0 | :x: | to | < 2.0 (incl. Etherpad 1.x) | :x: |.

4. The README never links SECURITY.md or CODE_OF_CONDUCT.md, and its Support list has no security route.

• Where: README.md:362
• Severity: low
• Checked: The core fact is true. grep -nE 'SECURITY|CODE_OF_CONDUCT' README.md returns nothing. The Support list (README.md:362-369) gives Discord, Twitter, GitHub and contact@newspeak.house, but no security route. SECURITY.md says "DO NOT create a public GitHub issue" and gives security@docs.plus. apps/webapp/public/.well-known/security.txt gives the same address.

The claim that the README "sends a reporter to the wrong address" goes too far. The README never says where to report a vulnerability. Several other routes already reach SECURITY.md:

• GitHub shows SECURITY.md on the repo Security tab.
• gh api .../private-vulnerability-reporting returns {"enabled":true}.
• CONTRIBUTING.md:424 links SECURITY.md.
• CONTRIBUTING.md:5-7 links CODE_OF_CONDUCT.md near the top of the file.
• docs/README.md:44 links SECURITY.md.
• The GitHub community profile already finds the Code of Conduct.

So a careful reporter finds SECURITY.md. The risk is limited to a reader who uses only the README Support list. That makes this a missing link, not misleading text, so the severity is low, not medium. The Code of Conduct half is weaker still: GitHub shows the file, and CONTRIBUTING links it in its first section. It costs one line, so the Fix adds it.

• Fix: In README.md §Support, add one line: "- 🔒 Security: report a vulnerability as SECURITY.md says, not in a public issue or on Discord." Also add "- Conduct: Code of Conduct". Make the security reporting channel reachable, and make SECURITY.md agree with itself #481 item 4 and Tidy the contributor docs, templates and internal package READMEs #486 item 1 each add one line to README §Support. Whichever lands second keeps the other's line. Replace the expired Discord invite in the docs and the app #480 changes only the Discord invite code.

Decisions

1. What happens to security@docs.plus? Recommended: keep it and make it receive mail (an MX record or a forward), then send a test message. Until that works, list GitHub private reporting first in SECURITY.md and security.txt. Alternative: drop the address and use GitHub private reporting alone.
2. Are the Severity table times real commitments? Recommended: the maintainer sets times they can keep, and the table becomes the one source. Item 2 depends on this, above all Critical at 24 hours.

Acceptance criteria

• Item 1 is fixed as its Fix says, or a comment here says why not.
• Item 2 is fixed as its Fix says, or a comment here says why not.
• Item 3 is fixed as its Fix says, or a comment here says why not.
• Item 4 is fixed as its Fix says, or a comment here says why not.
• A test mail to security@docs.plus arrives, or the address is gone from SECURITY.md, security.txt and terms.tsx.

Verify

1. Signed in as a non-maintainer, open https://github.com/docs-plus/docs.plus/security/advisories/new and check that the form opens.
2. If the address stays, dig +short MX docs.plus returns a mail host.
3. grep -n 'SECURITY.md' README.md returns the new Support line, and head -3 apps/webapp/public/.well-known/security.txt shows the GitHub Contact line first.

Generated by Claude Code