[SafeBrowsing] Clarify `danger_level` in safe_browsing/README.md

chrome/browser/resources/safe_browsing/README.md

Index: chrome/browser/resources/safe_browsing/README.md
diff --git a/chrome/browser/resources/safe_browsing/README.md b/chrome/browser/resources/safe_browsing/README.md
index d61aafff67c4d23b8dea5dddb84a0be33e5b5ccf..4e529739d691d740ab104172612555b8e9c861e8 100644
--- a/chrome/browser/resources/safe_browsing/README.md
+++ b/chrome/browser/resources/safe_browsing/README.md
@@ -65,16 +65,28 @@ See `download_file_types.proto` for all fields.
 
        3. The `default_file_type`'s settings will be filled in.
 
-  * `platform_settings.danger_level`: (required)
+  * `platform_settings.danger_level`: (required) Controls how files should be
+    handled by the UI in the absence of a better signal from the Safe Browsing
+    ping. This applies to all file types where `ping_setting` is either
+    `SAMPLED_PING` or `NO_PING`, or downloads where the Safe Browsing ping

[Nathan Parker, 2016/06/17 21:44:01]

and downloads

[asanka, 2016/06/21 16:58:48]

Done.

+    either fails or returns an `UNKNOWN` verdict. Exceptions are noted.

[Nathan Parker, 2016/06/17 21:44:01]

either fails, is disabled, or returns...

How about adding something like:

The warning controlled here is a generic "this file type may harm your
computer."  If the Safe Browsing verdict is UNWANTED or MALWARE, Chrome will
show that more severe warning regardless of this setting.

(This is hard to describe succinctly!)

[asanka, 2016/06/21 16:58:48]

Done and done. :)

     * `NOT_DANGEROUS`: Safe to download and open, even if the download
-       was accidental.
+       was accidental. No additional warnings are necessary.
     * `DANGEROUS`: Always warn the user that this file may harm their
       computer. We let them continue or discard the file. If Safe
-      Browsing returns a SAFE verdict, we still warn the user.
-    * `ALLOW_ON_USER_GESTURE`: Warn the user normally but skip the warning
-      if there was a user gesture or the user visited this site before
-      midnight last night (i.e. is a repeat visit). If Safe Browsing
-      returns a SAFE verdict for this file, it won't show a warning.
+      Browsing returns a `SAFE` verdict, we still warn the user.

[Nathan Parker, 2016/06/17 21:44:01]

(We should probably remove this logic once the backend can mark them UNKNOWN
reliably... this sort of mucks up the layering of decisions).

[asanka, 2016/06/21 16:58:48]

Acknowledged.

+    * `ALLOW_ON_USER_GESTURE`: Potentially dangerous, but is likely harmless if
+      the user is familiar with host and if the download was intentional. Chrome
+      doesn't warn the user if both of the following conditions are true:
+
+        * There is a user gesture associated with the network request that
+          initiated the download.
+        * There is a recorded visit to the referring origin that's older than
+          the most recent midnight. This is taken to imply that the user has a
+          history of visiting the site.
+
+      In addition, Chrome skips the warning if the download was explicit (i.e.
+      the user selected "Save link as ..." from the context menu).
 
   * `platform_settings.auto_open_hint`: (required).
     * `ALLOW_AUTO_OPEN`: File type can be opened automatically if the user