More wording improvements contributed by Sander Bos

git-svn-id: svn+ssh://svn.debian.org/svn/secure-testing@37894 e39458fd-73e7-0310-bf30-c45bca0a0e42

1 files changed, 97 insertions, 94 deletions

diff --git a/doc/security-team.d.o/security_tracker b/doc/security-team.d.o/security_tracker
index ea59f1ffa4..f27983d0d4 100644
--- a/doc/security-team.d.o/security_tracker
+++ b/doc/security-team.d.o/security_tracker
@@ -9,8 +9,8 @@ Everything in the [Debian Security Tracker](https://security-tracker.debian.org/
 "[Debian doesn't hide problems](https://www.debian.org/social_contract)" available. 
 
 The best thing about our tracking *system* is that it is very basic.
-There is no horrible overhead of web-based ticket/issue trackers, its
-just a subversion repository and some text files that we
+There is no horrible overhead of web-based ticket/issue trackers, it's
+just a Subversion (SVN) repository and some text files that we
 collaboratively edit and then some scripts to parse these files and
 generate useful reports available online. Everything is designed to be
 very simple to use, transparent and easy to see what other people are
@@ -19,8 +19,8 @@ working on so you can work on other things.
 Gentle Introduction
 --------------------
 
-This following will give you a basic walk-through of how the files are
-structured and how we do our work tracking issues. 
+The following will give you a basic walkthrough of how the files are
+structured, and how we do our work while tracking issues. 
 
 The best way to understand is to check out our repository from
 Subversion so you have the files on your computer and can follow along
@@ -29,7 +29,7 @@ at home. To do this you just need to do the following:
     svn co svn+ssh://<alioth user name>@svn.debian.org/svn/secure-testing
 
 This will check out the working repository (given that you already have
-an [Alioth](https://alioth.debian.org/account/register.php) account and [public key authentication already set up](http://wiki.debian.org/Alioth/SSH).  After successfully downloading,
+an [Alioth account](https://alioth.debian.org/account/register.php) and [public key authentication already set up](https://wiki.debian.org/Alioth/SSH).  After successful downloading,
 you will have a new directory called `secure-testing`.  Inside this directory
 are a number of subdirectories.  The `data` directory is where we do most of
 our work.
@@ -45,15 +45,15 @@ without an Alioth account as well:
 
     svn co svn://anonscm.debian.org/svn/secure-testing
 
-If you are a git fan, you can also use git-svn. Once you have the
-git-svn package installed, you can clone the subversion repository into
-your own local git repository with:
+If you are a Git fan, you can also use git-svn. Once you have the
+git-svn package installed, you can clone the Subversion repository into
+your own local Git repository with:
 
-    git svn clone svn+ssh://<alioth user account>@svn.debian.org/svn/secure-testing
+    git svn clone svn+ssh://<alioth user name>@svn.debian.org/svn/secure-testing
 
 Note that this will take a very long time (expect over two hours) since
 every commit from the very beginning (over 12,000 at this point) is
-checked out individually and merged into your git repository.
+checked out individually and merged into your Git repository.
 
 ### Subversion and git-svn Crash Course
 
@@ -68,62 +68,64 @@ with the secure-testing repository:
   `svn diff`       | `git diff`        | compare your local repo to remote secure-testing repo
 
 The CVE list (`CVE/list`)
-------------------------
+-------------------------
 
 ### Automatic Issue Updates
 
-Twice a day a cronjob runs that pulls down the latest full [CVE](glossary.html#CVE) lists
-from [Mitre](glossary.html#mitre), this automatically gets checked into `data/CVE/list`, and
+Twice a day a cron job runs that pulls down the latest full [CVE](glossary.html#CVE) lists
+from [MITRE](glossary.html#mitre), automatically checks that in into `data/CVE/list`, and
 also syncs that file with other lists like `data/DSA/list` and
 `data/DTSA/list`.
 
-These and every SVN commit is notified via either the [secure-testing-commits mailing list](http://lists.alioth.debian.org/mailman/listinfo/secure-testing-commits)
-or via the [KGB bot](http://packages.debian.org/sid/kgb-bot) on #debian-security on [OFTC](http://irc.oftc.net/). For example, the bot
-will say in the channel:
+These automatic commits as well as all Subversion commits are notified via either the [secure-testing-commits mailing list](https://lists.alioth.debian.org/mailman/listinfo/secure-testing-commits),
+or via the [KGB IRC bot](https://packages.debian.org/sid/kgb-bot) in the #debian-security channel on the [OFTC IRC network](http://www.oftc.net/). For example, the bot
+could say in the channel:
 
     17:14 < KGB-0> joeyh r21191 data/CVE/list * automatic update
 
-Most of our work is taking the new issues that Mitre releases and
-processing them so that the tracking data is correct. Read on for how we
-do this.
+Most of our work consists of taking new issues that MITRE releases and
+processing them so that the tracking data is correct. Read on for an
+explanation of how we do this.
 
 ### Processing `TODO` entries
 
-The Mitre update typically manifests in new CVE entries. So what we do
-is to update our svn repository and then edit `data/CVE/list` and look
+The MITRE update typically manifests in new CVE entries. So what we do
+is update our Subversion repository and then edit `data/CVE/list` and look
 for new `TODO` entries. These will often be in blocks of 10-50 or so,
-depending on how many new issues they have assigned.
+depending on how many new issues have been assigned by MITRE.
 
-Processing `TODO` entries means check if the problem affects Debian and
-to which packages, as well as, evaluate their severity. This information
+Processing `TODO` entries means checking if the problem affects Debian and
+if so which packages, as well as evaluate their severity. This information
 is based on *research* and not just in the CVE description in order to
-to prevent integrating false-positives or incorrect data in the security 
+prevent integrating false positives or incorrect data in the security 
 tracker. For example, if the CVE id says that something is 
-vulnerable prior to version X you need to check if that is 
+vulnerable prior to version X, you need to check if that is 
 the case as well as for the information given on 
-distro-specific issues. Always make sure you understand the 
-issue and are able to verify the information is correct.
+distribution specific issues. Always make sure you understand the 
+issue and are able to verify that the information is correct.
 
-So, a proper research should include reading the code, finding 
-fixes/commits in the upstream repository or even write 
-patches yourself if you have the time to do that. If you 
-can't assure that please add a `TODO` entry reflecting what is 
+Thus, a proper research should include reading the code, finding 
+fixes/commits in the upstream repository, or even writing
+patches yourself if you have the time and skills to do that. If you 
+can't assure that, please add a `TODO` entry reflecting what is 
 missing from your research. Check the section [`NOTE` and `TODO`
-entries](#NoteTodo) for more details.
+entries](#note-and-todo-entries) for more details.
 
 If you are aware of an error in some CVE description, please
-write to [oss-security mailing-list](glossary.html#oss-sec) cc-ing team@security.d.o.
+write to the [oss-security mailing list](glossary.html#oss-sec),
+with a carbon copy (cc) to team@security.debian.org.
 
 ### Issues `NOT-FOR-US` (NFU)
 
 Processing entries is done by first seeing if the issue is related to any
 software packaged in Debian. If it isn't a package in Debian and has no
-[ITP/RFP](https://www.debian.org/devel/wnpp/#l2) then you note that in the file with a `NOT-FOR-US:` tag. Third-party
+[ITP/RFP](https://www.debian.org/devel/wnpp/#l2) then you make a note of that
+in the file using a `NOT-FOR-US:` tag. Third-party
 modules not yet packaged for Debian are also tagged as NFU; even if their
 parent software is packaged for Debian. The module names should be
 mentioned in the NFU note in order to make issues apparent if that module
 should ever receive a proper package.  Another case are meta packages
-that only provide a downloader (e.g. flashplugin-nonfree). There is no
+that only provide a downloader (e.g., flashplugin-nonfree). There is no
 way to mark such packages as we have no influence on the version and
 technically the code is not present in Debian.
 
@@ -135,31 +137,31 @@ Example:
 Before marking a package NFU, the following should be done:
 
    - Read the full CVE description to determine the product name
-   - Search for the product using apt-cache search <name>
+   - Search for the product using `apt-cache search <name>`
    - If a file was referenced, search for the file using
       `apt-file search <name>`
-   - Search the [WNPP list](http://www.debian.org/devel/wnpp/) to see
-      if the product has an ITP or RFP (see [ITP/RFP packages](#ItpRfp) below)
-   - Search the [ftp-master removal list](http://ftp-master.debian.org/removals-full.txt)
-      or the [Package
-      Tracking System](https://packages.qa.debian.org/) to see if the
+   - Search the [WNPP list](https://www.debian.org/devel/wnpp/) to see
+      if the product has an ITP or RFP (see [ITP/RFP packages](#issues-in-itp-andor-rfp-packages) below)
+   - Search the [ftp-master removal list](https://ftp-master.debian.org/removals-full.txt)
+      or the [Package Tracking System](https://packages.qa.debian.org/) to see if the
       package was present in the past but was removed (see [Removed 
-      packages](#removed) below)
+      packages](#removed-packages) below)
 
 If there is any doubt, add a `NOTE` with your findings and/or ask others to
-double check using `TODO` (see [`NOTE` and `TODO` entries](#NoteTodo) below)
+double check using `TODO` (see [`NOTE` and `TODO` entries](#note-and-todo-entries) below).
 
 There is a tool that helps with sorting out all the NOT-FOR-US issues: 
-See "bin/check-new-issues -h". For the search functions in 
+`bin/check-new-issues -h`. For the search functions in 
 check-new-issues to work, you need to have unstable in your 
 sources.list and have done `apt-get update` and `apt-file update`. 
 Having libterm-readline-gnu-perl installed helps, too. If you are not
-running unstable, you can search at [http://packages.debian.org](http://packages.debian.org) or
-set up an [unstable chroot](http://www.debian.org/doc/manuals/reference/ch09#_chroot_system).
+running unstable, you can search at [https://packages.debian.org](https://packages.debian.org) or
+set up an [unstable chroot](https://www.debian.org/doc/manuals/reference/ch09#_chroot_system).
 
 ### Packages in the archive
 
-If the vulnerability refers to a package in the Debian archive (except for experimental, [see later](#packages-in-experimental-only)), look
+If the vulnerability refers to a package in the Debian archive (except for experimental,
+[see later](#packages-in-experimental-only)), look
 to see if the package is affected or not (sometimes newer versions that
 have the fixes have already been uploaded).
 
@@ -208,7 +210,7 @@ security issues, it only causes overhead.
 If you want to report a bug, bin/report-vuln might be helpful in creating
 the bug report.
 
-If a vulnerability does not affect Debian, e.g. because the vulnerable
+If a vulnerability does not affect Debian, e.g., because the vulnerable
 code is not contained, it is marked as <not-affected>:
 
     CVE-2004-2628 (Multiple directory traversal vulnerabilities in thttpd 2.07 beta 0.4, ...)
@@ -241,7 +243,8 @@ entry is:
             - webkit <undetermined>
             NOTE: webkit commit #123456
 
-The list of all of currently undetermined issues is aggregated [by the tracker](http://security-tracker.debian.org/tracker/status/undetermined).
+The list of all of currently undetermined issues is aggregated
+[by the tracker](https://security-tracker.debian.org/tracker/status/undetermined).
 This is a good place for new contributors to get started since these
 are issues that can be pruned quickly for new information that may
 not have been known during the initial disclosure, and thus marked
@@ -259,17 +262,16 @@ case, place the distribution tag `experimental`. For example:
 
 If the package is in unstable *and* in experimental, focus on unstable (we are 
 not tracking fixes in experimental). A note about the situation in experimental
-is appreciate. For example:
+is appreciated though. For example:
 
     CVE-2014-8564 (The _gnutls_ecc_ansi_x963_export function in gnutls_ecc.c in GnuTLS ...)
             - gnutls28 <unfixed> (bug #769154)
             NOTE: in experimental fixed in 3.3.10-1
 
-
 ### Issues in ITP and/or RFP packages
 
 If an issue is discovered in a package that has an RFP or ITP already filed,
-then that is also noted in order to track the problem, and make sure it is
+then that is also noted in order to track the problem, and made sure it is
 resolved before the package enters the archive.  These issues are marked with
 the <itp> tag.  Note this includes both ITPs and RFPs since (from a security
 tracking standpoint) there is no advantage in tracking them in separate ways.
@@ -281,7 +283,7 @@ An example entry for an ITP/RFP package is:
 ### Reserved entries
 
 Several security problems have coordinated dates of public disclosure,
-i.e. a CVE identifier has been assigned to a problem, but it's not
+i.e., a CVE identifier has been assigned to a problem, but it's not
 public yet. Also, several vendors have a pool of CVE ids they can
 assign to problems that are detected in their products. Such entries
 are marked as `RESERVED` in the tracker:
@@ -301,7 +303,7 @@ entries:
 ### Removed packages
 
 Sometimes there are cases, where a vulnerability hasn't been fixed with
-a code change, but simply by deciding that a package is that broken that
+a code change, but simply by deciding that a package is broken so severely that
 it needs to be removed from the archive entirely. This is tracked with
 the `<removed>` tag:
 
@@ -310,7 +312,7 @@ the `<removed>` tag:
 
 Also note that it is sufficient to mark a package as removed in unstable.
 The tracker is aware of which package is present in which distribution
-and marks other distributions that still contain the package automagically
+and marks other distributions that still contain the package automatically
 as unfixed.  For example, if libxml is in oldstable, but not stable or
 unstable, then:
 
@@ -319,16 +321,16 @@ unstable, then:
 will track oldstable as affected, but stable and unstable as `not-affected`.
 
 Once a package has been completely removed from all currently supported
-debian releases, it should be tracked in the `data/packages/removed-packages`
+Debian releases, it should be tracked in the `data/packages/removed-packages`
 file.  This file lists all packages (one source package per line) that were
-at one time in a debian release, but no longer exist in any supported
+at one time in a Debian release, but no longer exist in any supported
 version.  Additions to this file can be used to address failing consistency
 checks after a new release.
 
 ### end-of-life packages
 
-In some rare cases (i.e. webbrowsers) security support for some packages
-needed to be stopped before the end of the regular security maintenance
+In rare cases (i.e., webbrowsers) security support for packages
+needs to be stopped before the end of the regular security maintenance
 life cycle.
 
 Packages which are not anymore supported by the security team in a
@@ -351,8 +353,8 @@ descriptive so that it is clear what remains to be done. For example:
     CVE-2005-3990 (Directory traversal vulnerability in FastJar 0.93 allows remote ...)
             TODO: check, whether fastjar from the gcc source packages is affected
 
-If you are not sure about some decision (e.g. which package is affected) or
-triaging (e.g. bug severity) you can leave a TODO note for reviewing, 
+If you are not sure about some decision (e.g., which package is affected) or
+triaging (e.g., bug severity) you can leave a TODO note for reviewing, 
 explaining which aspect have to be reviewed. For example:
 
     CVE-2013-7295 (Tor before 0.2.4.20, when OpenSSL 1.x is used in ...)
@@ -380,7 +382,7 @@ These levels are mostly used to prioritize the order in which security
 problems are resolved. Anyway, we have a rough overview on how you should
 assess these levels. 
 
-**unimportant**: This problem does not affect the Debian binary package, e.g.
+**unimportant**: This problem does not affect the Debian binary package, e.g.,
              a vulnerable source file, which is not built, a vulnerable file
              in `doc/foo/examples/`, PHP Safe mode bugs, path disclosure (doesn't
              matter on Debian).
@@ -397,7 +399,7 @@ assess these levels.
 **medium** : For anything which permits code execution after user interaction.
              Local privilege escalation vulnerabilities are in this category as
              well, or remote privilege escalation if it's constrained to the
-             application (i.e. no shell access to the underlying system, such
+             application (i.e., no shell access to the underlying system, such
              as simple cross-site scripting). Most remote DoS vulnerabilities
              fall into this category, too.
 
@@ -420,14 +422,14 @@ their importance.
 
 ### Vulnerabilities without an assigned CVE id
 
-If you learn of a vulnerability to which has not been assigned a CVE id yet you request one.
+If you learn of a vulnerability to which no CVE id has been assigned yet, you can request one.
 To request a CVE for public issues, you can
-[write to the moderated oss-security list](http://people.redhat.com/kseifrie/CVE-OpenSource-Request-HOWTO.html#How%20to%20make%20a%20public%20request:).
+[write to the moderated oss-security list](https://github.com/RedHatProductSecurity/CVE-HOWTO).
 In the meantime, you can add an entry of the form
 
     CVE-2009-XXXX [optipng array overflow]
             - optipng 0.6.2.1-1 (low)
-            NOTE: http://secunia.com/advisories/34035/
+            NOTE: https://secunia.com/advisories/34035/
 
 It is desirable to include references
 which uniquely identify the issue, such as a permanent link to an
@@ -442,7 +444,7 @@ cross-referenced advisories nevertheless.
 CVE pool from Debian
 --------------------
 
-Debian can only assign CVE names from its own pool for issues which
+Debian can only assign CVE numbers from its own pool for issues which
 are not public.  To request a CVE from the Debian pool, write to
 <team@security.debian.org> and include a description which follows CVE
 conventions.
@@ -474,17 +476,18 @@ Generated Reports
 -----------------
 
 All of this tracking information gets automatically parsed and
-compared against madison to determine what has been fixed and what is
+compared against madison (a program which inspects a local Debian package archive and
+displays the versions of the given packages found in each suite) to determine what has been fixed and what is
 still waiting, this results in this website:
 
-[http://security-tracker.debian.org/](http://security-tracker.debian.org/)
+[https://security-tracker.debian.org/](https://security-tracker.debian.org/)
 
 It incorporates package lists and parses distribution lists and can
-thus be used to
+thus be used to:
 
 - Present the security history of a package
 - Provide overviews of vulnerable packages in stable, testing, sid and
-  oldstable (it still has some false positives, wrt packages in
+  oldstable (it still has some false positives; with respect to packages in
   stable that are present in stable, but not vulnerable, these need to
   be triaged individually).
 - Generate a list of packages that are subject to security problems, but
@@ -495,10 +498,10 @@ thus be used to
   be checked for security problems
 - Generate a list of provisional IDs that need to be turned into proper
   CVE entries
-- Show some potential problems in the data pool (e.g. misspelled package
+- Show some potential problems in the data pool (e.g., misspelled package
   names not found in the packages list, or potentially missing epochs)
 
-For every security problem it displays
+For every security problem it displays:
 
 - The CVE information
 - A severity assessment by NVD
@@ -507,7 +510,7 @@ For every security problem it displays
 - Additional notes from our tracker
 
 The DSA list (`DSA/list`)
------------------------
+-------------------------
 
 We maintain a list of all DSA advisories issued by the stable security
 team. This information is used to derive information about the state
@@ -520,15 +523,15 @@ entry for a DSA looks like this:
             [sarge] - unzip 5.52-1sarge2
             NOTE: fixed in testing at time of DSA
 
-The first line tracks the date, when a DSA was issued, the DSA
-identifier, the affected source package and the type of vulnerability.
+The first line tracks the date when a DSA was issued, the DSA
+identifier, the affected source package, and the type of vulnerability.
 The second line performs a cross-reference to the entry in `CVE/list`
 that maintains the state of the vulnerability in sid. Every entry that
 is added like this to `DSA/list` is parsed by a script and automatically
 added to `CVE/list`.  The next lines contain the fixes for stable and
 optionally oldstable, addressed with distribution tags.  You may add
 `NOTE:` entries freely, we use a `NOTE` entry for statistical purposes
-that tracks, when a fix has reached testing relative to the time when
+that tracks when a fix has reached testing relative to the time when
 it hit stable.
 
 There is no need to add anything to `CVE/list` for a DSA, the DSA
@@ -540,23 +543,23 @@ Checking in your changes
 ------------------------
 
 After thoroughly researching each issue (as described above) and editing
-the relevant files, commit your changes. Peer review is done via the 
-mailing list and IRC notifications (see "Automatic Issue Updates" above).
-However, changes to the tracker website itself (e.g. the files in lib/*
+the relevant files, commit your changes. Peer review is (hopefully) done via the 
+mailing list and IRC notifications (see [Automatic issue updates](#automatic-issue-updates) above).
+However, changes to the tracker website itself (e.g., the files in lib/*
 and bin/tracker_service.py) should be vetted and approved before being
-committed. The preferred way to do this is to send a patch to: 
+committed. The preferred way to do this is to send a patch to the
 debian-security-tracker@lists.debian.org mailing list.
 
 Commits are checked for syntax errors before they are actually committed,
 and you'll receive an error and your commit is aborted if it is in error.
-To check your changes yourself beforehand, use "make check-syntax" from
-the root of the svn directory.
+To check your changes yourself beforehand, use `make check-syntax` from
+the root of the SVN directory.
 
 Following up on security issues
 -------------------------------
 
 By simply loading this page and doing a little gardening of the
-different issues many things can be done. One thing is that you can
+different issues, many things can be done. One thing is that you can
 read all the bug reports of each issue and see if new information has
 been added to the end that might provide updated or changed
 information (such as if an issue has been closed, or a version of the
@@ -564,22 +567,22 @@ package has been uploaded that contains the fix). It is also useful to
 follow-up on the issues to prod the maintainer to deal with the issue,
 which they may have forgotten about.
 
-
 Tracking of security bugs in the BTS and linking them to a user tag by CVE
 --------------------------------------------------------------------------
 
 There's an automated tagging of security-related bugs to CVE IDs through
-the user tag security for the user debian-security@lists.debian.org
+the user tag security for the user debian-security@lists.debian.org.
 
 All bugs added to the tracker are automatically tagged. You can use
-the search [here](http://bugs.debian.org/cgi-bin/pkgreport.cgi?tag=security;users=debian-security@lists.debian.org;exclude=tracked)
+the search
+[here](https://bugs.debian.org/cgi-bin/pkgreport.cgi?tag=security;users=debian-security@lists.debian.org;exclude=tracked)
 to find all bugs not yet present in the tracker.
 
-All bug numbers added to the tracked are automatically associated
-to the relevant user tag.
+All bug numbers added to the tracker are automatically associated
+with the relevant user tag.
 
-If you checked an issue which doesn't need to be added to the tracked
-(e.g. because it's not security-relevant or otherwise bogus you can either
+If you checked an issue which doesn't need to be added to the tracker
+(e.g., because it's not security-relevant or otherwise bogus) you can either
 remove the security tag from the bugs or send a mail to control@bugs.debian.org
 with the following content:
 
@@ -588,8 +591,8 @@ with the following content:
 
 Contributing with the security tracker code
 -------------------------------------------
-**TODO**
 
+**TODO**
 
 Setting up a local testing instance
 -----------------------------------
@@ -608,4 +611,4 @@ The following commands build the databases for stable and run a python local ser
     make
     make serve
 
-The website is now available in `http://127.0.0.1:10605/tracker/`.
+The website is now available as `http://127.0.0.1:10605/tracker/`.