Plug-n-Hack (PnH) phase 1 allows easier integration and defines how security tools can advertise their capabilities to browsers.

Security tool manifest

To support PnH-1 security tools provide a manifest over HTTP(S) which defines the capabilities that the browser can make use of.
It is up to the tool authors to decide how the URL of the manifest is published.

The tool configures itself by serving an HTML document (we’ll call this the Configuration Document) to the browser. This can cause the browser to inspect the manifest and register the tool by firing a CustomEvent with the type ConfigureSecTool and a properties object which specifies the URL of the tool manifest. For example:

var manifest = {"detail":{"url":"http://localhost:8080/manifest"}};
var evt = new CustomEvent('ConfigureSecTool', manifest);

It is suggested that browsers wishing to support PnH restrict handling of CustomEvents such that they’re ignored where the event happens outside of user initiated actions.

The Configuration Document should then listen for a number of other events:

• ConfigureSecToolStarted - this notifies the document that the browser is processing the configuration; if this event is not received within a reasonable amount of time after the ConfigureSecTool event has been fired, you might want to warn the user that PnH does not seem to be supported by this browser (perhaps prompting them to install the appropriate addon).
• ConfigureSecToolFailed - this notifies the document that configuration has failed for some reason. The user should be notified that configuration has failed.
• ConfigureSecToolSucceeded - this notifies the document that configuration has succeeded. The user can be given a message to this effect.
• ConfigureSecToolActivated - this notifies the document that PnH support (perhaps previously unavailable, e.g. due to a missing addon) has been enabled.

You can see an example of a configuration document in the ZAP PnH addon. There’s another (possibly out of date) example here.
 

An example manifest (for OWASP ZAP) is:

{
  "toolName":"OWASP ZAP",
  "protocolVersion":"0.2",
  "features":{
    "proxy":{
      "PAC":"http://localhost:8080/proxy.pac",
      "CACert":"http://localhost:8080/OTHER/core/other/rootcert/"
    },
    "commands":{
      "prefix":"zap",
      "manifest":"http://localhost:8080/OTHER/mitm/other/service/"
    }
  }
}

The top level manifest includes optional links to a proxy PAC and a root CA certificate.

It also optionally links to another manifest which describes the commands the browser can invoke.

Serving manifests from outside of your tool

You may want to serve manifests from a separate webserver (e.g. for testing); Plug-n-hack requires tool and service manifests to be served from the same origin as the API endpoints but, for testing purposes, Ringleader (the Firefox addon implementation of the browser component) allows you to set a preference to relax or disable origin checks. The preference is

ringleader.check.origin

This can be set to 'off' to disble origin checks completely, or 'noport' to disable only port checks.

Security tool commands manifest

An example commands manifest (for OWASP ZAP) is: https://code.google.com/p/zap-extensions/source/browse/branches/beta/src/org/zaproxy/zap/extension/plugnhack/resource/service.json

Firefox UI

In Firefox the tool commands will be made available via the Developer Toolbar (GCLI) /en-US/docs/Tools/GCLI

A example of how the ZAP commands are currently displayed is:

Note that user specified parameters can be specified for commands, which can either be free text, a static pull down list of options or a dynamic list of options obtained from the tool on demand.

So if you select the “zap scan” command then you will be prompted to select a site from the list of sites currently known to ZAP.

PnH does not specify how tool commands should be displayed, so other browsers are free to display them in different ways.

Related links

Plug-n-Hack Overview