minor wording tweaks

proposed/security-reporting-process-meta.md

@@ -4,44 +4,46 @@ Security Disclosure Meta Document
 1. Summary
 ----------
 
-Unfortunately with all software development, security vulnerabilities are a
-fact of life that need to be addressed. It is important that when security
-vulnerabilities are found that researchers have an easy channel to the
-projects in question allowing them to disclose the issue to a controlled
-group of people.
-
+There are two aspects with dealing with security issues: One is the process
+by which security issues are reported and fixed in projects, the other
+is how the general public is informed about the issues and any remedies
+available. While PSR-10 addresses the later, this PSR, ie. PSR-9, deals with
+the former. So the goal of PSR-9 is to define the process by which security
+researchers and report security vulnerabilities to projects. It is important
+that when security vulnerabilities are found that researchers have an easy
+channel to the projects in question allowing them to disclose the issue to a
+controlled group of people.
 
 2. Why Bother?
 --------------
 
-As of right now, there isn't really a common standard for most parts of this
-process. There isn't a standard where researchers can find out about the
+As of right now, there isn't a common standard for most parts of this process.
+That is there isn't a standard where researchers can find out about the
 process for handling security issues for any given project. There is also
 no standard that explains to researchers what they can expect to happen if
-they report a vulnerability.
+they report a vulnerability. More importantly there is no standard on which
+projects can base the security reporting process that best fits them.
 
 3. Scope
 --------
 
 ## 3.1 Goals
 
-* A defined process for how vulnerabilities are reported, how these get fixed
-  and finally disclosed to the public
+* A defined process for how vulnerabilities are reported, the process by which
+  these get fixed and finally disclosed to the public
 
 ## 3.2 Non-Goals
 
 * Methods for reducing security vulnerabilities
-* Publication of security issues and fixes
+* Publication of security issues and fixes (see PSR-10)
 
 4. Approaches
 -------------
 
 Currently the most viable approach seems to be defining a base line workflow
 for how security vulnerabilities go from discovery to fixing to public
-disclosure. Inspiration could be drawn from [1].
-
-For further reference here is a list of security disclosure processes in
-various PHP and non-PHP projects:
+disclosure. Inspiration could be drawn from this list of security disclosure
+processes in various PHP and non-PHP projects:
 
 * http://symfony.com/doc/current/contributing/code/security.html
 * http://framework.zend.com/security/

proposed/security-reporting-process.md

@@ -1,10 +1,14 @@
 ## Introduction
 
-Unfortunately with all software development, security vulnerabilities are a
-fact of life that need to be addressed. It is important that when security
-vulnerabilities are found that researchers have an easy channel to the
-projects in question allowing them to disclose the issue to a controlled
-group of people.
+There are two aspects with dealing with security issues: One is the process
+by which security issues are reported and fixed in projects, the other
+is how the general public is informed about the issues and any remedies
+available. While PSR-10 addresses the later, this PSR, ie. PSR-9, deals with
+the former. So the goal of PSR-9 is to define the process by which security
+researchers and report security vulnerabilities to projects. It is important
+that when security vulnerabilities are found that researchers have an easy
+channel to the projects in question allowing them to disclose the issue to a
+controlled group of people.
 
 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
 "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
@@ -15,22 +19,28 @@ interpreted as described in [RFC 2119][].
 ## Goal
 
 The goal of this PSR is to give researchers, project leads, upstream project
-leads and end user a defined and structured process for disclosing security
+leads and end users a defined and structured process for disclosing security
 vulnerabilities.
 
 ## Security Disclosure Process Discovery
 
 Every project MUST provide a link to its security disclosure process in
-an obvious place. Ideally this should be on the main domain of the given
-project. This MAY be a sub-domain in case it is a sub-project of a larger
-initiative. The link MAY use the custom link relation
-``php-disclosure-process``, ie. for example
-``<link rel="php-disclosure-process" href="http://example.org/security"/>``.
+an obvious place. Ideally this should be on the root page the main domain of
+the given project. This MAY be a sub-domain in case it is a sub-project of a
+larger initiative. The link MAY use the custom link relation
+``php-vuln-reporting``, ie. for example
+``<link rel="php-vuln-reporting" href="http://example.org/security"/>``.
 
 Projects SHOULD ideally make the location prominent itself
 by either creating a dedicated sub-domain like ``http://security.example.org``
 or by making it a top level directory like ``http://example.org/security``.
 Alternatively projects MAY also simply reference this document, ie. PSR-9.
+By referencing PSR-9 a project basically states that they follow the
+default procedures as noted in the section "Default Procedures" towards
+the end of this document. Projects MUST list the variables noted at the start
+of that section in this reference (ie. project name, project domain, etc.).
+Projects MAY choose to list any part of the procedures that is not a MUST
+which they choose to omit.
 
 Note that projects MAY not have a dedicated domain. For example a project
 hosted on Github, Bitbucket or other service should still ensure that the
@@ -40,15 +50,24 @@ has a README file which references the procedures used so that it is
 automatically displayed.
 
 If necessary projects MAY have different disclosure process
-for different major version number. In this case one URL SHOULD be provided
+for different major version number. In this case one URL MUST be provided
 for each major version. In the case a major version is no longer receiving
 security fixes, instead of an URL a project MAY opt to instead simply
 note that the version is no longer receiving security fixes.
 
 ## Security Disclosure Process
 
 Every project MUST provide an email address in their security disclosure
-process description. If not specified otherwise, this email address is
-``security@[project domain]``. Projects SHALL NOT use contact forms.
+process description as the ``contact email address``. Projects SHALL NOT
+use contact forms.
 
-...?
+**TODO**: Add more things found here https://groups.google.com/d/msg/php-fig-psr-9-discussion/puGV_X0bj_M/Jr_IAS40StsJ?
+
+## Default Procedures
+
+* ``[project name]`` denotes the name on which the project uses to identify itself.
+* ``[project domain]`` denotes the main (sub)domain on which the project relies.
+
+If not specified otherwise, the ``contact email address`` is ``security@[project domain]``.
+
+**TODO**: Add more things noted in the previous section