Merge pull request #473 from lsmith77/security-disclosure

[PSR-10][WIP] initial draft for a security disclosure PSR

proposed/security-disclosure-publication-meta.md

@@ -0,0 +1,81 @@
+Security Disclosure Meta Document
+=================================
+
+1. Summary
+----------
+
+There are two aspects with dealing with security issues: One is 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-9 addresses the former, this PSR, ie. PSR-10, deals with
+the later. That is how security issues are disclosed and what format such
+disclosures should follow. Especially today where PHP developers are sharing
+code across projects more than ever, this PSR aims to ease the challenges in
+keeping an overview of security issues in all dependencies and the steps 
+required to address them.
+
+2. Why Bother?
+--------------
+
+End users  want to ensure that they stay informed about security issues.
+However they also want to be able to quickly check if they are affected to be
+able to take the necessary steps.
+
+Upstream users of code will also want to know these details. Furthermore they
+will want to know if its possible for them to be included into possible closed
+discussions before details about a security issue are made public.
+
+3. Scope
+--------
+
+## 3.1 Goals
+
+* Means to help in (semi-)automating discovery and fixing of known security
+  issues in projects using the affected code
+
+## 3.2 Non-Goals
+
+* Process for how vulnerabilities are reported and fixed
+* Methods for reducing security vulnerabilities
+
+4. Approaches
+-------------
+
+A key aspect here is that the information flow should be as structured as
+possible to help in automating things as much possible. For example,
+vulnerabilities should be published in a defined location and in a defined
+format. Inspiration could be taken from [1].
+
+That being said, the standard should not rely on any central authority
+above the projects. This is to ensure that no project becomes depend on an
+outside authority for something as sensitive as security related topics.
+However due to defined locations and formats, it will become possible for
+other people to build centralized tools around this information.
+
+5. People
+---------
+
+### 5.1 Editor
+
+* Lukas Kahwe Smith
+
+### 5.2 Sponsors
+
+* Larry Garfield (Drupal)
+* Korvin Szanto (concrete5)
+
+### 5.3 Coordinator
+
+* Korvin Szanto (concrete5)
+
+6. Votes
+--------
+
+
+7. Relevant Links
+-----------------
+
+[1]: https://github.com/FriendsOfPHP/security-advisories
+
+Initial discussion: https://groups.google.com/d/msg/php-fig/45AIj5bPHJ4/ThERB43j-u8J
+Discussion: https://groups.google.com/forum/#!forum/php-fig-psr-9-discussion

proposed/security-disclosure-publication.md

