update security policy

SECURITY.md

@@ -1,11 +1,15 @@
-c-ares security
-===============
+# c-ares Security Reporting Policy
+
+- [Publishing](#publishing)
+- [Reporting Vulnerabilities](#reporting-vulnerabilities)
+  - [Reporting Requirements](#reporting-requirements)
+- [Vulnerability Handling](#vulnerability-handling)
+- [Joining the Security Team](#joining-the-security-team)
 
 This document is intended to provide guidance on how security vulnerabilities
 should be handled in the c-ares project.
 
-Publishing Information
-----------------------
+## Publishing
 
 All known and public c-ares vulnerabilities will be listed on [the c-ares web
 site](https://c-ares.org/vulns.html).
@@ -14,8 +18,45 @@ Security vulnerabilities should not be entered in the project's public bug
 tracker unless the necessary configuration is in place to limit access to the
 issue to only the reporter and the project's security team.
 
-Vulnerability Handling
-----------------------
+## Reporting Vulnerabilities
+
+- The person discovering the issue, the reporter, reports the vulnerability
+  privately to [[email protected])[mailto:[email protected]). That's
+  an email alias that reaches a handful of selected and trusted people.
+
+- Messages that do not relate to the reporting or managing of an undisclosed
+  security vulnerability in c-ares are ignored and no further action is
+  required.
+
+### Reporting Requirements
+
+1. The report must have a detailed description of the issue so the security
+   team members can understand the issue.
+2. The report should have a valid minimal test case to reproduce the issue.
+  a. Any code in a test case that isn't relevant to reproducing the issue
+     ***must*** be removed.
+  b. The test case must compile cleanly with warnings enabled, for clang/gcc
+     at a minimum, `-Wall -W`.
+  c. The reporter must validate the API being called is being used in an
+     appropriate manner, in accordance with common C practices. e.g.:
+    i.   If an API takes a C string, that means the input must be a valid C
+         string (e.g. NULL terminated).
+    ii.  Must not cast incompatible data types to silence compiler warnings
+         (likely generated by 2b above) as this will cause undefined behavior.
+         Use the right data types. (e.g. `struct ares_txt_reply *` can't be cast
+         to `ares_dns_record_t *`, they are different types).
+    iii. Make sure to free/destroy any c-ares generated objects using the
+         correct function as documented in the man page of the function that
+         generated the object (e.g. use `ares_free_hostent()` to free
+         a `struct hostent *`, not `ares_data_free()`).
+3. The report should include a stacktrace/backtrace of the issue.
+4. Include this statement in the email text when submiting a report:
+```
+I acknowledge I have read and complied with the security reporting requirements
+as described in https://c-ares.org/security.html
+```
+
+## Vulnerability Handling
 
 The typical process for handling a new security vulnerability is as follows.
 
@@ -27,13 +68,7 @@ mailing list. Also messages associated with any commits should not make any
 reference to the security nature of the commit if done prior to the public
 announcement.
 
-- The person discovering the issue, the reporter, reports the vulnerability
-  privately to `[email protected]`. That's an email alias that reaches a
-  handful of selected and trusted people.
-
-- Messages that do not relate to the reporting or managing of an undisclosed
-  security vulnerability in c-ares are ignored and no further action is
-  required.
+- A vulnerability report is sent as per [Reporting Vulnerabilities](#reporting-vulnerabilities).
 
 - A person in the security team sends an e-mail to the original reporter to
   acknowledge the report.
@@ -46,10 +81,6 @@ announcement.
 - If the report is accepted, the team writes to the reporter to let them
   know it is accepted and that they are working on a fix.
 
-- The security team discusses the problem, works out a fix, considers the
-  impact of the problem and suggests a release schedule. This discussion
-  should involve the reporter as much as possible.
-
 - The release of the information should be "as soon as possible" and is most
   often synced with an upcoming release that contains the fix. If the
   reporter, or anyone else, thinks the next planned release is too far away
@@ -60,22 +91,30 @@ announcement.
   workarounds, when the release is out and make sure to credit all
   contributors properly.
 
-- Request a CVE number from
-  [distros@openwall](http://oss-security.openwall.org/wiki/mailing-lists/distros)
-  when also informing and preparing them for the upcoming public security
-  vulnerability announcement - attach the advisory draft for information. Note
-  that 'distros' won't accept an embargo longer than 19 days.
+- Request a CVE number from GitHub by drafting a security advisory via
+  [GitHub Security](https://github.com/c-ares/c-ares/security), then requesting
+  a CVE be assigned.
 
-- Update the "security advisory" with the CVE number.
+- The security team discusses the problem, works out a fix, considers the
+  impact of the problem and suggests a release schedule. This discussion
+  should involve the reporter as much as possible.
 
-- The security team commits the fix in a private branch. The commit message
+- The security team commits the fix in a private branch automatically generated
+  by the GitHub security advisory creation process. The commit message
   should ideally contain the CVE number. This fix is usually also distributed
   to the 'distros' mailing list to allow them to use the fix prior to the
   public announcement.
 
+- Send the advisory draft to [distros@openwall](http://oss-security.openwall.org/wiki/mailing-lists/distros)
+  to prepare them for the upcoming public security vulnerability announcement.
+  For high-severity fixes, a patch should also be attached so it can be
+  integrated prior to the official release. Note that 'distros' won't accept an
+  embargo longer than 19 days.
+
 - At the day of the next release, the private branch is merged into the master
-  branch and pushed. Once pushed, the information is accessible to the public
-  and the actual release should follow suit immediately afterwards.
+  branch and pushed, the GitHub advisory is made public.  Once pushed, the
+  information is accessible to the public and the actual release should follow
+  suit immediately afterwards.
 
 - The project team creates a release that includes the fix.
 
@@ -86,15 +125,17 @@ announcement.
 - The security web page on the web site should get the new vulnerability
   mentioned.
 
-C-ARES-SECURITY (at haxx dot se)
---------------------------------
 
-Who is on this list? There are a couple of criteria you must meet, and then we
-might ask you to join the list or you can ask to join it. It really isn't very
-formal. We basically only require that you have a long-term presence in the
-c-ares project and you have shown an understanding for the project and its way
-of working. You must've been around for a good while and you should have no
-plans in vanishing in the near future.
+## Joining the Security Team
+
+Who is on the security team receiving notices via [[email protected])[mailto:[email protected])?
+
+There are a couple of criteria you must meet, and then we might ask you to join
+the list or you can ask to join it. It really isn't very formal. We basically
+only require that you have a long-term presence in the c-ares project and you
+have shown an understanding for the project and its way of working. You must've
+been around for a good while and you should have no plans in vanishing in the
+near future.
 
 We do not make the list of partipants public mostly because it tends to vary
 somewhat over time and a list somewhere will only risk getting outdated.