mirror of https://github.com/MISP/misp-modules
1016 lines
40 KiB
HTML
1016 lines
40 KiB
HTML
|
|
|
|
|
|
|
|
<!doctype html>
|
|
<html lang="en" class="no-js">
|
|
<head>
|
|
|
|
<meta charset="utf-8">
|
|
<meta name="viewport" content="width=device-width,initial-scale=1">
|
|
<meta http-equiv="x-ua-compatible" content="ie=edge">
|
|
|
|
<meta name="description" content="MISP Modules Project">
|
|
|
|
|
|
<link rel="canonical" href="https://www.misp-project.org/contribute/">
|
|
|
|
|
|
<meta name="author" content="MISP Project">
|
|
|
|
|
|
<meta name="lang:clipboard.copy" content="Copy to clipboard">
|
|
|
|
<meta name="lang:clipboard.copied" content="Copied to clipboard">
|
|
|
|
<meta name="lang:search.language" content="en">
|
|
|
|
<meta name="lang:search.pipeline.stopwords" content="True">
|
|
|
|
<meta name="lang:search.pipeline.trimmer" content="True">
|
|
|
|
<meta name="lang:search.result.none" content="No matching documents">
|
|
|
|
<meta name="lang:search.result.one" content="1 matching document">
|
|
|
|
<meta name="lang:search.result.other" content="# matching documents">
|
|
|
|
<meta name="lang:search.tokenizer" content="[\s\-]+">
|
|
|
|
<link rel="shortcut icon" href="../img/favicon.ico">
|
|
<meta name="generator" content="mkdocs-1.0.4, mkdocs-material-4.4.0">
|
|
|
|
|
|
|
|
<title>Contribute - MISP Modules Documentation</title>
|
|
|
|
|
|
|
|
<link rel="stylesheet" href="../assets/stylesheets/application.0284f74d.css">
|
|
|
|
<link rel="stylesheet" href="../assets/stylesheets/application-palette.01803549.css">
|
|
|
|
|
|
|
|
|
|
<meta name="theme-color" content="">
|
|
|
|
|
|
|
|
<script src="../assets/javascripts/modernizr.74668098.js"></script>
|
|
|
|
|
|
|
|
<link href="https://fonts.gstatic.com" rel="preconnect" crossorigin>
|
|
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,400,400i,700|Roboto+Mono&display=fallback">
|
|
<style>body,input{font-family:"Roboto","Helvetica Neue",Helvetica,Arial,sans-serif}code,kbd,pre{font-family:"Roboto Mono","Courier New",Courier,monospace}</style>
|
|
|
|
|
|
<link rel="stylesheet" href="../assets/fonts/material-icons.css">
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</head>
|
|
|
|
|
|
|
|
<body dir="ltr" data-md-color-primary="white" data-md-color-accent="blue">
|
|
|
|
<svg class="md-svg">
|
|
<defs>
|
|
|
|
|
|
<svg xmlns="http://www.w3.org/2000/svg" width="416" height="448" viewBox="0 0 416 448" id="__github"><path fill="currentColor" d="M160 304q0 10-3.125 20.5t-10.75 19T128 352t-18.125-8.5-10.75-19T96 304t3.125-20.5 10.75-19T128 256t18.125 8.5 10.75 19T160 304zm160 0q0 10-3.125 20.5t-10.75 19T288 352t-18.125-8.5-10.75-19T256 304t3.125-20.5 10.75-19T288 256t18.125 8.5 10.75 19T320 304zm40 0q0-30-17.25-51T296 232q-10.25 0-48.75 5.25Q229.5 240 208 240t-39.25-2.75Q130.75 232 120 232q-29.5 0-46.75 21T56 304q0 22 8 38.375t20.25 25.75 30.5 15 35 7.375 37.25 1.75h42q20.5 0 37.25-1.75t35-7.375 30.5-15 20.25-25.75T360 304zm56-44q0 51.75-15.25 82.75-9.5 19.25-26.375 33.25t-35.25 21.5-42.5 11.875-42.875 5.5T212 416q-19.5 0-35.5-.75t-36.875-3.125-38.125-7.5-34.25-12.875T37 371.5t-21.5-28.75Q0 312 0 260q0-59.25 34-99-6.75-20.5-6.75-42.5 0-29 12.75-54.5 27 0 47.5 9.875t47.25 30.875Q171.5 96 212 96q37 0 70 8 26.25-20.5 46.75-30.25T376 64q12.75 25.5 12.75 54.5 0 21.75-6.75 42 34 40 34 99.5z"/></svg>
|
|
|
|
</defs>
|
|
</svg>
|
|
<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" data-md-component="overlay" for="__drawer"></label>
|
|
|
|
<a href="#how-to-add-your-own-misp-modules" tabindex="1" class="md-skip">
|
|
Skip to content
|
|
</a>
|
|
|
|
|
|
<header class="md-header" data-md-component="header">
|
|
<nav class="md-header-nav md-grid">
|
|
<div class="md-flex">
|
|
<div class="md-flex__cell md-flex__cell--shrink">
|
|
<a href="https://www.misp-project.org/" title="MISP Modules Documentation" class="md-header-nav__button md-logo">
|
|
|
|
<img src="../img/misp.png" width="24" height="24">
|
|
|
|
</a>
|
|
</div>
|
|
<div class="md-flex__cell md-flex__cell--shrink">
|
|
<label class="md-icon md-icon--menu md-header-nav__button" for="__drawer"></label>
|
|
</div>
|
|
<div class="md-flex__cell md-flex__cell--stretch">
|
|
<div class="md-flex__ellipsis md-header-nav__title" data-md-component="title">
|
|
|
|
<span class="md-header-nav__topic">
|
|
MISP Modules Documentation
|
|
</span>
|
|
<span class="md-header-nav__topic">
|
|
|
|
Contribute
|
|
|
|
</span>
|
|
|
|
</div>
|
|
</div>
|
|
<div class="md-flex__cell md-flex__cell--shrink">
|
|
|
|
<label class="md-icon md-icon--search md-header-nav__button" for="__search"></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" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="query" data-md-state="active">
|
|
<label class="md-icon md-search__icon" for="__search"></label>
|
|
<button type="reset" class="md-icon md-search__icon" data-md-component="reset" tabindex="-1">
|
|

