PFS2

From MozillaWiki
Jump to: navigation, search

PFS2 is a simple HTTP service intended to:

  1. Assist in finding plugins for MIME types whose handling is unknown to the client
  2. Offer version and security vulnerability data on installed plugins for upgrade recommendations

Server

The server side of PFS2 maintains a database of plugins and plugin releases. These records are indexed by MIME type, and a set of client application details that help identify the most appropriate versions of plugins for a given platform, OS, locale, & etc.

Installation

  • Requirements
    • Apache
    • PHP 5.2+ (both web server and CLI)
    • MySQL 5.x
    • Memcached
  • Configure Apache's document root to point at htdocs
  • Create a MySQL database from schema
   mysqladmin -uroot -p create pfs2
   mysql -uroot -p pfs2 -e "grant all privileges on pfs2.* to pfs2@'localhost' identified by 'pfs2';"
   mysql -uroot -p pfs2 < conf/schema.sql
  • Update configuration
   cp conf/config.php-dist conf/config.php
   # edit the config file to reflect master and shadow databases, 
   # as well as memcache server
   vim conf/config.php 
  • Update database from plugin definitions
   php bin/update-db.php

Request Parameters

Queries against PFS2 are performed using HTTP GET, with the following parameters supported:

mimetype 
A space-separated list of mimetypes for a plugin. (Note: space can be encoded as + in URLs.)
clientOS 
The client's OS (eg. navigator.oscpu, "Windows NT 5.1", "Intel Mac OS X 10.5")
chromeLocale 
The client's locale (eg. navigator.language)
appID 
The client's app ID (eg. navigator.??? (userAgent?), Firefox is "{ec8030f7-c20a-464f-9b0e-13a3a9e97384}")
appRelease 
Client app release version (eg. navigator.??? (userAgent?), "3.5.3")
appVersion 
Client's application build version (eg. navigator.buildID, "20090824085414")
callback 
Function wrapper for JSON output, (see also: JSONP technique)

Example request

Line breaks added for clarity:

   curl -s 'http://dev.pfs2.mozilla.org/?
       mimetype=application/x-shockwave-flash&
       appID=%7Bec8030f7-c20a-464f-9b0e-13a3a9e97384%7D&
       appVersion=2008052906&
       appRelease=3.5&
       clientOS=mac&
       chromeLocale=ja-JP'

Response Format

The response MIME type for PFS2 is either application/json, or text/javascript if the callback parameter is non-empty.

The top-level JSON payload is an object pairing plugin identifiers (pfs_ids) each with an object describing a plugin's releases and known aliases. Note that the pfs_id values are unique only to PFS2, and simply serve as a way to organize plugins that may change names and other attributes between releases.

Overall structure

Plugin descriptions have the following overall structure:

   [
       {
           "aliases": {
               "literal": [ ... ],
               "regex": [ ... ]
           },
           "releases": {
               "latest": { ... },
               "others": [ ... ]
           }
       }
   ]

Plugin name aliases

The aliases property consists of lists of names by which the plugin has been called, separated into exact matches (literal) and regular expressions for pattern matches (regex). Since plugins change names between releases, and provide little else in the way of uniquely identifying details, these lists are meant to assist in identifying plugins already installed and matching them with PFS2 results.

For example:

   [
       {
           "aliases": [
               "literal": [
                   "Adobe Flash Player", 
                   "Shockwave Flash"
               ],
               "regex": [
                   ".*Flash.*"
               ]
           ],
           "releases": [ ... ]
       }
   ]

Plugin releases

The releases property points to an object, itself with two properties:

latest 
The latest release for the plugin known by PFS2
others 
A list of other outdated and vulnerable releases of the plugin

Plugin release descriptions

Each of the plugin releases are described by objects bearing some or all of the following properties:

pfs_id 
pfs_id of the plugin within PFS2
name 
Name of the plugin
vendor 
Name of the vendor providing the plugin
version 
A dot-separated normalized version for the plugin, may differ from official vendor versioning scheme in order to maintain internal consistency in PFS2
guid 
A GUID for the plugin release, may differ between releases and platforms (unlike pfs_id)
status 
Current status of the release, eg. latest, outdated, vulnerable
vulnerability_description 
For status vulnerable, a short description of security vulnerabilities for the plugin release
vulnerability_url 
For status vulnerable, a URL detailing security vulnerabilities for the plugin release
filename 
Filename of the plugin as installed
url 
URL with details describing the plugin
license_url 
URL where the license for using the plugin may be found
manual_installation_url 
URL for a manually-launched executable installer for the plugin
xpi_location 
URL for an XPI-based installer for the plugin
installer_location 
URL for an executable installer for the plugin (mainly for Windows)
installer_hash 
A hash of the installer's contents for verifying its integrity
installer_shows_ui 
(0/1) whether or not the installer displays a user interface
needs_restart 
(0/1) whether or not the OS needs to restart after plugin installation
xpcomabi 
(Not sure, inherited from PFS1, need a description)
min 
(Not sure, inherited from PFS1, need a description)
max 
(Not sure, inherited from PFS1, need a description)
app_release 
Client app release for which the plugin is intended (* is wildcard)
app_version 
Client app version for which the plugin is intended (* is wildcard)
locale 
Client app locale for which the plugin is intended (* is wildcard)
os_name 
Client app OS for which the plugin is intended (* is wildcard)
modified 
Timestamp when last the release record was modified

