Revision 459409 of Plug-n-Hack Phase1

  • Revision slug: Plug-n-Hack/Plug-n-Hack_Phase1
  • Revision title: Plug-n-Hack Phase1
  • Revision id: 459409
  • Created:
  • Creator: psiinon
  • Is current revision? No
  • Comment Added manifest details c/o Mark Goodwin

Revision Content

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.

Security tool commands manifest

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

Firefox UI

In Firefox the tool commands will be made available via the Developer Toolbar (GCLI) https://developer.mozilla.org/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

Revision Source

<p>Plug-n-Hack (PnH) phase 1 allows easier integration and defines how security tools can advertise their capabilities to browsers.</p>
<h2>Security tool manifest</h2>
<p>To support PnH-1 security tools provide a manifest over HTTP(S) which defines the capabilities that the browser can make use of.<br />
  It is up to the tool authors to decide how the URL of the manifest is published.<br />
  <br />
  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:</p>
<pre>
var manifest = {"detail":{"url":"http://localhost:8080/manifest"}};
var evt = new CustomEvent('ConfigureSecTool', manifest);</pre>
<p>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.<br />
  <br />
  The Configuration Document should then listen for a number of other events:</p>
<ul>
  <li><strong>ConfigureSecToolStarted</strong> - 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).</li>
  <li><strong>ConfigureSecToolFailed</strong> - this notifies the document that configuration has failed for some reason. The user should be notified that configuration has failed.</li>
  <li><strong>ConfigureSecToolSucceeded</strong> - this notifies the document that configuration has succeeded. The user can be given a message to this effect.</li>
  <li><strong>ConfigureSecToolActivated</strong> - this notifies the document that PnH support (perhaps previously unavailable, e.g. due to a missing addon) has been enabled.</li>
</ul>
<p>You can see an <a href="http://www.google.com/url?q=https%3A%2F%2Fzap-extensions.googlecode.com%2Fsvn%2Fbranches%2Falpha%2Fsrc%2Forg%2Fzaproxy%2Fzap%2Fextension%2Fmitmconf%2Fresource%2Fwelcome.html" title="http://www.google.com/url?q=https%3A%2F%2Fzap-extensions.googlecode.com%2Fsvn%2Fbranches%2Falpha%2Fsrc%2Forg%2Fzaproxy%2Fzap%2Fextension%2Fmitmconf%2Fresource%2Fwelcome.html">example of a configuration document</a> in the ZAP PnH addon. There’s another (possibly out of date) example <a href="https://www.google.com/url?q=https%3A%2F%2Fgithub.com%2Fmozmark%2Fringleader%2Fblob%2Fmaster%2Fdoc%2Fprovider_sample.html&amp;sa=D&amp;sntz=1&amp;usg=AFQjCNEXjMFmiRdOMbldkgLUab3PJUdL4w" title="https://www.google.com/url?q=https%3A%2F%2Fgithub.com%2Fmozmark%2Fringleader%2Fblob%2Fmaster%2Fdoc%2Fprovider_sample.html&amp;sa=D&amp;sntz=1&amp;usg=AFQjCNEXjMFmiRdOMbldkgLUab3PJUdL4w">here</a>.<br />
  &nbsp;</p>
<p>An example manifest (for OWASP ZAP) is:</p>
<pre>
{

  "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/"

    }

  }

}</pre>
<p>The top level manifest includes optional links to a proxy PAC and a root CA certificate.</p>
<p>It also optionally links to another manifest which describes the commands the browser can invoke.</p>
<h2>Security tool commands manifest</h2>
<p>An example commands manifest (for OWASP ZAP) is: <a href="https://code.google.com/p/zap-extensions/source/browse/branches/alpha/src/org/zaproxy/zap/extension/mitmconf/resource/service.json" rel="nofollow">https://code.google.com/p/zap-extensions/source/browse/branches/alpha/src/org/zaproxy/zap/extension/mitmconf/resource/service.json</a></p>
<h2>Firefox UI</h2>
<p>In Firefox the tool commands will be made available via the Developer Toolbar (GCLI) <a href="https://developer.mozilla.org/en-US/docs/Tools/GCLI" rel="nofollow">https://developer.mozilla.org/en-US/docs/Tools/GCLI</a></p>
<p>A example of how the ZAP commands are currently displayed is:</p>
<p><img alt="" data-image-="" src="https://lh6.googleusercontent.com/Zfp0TAfswgxVDrm2Ex5i0tXmD3aPJW38WGZR-ViYHNd-UVmQ8no-hQlaSTSNXagMjQk_YFN0tEbPLf4tu2QS1KFrld89DiSjIRu7E9Y_3BTImlp05x-jVYPfgA" /></p>
<p>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.</p>
<p>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.</p>
<p>PnH does not specify how tool commands should be displayed, so other browsers are free to display them in different ways.</p>
<dl>
  <dt>
    Related links</dt>
  <dd>
    <a href="https://developer.mozilla.org/en-US/docs/Plug-n-Hack" title="/en-US/docs/Zest">Plug-n-Hack Overview</a></dd>
</dl>
Revert to this revision