Merge ~emitorino/ubuntu-cve-tracker:update_usn_guidelines into ubuntu-cve-tracker:master

[Emilia Torino]

- README.usn: Add further USN guidelines

Every day the security team creates USNs and is very important to keep a consistent voice and feel for the benefit of our users.

The updates added to README.usn aim consolidate general rules and guidelines to make sure we achieve such goal.

7df6470... by Emilia Torino on 2022-06-14

Explaining README sections

Signed-off-by: Maria Emilia Torino <email address hidden>

[Alex Murray (alexmurray)]

Very nicely done Emi! LGTM.

review: Approve

[Spyros Seimenis (sespiros)]

LGTM! (minor typo)

38cd43a... by Emilia Torino on 2022-06-15

Fixing typo

Signed-off-by: Maria Emilia Torino <email address hidden>

[Emilia Torino (emitorino)]

> LGTM! (minor typo)

Fixed. Thanks!

[Mark Esler (eslerm)]

This looks great! I learned a lot and will use it as a reference often.

Here are minor suggestions:

Line 27: use "nickname" and "organization" instead of abbreviations.

Line 35: "isummary" perhaps a typo?

Line 77: I'd depoliticize the `woke` list by changing that filename to `inclusivity`, but that's another topic.

Lines 86, 317, and 319: `id est` and `example given` syntax inconsistency. Most of the document uses the form `i.e.` or `e.g.`. I'd choose one of the two syntax's.

[Mark Esler (eslerm)]

adding inline comments for above

7055663... by Emilia Torino on 2022-06-15

Adding further MP suggestions

Signed-off-by: Maria Emilia Torino <email address hidden>

[Emilia Torino (emitorino)]

Adding Mark's suggestions.

[Emilia Torino (emitorino)]

> This looks great! I learned a lot and will use it as a reference often.
>
> Here are minor suggestions:
>
> Line 27: use "nickname" and "organization" instead of abbreviations.
>
> Line 35: "isummary" perhaps a typo?
>
> Line 77: I'd depoliticize the `woke` list by changing that filename to
> `inclusivity`, but that's another topic.
>
> Lines 86, 317, and 319: `id est` and `example given` syntax inconsistency.
> Most of the document uses the form `i.e.` or `e.g.`. I'd choose one of the two
> syntax's.

Thanks a lot for the suggestions!

diff --git a/README.usn b/README.usn
index 6d7393d..ac8156f 100644
--- a/README.usn
+++ b/README.usn
@@ -1,52 +1,210 @@
-USNs need a consistent feel. Eg:
+USNs need a consistent voice and feel for the benefit of our users.
+
+This document consolidates rules, guidelines and examples applying to USN
+sections.
+
+* General rules for the description
+
+For every CVE involved in the USN, the description should be like:
 
 [<name> discovered that <pkg>....] <problem>. <kinds of exploits possible>.
-Spell out things like denial of service. Avoid non-inclusive terms and
-phrases like man in the middle or blacklist/whitelist.
-(CVE-XXXX-XXXX) -- only if multiple CVEs
+<result>
+
+The first sentence explains the problem in the package. The second one explains
+how an attacker could possibly exploit such problem, resulting in a security
+issue.
+
+** Discoverer
+For the discoverer <name>, check $UCT for the Discovered-by field. If it’s
+empty, look for the discoverer in bugs, patches, etc. We only use real names
+(not nicknames or organizations) in credits and be aware that the patch
+supplier is not always the discoverer. If there is no discoverer available,
+simply use: "It was discovered that <pkg> ..."
+
+** Affected packages
+For <pkg>, use the upstream package name in the title, description and
+isummary (issue summary) sections. This not always matches with the ubuntu
+source package name being patched. Only mention the package name, not affected
+versions.
+
+Make sure the source package description was properly set for every affected
+release (i.e. the value for the usn.py --source-description argument in the
+generated usn shell script is set). If it was not automatically populated, make
+sure the source package is present in $UCT/meta_list/package_info_overrides.json
+and add it if it is not.
 
-Write one paragraph for each CVE or, if the description is identical for
-multiple CVEs, consolidate and list the CVEs in the brackets. Don’t include the
-CVE number if there is only one CVE being fixed or if all the CVEs share a
-description.
+** CVEs references
+If the USN involves multiple CVEs, write one paragraph for each one. Add
+(CVE-XXXX-XXXX) at the end of each description, after the final dot.
+
+If the description is identical for multiple CVEs, consolidate all into one
+paragraph and list the CVEs in the brackets. e.g. (CVE-XXXX-XXXX, CVE-XXXX-XXXY)
+
+If there is only one CVE being fixed, do not add the CVE number.
 
 If a CVE only affected some of the releases mentioned in the USN, suffix the
 paragraph with the sentence `This issue only affected <releases>.`, e.g.:
 Ubuntu 16.04 ESM, Ubuntu 18.04 LTS and Ubuntu 20.04 LTS.
 
-For the discoverer <name>, check $UCT for the Discovered-by field. If it’s
-empty, look for the discoverer in bugs, patches, etc. We only use real names
-(not nicks or orgs) in credits and be aware that the patch supplier is not
-always the discoverer.
+** Terms
+Spell out terms. Instead of using "DoS", use "denial of service".
 
