misp-modules/contribute/index.html

1010 lines
44 KiB
HTML
Raw Normal View History

<!doctype html>
<html lang="en" class="no-js">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="description" content="MISP Modules Project">
<meta name="author" content="MISP Project">
<link rel="canonical" href="https://www.misp-project.org/contribute/">
<link rel="prev" href="../install/">
<link rel="next" href="../license/">
<link rel="icon" href="../img/favicon.ico">
<meta name="generator" content="mkdocs-1.4.2, mkdocs-material-9.0.0">
<title>Contribute - MISP Modules Documentation</title>
<link rel="stylesheet" href="../assets/stylesheets/main.f79797b0.min.css">
<link rel="stylesheet" href="../assets/stylesheets/palette.2505c338.min.css">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,300i,400,400i,700,700i%7CRoboto+Mono:400,400i,700,700i&display=fallback">
<style>:root{--md-text-font:"Roboto";--md-code-font:"Roboto Mono"}</style>
<script>__md_scope=new URL("..",location),__md_hash=e=>[...e].reduce((e,_)=>(e<<5)-e+_.charCodeAt(0),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
</head>
<body dir="ltr" data-md-color-scheme="default" data-md-color-primary="white" data-md-color-accent="blue">
<input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
<input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
<label class="md-overlay" for="__drawer"></label>
<div data-md-component="skip">
<a href="#how-to-add-your-own-misp-modules" class="md-skip">
Skip to content
</a>
</div>
<div data-md-component="announce">
</div>
<header class="md-header" data-md-component="header">
<nav class="md-header__inner md-grid" aria-label="Header">
<a href=".." title="MISP Modules Documentation" class="md-header__button md-logo" aria-label="MISP Modules Documentation" data-md-component="logo">
<img src="../img/misp.png" alt="logo">
</a>
<label class="md-header__button md-icon" for="__drawer">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3V6m0 5h18v2H3v-2m0 5h18v2H3v-2Z"/></svg>
</label>
<div class="md-header__title" data-md-component="header-title">
<div class="md-header__ellipsis">
<div class="md-header__topic">
<span class="md-ellipsis">
MISP Modules Documentation
</span>
</div>
<div class="md-header__topic" data-md-component="header-topic">
<span class="md-ellipsis">
Contribute
</span>
</div>
</div>
</div>
<label class="md-header__button md-icon" for="__search">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.516 6.516 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5Z"/></svg>
</label>
<div class="md-search" data-md-component="search" role="dialog">
<label class="md-search__overlay" for="__search"></label>
<div class="md-search__inner" role="search">
<form class="md-search__form" name="search">
<input type="text" class="md-search__input" name="query" aria-label="Search" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" required>
<label class="md-search__icon md-icon" for="__search">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.516 6.516 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5Z"/></svg>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11h12Z"/></svg>
</label>
<nav class="md-search__options" aria-label="Search">
<button type="reset" class="md-search__icon md-icon" title="Clear" aria-label="Clear" tabindex="-1">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12 19 6.41Z"/></svg>
</button>
</nav>
</form>
<div class="md-search__output">
<div class="md-search__scrollwrap" data-md-scrollfix>
<div class="md-search-result" data-md-component="search-result">
<div class="md-search-result__meta">
Initializing search
</div>
<ol class="md-search-result__list"></ol>
</div>
</div>
</div>
</div>
</div>
<div class="md-header__source">
<a href="https://github.com/MISP/misp-modules/" title="Go to repository" class="md-source" data-md-component="source">
<div class="md-source__icon md-icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Free 6.2.1 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc.--><path d="M439.55 236.05 244 40.45a28.87 28.87 0 0 0-40.81 0l-40.66 40.63 51.52 51.52c27.06-9.14 52.68 16.77 43.39 43.68l49.66 49.66c34.23-11.8 61.18 31 35.47 56.69-26.49 26.49-70.21-2.87-56-37.34L240.22 199v121.85c25.3 12.54 22.26 41.85 9.08 55a34.34 34.34 0 0 1-48.55 0c-17.57-17.6-11.07-46.91 11.25-56v-123c-20.8-8.51-24.6-30.74-18.64-45L142.57 101 8.45 235.14a28.86 28.86 0 0 0 0 40.81l195.61 195.6a28.86 28.86 0 0 0 40.8 0l194.69-194.69a28.86 28.86 0 0 0 0-40.81z"/></svg>
</div>
<div class="md-source__repository">
MISP/misp-modules
</div>
</a>
</div>
</nav>
</header>
<div class="md-container" data-md-component="container">
<main class="md-main" data-md-component="main">
<div class="md-main__inner md-grid">
<div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" >
<div class="md-sidebar__scrollwrap">
<div class="md-sidebar__inner">
<nav class="md-nav md-nav--primary" aria-label="Navigation" data-md-level="0">
<label class="md-nav__title" for="__drawer">
<a href=".." title="MISP Modules Documentation" class="md-nav__button md-logo" aria-label="MISP Modules Documentation" data-md-component="logo">
<img src="../img/misp.png" alt="logo">
</a>
MISP Modules Documentation
</label>
<div class="md-nav__source">
<a href="https://github.com/MISP/misp-modules/" title="Go to repository" class="md-source" data-md-component="source">
<div class="md-source__icon md-icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Free 6.2.1 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc.--><path d="M439.55 236.05 244 40.45a28.87 28.87 0 0 0-40.81 0l-40.66 40.63 51.52 51.52c27.06-9.14 52.68 16.77 43.39 43.68l49.66 49.66c34.23-11.8 61.18 31 35.47 56.69-26.49 26.49-70.21-2.87-56-37.34L240.22 199v121.85c25.3 12.54 22.26 41.85 9.08 55a34.34 34.34 0 0 1-48.55 0c-17.57-17.6-11.07-46.91 11.25-56v-123c-20.8-8.51-24.6-30.74-18.64-45L142.57 101 8.45 235.14a28.86 28.86 0 0 0 0 40.81l195.61 195.6a28.86 28.86 0 0 0 40.8 0l194.69-194.69a28.86 28.86 0 0 0 0-40.81z"/></svg>
</div>
<div class="md-source__repository">
MISP/misp-modules
</div>
</a>
</div>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href=".." class="md-nav__link">
Home
</a>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle" data-md-toggle="__nav_2" type="checkbox" id="__nav_2" >
<label class="md-nav__link" for="__nav_2">
Modules
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" aria-label="Modules" data-md-level="1">
<label class="md-nav__title" for="__nav_2">
<span class="md-nav__icon md-icon"></span>
Modules
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../expansion/" class="md-nav__link">
Expansion Modules
</a>
</li>
<li class="md-nav__item">
<a href="../export_mod/" class="md-nav__link">
Export Modules
</a>
</li>
<li class="md-nav__item">
<a href="../import_mod/" class="md-nav__link">
Import Modules
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="../install/" class="md-nav__link">
Install Guides
</a>
</li>
<li class="md-nav__item md-nav__item--active">
<input class="md-nav__toggle md-toggle" data-md-toggle="toc" type="checkbox" id="__toc">
<label class="md-nav__link md-nav__link--active" for="__toc">
Contribute
<span class="md-nav__icon md-icon"></span>
</label>
<a href="./" class="md-nav__link md-nav__link--active">
Contribute
</a>
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
<label class="md-nav__title" for="__toc">
<span class="md-nav__icon md-icon"></span>
Table of contents
</label>
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item">
<a href="#how-to-add-your-own-misp-modules" class="md-nav__link">
How to add your own MISP modules?
</a>
<nav class="md-nav" aria-label="How to add your own MISP modules?">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#introspection" class="md-nav__link">
introspection
</a>
</li>
<li class="md-nav__item">
<a href="#version" class="md-nav__link">
version
</a>
</li>
<li class="md-nav__item">
<a href="#additional-configuration-values" class="md-nav__link">
Additional Configuration Values
</a>
</li>
<li class="md-nav__item">
<a href="#handler" class="md-nav__link">
handler
</a>
<nav class="md-nav" aria-label="handler">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#export-module" class="md-nav__link">
export module
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#module-type" class="md-nav__link">
Module type
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#testing-your-modules" class="md-nav__link">
Testing your modules?
</a>
<nav class="md-nav" aria-label="Testing your modules?">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#enable-your-module-in-the-web-interface" class="md-nav__link">
Enable your module in the web interface
</a>
</li>
<li class="md-nav__item">
<a href="#set-any-other-required-settings-for-your-module" class="md-nav__link">
Set any other required settings for your module
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#documentation" class="md-nav__link">
Documentation
</a>
</li>
<li class="md-nav__item">
<a href="#tips-for-developers-creating-modules" class="md-nav__link">
Tips for developers creating modules
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle" data-md-toggle="__nav_5" type="checkbox" id="__nav_5" >
<label class="md-nav__link" for="__nav_5">
About
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" aria-label="About" data-md-level="1">
<label class="md-nav__title" for="__nav_5">
<span class="md-nav__icon md-icon"></span>
About
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../license/" class="md-nav__link">
License
</a>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</div>
</div>
</div>
<div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" >
<div class="md-sidebar__scrollwrap">
<div class="md-sidebar__inner">
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
<label class="md-nav__title" for="__toc">
<span class="md-nav__icon md-icon"></span>
Table of contents
</label>
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item">
<a href="#how-to-add-your-own-misp-modules" class="md-nav__link">
How to add your own MISP modules?
</a>
<nav class="md-nav" aria-label="How to add your own MISP modules?">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#introspection" class="md-nav__link">
introspection
</a>
</li>
<li class="md-nav__item">
<a href="#version" class="md-nav__link">
version
</a>
</li>
<li class="md-nav__item">
<a href="#additional-configuration-values" class="md-nav__link">
Additional Configuration Values
</a>
</li>
<li class="md-nav__item">
<a href="#handler" class="md-nav__link">
handler
</a>
<nav class="md-nav" aria-label="handler">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#export-module" class="md-nav__link">
export module
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#module-type" class="md-nav__link">
Module type
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#testing-your-modules" class="md-nav__link">
Testing your modules?
</a>
<nav class="md-nav" aria-label="Testing your modules?">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#enable-your-module-in-the-web-interface" class="md-nav__link">
Enable your module in the web interface
</a>
</li>
<li class="md-nav__item">
<a href="#set-any-other-required-settings-for-your-module" class="md-nav__link">
Set any other required settings for your module
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#documentation" class="md-nav__link">
Documentation
</a>
</li>
<li class="md-nav__item">
<a href="#tips-for-developers-creating-modules" class="md-nav__link">
Tips for developers creating modules
</a>
</li>
</ul>
</nav>
</div>
</div>
</div>
<div class="md-content" data-md-component="content">
<article class="md-content__inner md-typeset">
<h1>Contribute</h1>
<h2 id="how-to-add-your-own-misp-modules">How to add your own MISP modules?<a class="headerlink" href="#how-to-add-your-own-misp-modules" title="Permanent link">&para;</a></h2>
<p>Create your module in <a href="https://github.com/MISP/misp-modules/tree/master/misp_modules/modules/expansion/">misp_modules/modules/expansion/</a>, <a href="https://github.com/MISP/misp-modules/tree/master/misp_modules/modules/export_mod/">misp_modules/modules/export_mod/</a>, or <a href="https://github.com/MISP/misp-modules/tree/master/misp_modules/modules/import_mod/">misp_modules/modules/import_mod/</a>. The module should have at minimum three functions:</p>
<ul>
<li><strong>introspection</strong> function that returns a dict of the supported attributes (input and output) by your expansion module.</li>
<li><strong>handler</strong> function which accepts a JSON document to expand the values and return a dictionary of the expanded values.</li>
<li><strong>version</strong> function that returns a dict with the version and the associated meta-data including potential configurations required of the module.</li>
</ul>
<p>Don't forget to return an error key and value if an error is raised to propagate it to the MISP user-interface.</p>
<p>Your module's script name should also be added in the <code>__all__</code> list of <code>&lt;module type folder&gt;/__init__.py</code> in order for it to be loaded.</p>
<div class="highlight"><pre><span></span><code><span class="o">...</span>
<span class="c1"># Checking for required value</span>
<span class="k">if</span> <span class="ow">not</span> <span class="n">request</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;ip-src&#39;</span><span class="p">):</span>
<span class="c1"># Return an error message</span>
<span class="k">return</span> <span class="p">{</span><span class="s1">&#39;error&#39;</span><span class="p">:</span> <span class="s2">&quot;A source IP is required&quot;</span><span class="p">}</span>
<span class="o">...</span>
</code></pre></div>
<h3 id="introspection">introspection<a class="headerlink" href="#introspection" title="Permanent link">&para;</a></h3>
<p>The function that returns a dict of the supported attributes (input and output) by your expansion module.</p>
<div class="highlight"><pre><span></span><code><span class="n">mispattributes</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;input&#39;</span><span class="p">:</span> <span class="p">[</span><span class="s1">&#39;link&#39;</span><span class="p">,</span> <span class="s1">&#39;url&#39;</span><span class="p">],</span>
<span class="s1">&#39;output&#39;</span><span class="p">:</span> <span class="p">[</span><span class="s1">&#39;attachment&#39;</span><span class="p">,</span> <span class="s1">&#39;malware-sample&#39;</span><span class="p">]}</span>
<span class="k">def</span> <span class="nf">introspection</span><span class="p">():</span>
<span class="k">return</span> <span class="n">mispattributes</span>
</code></pre></div>
<h3 id="version">version<a class="headerlink" href="#version" title="Permanent link">&para;</a></h3>
<p>The function that returns a dict with the version and the associated meta-data including potential configurations required of the module.</p>
<h3 id="additional-configuration-values">Additional Configuration Values<a class="headerlink" href="#additional-configuration-values" title="Permanent link">&para;</a></h3>
<p>If your module requires additional configuration (to be exposed via the MISP user-interface), you can define those in the moduleconfig value returned by the version function.</p>
<div class="highlight"><pre><span></span><code><span class="c1"># config fields that your code expects from the site admin</span>
<span class="n">moduleconfig</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;apikey&quot;</span><span class="p">,</span> <span class="s2">&quot;event_limit&quot;</span><span class="p">]</span>
<span class="k">def</span> <span class="nf">version</span><span class="p">():</span>
<span class="n">moduleinfo</span><span class="p">[</span><span class="s1">&#39;config&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="n">moduleconfig</span>
<span class="k">return</span> <span class="n">moduleinfo</span>
</code></pre></div>
<p>When you do this a config array is added to the meta-data output containing all the potential configuration values:</p>
<div class="highlight"><pre><span></span><code>&quot;meta&quot;: {
&quot;description&quot;: &quot;PassiveTotal expansion service to expand values with multiple Passive DNS sources&quot;,
&quot;config&quot;: [
&quot;username&quot;,
&quot;password&quot;
],
&quot;module-type&quot;: [
&quot;expansion&quot;,
&quot;hover&quot;
],
...
</code></pre></div>
<p>If you want to use the configuration values set in the web interface they are stored in the key <code>config</code> in the JSON object passed to the handler.</p>
<div class="highlight"><pre><span></span><code>def handler(q=False):
# Check if we were given a configuration
config = q.get(&quot;config&quot;, {})
# Find out if there is a username field
username = config.get(&quot;username&quot;, None)
</code></pre></div>
<h3 id="handler">handler<a class="headerlink" href="#handler" title="Permanent link">&para;</a></h3>
<p>The function which accepts a JSON document to expand the values and return a dictionary of the expanded values.</p>
<div class="highlight"><pre><span></span><code><span class="k">def</span> <span class="nf">handler</span><span class="p">(</span><span class="n">q</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>
<span class="s2">&quot;Fully functional rot-13 encoder&quot;</span>
<span class="k">if</span> <span class="n">q</span> <span class="ow">is</span> <span class="kc">False</span><span class="p">:</span>
<span class="k">return</span> <span class="kc">False</span>
<span class="n">request</span> <span class="o">=</span> <span class="n">json</span><span class="o">.</span><span class="n">loads</span><span class="p">(</span><span class="n">q</span><span class="p">)</span>
<span class="n">src</span> <span class="o">=</span> <span class="n">request</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;ip-src&#39;</span><span class="p">)</span>
<span class="k">if</span> <span class="n">src</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
<span class="c1"># Return an error message</span>
<span class="k">return</span> <span class="p">{</span><span class="s1">&#39;error&#39;</span><span class="p">:</span> <span class="s2">&quot;A source IP is required&quot;</span><span class="p">}</span>
<span class="k">else</span><span class="p">:</span>
<span class="k">return</span> <span class="p">{</span><span class="s1">&#39;results&#39;</span><span class="p">:</span>
<span class="n">codecs</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="n">src</span><span class="p">,</span> <span class="s2">&quot;rot-13&quot;</span><span class="p">)}</span>
</code></pre></div>
<h4 id="export-module">export module<a class="headerlink" href="#export-module" title="Permanent link">&para;</a></h4>
<p>For an export module, the <code>request["data"]</code> object corresponds to a list of events (dictionaries) to handle.</p>
<p>Iterating over events attributes is performed using their <code>Attribute</code> key.</p>
<div class="highlight"><pre><span></span><code><span class="o">...</span>
<span class="k">for</span> <span class="n">event</span> <span class="ow">in</span> <span class="n">request</span><span class="p">[</span><span class="s2">&quot;data&quot;</span><span class="p">]:</span>
<span class="k">for</span> <span class="n">attribute</span> <span class="ow">in</span> <span class="n">event</span><span class="p">[</span><span class="s2">&quot;Attribute&quot;</span><span class="p">]:</span>
<span class="c1"># do stuff w/ attribute[&#39;type&#39;], attribute[&#39;value&#39;], ...</span>
<span class="o">...</span>
<span class="c1">### Returning Binary Data</span>
<span class="n">If</span> <span class="n">you</span> <span class="n">want</span> <span class="n">to</span> <span class="k">return</span> <span class="n">a</span> <span class="n">file</span> <span class="ow">or</span> <span class="n">other</span> <span class="n">data</span> <span class="n">you</span> <span class="n">need</span> <span class="n">to</span> <span class="n">add</span> <span class="n">a</span> <span class="n">data</span> <span class="n">attribute</span><span class="o">.</span>
<span class="o">~~~</span><span class="n">python</span>
<span class="p">{</span><span class="s2">&quot;results&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;values&quot;</span><span class="p">:</span> <span class="s2">&quot;filename.txt&quot;</span><span class="p">,</span>
<span class="s2">&quot;types&quot;</span><span class="p">:</span> <span class="s2">&quot;attachment&quot;</span><span class="p">,</span>
<span class="s2">&quot;data&quot;</span> <span class="p">:</span> <span class="n">base64</span><span class="o">.</span><span class="n">b64encode</span><span class="p">(</span><span class="o">&lt;</span><span class="n">ByteIO</span><span class="o">&gt;</span><span class="p">)</span> <span class="c1"># base64 encode your data first</span>
<span class="s2">&quot;comment&quot;</span><span class="p">:</span> <span class="s2">&quot;This is an attachment&quot;</span><span class="p">}}</span>
</code></pre></div>
<p>If the binary file is malware you can use 'malware-sample' as the type. If you do this the malware sample will be automatically zipped and password protected ('infected') after being uploaded.</p>
<div class="highlight"><pre><span></span><code><span class="p">{</span><span class="s2">&quot;results&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;values&quot;</span><span class="p">:</span> <span class="s2">&quot;filename.txt&quot;</span><span class="p">,</span>
<span class="s2">&quot;types&quot;</span><span class="p">:</span> <span class="s2">&quot;malware-sample&quot;</span><span class="p">,</span>
<span class="s2">&quot;data&quot;</span> <span class="p">:</span> <span class="n">base64</span><span class="o">.</span><span class="n">b64encode</span><span class="p">(</span><span class="o">&lt;</span><span class="n">ByteIO</span><span class="o">&gt;</span><span class="p">)</span> <span class="c1"># base64 encode your data first</span>
<span class="s2">&quot;comment&quot;</span><span class="p">:</span> <span class="s2">&quot;This is an attachment&quot;</span><span class="p">}}</span>
</code></pre></div>
<p><a href="https://github.com/MISP/PyMISP/blob/4f230c9299ad9d2d1c851148c629b61a94f3f117/pymisp/mispevent.py#L185-L200">To learn more about how data attributes are processed you can read the processing code here.</a></p>
<h3 id="module-type">Module type<a class="headerlink" href="#module-type" title="Permanent link">&para;</a></h3>
<p>A MISP module can be of four types:</p>
<ul>
<li><strong>expansion</strong> - service related to an attribute that can be used to extend and update an existing event.</li>
<li><strong>hover</strong> - service related to an attribute to provide additional information to the users without updating the event.</li>
<li><strong>import</strong> - service related to importing and parsing an external object that can be used to extend an existing event.</li>
<li><strong>export</strong> - service related to exporting an object, event, or data.</li>
</ul>
<p>module-type is an array where the list of supported types can be added.</p>
<h2 id="testing-your-modules">Testing your modules?<a class="headerlink" href="#testing-your-modules" title="Permanent link">&para;</a></h2>
<p>MISP uses the <strong>modules</strong> function to discover the available MISP modules and their supported MISP attributes:</p>
<div class="highlight"><pre><span></span><code>% curl -s http://127.0.0.1:6666/modules | jq .
[
{
&quot;name&quot;: &quot;passivetotal&quot;,
&quot;type&quot;: &quot;expansion&quot;,
&quot;mispattributes&quot;: {
&quot;input&quot;: [
&quot;hostname&quot;,
&quot;domain&quot;,
&quot;ip-src&quot;,
&quot;ip-dst&quot;
],
&quot;output&quot;: [
&quot;ip-src&quot;,
&quot;ip-dst&quot;,
&quot;hostname&quot;,
&quot;domain&quot;
]
},
&quot;meta&quot;: {
&quot;description&quot;: &quot;PassiveTotal expansion service to expand values with multiple Passive DNS sources&quot;,
&quot;config&quot;: [
&quot;username&quot;,
&quot;password&quot;
],
&quot;author&quot;: &quot;Alexandre Dulaunoy&quot;,
&quot;version&quot;: &quot;0.1&quot;
}
},
{
&quot;name&quot;: &quot;sourcecache&quot;,
&quot;type&quot;: &quot;expansion&quot;,
&quot;mispattributes&quot;: {
&quot;input&quot;: [
&quot;link&quot;
],
&quot;output&quot;: [
&quot;link&quot;
]
},
&quot;meta&quot;: {
&quot;description&quot;: &quot;Module to cache web pages of analysis reports, OSINT sources. The module returns a link of the cached page.&quot;,
&quot;author&quot;: &quot;Alexandre Dulaunoy&quot;,
&quot;version&quot;: &quot;0.1&quot;
}
},
{
&quot;name&quot;: &quot;dns&quot;,
&quot;type&quot;: &quot;expansion&quot;,
&quot;mispattributes&quot;: {
&quot;input&quot;: [
&quot;hostname&quot;,
&quot;domain&quot;
],
&quot;output&quot;: [
&quot;ip-src&quot;,
&quot;ip-dst&quot;
]
},
&quot;meta&quot;: {
&quot;description&quot;: &quot;Simple DNS expansion service to resolve IP address from MISP attributes&quot;,
&quot;author&quot;: &quot;Alexandre Dulaunoy&quot;,
&quot;version&quot;: &quot;0.1&quot;
}
}
]
</code></pre></div>
<p>The MISP module service returns the available modules in a JSON array containing each module name along with their supported input attributes.</p>
<p>Based on this information, a query can be built in a JSON format and saved as body.json:</p>
<div class="highlight"><pre><span></span><code><span class="p">{</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;hostname&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;www.foo.be&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;module&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;dns&quot;</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>
</code></pre></div>
<p>Then you can POST this JSON format query towards the MISP object server:</p>
<div class="highlight"><pre><span></span><code>curl -s http://127.0.0.1:6666/query -H <span class="s2">&quot;Content-Type: application/json&quot;</span> --data @body.json -X POST
</code></pre></div>
<p>The module should output the following JSON:</p>
<div class="highlight"><pre><span></span><code><span class="p">{</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;results&quot;</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"></span>
<span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;types&quot;</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"></span>
<span class="w"> </span><span class="s2">&quot;ip-src&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="s2">&quot;ip-dst&quot;</span><span class="w"></span>
<span class="w"> </span><span class="p">],</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;values&quot;</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"></span>
<span class="w"> </span><span class="s2">&quot;188.65.217.78&quot;</span><span class="w"></span>
<span class="w"> </span><span class="p">]</span><span class="w"></span>
<span class="w"> </span><span class="p">}</span><span class="w"></span>
<span class="w"> </span><span class="p">]</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>
</code></pre></div>
<p>It is also possible to restrict the category options of the resolved attributes by passing a list of categories along (optional):</p>
<div class="highlight"><pre><span></span><code><span class="p">{</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;results&quot;</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"></span>
<span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;types&quot;</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"></span>
<span class="w"> </span><span class="s2">&quot;ip-src&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="s2">&quot;ip-dst&quot;</span><span class="w"></span>
<span class="w"> </span><span class="p">],</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;values&quot;</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"></span>
<span class="w"> </span><span class="s2">&quot;188.65.217.78&quot;</span><span class="w"></span>
<span class="w"> </span><span class="p">],</span><span class="w"></span>
<span class="w"> </span><span class="nt">&quot;categories&quot;</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"></span>
<span class="w"> </span><span class="s2">&quot;Network activity&quot;</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="s2">&quot;Payload delivery&quot;</span><span class="w"></span>
<span class="w"> </span><span class="p">]</span><span class="w"></span>
<span class="w"> </span><span class="p">}</span><span class="w"></span>
<span class="w"> </span><span class="p">]</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>
</code></pre></div>
<p>For both the type and the category lists, the first item in the list will be the default setting on the interface.</p>
<h3 id="enable-your-module-in-the-web-interface">Enable your module in the web interface<a class="headerlink" href="#enable-your-module-in-the-web-interface" title="Permanent link">&para;</a></h3>
<p>For a module to be activated in the MISP web interface it must be enabled in the "Plugin Settings.</p>
<p>Go to "Administration &gt; Server Settings" in the top menu
- Go to "Plugin Settings" in the top "tab menu bar"
- Click on the name of the type of module you have created to expand the list of plugins to show your module.
- Find the name of your plugin's "enabled" value in the Setting Column.
"Plugin.[MODULE NAME]_enabled"
- Double click on its "Value" column</p>
<div class="highlight"><pre><span></span><code>Priority Setting Value Description Error Message
Recommended Plugin.Import_ocr_enabled false Enable or disable the ocr module. Value not set.
</code></pre></div>
<ul>
<li>Use the drop-down to set the enabled value to 'true'</li>
</ul>
<div class="highlight"><pre><span></span><code>Priority Setting Value Description Error Message
Recommended Plugin.Import_ocr_enabled true Enable or disable the ocr module. Value not set.
</code></pre></div>
<h3 id="set-any-other-required-settings-for-your-module">Set any other required settings for your module<a class="headerlink" href="#set-any-other-required-settings-for-your-module" title="Permanent link">&para;</a></h3>
<p>In this same menu set any other plugin settings that are required for testing.</p>
<h2 id="documentation">Documentation<a class="headerlink" href="#documentation" title="Permanent link">&para;</a></h2>
<p>In order to provide documentation about some modules that require specific input / output / configuration, the <a href="https://github.com/MISP/misp-modules/tree/master/doc">doc</a> directory contains detailed information about the general purpose, requirements, features, input and output of each of these modules:</p>
<ul>
<li>***description** - quick description of the general purpose of the module, as the one given by the moduleinfo</li>
<li><strong>requirements</strong> - special libraries needed to make the module work</li>
<li><strong>features</strong> - description of the way to use the module, with the required MISP features to make the module give the intended result</li>
<li><strong>references</strong> - link(s) giving additional information about the format concerned in the module</li>
<li><strong>input</strong> - description of the format of data used in input</li>
<li><strong>output</strong> - description of the format given as the result of the module execution</li>
</ul>
<p>In addition to the module documentation please add your module to <a href="https://github.com/MISP/misp-modules/tree/master/docs/index.md">docs/index.md</a>.</p>
<p>There are also <a href="https://www.misp-project.org/misp-training/3.1-misp-modules.pdf">complementary slides</a> for the creation of MISP modules.</p>
<h2 id="tips-for-developers-creating-modules">Tips for developers creating modules<a class="headerlink" href="#tips-for-developers-creating-modules" title="Permanent link">&para;</a></h2>
<p>Download a pre-built virtual image from the <a href="https://www.circl.lu/services/misp-training-materials/">MISP training materials</a>.</p>
<ul>
<li>Create a Host-Only adapter in VirtualBox</li>
<li>Set your Misp OVA to that Host-Only adapter</li>
<li>Start the virtual machine</li>
<li>Get the IP address of the virutal machine</li>
<li>SSH into the machine (Login info on training page)</li>
<li>Go into the misp-modules directory</li>
</ul>
<div class="highlight"><pre><span></span><code><span class="nb">cd</span> /usr/local/src/misp-modules
</code></pre></div>
<p>Set the git repo to your fork and checkout your development branch. If you SSH'ed in as the misp user you will have to use sudo.</p>
<div class="highlight"><pre><span></span><code>sudo git remote set-url origin https://github.com/YourRepo/misp-modules.git
sudo git pull
sudo git checkout MyModBranch
</code></pre></div>
<p>Remove the contents of the build directory and re-install misp-modules.</p>
<div class="highlight"><pre><span></span><code><span class="n">sudo</span> <span class="n">rm</span> <span class="o">-</span><span class="n">fr</span> <span class="n">build</span><span class="o">/*</span>
<span class="n">sudo</span> <span class="n">pip3</span> <span class="n">install</span> <span class="o">--</span><span class="n">upgrade</span> <span class="o">.</span>
</code></pre></div>
<p>SSH in with a different terminal and run <code>misp-modules</code> with debugging enabled.</p>
<div class="highlight"><pre><span></span><code><span class="n">sudo</span> <span class="n">killall</span> <span class="n">misp</span><span class="o">-</span><span class="n">modules</span>
<span class="n">misp</span><span class="o">-</span><span class="n">modules</span> <span class="o">-</span><span class="n">d</span>
</code></pre></div>
<p>In your original terminal you can now run your tests manually and see any errors that arrive</p>
<div class="highlight"><pre><span></span><code><span class="nb">cd</span> tests/
curl -s http://127.0.0.1:6666/query -H <span class="s2">&quot;Content-Type: application/json&quot;</span> --data @MY_TEST_FILE.json -X POST
<span class="nb">cd</span> ../
</code></pre></div>
</article>
</div>
</div>
</main>
<footer class="md-footer">
<div class="md-footer-meta md-typeset">
<div class="md-footer-meta__inner md-grid">
<div class="md-copyright">
<div class="md-copyright__highlight">
Copyright &copy; 2019-2023 MISP Project
</div>
Made with
<a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
Material for MkDocs
</a>
</div>
<div class="md-social">
<a href="https://twitter.com/MISPProject" target="_blank" rel="noopener" title="twitter.com" class="md-social__link">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 6.2.1 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc.--><path d="M459.37 151.716c.325 4.548.325 9.097.325 13.645 0 138.72-105.583 298.558-298.558 298.558-59.452 0-114.68-17.219-161.137-47.106 8.447.974 16.568 1.299 25.34 1.299 49.055 0 94.213-16.568 130.274-44.832-46.132-.975-84.792-31.188-98.112-72.772 6.498.974 12.995 1.624 19.818 1.624 9.421 0 18.843-1.3 27.614-3.573-48.081-9.747-84.143-51.98-84.143-102.985v-1.299c13.969 7.797 30.214 12.67 47.431 13.319-28.264-18.843-46.781-51.005-46.781-87.391 0-19.492 5.197-37.36 14.294-52.954 51.655 63.675 129.3 105.258 216.365 109.807-1.624-7.797-2.599-15.918-2.599-24.04 0-57.828 46.782-104.934 104.934-104.934 30.213 0 57.502 12.67 76.67 33.137 23.715-4.548 46.456-13.32 66.599-25.34-7.798 24.366-24.366 44.833-46.132 57.827 21.117-2.273 41.584-8.122 60.426-16.243-14.292 20.791-32.161 39.308-52.628 54.253z"/></svg>
</a>
<a href="https://github.com/MISP" target="_blank" rel="noopener" title="github.com" class="md-social__link">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 480 512"><!--! Font Awesome Free 6.2.1 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc.--><path d="M186.1 328.7c0 20.9-10.9 55.1-36.7 55.1s-36.7-34.2-36.7-55.1 10.9-55.1 36.7-55.1 36.7 34.2 36.7 55.1zM480 278.2c0 31.9-3.2 65.7-17.5 95-37.9 76.6-142.1 74.8-216.7 74.8-75.8 0-186.2 2.7-225.6-74.8-14.6-29-20.2-63.1-20.2-95 0-41.9 13.9-81.5 41.5-113.6-5.2-15.8-7.7-32.4-7.7-48.8 0-21.5 4.9-32.3 14.6-51.8 45.3 0 74.3 9 108.8 36 29-6.9 58.8-10 88.7-10 27 0 54.2 2.9 80.4 9.2 34-26.7 63-35.2 107.8-35.2 9.8 19.5 14.6 30.3 14.6 51.8 0 16.4-2.6 32.7-7.7 48.2 27.5 32.4 39 72.3 39 114.2zm-64.3 50.5c0-43.9-26.7-82.6-73.5-82.6-18.9 0-37 3.4-56 6-14.9 2.3-29.8 3.2-45.1 3.2-15.2 0-30.1-.9-45.1-3.2-18.7-2.6-37-6-56-6-46.8 0-73.5 38.7-73.5 82.6 0 87.8 80.4 101.3 150.4 101.3h48.2c70.3 0 150.6-13.4 150.6-101.3zm-82.6-55.1c-25.8 0-36.7 34.2-36.7 55.1s10.9 55.1 36.7 55.1 36.7-34.2 36.7-55.1-10.9-55.1-36.7-55.1z"/></svg>
</a>
</div>
</div>
</div>
</footer>
</div>
<div class="md-dialog" data-md-component="dialog">
<div class="md-dialog__inner md-typeset"></div>
</div>
<script id="__config" type="application/json">{"base": "..", "features": [], "search": "../assets/javascripts/workers/search.12658920.min.js", "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}}</script>
<script src="../assets/javascripts/bundle.5cf534bf.min.js"></script>
</body>
</html>