hansken-extraction-plugin-s…/0.9.16/dev/spec.html



<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="../">
<head>
  <meta charset="utf-8" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Extraction Plugin specifications &mdash; Hansken Extraction Plugins for plugin developers 0.9.16
 documentation</title>
      <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=d75fae25" />
      <link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=e59714d7" />
      <link rel="stylesheet" type="text/css" href="../_static/wider_pages.css?v=32ad70ab" />


      <script src="../_static/jquery.js?v=5d32c60e"></script>
      <script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
      <script src="../_static/documentation_options.js?v=433a2a34"></script>
      <script src="../_static/doctools.js?v=9a2dae69"></script>
      <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
    <script src="../_static/js/theme.js"></script>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="Java" href="java.html" />
    <link rel="prev" title="Kubernetes, Autoscaling, Resourcemanagement" href="concepts/kubernetes_autoscaling.html" />
</head>

<body class="wy-body-for-nav">
  <div class="wy-grid-for-nav">
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search" >


          <a href="../index.html" class="icon icon-home">
            Hansken Extraction Plugins for plugin developers
          </a>
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>
        </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
              <p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="introduction.html">Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="concepts.html">General concepts</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Extraction Plugin specifications</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#plugin-protocol">Plugin protocol</a></li>
<li class="toctree-l2"><a class="reference internal" href="#packaging">Packaging</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="java.html">Java</a></li>
<li class="toctree-l1"><a class="reference internal" href="python.html">Python</a></li>
<li class="toctree-l1"><a class="reference internal" href="examples.html">Examples</a></li>
<li class="toctree-l1"><a class="reference internal" href="faq.html">Frequently Asked Questions</a></li>
<li class="toctree-l1"><a class="reference internal" href="../contact.html">Contact</a></li>
<li class="toctree-l1"><a class="reference internal" href="../changes.html">Changelog</a></li>
</ul>

        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="../index.html">Hansken Extraction Plugins for plugin developers</a>
      </nav>

      <div class="wy-nav-content">
        <div class="rst-content">
          <div role="navigation" aria-label="Page navigation">
  <ul class="wy-breadcrumbs">
      <li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
      <li class="breadcrumb-item active">Extraction Plugin specifications</li>
      <li class="wy-breadcrumbs-aside">
            <a href="../_sources/dev/spec.md.txt" rel="nofollow"> View page source</a>
      </li>
  </ul>
  <hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">

  <section id="extraction-plugin-specifications">
<h1>Extraction Plugin specifications<a class="headerlink" href="#extraction-plugin-specifications" title="Link to this heading"></a></h1>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>If you use the Java or Python extraction plugin SDK, you don’t have
to worry about these specifications. The Java and Python SDKs makes
sure your plugin is compiled and packaged conform to the extraction
plugin specifications.</p>
</div>
<p>This page describes the specifications that define an extraction plugin.
The spec contains two major parts: a plugin protocol, and the plugin packaging
method.</p>
<p>This specification applies to plugins that are not embedded within Hansken,
but to plugins that developed and distributed outside the scope of the Hansken
platform development.</p>
<section id="plugin-protocol">
<h2>Plugin protocol<a class="headerlink" href="#plugin-protocol" title="Link to this heading"></a></h2>
<p>An extraction plugin is a process that implements a <a class="reference external" href="https://grpc.io/">GRPC</a>
service <code class="docutils literal notranslate"><span class="pre">ExtractionPluginService</span></code>. The service defines a protocol that is
used to allow communication between Hansken and an extraction plugin. The
GRPC and protocol definitions can be found in the extraction plugin source
code, under the folder <code class="docutils literal notranslate"><span class="pre">grpc</span></code>.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The source code of the Extraction Plugin is currently not available
outside the scope of the Hansken core development teams. If you are
interested in the GRPC definitions, please <a class="reference internal" href="../contact.html"><span class="doc">Contact</span></a> the
Hansken development team.</p>
</div>
</section>
<section id="packaging">
<h2>Packaging<a class="headerlink" href="#packaging" title="Link to this heading"></a></h2>
<p>An extraction plugin is packaged as a container image – conform the open
container initiative <a class="reference external" href="https://github.com/opencontainers/image-spec">image spec</a>.
An extraction plugin can be</p>
<p>The <code class="docutils literal notranslate"><span class="pre">ENTRYPOINT</span></code> of the container image should be a process that starts a GRPC
server that implements the plugin protocol. The GRPC protocol should run on port
<code class="docutils literal notranslate"><span class="pre">8999</span></code> by default. The plugin should always observe the <code class="docutils literal notranslate"><span class="pre">PLUGIN_PORT</span></code> environment
variable, and run on that port if set.</p>
<p>The container image should be labeled with the plugin info.
The plugin info returned by the plugin plugin-info call and container labels
are required to match. If not, Hansken will not accept your plugin during
extractions - as it is unsure if the intended plugin is processing traces.</p>
<p>The labels that are expected are:</p>
<ul>
<li><p><code class="docutils literal notranslate"><span class="pre">org.hansken.plugin-info.id</span></code> (conform <a class="reference internal" href="concepts/plugin_naming_convention.html"><span class="doc">Plugin naming convention</span></a>)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">org.hansken.plugin-info.version</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">org.hansken.plugin-info.api-version</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">org.hansken.plugin-info.description</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">org.hansken.plugin-info.webpage</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">org.hansken.plugin-info.deferred-iterations</span></code> (optional, only has a meaning for deferred extraction plugins)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">org.hansken.plugin-info.matcher</span></code> (see <a class="reference internal" href="concepts/hql_lite.html"><span class="doc">HQL-Lite</span></a>)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">org.hansken.plugin-info.license</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">org.hansken.plugin-info.author-name</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">org.hansken.plugin-info.author-organisation</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">org.hansken.plugin-info.author-email</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">org.hansken.plugin-info.resource-max_cpu</span></code> (in millicpu, optional)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">org.hansken.plugin-info.resource-max_mem</span></code> (in mbs, optional)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">org.hansken.plugin-info.bulk-mode</span></code> (optional, false by default)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">org.hansken.plugin-info.transformers</span></code> (the signatures of the transformer methods as JSON). The transformers field contains a JSON array and is structured as follows:</p>
<div class="highlight-json notranslate"><div class="highlight"><pre><span></span><span class="p">[</span>
<span class="w">    </span><span class="p">{</span><span class="nt">&quot;method_name&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;test_func&quot;</span><span class="p">,</span><span class="w"> </span><span class="nt">&quot;parameters&quot;</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="nt">&quot;arg_1&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;str&quot;</span><span class="p">,</span><span class="w"> </span><span class="nt">&quot;arg_2&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;str&quot;</span><span class="p">},</span><span class="w"> </span><span class="nt">&quot;return_type&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;vector&quot;</span><span class="p">}</span>
<span class="p">]</span>
</pre></div>
</div>
</li>
</ul>
</section>
</section>


           </div>
          </div>
          <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
        <a href="concepts/kubernetes_autoscaling.html" class="btn btn-neutral float-left" title="Kubernetes, Autoscaling, Resourcemanagement" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
        <a href="java.html" class="btn btn-neutral float-right" title="Java" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
    </div>

  <hr/>

  <div role="contentinfo">
    <p>&#169; Copyright 2020-2026 Netherlands Forensic Institute.</p>
  </div>

  Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
    <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
    provided by <a href="https://readthedocs.org">Read the Docs</a>.


</footer>
        </div>
      </div>
    </section>
  </div>
  <script>
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
      });
  </script>

</body>
</html>