-For <pkg>, use the upstream package name.
+Don't capitalize terms. Instead of using "Denial of Service" use "denial of
+service".
 
-If the vulnerability requires user action, one possible template is:
-If a user <or automated system> were tricked into <opening a specially crafted
-<file type> || performing <action>>
+Avoid non-inclusive terms and phrases. Use "allowlist" in place of "whitelist"
+and "denylist" or "blocklist" in place of "blacklist". Find alternative terms in
+https://git.launchpad.net/usn-tool/tree/woke.yaml The scripts involved in the
+USN publication process will use this suggestions to report possible
+non-inclusive terms being mentioned.
+
+** Vulnerability explanation
+
+Be specific, but not overly detailed. Avoid being too technical. Use "under
+certain circumstances" instead of detailing specific files, functions, etc.
+
+Write the description in past tense. e.g.: "MySQL had a vulnerability" vs
+"MySQL has a vulnerability".
 
 If possible, fill in details on the adversary, e.g:
 <An unprivileged || A privileged> <local || remote> attacker <with
-x privileges>
+x privileges>. If a live connection is needed for the vulnerability to be
+exploited, use "authenticated user" instead of "attacker" to give a better
+sense of the scope.
+
+If the vulnerability requires user action, one possible template is:
+If a user <or automated system> were tricked into <opening a specially crafted
+<file type> || performing <action>> an attacker could possibly use this issue
+to <result>.
+
+For <kinds of exploits possible>, generally try to be as specific as possible.
+Add: "<adversary> could possibly use this issue to ..." since we cannot confirm
+how the adversary will take advantage of the vulnerability.
+
+If the impact is not clear, use the following generic statement:
+"resulting in <result>, or another unspecified impact".
+
+** Regressions
+
+Make sure the USN title is <pkg> regression. The description should say:
+USN-XXXX-1 fixed <vulnerabilities | a vulnerability> in <pkg>. Unfortunately
+that update <problem> and could introduce a regression. This updated fixes the
+problem.
 
-For <kinds of exploits possible>, generally try to be as specific as
-possible. Some generic examples of attacks are:
-<possibly use this issue | exploit this with a crafted <input>>
+We apologize for the inconvenience.
 
-Some generic examples of effects are:
-cause <pkg> <to expose sensitive information | execute arbitrary code>
-If the impact is not clear, the following is a generic statement on impact:
-crash, resulting in a denial of service, or possibly execute arbitrary code.
+Original advisory details: <USN-XXXX-1 description>
 
 
-Be specific, but not overly detailed. Examples:
+* General rules for the summary
 
-Temporary file race:
+If several CVEs are fixed in the USN, keep the summary as "Several issues were
+fixed in <pkg>" (even if all CVEs share the same description).
+
+Otherwise the summary should be written as: <pkg> could <result> if <condition>
+
+* General rules for the title
+
+<pkg> should respect the upstream name. If more than one CVE is fixed, make
+sure the title is in plural: <pkg> vulnerabilities
+
+* General rules for affected binaries
+
+Even though more than one binary can be generated as part of the source package
+update, the USN should only list the binary/binaries that are indeed affected
+by the CVE/CVEs being fixed for every release.
+
+* Examples
+
+Memory management
+-----------------
+<name> discovered that <pkg> did not properly manage memory <condition>.
+<kinds of exploits possible>. <result>
+
+It was discovered that HTMLDOC did not properly manage memory under certain
+circumstances. If a user were tricked into opening a specially crafted HTML
+file, a remote attacker could possibly use this issue to cause HTMLDOC to
+crash, resulting in a denial of service, or possibly execute arbitrary code
+
+Florian Weimer discovered that Cron incorrectly handled certain memory
+operations during crontab file creation. An attacker could possibly use
+this issue to cause a denial of service
+
+It was discovered that Thunderbird did not properly manage memory when
+using XUL tree elements. If a user were tricked into viewing malicious
+content, a remote attacker could cause a denial of service or possibly
+execute arbitrary code with the privileges of the user invoking the
+programs.
+
+Danilo Ramos discovered that rsync incorrectly handled memory when
+performing certain zlib deflating operations. An attacker could use this
+issue to cause rsync to crash, resulting in a denial of service, or
+possibly execute arbitrary code.
+
+It was discovered that FFmpeg incorrectly handled memory when using certain
+filters. An attacker could possibly use this issue to cause a denial of service
+or other unspecified impact.
+
+User input
+-----------------
+<name> discovered that <pkg> did not properly manage certain inputs.
+<kinds of exploits possible>. <result>
+
+Han Zheng discovered that Liblouis incorrectly handled certain inputs.
+An attacker could possibly use this issue to cause a crash
+
+File management
+-----------------
+<name> discovered that <pkg> did not properly manage certain files.
+<kinds of exploits possible>. <result>
+
+It was discovered that Ghostscript incorrectly handled certain PostScript
+files. If a user or automated system were tricked into processing a
+specially crafted file, a remote attacker could possibly use this issue to
+access arbitrary files, execute arbitrary code, or cause a denial of
+service.
+
+It was discovered that nginx incorrectly handled files with
+certain modification dates. A remote attacker could possibly
+use this issue to cause a denial of service or other unspecified
+impact.
+
+Crafted websites
+-----------------
+It was discovered that Go applications incorrectly handled uploaded content. If
+a user were tricked into visiting a malicious page, a remote attacker could
+exploit this with a crafted file to conduct cross-site scripting (XSS) attacks.
+
+Permissions
+-----------------
+<name> discovered that <pkg> incorrectly handled permissions <condition>.
+<kinds of exploits possible>. <result>
+
+It was discovered that the postinst maintainer script in Cron unsafely
+handled file permissions during package install or update operations.
+An attacker could possibly use this issue to perform a privilege
+escalation attack
+
+Jan Schejbal discovered that Paramiko incorrectly handled permissions when
+writing private key files. A local attacker could possibly use this issue
+to gain access to private keys.
+
+Dan Rabe discovered that OpenJDK incorrectly verified access permissions
+in the JAXP component. An attacker could possibly use this to specially
+craft an XML file to obtain sensitive information.
+
+James Troup discovered that snap did not properly manage the permissions for
+the snap directories. A local attacker could possibly use this issue to expose
+sensitive information
+
+Temporary file race
+-----------------
 <name> discovered that <pkg> created temporary files in an insecure way.
 <Local|Remote> users could exploit a race condition to create or overwrite
 files with the privileges of the user invoking the program.
 
