[PATCH 0/2] rSTify 'report-a-bug' and 'security-process'; move them to QEMU Git

[PATCH 0/2] rSTify 'report-a-bug' and 'security-process'; move them to QEMU Git

[Kashyap Chamarthy]

This series rSTifies the said web pages[1][2] from the QEMU web and
moves them to docs/devel/ in QEMU Git.  This is based on Paolo's
feedback here[3].

The rename to 'reporting-a-bug' is done to be consistent with the other
in-tree docs.  And I put 'security-process' first because, we refer to
it from 'reporting-a-bug'.  (If we reverse the order, the build fails --
correctly so.)

[1] https://www.qemu.org/contribute/report-a-bug/
[2] https://www.qemu.org/contribute/security-process
[3] https://lists.nongnu.org/archive/html/qemu-devel/2021-11/msg04002.html

Kashyap Chamarthy (2):
  docs: rSTify "security-process" page; move it to QEMU Git
  docs: rSTify "report-a-bug" page; move it to QEMU Git

 docs/devel/index.rst            |   9 +-
 docs/devel/reporting-a-bug.rst  |  37 +++++++
 docs/devel/security-process.rst | 190 ++++++++++++++++++++++++++++++++
 3 files changed, 233 insertions(+), 3 deletions(-)
 create mode 100644 docs/devel/reporting-a-bug.rst
 create mode 100644 docs/devel/security-process.rst

-- 
2.31.1

[PATCH 1/2] docs: rSTify "security-process" page; move it to QEMU Git

[Kashyap Chamarthy]

This is based on Paolo's suggestion[1] that the 'security-process'[2]
page being a candidate for docs/devel.

Converted from Markdown to rST using:

    $> pandoc -f markdown -t rst security-process.md \
        -o security-process.rst

It's a 1-1 conversion (I double-checked to the best I could).  I've also
checked that the hyperlinks work correctly post-conversion.

[1] https://lists.nongnu.org/archive/html/qemu-devel/2021-11/msg04002.html
[2] https://www.qemu.org/contribute/security-process

Suggested-by: Paolo Bonzini <pbonzini@redhat.com>
Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com>
---
 docs/devel/index.rst            |   1 +
 docs/devel/security-process.rst | 190 ++++++++++++++++++++++++++++++++
 2 files changed, 191 insertions(+)
 create mode 100644 docs/devel/security-process.rst

diff --git a/docs/devel/index.rst b/docs/devel/index.rst
index afd937535e..424eff9294 100644
--- a/docs/devel/index.rst
+++ b/docs/devel/index.rst
@@ -48,3 +48,4 @@ modifying QEMU's source code.
    trivial-patches
    submitting-a-patch
    submitting-a-pull-request