Example response

   $ curl -s 'http://dev.pfs2.mozilla.org/?mimetype=application/x-shockwave-flash&appID=%7Bec8030f7-c20a-464f-9b0e-13a3a9e97384%7D&appVersion=2008052906&appRelease=3.5&clientOS=mac&chromeLocale=ja-JP'
   
   [
       {
           "aliases": {
               "literal": [
                   "Adobe Flash Player", 
                   "Shockwave Flash"
               ],
               "regex": [
                   ".*Flash.*"
               ] 
           },
           "releases": {
               "latest": {
                   "status": "latest", 
                   "app_release": "3.5", 
                   "app_version": "*", 
                   "vendor": "Adobe", 
                   "pfs_id": "adobe-flash-player", 
                   "url": "http://www.adobe.com/go/getflashplayer", 
                   "modified": "2009-09-18T23:09:55+00:00", 
                   "app_id": "{ec8030f7-c20a-464f-9b0e-13a3a9e97384}", 
                   "locale": "ja-JP", 
                   "version": "11.0.0.0", 
                   "license_url": "http://www.adobe.com/go/eula_flashplayer_jp", 
                   "guid": "{89977581-9028-4be0-b151-7c4f9bcd3211}", 
                   "xpi_location": "http://fpdownload.macromedia.com/get/flashplayer/xpi/current/flashplayer-mac.xpi", 
                   "os_name": "mac", 
                   "name": "Adobe Flash Player"
               },
               "others": [
                   {
                       "status": "vulnerable", 
                       "app_release": "*", 
                       "os_name": "*", 
                       "vendor": "Adobe", 
                       "pfs_id": "adobe-flash-player", 
                       "url": "http://www.adobe.com/go/getflashplayer", 
                       "modified": "2009-09-18T23:09:55+00:00", 
                       "app_id": "{ec8030f7-c20a-464f-9b0e-13a3a9e97384}", 
                       "vulnerability_url": "http://www.adobe.com/support/security/bulletins/apsb09-10.html", 
                       "version": "9.0.159.0", 
                       "license_url": "http://www.adobe.com/go/eula_flashplayer", 
                       "locale": "*", 
                       "app_version": "*", 
                       "name": "Adobe Flash Player"
                   }, 
                   {
                       "status": "vulnerable", 
                       "app_release": "*", 
                       "os_name": "*", 
                       "vendor": "Adobe", 
                       "pfs_id": "adobe-flash-player", 
                       "url": "http://www.adobe.com/go/getflashplayer", 
                       "modified": "2009-09-18T23:09:55+00:00", 
                       "app_id": "{ec8030f7-c20a-464f-9b0e-13a3a9e97384}", 
                       "vulnerability_url": "http://documents.iss.net/whitepapers/IBM_X-Force_WP_final.pdf", 
                       "version": "9.0.115.0", 
                       "license_url": "http://www.adobe.com/go/eula_flashplayer", 
                       "locale": "*", 
                       "app_version": "*", 
                       "name": "Adobe Flash Player"
                   }
               ]
           }
       }
   ]

Client

Codebases

Perfidies is the PFS2 client. It will be usable for plugin page, web badges, etc.

PFS2 inputs

  • App ID is hardcoded in the JS. We'll update this script when a new appId is available. Firefox always uses the same app id and it won't change any time soon.
  • appID={ec8030f7-c20a-464f-9b0e-13a3a9e97384}
  • mimetype - navigator.plugins[x].type roughly
  • appVersion = navigator.buildid roughly
  • appRelease = navigator.appVersion roughly
  • clientOS = navigator.oscpu roughly
  • chromeLocale = navigator.language

Environments

General Algorithm

  1. Taking all the plugins in the browser
  2. For each Plugin
    1. Take all the mime-types in the plugin
    2. For each mime type
      1. Normalize the mime-type
      2. concatenate them into a space delimited list
      3. Query the Plugin Finder Service by mime-type and other parameters
        1. Take all the plugin infos which is the response
        2. For each info
          1. Try to match the alias literal `names` in the response to the plugins name
          2. Try to match the alisas regexs in the response to the plugins literal name
            1. if there is a match, use the info from this mime-type. Check version and vulnerability
            2. if all mime-types are exausted and no plugin name is matched, then this plugin is 'unknown', continue with next plugin

Matching info name to plugin name

This is a fragile piece of the algorithm. The PFS2 server has a 'name' field in the response. The client will try to match this against

  1. plugin.name

Quantity of calls per plugin

Some plugins like Quicktime register 76 plugins. We'll want to have them all in the DB, so the first call by mime-type matches.

The PFS2 Client limits on how many mime types will be concatentated together to keep the total characters below a configurable amount. If the mime-types exceed this, multiple PFS requests will be made for the plugin.

Mime-Type Normalization

Some Java Plugins like apples register many mime-types, because the mime-type includes platform version information like:

 application/x-java-applet;version=1.3
 application/x-java-applet;version=1.5

We can normalize these, since ; isn't a valid character in a MIME type.

Plugin Release Statuses

For a given app id, platform, etc a list of releases of plugins are returned. The following are the status states a plugin can be in

  1. DISABLE - "vulnerable" - also no newer release known
  2. VULNERABLE - "vulnerable" An exploit is published against this specific release number
  3. OUTDATED - "outdated" or version detection shows the plugin is known and older than a known plugin version
  4. CURRENT - "latest" exact match of the latest known release
  5. UNKNOWN - Either no plugin match was made, or the version of the plugin in the browser cannot be detected for some reason

We need to spec out the vulnerability mechanism

Generic Plugin Version Comparison

Current vs Out of date compares version components from left to right. Example: 5.10.3 compared to 5.11

  1. explode verison on '.'
  2. compare 5 to 5
  3. compare 10 to 11, 5.11 is higher

Unknown and Newer plugins

The client library will record unknown plugins by requesting a well known 1 pixel image and encode the plugin info into the request. These details can be harvested from web logs in a low tech way in bulk, at our leisure to discover popular plugins not in the DB.

Related Information