-User-assisted:
+User-assisted
+-----------------
 <name> discovered that <pkg> did <error condition>.  If a user were tricked
 into opening a specially crafted <file type>, an attacker could <result>
 in <pkg>.
@@ -56,8 +214,8 @@ comparisons in certain operations. If a user were tricked into opening a
 specially crafted PNG image, an attacker could cause a denial of service in
 applications linked against libpng.
 
-
-Remote vulnerability:
+Remote vulnerability
+-----------------
 <name> discovered that <pkg> did <error condition>. A remote attacker could
 <attack technique> to the server and <result>.
 
@@ -65,8 +223,8 @@ Nahuel Riva and Gerardo Richarte discovered that the DHCP server did not
 correctly handle certain client options. A remote attacker could send malicious
 DHCP replies to the server and execute arbitrary code. 
 
-
-Remote authenticated user vulnerability:
+Remote authenticated user vulnerability
+-----------------
 <name> discovered that <pkg> did <error condition>. An authenticated user could
 <attack technique> to <result>.
 
@@ -74,8 +232,8 @@ Neil Kettle discovered that MySQL could be made to dereference a NULL pointer
 and divide by zero. An authenticated user could exploit this with a crafted IF
 clause, leading to a denial of service. (CVE-2007-2583)
 
-
-Automated system:
+Automated system
+-----------------
 <name> discovered that <pkg> did <error condition>. If a user or automated
 system were tricked...
 
@@ -84,8 +242,8 @@ archives. If a user or automated system were tricked into processing a
 specially crafted bzip2 archive, applications linked against libbz2 could be
 made to crash, possibly leading to a denial of service. 
 
-
-Local vulnerability:
+Local vulnerability
+-----------------
 <name> discovered that <pkg> did <error condition>. A local user could <attack
 technique> and <result>.
 
@@ -94,12 +252,8 @@ when using helper programs. Local users may be able to bypass security
 restrictions and gain root privileges using programs such as mount.nfs or
 mount.cifs.
 
-
-Man in the Middle -
+Machine in the middle
 -----------------
-Don't use this term directly as it is not inclusive and too jargony -
-instead just describe the scenario, ie.
-
 <name> discovered that <pkg> did not <error condition> when using a secure
 connection. If a remote attacker were able to intercept communication this
 flaw could be exploited to view sensitive information.
@@ -108,25 +262,14 @@ It was discovered that Pidgin did not validate SSL certificates when using a
 secure connection. If a remote attacker were able to intercept
 communications this flaw could be exploited to view sensitive information.
 
-In the above:
-<result> might be:
-* what privileges the attacker ends up with.  e.g.  "..and execute arbitrary
-code with root privileges" or "... with user privileges"
-* denial of service
-* escalated priviliges
-
-Tips:
-use "authenticated user" instead of "attacker" for the stuff that needs a live
-connection to give a better sense of the scope.
-
-don't capitalize things like "denial of service"
-
-do capitalize when there is an official upstream name (eg MySQL vs mysql)
-
-write the USN in past tense.  Eg "MySQL had a vulnerability" vs "MySQL has a
-vulnerability"
+Summary
+-----------------
+ImageMagick could be made to crash if it opened a specially crafted file.
 
-avoid non-inclusive language - use "allowlist" in place of "whitelist" and
-"denylist" or "blocklist" in place of "blacklist"
+e2fsprogs could be made to crash or possibly run programs if it processed a
+specially crafted file system image
 
+Ruby could be made to crash or read sensitive information when processing
+certain input.
 
+FreeRDP could allow unintended access to network services.