+   security-process
diff --git a/docs/devel/security-process.rst b/docs/devel/security-process.rst
new file mode 100644
index 0000000000..cc1000fe43
--- /dev/null
+++ b/docs/devel/security-process.rst
@@ -0,0 +1,190 @@
+.. _security-process:
+
+Security Process
+================
+
+Please report any suspected security issue in QEMU to the security
+mailing list at:
+
+-  `<qemu-security@nongnu.org> <https://lists.nongnu.org/mailman/listinfo/qemu-security>`__
+
+To report an issue via `GPG <https://gnupg.org/>`__ encrypted email,
+please send it to the Red Hat Product Security team at:
+
+-  `<secalert@redhat.com> <https://access.redhat.com/security/team/contact/#contact>`__
+
+**Note:** after the triage, encrypted issue details shall be sent to the
+upstream ‘qemu-security’ mailing list for archival purposes.
+
+How to report an issue
+----------------------
+
+-  Please include as many details as possible in the issue report. Ex:
+
+   -  QEMU version, upstream commit/tag
+   -  Host & Guest architecture x86/Arm/PPC, 32/64 bit etc.
+   -  Affected code area/snippets
+   -  Stack traces, crash details
+   -  Malicious inputs/reproducer steps etc.
+   -  Any configurations/settings required to trigger the issue.
+
+-  Please share the QEMU command line used to invoke a guest VM.
+
+-  Please specify whom to acknowledge for reporting this issue.
+
+How we respond
+~~~~~~~~~~~~~~
+
+-  Process of handling security issues comprises following steps:
+
+   0) **Acknowledge:**
+
+   -  A non-automated response email is sent to the reporter(s) to
+      acknowledge the reception of the report. (*60 day’s counter starts
+      here*)
+
+   1) **Triage:**
+
+   -  Examine the issue details and confirm whether the issue is genuine
+   -  Validate if it can be misused for malicious purposes
+   -  Determine its worst case impact and severity
+      [Low/Moderate/Important/Critical]
+
+   2) **Response:**
+
+   -  Negotiate embargo timeline (if required, depending on severity)
+   -  Request a `CVE <https://cveform.mitre.org/>`__ and open an
+      upstream `bug <https://www.qemu.org/contribute/report-a-bug/>`__
+   -  Create an upstream fix patch annotated with
+
+      -  CVE-ID
+      -  Link to an upstream bugzilla
+      -  Reported-by, Tested-by etc. tags
+
+   -  Once the patch is merged, close the upstream bug with a link to
+      the commit
+
+      -  Fixed in:
+
+-  Above security lists are operated by select analysts, maintainers
+   and/or representatives from downstream communities.
+
+-  List members follow a **responsible disclosure** policy. Any
+   non-public information you share about security issues, is kept
+   confidential within members of the QEMU security team and a minimal
+   supporting staff in their affiliated companies. Such information will
+   not be disclosed to third party organisations/individuals without
+   prior permission from the reporter(s).
+
+-  We aim to process security issues within maximum of **60 days**. That
+   is not to say that issues will remain private for 60 days, nope.
+   After the triaging step above
+
+   -  If severity of the issue is sufficiently low, an upstream public
+      bug will be created immediately.
+   -  If severity of the issue requires co-ordinated disclosure at a
+      future date, then the embargo process below is followed, and
+      upstream bug will be opened at the end of the embargo period.
+
+   This will allow upstream contributors to create, test and track fix
+   patch(es).
+
+Publication embargo
+~~~~~~~~~~~~~~~~~~~
+
+-  If a security issue is reported that is not already public and its
+   severity requires coordinated disclosure, then an embargo date will
+   be set and communicated to the reporter(s).
+
+-  Embargo periods will be negotiated by mutual agreement between
+   reporter(s), members of the security list and other relevant parties
+   to the problem. The preferred embargo period is upto `2
+   weeks <https://oss-security.openwall.org/wiki/mailing-lists/distros>`__.
+   However, longer embargoes may be negotiated if the severity of the
+   issue requires it.
+
+-  Members of the security list agree not to publicly disclose any
+   details of an embargoed security issue until its embargo date
+   expires.
+
+CVE allocation
+~~~~~~~~~~~~~~
+
+Each security issue is assigned a `CVE <https://cveform.mitre.org/>`__
+number. The CVE number is allocated by one of the vendor security
+engineers on the security list.
+
+When to contact the QEMU Security List
+--------------------------------------
+
+You should contact the Security List if: \* You think there may be a
+security vulnerability in QEMU. \* You are unsure about how a known
+vulnerability affects QEMU. \* You can contact us in English. We are
+unable to respond in other languages.
+
+When *not* to contact the QEMU Security List
+--------------------------------------------
+
+-  You need assistance in a language other than English.
+-  You require technical assistance (for example, “how do I configure
+   QEMU?”).
+-  You need help upgrading QEMU due to security alerts.
+-  Your issue is not security related.
+
+How impact and severity of a bug is decided
+-------------------------------------------
+
+**Security criterion:** ->
+https://www.qemu.org/docs/master/system/security.html
+
+All security issues in QEMU are not equal. Based on the parts of the
+QEMU sources wherein the bug is found, its impact and severity could
+vary.
+
+In particular, QEMU is used in many different scenarios; some of them
+assume that the guest is trusted, some of them don’t. General
+considerations to triage QEMU issues and decide whether a configuration
+is security sensitive include:
+
+-  Is there any feasible way for a malicious party to exploit this flaw
+   and cause real damage? (e.g. from a guest or via downloadable images)
+-  Does the flaw require access to the management interface? Would the
+   management interface be accessible in the scenario where the flaw
+   could cause real damage?
+-  Is QEMU used in conjunction with a hypervisor (as opposed to TCG
+   binary translation)?
+-  Is QEMU used to offer virtualised production services, as opposed to
+   usage as a development platform?
+
+Whenever some or all of these questions have negative answers, what
+appears to be a major security flaw might be considered of low severity
+because it could only be exercised in use cases where QEMU and
+everything interacting with it is trusted.
+
+For example, consider upstream commit `9201bb9 “sdhci.c: Limit the
+maximum block
+size” <https://gitlab.com/qemu-project/qemu/-/commit/9201bb9>`__, an of
+out of bounds (OOB) memory access (ie. buffer overflow) issue that was
+found and fixed in the SD Host Controller emulation (hw/sd/sdhci.c).
+
+On the surface, this bug appears to be a genuine security flaw, with
+potentially severe implications. But digging further down, there are
+only two ways to use SD Host Controller emulation, one is via
+‘sdhci-pci’ interface and the other is via ‘generic-sdhci’ interface.
+
+Of these two, the ‘sdhci-pci’ interface had actually been disabled by
+default in the upstream QEMU releases (commit `1910913 “sdhci: Make
+device”sdhci-pci" unavailable with
+-device" <https://gitlab.com/qemu-project/qemu/-/commit/1910913>`__ at
+the time the flaw was reported; therefore, guests could not possibly use
+‘sdhci-pci’ for any purpose.
+
+The ‘generic-sdhci’ interface, instead, had only one user in ‘Xilinx
+Zynq Baseboard emulation’ (hw/arm/xilinx_zynq.c). Xilinx Zynq is a
+programmable systems on chip (SoC) device. While QEMU does emulate this
+device, in practice it is used to facilitate cross-platform
+developmental efforts, i.e. QEMU is used to write programs for the SoC
+device. In such developer environments, it is generally assumed that the
+guest is trusted.
+
+And thus, this buffer overflow turned out to be a security non-issue.
-- 
2.31.1

[PATCH 2/2] docs: rSTify "report-a-bug" page; move it to QEMU Git

[Kashyap Chamarthy]

This is also based on Paolo's suggestion[1] of "report-a-bug" page[2]
from the QEMU website being a candidate for docs/devel.

Converted from Markdown to rST using:

    $> pandoc -f markdown -t rst report-a-bug.md \
            -o reporting-a-bug.rst

Modifications:

- Rename this from "report-a-bug" page to "reporting-a-bug" to be
  consistent with existing in-tree docs.

- Use internal rST reference to "submitting-a-patch.rst"; and slightly
  tweak the sentence where this is referenced.

- Also tweak the description at the top of the 'index.rst' to to reflect
  that the manual also documents some of QEMU's development processes.

[1] https://lists.nongnu.org/archive/html/qemu-devel/2021-11/msg04002.html
[2] https://www.qemu.org/contribute/report-a-bug/

Suggested-by: Paolo Bonzini <pbonzini@redhat.com>
Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com>
---
 docs/devel/index.rst           |  8 +++++---
 docs/devel/reporting-a-bug.rst | 37 ++++++++++++++++++++++++++++++++++
 2 files changed, 42 insertions(+), 3 deletions(-)
 create mode 100644 docs/devel/reporting-a-bug.rst

diff --git a/docs/devel/index.rst b/docs/devel/index.rst
index 424eff9294..39797679de 100644
--- a/docs/devel/index.rst
+++ b/docs/devel/index.rst
@@ -2,9 +2,10 @@
 Developer Information
 ---------------------
 
-This section of the manual documents various parts of the internals of QEMU.
-You only need to read it if you are interested in reading or
-modifying QEMU's source code.
+This section of the manual documents some of QEMU's development
+practises, and various internals of QEMU.  These documents are
+particularly useful for those interested in reading or modifying QEMU's
+source code.
 
 .. toctree::
    :maxdepth: 2
@@ -49,3 +50,4 @@ modifying QEMU's source code.
    submitting-a-patch
    submitting-a-pull-request
    security-process
+   reporting-a-bug
diff --git a/docs/devel/reporting-a-bug.rst b/docs/devel/reporting-a-bug.rst
new file mode 100644
index 0000000000..a72f91caf4
--- /dev/null
+++ b/docs/devel/reporting-a-bug.rst
@@ -0,0 +1,37 @@
+.. _reporting-a-bug:
+
+Reporting a bug
+===============
+
+Bugs can be filed at our `bug
+tracker <https://gitlab.com/qemu-project/qemu/-/issues>`__, which is
+hosted on GitLab. Note: If you’ve got a problem with how your Linux
+distribution packages QEMU, please use the bug tracker from your distro
+instead.
+
+When submitting a bug report, please try to do the following:
+
+-  Include the QEMU release version or the git commit hash into the
+   description, so that it is later still clear in which version you
+   have found the bug. Reports against the `latest
+   release </download/#source>`__ or even the latest development tree
+   are usually acted upon faster.
+
+-  Include the full command line used to launch the QEMU guest.
+
+-  Reproduce the problem directly with a QEMU command-line. Avoid
+   frontends and management stacks, to ensure that the bug is in QEMU
+   itself and not in a frontend.
+
+-  Include information about the host and guest (operating system,
+   version, 32/64-bit).
+
+QEMU does not use GitLab merge requests; patches are sent to the mailing
+list according to the guidelines mentioned here: :ref:`submitting-a-patch`.
+
+Do **NOT** report security issues (or other bugs, too) as “confidential”
+bugs in the bug tracker. QEMU has a :ref:`security-process` for issues
+that should be reported in a non-public way instead.
+
+For problems with KVM in the kernel, use the kernel bug tracker instead;
+the `KVM wiki <https://www.linux-kvm.org/page/Bugs>`__ has the details.
-- 
2.31.1

Re: [PATCH 1/2] docs: rSTify "security-process" page; move it to QEMU Git

[Peter Maydell]

On Wed, 24 Nov 2021 at 14:27, Kashyap Chamarthy <kchamart@redhat.com> wrote:
>
> This is based on Paolo's suggestion[1] that the 'security-process'[2]
> page being a candidate for docs/devel.
>
> Converted from Markdown to rST using:
>
>     $> pandoc -f markdown -t rst security-process.md \
>         -o security-process.rst
>
> It's a 1-1 conversion (I double-checked to the best I could).  I've also
> checked that the hyperlinks work correctly post-conversion.
>
> [1] https://lists.nongnu.org/archive/html/qemu-devel/2021-11/msg04002.html
> [2] https://www.qemu.org/contribute/security-process
>

Reviewed-by: Peter Maydell <peter.maydell@linaro.org>

thanks
-- PMM

Re: [PATCH 2/2] docs: rSTify "report-a-bug" page; move it to QEMU Git

[Peter Maydell]

On Wed, 24 Nov 2021 at 14:27, Kashyap Chamarthy <kchamart@redhat.com> wrote:
>
> This is also based on Paolo's suggestion[1] of "report-a-bug" page[2]
> from the QEMU website being a candidate for docs/devel.
>
> Converted from Markdown to rST using:
>
>     $> pandoc -f markdown -t rst report-a-bug.md \
>             -o reporting-a-bug.rst
>
> Modifications:
>
> - Rename this from "report-a-bug" page to "reporting-a-bug" to be
>   consistent with existing in-tree docs.
>
> - Use internal rST reference to "submitting-a-patch.rst"; and slightly
>   tweak the sentence where this is referenced.
>
> - Also tweak the description at the top of the 'index.rst' to to reflect
>   that the manual also documents some of QEMU's development processes.
>
> [1] https://lists.nongnu.org/archive/html/qemu-devel/2021-11/msg04002.html
> [2] https://www.qemu.org/contribute/report-a-bug/
>
> Suggested-by: Paolo Bonzini <pbonzini@redhat.com>
> Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com>
> ---
>  docs/devel/index.rst           |  8 +++++---
>  docs/devel/reporting-a-bug.rst | 37 ++++++++++++++++++++++++++++++++++
>  2 files changed, 42 insertions(+), 3 deletions(-)
>  create mode 100644 docs/devel/reporting-a-bug.rst

I don't think the bug-reporting instructions really belong in 'devel',
because we would like all users to report bugs, not just developers.
I think the /about/ section would be a better home for this file.

-- PMM

Re: [PATCH 2/2] docs: rSTify "report-a-bug" page; move it to QEMU Git

[Kashyap Chamarthy]

On Mon, Nov 29, 2021 at 01:35:11PM +0000, Peter Maydell wrote:
> On Wed, 24 Nov 2021 at 14:27, Kashyap Chamarthy <kchamart@redhat.com> wrote:

[...]

> > [1] https://lists.nongnu.org/archive/html/qemu-devel/2021-11/msg04002.html
> > [2] https://www.qemu.org/contribute/report-a-bug/
> >
> > Suggested-by: Paolo Bonzini <pbonzini@redhat.com>
> > Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com>
> > ---
> >  docs/devel/index.rst           |  8 +++++---
> >  docs/devel/reporting-a-bug.rst | 37 ++++++++++++++++++++++++++++++++++
> >  2 files changed, 42 insertions(+), 3 deletions(-)
> >  create mode 100644 docs/devel/reporting-a-bug.rst
> 
> I don't think the bug-reporting instructions really belong in 'devel',
> because we would like all users to report bugs, not just developers.
> I think the /about/ section would be a better home for this file.

(Sorry for the slowness, I was out the last 4 days.)

Yeah; fair point.  Not sure why I didn't think about it :-).  I'll drop
this one.

        - - -

What do you think about these two pages:

    https://wiki.qemu.org/Contribute/FAQ
    https://wiki.qemu.org/Documentation/GettingStartedDevelopers

I think the 'Contribute/FAQ' page could be on the website, because the
same argument: FAQ can be used by any contributor, not just developers.
But 'GettingStartedDevelopers' can be in docs/devel/.  

Let me know if you think differently.

-- 
/kashyap