Security/Features/Application Reputation Design Doc

Goal

Document application reputation implementation decisions so that other people than the author can debug it.

Background

Google has offered an application reputation feature to detect malicious downloads as part of Google Safe Browsing since 2012 [1]. Although this part of the Safe Browsing API is not documented, they have offered it to us for use in Firefox. Malicious download detection is separate from detection of phishing and malware pages, though both features use some of the same mechanisms.

This document attempts to document all of the things that Google Chrome does, so that even in the absence of official API documentation from Google, we collectively have a better chance of implementing this feature correctly.

High-level overview

The user-agent performs local lookups whenever a binary file is downloaded. If a local result is not found, the user-agent may perform a remote-lookup on Windows only. The bulk of Chrome's implementation is found in DownloadProtectionService [2].

When a binary file is downloaded, the user-agent extracts several pieces of metadata about the file, including:

1. The target URL from which the file was downloaded, its referrer URL and any URLs in the redirect chain.
2. The SHA-256 hash of the contents of the file.
3. Any certificate verification information obtained through the Windows Authenticode APIs.
4. The length of the file in bytes.
5. The suggested filename for the download.

Using this metadata, the user-agent performs a local lookups against a blocklist. In Chrome, this happens in DownloadProtectionService::CheckDownloadUrl [3]. If no match is found, the user-agent checks whether the binary is supported. In Chrome, the entry point is in DownloadProtectionService::CheckClientDownloadRequest [4]. If the download is supported, it checks an allowlist. In Chrome, these checks happen in CheckClientDownloadRequest::CheckWhitelists [5]. If the binary is signed, then the code signing information is checked against the allowlist. In Chrome, these checks begin inside CheckWhitelists [6].

If any blocklist matches are found, the user-agent must not save the file to disk. If any allowlist matches are found, the user-agent may treat the binary as trusted and skip the remote lookup. If no matches are found and the binary was unsigned or signature extraction completed successfully (on Windows only), the user-agent may send a remote lookup to the application reputation service.

Metadata extraction

In Firefox, SHA-256 hash computation is performed in BackgroundFileSaver via DigestOutputStream as the temporary file is written to disk [7]. After the download is complete, BackgroundFileSaver computes the signature verification of the downloaded file in ExtractSignatureInfo on Windows only [8]. Both of these operations happen on a worker thread.

Extraction of the redirect chain will hopefully happen via exposing mRedirectedCacheKeys from HttpBaseChannel.

Local lists

Application reputation requres two lists, goog-badbinurl-shavar for blocklisting and goog-downloadwhite-digest256 for allowlisting. Both of these lists are updated in the same way as existing Safe Browsing lists [9]. The shavar list is an existing format. The digest256 list is similar to shavar, except that all of its entries are the full 256-bit hash. Lookups based on increasing-sized fragments of the URL happen in exactly the same way.

The Chrome implementation for the digest256 list can be found in SafeBrowsingProtocolParser [10]. The Firefox implementation for the digest256 list may be found in ProtocolParser [11].

Local lookups

URL-based lookups for the target URL and its redirect chain happen in the same way for published Safe Browsing API. For certificate information lookups, the user-agent generates URLs based on signing information and looks up the resulting URL and its fragments in the same way.

A binary may be signed by multiple certificates. Each certificate may be part of a certificate chain, where the previous link in the chain is the issuer of the current certificate, all the way to the root certificate. Certificate chain information is extracted by the WinVerifyTrust and WTHelperProvDataFromStateData Windows API functions. In Chrome, this implementation is in SignatureUtil [12]. In Firefox, this implementation is in BackgroundFileSaver.

For each certificate chain, let CN be the common name of the signer (the first certificate of the chain), O be the organization name of the signer, and OU the organization unit of the signer. For each issuer in the certificate chain starting with the issuer of the signer, construct a whitelist string of the form:

sb-ssl.google.com/safebrowsing/csd/certificate/<issuer_fingerprint[/CN=<common_name][/O=<organization_name>][OU=<organization_unit>]

Thus every for every certificate chain of length n, n-1 whitelist strings are constructed. In Chrome, certificate whitelist strings are constructed in CertificateChainIsWhitelisted [13].

Remote lookup

The user-agent stuffs all file metadata into a ClientDownloadRequest protocol buffer and sends it to the remote service. If a MALWARE verdict is received, the downloaded file should not be saved and the UI should report that the download may be malware. In Chrome, this occurs in CheckClientDownloadRequest::SendRequest [14]. In Firefox, this happens in ApplicationReputation::PendingLookup::SendRemoteQuery [15] and in the JS DownloadIntegration.shouldBlockForApplicationReputation [16].

Preliminary results

How do we know if it works? See Security/Features/Application_Reputation_Preliminary_Results for preliminary results.