@@ -0,0 +1,85 @@
+## Introduction
+
+There are two aspects with dealing with security issues: One is 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-9 addresses the former, this PSR, ie. PSR-10, deals with
+the later. That is how security issues are disclosed and what format such
+disclosures should follow. Especially today where PHP developers are sharing
+code across projects more than ever, this PSR aims to ease the challenges in
+keeping an overview of security issues in all dependencies and the steps 
+required to address them.
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
+"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
+interpreted as described in [RFC 2119][].
+
+[RFC 2119]: http://tools.ietf.org/html/rfc2119
+
+## Goal
+
+The goal of this PSR is to give project leads a clearly defined approach
+to allowing end users to discover security disclosures including a clearly
+defined structured format for disclosures.
+
+## Disclosure Discovery
+
+Every project MUST provide a link to its security vulnerability database 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. If the project has a dedicated page for its disclosure process
+discovery then this is also considered a good place for this link.
+The link MAY use the custom link relation ``php-vuln-disclosures``,
+ie. for example
+``<link rel="php-vuln-disclosures" href="http://example.org/disclosures"/>``.
+
+Note that projects MAY choose to host their disclosure files on a domain
+other than their main project page. It is RECOMMENDED to not store the
+disclosures in a VCS as this can lead to the confusions about which branch
+is the relevant branch. If a VCS is used then additional steps should be taken
+to clearly document to users which branch contains all vulnerabilities for
+all versions. If necessary projects MAY however split vulnerability disclosure
+files by major version number. In this case again this should be clearly
+documented.
+
+## Disclosure Format
+
+The disclosure format is based on Atom [1], which in turn is based on XML. It
+leverages the "The Common Vulnerability Reporting Framework (CVRF) v1.1" [2].
+Specifically it leverages its dictionary [3] as its base terminology.
+
+The Atom extensions allow a structured description of the vulnerability to
+enable automated tools to determine if installed is likely affected by the
+vulnerability. However human readability is considered highly important and as
+such not the full CVRF is used.
+
+Note that for each vulnerability only a single entry should be created. In case
+any information changes the original file MUST be updated along with the last
+update field.
+
+Any disclosure uses ``entryType`` using the following tags from the Atom namespace:
+
+* title (short description of the vulnerability and affected versions)
+* summary (description of the vulnerability)
+* author (contact information)
+* published (initial publication date)
+* updated (date of the last update)
+* link (to reference more information)
+* id (project specific vulnerability id)
+
+In addition the following tags are added:
+
+* name (name of the product)
+* cve (unique CVE ID)
+* cwe (unique CWE ID)
+* severity (low, medium high)
+* affected (version(s) using composer syntax [4])
+* status (open, in progress, disputed, completed)
+* remediation (textual description for how to fix an affected system)
+* remediationType (workaround, mitigation, vendor fix, none available, will not fix)
+* remediationLink (URL to give additional information for remediation)
+
+[1] https://tools.ietf.org/html/rfc4287
+[2] http://www.icasi.org/cvrf-1.1
+[3] http://www.icasi.org/cvrf-1.1-dictionary
+[4] https://getcomposer.org/doc/01-basic-usage.md#package-versions

proposed/security-disclosure-publication.xsd

@@ -0,0 +1,60 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<xs:schema
+        xmlns:xs="http://www.w3.org/2001/XMLSchema"
+        targetNamespace="http://www.php-fig.org/schemas/security-disclosure"
+        xmlns:sd="http://www.php-fig.org/schemas/security-disclosure"
+        xmlns:atom="http://www.w3.org/2005/Atom"
+        elementFormDefault="qualified">
+
+    <xs:element name="name" type="xs:string" />
+
+    <xs:element name="cve" type="xs:string" />
+
+    <xs:element name="cwe" type="xs:string" minOccurs="0" />
+
+    <xs:simpleType name="severity">
+        <xs:restriction base="xs:string">
+            <xs:enumeration value="low" />
+            <xs:enumeration value="medium" />
+            <xs:enumeration value="high" />
+        </xs:restriction>
+    </xs:simpleType>
+
+    <xs:simpleType name="status">
+        <xs:restriction base="xs:string">
+            <xs:enumeration value="open" />
+            <xs:enumeration value="in progress" />
+            <xs:enumeration value="disputed" />
+            <xs:enumeration value="completed" />
+        </xs:restriction>
+    </xs:simpleType>
+
+    <xs:element name="remediation" type="sd:remediationType" minOccurs="0" maxOccurs="unbounded" />
+
+    <xs:complexType name="remediationType">
+        <xs:annotation>
+            <xs:documentation>
+                The PHP FIG security disclosure remediation construct is to be used to specify a specific remediation
+                option for a specific vulnerability.
+            </xs:documentation>
+        </xs:annotation>
+        <xs:choice maxOccurs="unbounded">
+            <xs:element name="summary" type="xs:string" />
+
+            <xs:element name="affected" type="xs:string" />
+
+            <xs:simpleType name="type">
+                <xs:restriction base="xs:string">
+                    <xs:enumeration value="workaround" />
+                    <xs:enumeration value="mitigation" />
+                    <xs:enumeration value="none available" />
+                    <xs:enumeration value="will not fix" />
+                </xs:restriction>
+            </xs:simpleType>
+
+            <xs:element name="link" type="atom:linkType" minOccurs="0" maxOccurs="unbounded" />
+        </xs:choice>
+    </xs:complexType>
+
+</xs:schema>