|
|
</button>
|
|
</form>
|
|
<div class="md-search__output">
|
|
<div class="md-search__scrollwrap" data-md-scrollfix>
|
|
<div class="md-search-result" data-md-component="result">
|
|
<div class="md-search-result__meta">
|
|
Type to start searching
|
|
</div>
|
|
<ol class="md-search-result__list"></ol>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
</div>
|
|
|
|
<div class="md-flex__cell md-flex__cell--shrink">
|
|
<div class="md-header-nav__source">
|
|
|
|
|
|
|
|
|
|
|
|
<a href="https://github.com/MISP/misp-modules/" title="Go to repository" class="md-source" data-md-source="github">
|
|
|
|
<div class="md-source__icon">
|
|
<svg viewBox="0 0 24 24" width="24" height="24">
|
|
<use xlink:href="#__github" width="24" height="24"></use>
|
|
</svg>
|
|
</div>
|
|
|
|
<div class="md-source__repository">
|
|
MISP/misp-modules
|
|
</div>
|
|
</a>
|
|
</div>
|
|
</div>
|
|
|
|
</div>
|
|
</nav>
|
|
</header>
|
|
|
|
<div class="md-container">
|
|
|
|
|
|
|
|
|
|
<main class="md-main">
|
|
<div class="md-main__inner md-grid" data-md-component="container">
|
|
|
|
|
|
<div class="md-sidebar md-sidebar--primary" data-md-component="navigation">
|
|
<div class="md-sidebar__scrollwrap">
|
|
<div class="md-sidebar__inner">
|
|
<nav class="md-nav md-nav--primary" data-md-level="0">
|
|
<label class="md-nav__title md-nav__title--site" for="__drawer">
|
|
<a href="https://www.misp-project.org/" title="MISP Modules Documentation" class="md-nav__button md-logo">
|
|
|
|
<img src="../img/misp.png" width="48" height="48">
|
|
|
|
</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-source="github">
|
|
|
|
<div class="md-source__icon">
|
|
<svg viewBox="0 0 24 24" width="24" height="24">
|
|
<use xlink:href="#__github" width="24" height="24"></use>
|
|
</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=".." title="Home" class="md-nav__link">
|
|
Home
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item md-nav__item--nested">
|
|
|
|
<input class="md-toggle md-nav__toggle" data-md-toggle="nav-2" type="checkbox" id="nav-2">
|
|
|
|
<label class="md-nav__link" for="nav-2">
|
|
Modules
|
|
</label>
|
|
<nav class="md-nav" data-md-component="collapsible" data-md-level="1">
|
|
<label class="md-nav__title" for="nav-2">
|
|
Modules
|
|
</label>
|
|
<ul class="md-nav__list" data-md-scrollfix>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../expansion/" title="Expansion Modules" class="md-nav__link">
|
|
Expansion Modules
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../export_mod/" title="Export Modules" class="md-nav__link">
|
|
Export Modules
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../import_mod/" title="Import Modules" class="md-nav__link">
|
|
Import Modules
|
|
</a>
|
|
</li>
|
|
|
|
|
|
</ul>
|
|
</nav>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../install/" title="Install Guides" class="md-nav__link">
|
|
Install Guides
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item md-nav__item--active">
|
|
|
|
<input class="md-toggle md-nav__toggle" data-md-toggle="toc" type="checkbox" id="__toc">
|
|
|
|
|
|
<label class="md-nav__link md-nav__link--active" for="__toc">
|
|
Contribute
|
|
</label>
|
|
|
|
<a href="./" title="Contribute" class="md-nav__link md-nav__link--active">
|
|
Contribute
|
|
</a>
|
|
|
|
|
|
<nav class="md-nav md-nav--secondary">
|
|
|
|
|
|
|
|
<label class="md-nav__title" for="__toc">Table of contents</label>
|
|
<ul class="md-nav__list" data-md-scrollfix>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#how-to-add-your-own-misp-modules" title="How to add your own MISP modules?" class="md-nav__link">
|
|
How to add your own MISP modules?
|
|
</a>
|
|
|
|
<nav class="md-nav">
|
|
<ul class="md-nav__list">
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#introspection" title="introspection" class="md-nav__link">
|
|
introspection
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#version" title="version" class="md-nav__link">
|
|
version
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#additional-configuration-values" title="Additional Configuration Values" class="md-nav__link">
|
|
Additional Configuration Values
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#handler" title="handler" class="md-nav__link">
|
|
handler
|
|
</a>
|
|
|
|
<nav class="md-nav">
|
|
<ul class="md-nav__list">
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#export-module" title="export module" class="md-nav__link">
|
|
export module
|
|
</a>
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
</nav>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#module-type" title="Module type" class="md-nav__link">
|
|
Module type
|
|
</a>
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
</nav>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#testing-your-modules" title="Testing your modules?" class="md-nav__link">
|
|
Testing your modules?
|
|
</a>
|
|
|
|
<nav class="md-nav">
|
|
<ul class="md-nav__list">
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#enable-your-module-in-the-web-interface" title="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" title="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" title="Documentation" class="md-nav__link">
|
|
Documentation
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#tips-for-developers-creating-modules" title="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-toggle md-nav__toggle" data-md-toggle="nav-5" type="checkbox" id="nav-5">
|
|
|
|
<label class="md-nav__link" for="nav-5">
|
|
About
|
|
</label>
|
|
<nav class="md-nav" data-md-component="collapsible" data-md-level="1">
|
|
<label class="md-nav__title" for="nav-5">
|
|
About
|
|
</label>
|
|
<ul class="md-nav__list" data-md-scrollfix>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../license/" title="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="toc">
|
|
<div class="md-sidebar__scrollwrap">
|
|
<div class="md-sidebar__inner">
|
|
|
|
<nav class="md-nav md-nav--secondary">
|
|
|
|
|
|
|
|
<label class="md-nav__title" for="__toc">Table of contents</label>
|
|
<ul class="md-nav__list" data-md-scrollfix>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#how-to-add-your-own-misp-modules" title="How to add your own MISP modules?" class="md-nav__link">
|
|
How to add your own MISP modules?
|
|
</a>
|
|
|
|
<nav class="md-nav">
|
|
<ul class="md-nav__list">
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#introspection" title="introspection" class="md-nav__link">
|
|
introspection
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#version" title="version" class="md-nav__link">
|
|
version
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#additional-configuration-values" title="Additional Configuration Values" class="md-nav__link">
|
|
Additional Configuration Values
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#handler" title="handler" class="md-nav__link">
|
|
handler
|
|
</a>
|
|
|
|
<nav class="md-nav">
|
|
<ul class="md-nav__list">
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#export-module" title="export module" class="md-nav__link">
|
|
export module
|
|
</a>
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
</nav>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#module-type" title="Module type" class="md-nav__link">
|
|
Module type
|
|
</a>
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
</nav>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#testing-your-modules" title="Testing your modules?" class="md-nav__link">
|
|
Testing your modules?
|
|
</a>
|
|
|
|
<nav class="md-nav">
|
|
<ul class="md-nav__list">
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#enable-your-module-in-the-web-interface" title="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" title="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" title="Documentation" class="md-nav__link">
|
|
Documentation
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#tips-for-developers-creating-modules" title="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">
|
|
<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">¶</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><module type folder>/__init__.py</code> in order for it to be loaded.</p>
|
|
<div class="codehilite"><pre><span></span><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">'ip-src'</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">'error'</span><span class="p">:</span> <span class="s2">"A source IP is required"</span><span class="p">}</span>
|
|
<span class="o">...</span>
|
|
</pre></div>
|
|
|
|
<h3 id="introspection">introspection<a class="headerlink" href="#introspection" title="Permanent link">¶</a></h3>
|
|
<p>The function that returns a dict of the supported attributes (input and output) by your expansion module.</p>
|
|
<div class="codehilite"><pre><span></span><span class="n">mispattributes</span> <span class="o">=</span> <span class="p">{</span><span class="s1">'input'</span><span class="p">:</span> <span class="p">[</span><span class="s1">'link'</span><span class="p">,</span> <span class="s1">'url'</span><span class="p">],</span>
|
|
<span class="s1">'output'</span><span class="p">:</span> <span class="p">[</span><span class="s1">'attachment'</span><span class="p">,</span> <span class="s1">'malware-sample'</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>
|
|
</pre></div>
|
|
|
|
<h3 id="version">version<a class="headerlink" href="#version" title="Permanent link">¶</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">¶</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="codehilite"><pre><span></span><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">"apikey"</span><span class="p">,</span> <span class="s2">"event_limit"</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">'config'</span><span class="p">]</span> <span class="o">=</span> <span class="n">moduleconfig</span>
|
|
<span class="k">return</span> <span class="n">moduleinfo</span>
|
|
</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="codehilite"><pre><span></span>"meta": {
|
|
"description": "PassiveTotal expansion service to expand values with multiple Passive DNS sources",
|
|
"config": [
|
|
"username",
|
|
"password"
|
|
],
|
|
"module-type": [
|
|
"expansion",
|
|
"hover"
|
|
],
|
|
|
|
...
|
|
</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="codehilite"><pre><span></span>def handler(q=False):
|
|
|
|
# Check if we were given a configuration
|
|
config = q.get("config", {})
|
|
|
|
# Find out if there is a username field
|
|
username = config.get("username", None)
|
|
</pre></div>
|
|
|
|
<h3 id="handler">handler<a class="headerlink" href="#handler" title="Permanent link">¶</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="codehilite"><pre><span></span><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="bp">False</span><span class="p">):</span>
|
|
<span class="s2">"Fully functional rot-13 encoder"</span>
|
|
<span class="k">if</span> <span class="n">q</span> <span class="ow">is</span> <span class="bp">False</span><span class="p">:</span>
|
|
<span class="k">return</span> <span class="bp">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">'ip-src'</span><span class="p">)</span>
|
|
<span class="k">if</span> <span class="n">src</span> <span class="ow">is</span> <span class="bp">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">'error'</span><span class="p">:</span> <span class="s2">"A source IP is required"</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">'results'</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">"rot-13"</span><span class="p">)}</span>
|
|
</pre></div>
|
|
|
|
<h4 id="export-module">export module<a class="headerlink" href="#export-module" title="Permanent link">¶</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="codehilite"><pre><span></span><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">"data"</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">"Attribute"</span><span class="p">]:</span>
|
|
<span class="c1"># do stuff w/ attribute['type'], attribute['value'], ...</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="nb">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">"results"</span><span class="p">:</span> <span class="p">{</span><span class="s2">"values"</span><span class="p">:</span> <span class="s2">"filename.txt"</span><span class="p">,</span>
|
|
<span class="s2">"types"</span><span class="p">:</span> <span class="s2">"attachment"</span><span class="p">,</span>
|
|
<span class="s2">"data"</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"><</span><span class="n">ByteIO</span><span class="o">></span><span class="p">)</span> <span class="c1"># base64 encode your data first</span>
|
|
<span class="s2">"comment"</span><span class="p">:</span> <span class="s2">"This is an attachment"</span><span class="p">}}</span>
|
|
</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="codehilite"><pre><span></span><span class="p">{</span><span class="s2">"results"</span><span class="p">:</span> <span class="p">{</span><span class="s2">"values"</span><span class="p">:</span> <span class="s2">"filename.txt"</span><span class="p">,</span>
|
|
<span class="s2">"types"</span><span class="p">:</span> <span class="s2">"malware-sample"</span><span class="p">,</span>
|
|
<span class="s2">"data"</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"><</span><span class="n">ByteIO</span><span class="o">></span><span class="p">)</span> <span class="c1"># base64 encode your data first</span>
|
|
<span class="s2">"comment"</span><span class="p">:</span> <span class="s2">"This is an attachment"</span><span class="p">}}</span>
|
|
</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">¶</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">¶</a></h2>
|
|
<p>MISP uses the <strong>modules</strong> function to discover the available MISP modules and their supported MISP attributes:</p>
|
|
<div class="codehilite"><pre><span></span>% curl -s http://127.0.0.1:6666/modules | jq .
|
|
[
|
|
{
|
|
"name": "passivetotal",
|
|
"type": "expansion",
|
|
"mispattributes": {
|
|
"input": [
|
|
"hostname",
|
|
"domain",
|
|
"ip-src",
|
|
"ip-dst"
|
|
],
|
|
"output": [
|
|
"ip-src",
|
|
"ip-dst",
|
|
"hostname",
|
|
"domain"
|
|
]
|
|
},
|
|
"meta": {
|
|
"description": "PassiveTotal expansion service to expand values with multiple Passive DNS sources",
|
|
"config": [
|
|
"username",
|
|
"password"
|
|
],
|
|
"author": "Alexandre Dulaunoy",
|
|
"version": "0.1"
|
|
}
|
|
},
|
|
{
|
|
"name": "sourcecache",
|
|
"type": "expansion",
|
|
"mispattributes": {
|
|
"input": [
|
|
"link"
|
|
],
|
|
"output": [
|
|
"link"
|
|
]
|
|
},
|
|
"meta": {
|
|
"description": "Module to cache web pages of analysis reports, OSINT sources. The module returns a link of the cached page.",
|
|
"author": "Alexandre Dulaunoy",
|
|
"version": "0.1"
|
|
}
|
|
},
|
|
{
|
|
"name": "dns",
|
|
"type": "expansion",
|
|
"mispattributes": {
|
|
"input": [
|
|
"hostname",
|
|
"domain"
|
|
],
|
|
"output": [
|
|
"ip-src",
|
|
"ip-dst"
|
|
]
|
|
},
|
|
"meta": {
|
|
"description": "Simple DNS expansion service to resolve IP address from MISP attributes",
|
|
"author": "Alexandre Dulaunoy",
|
|
"version": "0.1"
|
|
}
|
|
}
|
|
]
|
|
</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="codehilite"><pre><span></span><span class="p">{</span>
|
|
<span class="nt">"hostname"</span><span class="p">:</span> <span class="s2">"www.foo.be"</span><span class="p">,</span>
|
|
<span class="nt">"module"</span><span class="p">:</span> <span class="s2">"dns"</span>
|
|
<span class="p">}</span>
|
|
</pre></div>
|
|
|
|
<p>Then you can POST this JSON format query towards the MISP object server:</p>
|
|
<div class="codehilite"><pre><span></span>curl -s http://127.0.0.1:6666/query -H <span class="s2">"Content-Type: application/json"</span> --data @body.json -X POST
|
|
</pre></div>
|
|
|
|
<p>The module should output the following JSON:</p>
|
|
<div class="codehilite"><pre><span></span><span class="p">{</span>
|
|
<span class="nt">"results"</span><span class="p">:</span> <span class="p">[</span>
|
|
<span class="p">{</span>
|
|
<span class="nt">"types"</span><span class="p">:</span> <span class="p">[</span>
|
|
<span class="s2">"ip-src"</span><span class="p">,</span>
|
|
<span class="s2">"ip-dst"</span>
|
|
<span class="p">],</span>
|
|
<span class="nt">"values"</span><span class="p">:</span> <span class="p">[</span>
|
|
<span class="s2">"188.65.217.78"</span>
|
|
<span class="p">]</span>
|
|
<span class="p">}</span>
|
|
<span class="p">]</span>
|
|
<span class="p">}</span>
|
|
</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="codehilite"><pre><span></span><span class="p">{</span>
|
|
<span class="nt">"results"</span><span class="p">:</span> <span class="p">[</span>
|
|
<span class="p">{</span>
|
|
<span class="nt">"types"</span><span class="p">:</span> <span class="p">[</span>
|
|
<span class="s2">"ip-src"</span><span class="p">,</span>
|
|
<span class="s2">"ip-dst"</span>
|
|
<span class="p">],</span>
|
|
<span class="nt">"values"</span><span class="p">:</span> <span class="p">[</span>
|
|
<span class="s2">"188.65.217.78"</span>
|
|
<span class="p">],</span>
|
|
<span class="nt">"categories"</span><span class="p">:</span> <span class="p">[</span>
|
|
<span class="s2">"Network activity"</span><span class="p">,</span>
|
|
<span class="s2">"Payload delivery"</span>
|
|
<span class="p">]</span>
|
|
<span class="p">}</span>
|
|
<span class="p">]</span>
|
|
<span class="p">}</span>
|
|
</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">¶</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 > 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="codehilite"><pre><span></span>Priority Setting Value Description Error Message
|
|
Recommended Plugin.Import_ocr_enabled false Enable or disable the ocr module. Value not set.
|
|
</pre></div>
|
|
|
|
<ul>
|
|
<li>Use the drop-down to set the enabled value to 'true'</li>
|
|
</ul>
|
|
<div class="codehilite"><pre><span></span>Priority Setting Value Description Error Message
|
|
Recommended Plugin.Import_ocr_enabled true Enable or disable the ocr module. Value not set.
|
|
</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">¶</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">¶</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 modul documentation please add your module to <a href="https://github.com/MISP/misp-modules/tree/master/docs/index.md">docs/index.md</a>.</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">¶</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="codehilite"><pre><span></span><span class="nb">cd</span> /usr/local/src/misp-modules
|
|
</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="codehilite"><pre><span></span>sudo git remote set-url origin https://github.com/YourRepo/misp-modules.git
|
|
sudo git pull
|
|
sudo git checkout MyModBranch
|
|
</pre></div>
|
|
|
|
<p>Remove the contents of the build directory and re-install misp-modules.</p>
|
|
<div class="codehilite"><pre><span></span><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>
|
|
</pre></div>
|
|
|
|
<p>SSH in with a different terminal and run <code>misp-modules</code> with debugging enabled.</p>
|
|
<div class="codehilite"><pre><span></span><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>
|
|
</pre></div>
|
|
|
|
<p>In your original terminal you can now run your tests manually and see any errors that arrive</p>
|
|
<div class="codehilite"><pre><span></span><span class="nb">cd</span> tests/
|
|
curl -s http://127.0.0.1:6666/query -H <span class="s2">"Content-Type: application/json"</span> --data @MY_TEST_FILE.json -X POST
|
|
<span class="nb">cd</span> ../
|
|
</pre></div>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</article>
|
|
</div>
|
|
</div>
|
|
</main>
|
|
|
|
|
|
<footer class="md-footer">
|
|
|
|
<div class="md-footer-nav">
|
|
<nav class="md-footer-nav__inner md-grid">
|
|
|
|
<a href="../install/" title="Install Guides" class="md-flex md-footer-nav__link md-footer-nav__link--prev" rel="prev">
|
|
<div class="md-flex__cell md-flex__cell--shrink">
|
|
<i class="md-icon md-icon--arrow-back md-footer-nav__button"></i>
|
|
</div>
|
|
<div class="md-flex__cell md-flex__cell--stretch md-footer-nav__title">
|
|
<span class="md-flex__ellipsis">
|
|
<span class="md-footer-nav__direction">
|
|
Previous
|
|
</span>
|
|
Install Guides
|
|
</span>
|
|
</div>
|
|
</a>
|
|
|
|
|
|
<a href="../license/" title="License" class="md-flex md-footer-nav__link md-footer-nav__link--next" rel="next">
|
|
<div class="md-flex__cell md-flex__cell--stretch md-footer-nav__title">
|
|
<span class="md-flex__ellipsis">
|
|
<span class="md-footer-nav__direction">
|
|
Next
|
|
</span>
|
|
License
|
|
</span>
|
|
</div>
|
|
<div class="md-flex__cell md-flex__cell--shrink">
|
|
<i class="md-icon md-icon--arrow-forward md-footer-nav__button"></i>
|
|
</div>
|
|
</a>
|
|
|
|
</nav>
|
|
</div>
|
|
|
|
<div class="md-footer-meta md-typeset">
|
|
<div class="md-footer-meta__inner md-grid">
|
|
<div class="md-footer-copyright">
|
|
|
|
<div class="md-footer-copyright__highlight">
|
|
Copyright © 2019 MISP Project
|
|
</div>
|
|
|
|
powered by
|
|
<a href="https://www.mkdocs.org">MkDocs</a>
|
|
and
|
|
<a href="https://squidfunk.github.io/mkdocs-material/">
|
|
Material for MkDocs</a>
|
|
</div>
|
|
|
|
<div class="md-footer-social">
|
|
<link rel="stylesheet" href="../assets/fonts/font-awesome.css">
|
|
|
|
<a href="https://www.misp-project.org/" class="md-footer-social__link fa fa-globe"></a>
|
|
|
|
<a href="https://github.com/MISP" class="md-footer-social__link fa fa-github-alt"></a>
|
|
|
|
<a href="https://twitter.com/MISPProject" class="md-footer-social__link fa fa-twitter"></a>
|
|
|
|
</div>
|
|
|
|
</div>
|
|
</div>
|
|
</footer>
|
|
|
|
</div>
|
|
|
|
<script src="../assets/javascripts/application.245445c6.js"></script>
|
|
|
|
<script>app.initialize({version:"1.0.4",url:{base:".."}})</script>
|
|
|
|
|
|
</body>
|
|
</html> |