http://git-wip-us.apache.org/repos/asf/metron/blob/ae1d3eb9/site/current-book/use-cases/index.html ---------------------------------------------------------------------- diff --git a/site/current-book/use-cases/index.html b/site/current-book/use-cases/index.html index e8c6b28..684cc14 100644 --- a/site/current-book/use-cases/index.html +++ b/site/current-book/use-cases/index.html @@ -1,227 +1,114 @@ <!DOCTYPE html> <!-- - | Generated by Apache Maven Doxia at 2018-01-03 - | Rendered using Apache Maven Fluido Skin 1.3.0 + | Generated by Apache Maven Doxia Site Renderer 1.8 from src/site/markdown/use-cases/index.md at 2018-06-07 + | Rendered using Apache Maven Fluido Skin 1.7 --> <html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> - <meta name="Date-Revision-yyyymmdd" content="20180103" /> + <meta name="Date-Revision-yyyymmdd" content="20180607" /> <meta http-equiv="Content-Language" content="en" /> <title>Metron – Worked Examples</title> - <link rel="stylesheet" href="../css/apache-maven-fluido-1.3.0.min.css" /> + <link rel="stylesheet" href="../css/apache-maven-fluido-1.7.min.css" /> <link rel="stylesheet" href="../css/site.css" /> <link rel="stylesheet" href="../css/print.css" media="print" /> - - - <script type="text/javascript" src="../js/apache-maven-fluido-1.3.0.min.js"></script> - - - -<script type="text/javascript">$( document ).ready( function() { $( '.carousel' ).carousel( { interval: 3500 } ) } );</script> - - </head> - <body class="topBarDisabled"> - - - - - <div class="container-fluid"> - <div id="banner"> - <div class="pull-left"> - <a href="http://metron.apache.org/"; id="bannerLeft"> - <img src="../images/metron-logo.png" alt="Apache Metron" width="148px" height="48px"/> - </a> - </div> - <div class="pull-right"> </div> + <script type="text/javascript" src="../js/apache-maven-fluido-1.7.min.js"></script> +<script type="text/javascript"> + $( document ).ready( function() { $( '.carousel' ).carousel( { interval: 3500 } ) } ); + </script> + </head> + <body class="topBarDisabled"> + <div class="container-fluid"> + <div id="banner"> + <div class="pull-left"><a href="http://metron.apache.org/"; id="bannerLeft"><img src="../images/metron-logo.png" alt="Apache Metron" width="148px" height="48px"/></a></div> + <div class="pull-right"></div> <div class="clear"><hr/></div> </div> <div id="breadcrumbs"> <ul class="breadcrumb"> - - - <li class=""> - <a href="http://www.apache.org"; class="externalLink" title="Apache"> - Apache</a> - </li> - <li class="divider ">/</li> - <li class=""> - <a href="http://metron.apache.org/"; class="externalLink" title="Metron"> - Metron</a> - </li> - <li class="divider ">/</li> - <li class=""> - <a href="../index.html" title="Documentation"> - Documentation</a> - </li> - <li class="divider ">/</li> - <li class="">Worked Examples</li> - - - - <li id="publishDate" class="pull-right">Last Published: 2018-01-03</li> <li class="divider pull-right">|</li> - <li id="projectVersion" class="pull-right">Version: 0.4.2</li> - - </ul> + <li class=""><a href="http://www.apache.org"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> + <li class=""><a href="http://metron.apache.org/"; class="externalLink" title="Metron">Metron</a><span class="divider">/</span></li> + <li class=""><a href="../index.html" title="Documentation">Documentation</a><span class="divider">/</span></li> + <li class="active ">Worked Examples</li> + <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2018-06-07</li> + <li id="projectVersion" class="pull-right">Version: 0.5.0</li> + </ul> </div> - - <div class="row-fluid"> - <div id="leftColumn" class="span3"> + <div id="leftColumn" class="span2"> <div class="well sidebar-nav"> - - - <ul class="nav nav-list"> - <li class="nav-header">User Documentation</li> - - <li> - - <a href="../index.html" title="Metron"> - <i class="icon-chevron-down"></i> - Metron</a> - <ul class="nav nav-list"> - - <li> - - <a href="../Upgrading.html" title="Upgrading"> - <i class="none"></i> - Upgrading</a> - </li> - - <li> - - <a href="../metron-analytics/index.html" title="Analytics"> - <i class="icon-chevron-right"></i> - Analytics</a> - </li> - - <li> - - <a href="../metron-contrib/metron-docker/index.html" title="Docker"> - <i class="none"></i> - Docker</a> - </li> - - <li> - - <a href="../metron-deployment/index.html" title="Deployment"> - <i class="icon-chevron-right"></i> - Deployment</a> - </li> - - <li> - - <a href="../metron-interface/metron-alerts/index.html" title="Alerts"> - <i class="none"></i> - Alerts</a> - </li> - - <li> - - <a href="../metron-interface/metron-config/index.html" title="Config"> - <i class="none"></i> - Config</a> - </li> - - <li> - - <a href="../metron-interface/metron-rest/index.html" title="Rest"> - <i class="none"></i> - Rest</a> - </li> - - <li> - - <a href="../metron-platform/index.html" title="Platform"> - <i class="icon-chevron-right"></i> - Platform</a> - </li> - - <li> - - <a href="../metron-sensors/index.html" title="Sensors"> - <i class="icon-chevron-right"></i> - Sensors</a> - </li> - - <li> - - <a href="../metron-stellar/stellar-3rd-party-example/index.html" title="Stellar-3rd-party-example"> - <i class="none"></i> - Stellar-3rd-party-example</a> - </li> - - <li> - - <a href="../metron-stellar/stellar-common/index.html" title="Stellar-common"> - <i class="icon-chevron-right"></i> - Stellar-common</a> - </li> - - <li class="active"> - - <a href="#"><i class="icon-chevron-down"></i>Use-cases</a> - <ul class="nav nav-list"> - - <li> - - <a href="../use-cases/forensic_clustering/index.html" title="Forensic_clustering"> - <i class="none"></i> - Forensic_clustering</a> - </li> - - <li> - - <a href="../use-cases/geographic_login_outliers/index.html" title="Geographic_login_outliers"> - <i class="none"></i> - Geographic_login_outliers</a> - </li> - </ul> - </li> - </ul> - </li> - </ul> - - - - <hr class="divider" /> - - <div id="poweredBy"> - <div class="clear"></div> - <div class="clear"></div> - <div class="clear"></div> - <a href="http://maven.apache.org/"; title="Built by Maven" class="poweredBy"> - <img class="builtBy" alt="Built by Maven" src="../images/logos/maven-feather.png" /> - </a> - </div> + <ul class="nav nav-list"> + <li class="nav-header">User Documentation</li> + <li><a href="../index.html" title="Metron"><span class="icon-chevron-down"></span>Metron</a> + <ul class="nav nav-list"> + <li><a href="../CONTRIBUTING.html" title="CONTRIBUTING"><span class="none"></span>CONTRIBUTING</a></li> + <li><a href="../Upgrading.html" title="Upgrading"><span class="none"></span>Upgrading</a></li> + <li><a href="../metron-analytics/index.html" title="Analytics"><span class="icon-chevron-right"></span>Analytics</a></li> + <li><a href="../metron-contrib/metron-docker/index.html" title="Docker"><span class="none"></span>Docker</a></li> + <li><a href="../metron-contrib/metron-performance/index.html" title="Performance"><span class="none"></span>Performance</a></li> + <li><a href="../metron-deployment/index.html" title="Deployment"><span class="icon-chevron-right"></span>Deployment</a></li> + <li><a href="../metron-interface/metron-alerts/index.html" title="Alerts"><span class="none"></span>Alerts</a></li> + <li><a href="../metron-interface/metron-config/index.html" title="Config"><span class="none"></span>Config</a></li> + <li><a href="../metron-interface/metron-rest/index.html" title="Rest"><span class="none"></span>Rest</a></li> + <li><a href="../metron-platform/index.html" title="Platform"><span class="icon-chevron-right"></span>Platform</a></li> + <li><a href="../metron-sensors/index.html" title="Sensors"><span class="icon-chevron-right"></span>Sensors</a></li> + <li><a href="../metron-stellar/stellar-3rd-party-example/index.html" title="Stellar-3rd-party-example"><span class="none"></span>Stellar-3rd-party-example</a></li> + <li><a href="../metron-stellar/stellar-common/index.html" title="Stellar-common"><span class="icon-chevron-right"></span>Stellar-common</a></li> + <li><a href="../metron-stellar/stellar-zeppelin/index.html" title="Stellar-zeppelin"><span class="none"></span>Stellar-zeppelin</a></li> + <li class="active"><a href="#"><span class="icon-chevron-down"></span>Use-cases</a> + <ul class="nav nav-list"> + <li><a href="../use-cases/forensic_clustering/index.html" title="Forensic_clustering"><span class="none"></span>Forensic_clustering</a></li> + <li><a href="../use-cases/geographic_login_outliers/index.html" title="Geographic_login_outliers"><span class="none"></span>Geographic_login_outliers</a></li> + <li><a href="../use-cases/typosquat_detection/index.html" title="Typosquat_detection"><span class="none"></span>Typosquat_detection</a></li> + </ul> +</li> + </ul> +</li> +</ul> + <hr /> + <div id="poweredBy"> + <div class="clear"></div> + <div class="clear"></div> + <div class="clear"></div> + <div class="clear"></div> +<a href="http://maven.apache.org/"; title="Built by Maven" class="poweredBy"><img class="builtBy" alt="Built by Maven" src="../images/logos/maven-feather.png" /></a> + </div> </div> </div> - - - <div id="bodyColumn" class="span9" > - - <h1>Worked Examples</h1> + <div id="bodyColumn" class="span10" > +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +--> +<h1>Worked Examples</h1> <p><a name="Worked_Examples"></a></p> <p>The following are worked examples of use-cases that showcase some (or many) component(s) of Metron.</p> - </div> - </div> - </div> - + </div> + </div> + </div> <hr/> - <footer> - <div class="container-fluid"> - <div class="row span12">Copyright © 2018 - <a href="https://www.apache.org";>The Apache Software Foundation</a>. - All Rights Reserved. - + <div class="container-fluid"> + <div class="row-fluid"> +é 2015-2016 The Apache Software Foundation. Apache Metron, Metron, Apache, the Apache feather logo, + and the Apache Metron project logo are trademarks of The Apache Software Foundation. + </div> </div> - - - - </div> </footer> </body> </html>
http://git-wip-us.apache.org/repos/asf/metron/blob/ae1d3eb9/site/current-book/use-cases/typosquat_detection/index.html ---------------------------------------------------------------------- diff --git a/site/current-book/use-cases/typosquat_detection/index.html b/site/current-book/use-cases/typosquat_detection/index.html new file mode 100644 index 0000000..03c3581 --- /dev/null +++ b/site/current-book/use-cases/typosquat_detection/index.html @@ -0,0 +1,545 @@ +<!DOCTYPE html> +<!-- + | Generated by Apache Maven Doxia Site Renderer 1.8 from src/site/markdown/use-cases/typosquat_detection/index.md at 2018-06-07 + | Rendered using Apache Maven Fluido Skin 1.7 +--> +<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en"> + <head> + <meta charset="UTF-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <meta name="Date-Revision-yyyymmdd" content="20180607" /> + <meta http-equiv="Content-Language" content="en" /> + <title>Metron – Problem Statement</title> + <link rel="stylesheet" href="../../css/apache-maven-fluido-1.7.min.css" /> + <link rel="stylesheet" href="../../css/site.css" /> + <link rel="stylesheet" href="../../css/print.css" media="print" /> + <script type="text/javascript" src="../../js/apache-maven-fluido-1.7.min.js"></script> +<script type="text/javascript"> + $( document ).ready( function() { $( '.carousel' ).carousel( { interval: 3500 } ) } ); + </script> + </head> + <body class="topBarDisabled"> + <div class="container-fluid"> + <div id="banner"> + <div class="pull-left"><a href="http://metron.apache.org/"; id="bannerLeft"><img src="../../images/metron-logo.png" alt="Apache Metron" width="148px" height="48px"/></a></div> + <div class="pull-right"></div> + <div class="clear"><hr/></div> + </div> + + <div id="breadcrumbs"> + <ul class="breadcrumb"> + <li class=""><a href="http://www.apache.org"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> + <li class=""><a href="http://metron.apache.org/"; class="externalLink" title="Metron">Metron</a><span class="divider">/</span></li> + <li class=""><a href="../../index.html" title="Documentation">Documentation</a><span class="divider">/</span></li> + <li class="active ">Problem Statement</li> + <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2018-06-07</li> + <li id="projectVersion" class="pull-right">Version: 0.5.0</li> + </ul> + </div> + <div class="row-fluid"> + <div id="leftColumn" class="span2"> + <div class="well sidebar-nav"> + <ul class="nav nav-list"> + <li class="nav-header">User Documentation</li> + <li><a href="../../index.html" title="Metron"><span class="icon-chevron-down"></span>Metron</a> + <ul class="nav nav-list"> + <li><a href="../../CONTRIBUTING.html" title="CONTRIBUTING"><span class="none"></span>CONTRIBUTING</a></li> + <li><a href="../../Upgrading.html" title="Upgrading"><span class="none"></span>Upgrading</a></li> + <li><a href="../../metron-analytics/index.html" title="Analytics"><span class="icon-chevron-right"></span>Analytics</a></li> + <li><a href="../../metron-contrib/metron-docker/index.html" title="Docker"><span class="none"></span>Docker</a></li> + <li><a href="../../metron-contrib/metron-performance/index.html" title="Performance"><span class="none"></span>Performance</a></li> + <li><a href="../../metron-deployment/index.html" title="Deployment"><span class="icon-chevron-right"></span>Deployment</a></li> + <li><a href="../../metron-interface/metron-alerts/index.html" title="Alerts"><span class="none"></span>Alerts</a></li> + <li><a href="../../metron-interface/metron-config/index.html" title="Config"><span class="none"></span>Config</a></li> + <li><a href="../../metron-interface/metron-rest/index.html" title="Rest"><span class="none"></span>Rest</a></li> + <li><a href="../../metron-platform/index.html" title="Platform"><span class="icon-chevron-right"></span>Platform</a></li> + <li><a href="../../metron-sensors/index.html" title="Sensors"><span class="icon-chevron-right"></span>Sensors</a></li> + <li><a href="../../metron-stellar/stellar-3rd-party-example/index.html" title="Stellar-3rd-party-example"><span class="none"></span>Stellar-3rd-party-example</a></li> + <li><a href="../../metron-stellar/stellar-common/index.html" title="Stellar-common"><span class="icon-chevron-right"></span>Stellar-common</a></li> + <li><a href="../../metron-stellar/stellar-zeppelin/index.html" title="Stellar-zeppelin"><span class="none"></span>Stellar-zeppelin</a></li> + <li><a href="../../use-cases/index.html" title="Use-cases"><span class="icon-chevron-down"></span>Use-cases</a> + <ul class="nav nav-list"> + <li><a href="../../use-cases/forensic_clustering/index.html" title="Forensic_clustering"><span class="none"></span>Forensic_clustering</a></li> + <li><a href="../../use-cases/geographic_login_outliers/index.html" title="Geographic_login_outliers"><span class="none"></span>Geographic_login_outliers</a></li> + <li class="active"><a href="#"><span class="none"></span>Typosquat_detection</a></li> + </ul> +</li> + </ul> +</li> +</ul> + <hr /> + <div id="poweredBy"> + <div class="clear"></div> + <div class="clear"></div> + <div class="clear"></div> + <div class="clear"></div> +<a href="http://maven.apache.org/"; title="Built by Maven" class="poweredBy"><img class="builtBy" alt="Built by Maven" src="../../images/logos/maven-feather.png" /></a> + </div> + </div> + </div> + <div id="bodyColumn" class="span10" > +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +--> +<h1>Problem Statement</h1> +<p><a name="Problem_Statement"></a></p> +<p><a class="externalLink" href="https://en.wikipedia.org/wiki/Typosquatting";>Typosquatting</a> is a form of cybersquatting which relies on likely typos to trick unsuspecting users to visit possibly malicious URLs. In the best case, this is a mischievous joke as in the following RickRoll: <a class="externalLink" href="http://www.latlmes.com/breaking/apache-metron-named-best-software-by-asf-1";>http://www.latlmes.com/breaking/apache-metron-named-best-software-by-asf-1</a>. In the worst case, however, it can be overtly malicious as Bitcoin users found out in <a class="externalLink" href="https://nakedsecurity.sophos.com/2014/03/24/bitcoin-user-loses-10k-to-typosquatters/";>2016</a> when thousands of dollars of Bitcoin was stolen as part of a phishing attack which used typosquatting.</p> +<p>It is therefore of use for us to detect so called typosquatting attacks as they appear over the network. We have had for some time, through the flatfile loader and open source typosquatting generation tools such as <a class="externalLink" href="https://github.com/elceef/dnstwist";>DNS Twist</a>, the ability to generated potential typosquatted domains, import them into HBase and look them up via <tt>ENRICHMENT_EXISTS</tt>.</p> +<p>There are some challenges with this approach, though entirely viable:</p> +<ul> + +<li>Even for modest numbers of domains, the number of records can grow quite large. The Top Alexa 10k domains has on the order of 3 million potential typosquatted domains.</li> +<li>It still requires a network hop if out of cache.</li> +</ul> +<p><a name="The_Tools_Metron_Provides"></a></p> +<h1>The Tools Metron Provides</h1> +<div class="section"> +<h2><a name="Bloom_Filters"></a>Bloom Filters</h2> +<p>It would be nice to have a local solution for these types of problems that may tradeoff accuracy for better locality and space. Those who have been following the general theme of Metron’s analytics philosophy will see that we are likely in the domain where a probabalistic sketching data structure is in order. In this case, we are asking simple existence queries, so a <a class="externalLink" href="https://en.wikipedia.org/wiki/Bloom_filter";>Bloom Filter</a> fits well here.</p> +<p>In Metron, we have the ability to create, add and merge bloom filters via:</p> +<ul> + +<li><tt>BLOOM_INIT( size, fpp)</tt> - Creates a bloom filter to handle <tt>size</tt> number of elements with <tt>fpp</tt> probability of false positives (<tt>0 < fpp < 1</tt>).</li> +<li><tt>BLOOM_ADD( filter, object)</tt> - Add an item to an existing bloom filter.</li> +<li><tt>BLOOM_MERGE( filters )</tt> - Merge a <tt>filters</tt>, a list of Bloom Filters.</li> +</ul></div> +<div class="section"> +<h2><a name="Typosquatting_Domain_Generation"></a>Typosquatting Domain Generation</h2> +<p>Now that we have a suitable data structure, we need a way to generate potential typosquatted domains for a given domain. Following the good work of <a class="externalLink" href="https://github.com/elceef/dnstwist";>DNS Twist</a>, we have ported their set of typosquatting strategies to Metron:</p> +<ul> + +<li>Bitsquatting - See <a class="externalLink" href="http://dinaburg.org/bitsquatting.html";>here</a></li> +<li>Homoglyphs - Substituting characters for ascii or unicode analogues which are visually similar (e.g. <tt>latlmes.com</tt> for <tt>latimes.com</tt> as above)</li> +<li>Subdomain - Making part of the domain a subdomain (e.g. <tt>am.azon.com</tt>)</li> +<li>Hyphenation</li> +<li>Insertion</li> +<li>Addition</li> +<li>Omission</li> +<li>Repetition</li> +<li>Replacement</li> +<li>Transposition</li> +<li>Vowel swapping</li> +</ul> +<p>The Stellar function in Metron is <tt>DOMAIN_TYPOSQUAT( domain )</tt>. It is recommended to remove the TLD from the domain. You can see it in action here with our rick roll example above:</p> + +<div> +<div> +<pre class="source">[Stellar]>>> 'latlmes' in DOMAIN_TYPOSQUAT( 'latimes') +true +</pre></div></div> +</div> +<div class="section"> +<h2><a name="Generating_Summaries"></a>Generating Summaries</h2> +<p>We need a way to generate the summary sketches from flat data for this to work. This is similar to, but somewhat different from, loading flat data into HBase. Instead of each row in the file being loaded generating a record in HBase, what we want is for each record to contribute to the summary sketch and at the end to write out the summary sketch.</p> +<p>For this purpose, we have a new utility <tt>$METRON_HOME/bin/flatfile_summarizer.sh</tt> to accompany <tt>$METRON_HOME/bin/flatfile_loader.sh</tt>. The same extractor config is used, but we have 3 new configuration options:</p> +<ul> + +<li><tt>state_init</tt> - Allows a state object to be initialized. This is a string, so a single expression is created. The output of this expression will be available as the <tt>state</tt> variable.</li> +<li><tt>state_update</tt> - Allows a state object to be updated. This is a map, so you can have temporary variables here. Note that you can reference the <tt>state</tt> variable from this.</li> +<li><tt>state_merge</tt> - Allows a list of states to be merged. This is a string, so a single expression. There is a special field called <tt>states</tt> available, which is a list of the states (one per thread). If this is not in existence, the number of threads is bound to one.</li> +</ul> +<p>Just as with <tt>flatfile_loader.sh</tt>, you can specify the number of threads (via <tt>-p</tt>) and batch size (via <tt>-b</tt>), but now you have the opportunity to specify the output destination (via <tt>-o</tt>) and the output mode (via <tt>-om</tt>). The current output modes are:</p> +<ul> + +<li><tt>LOCAL</tt> - The default, to local disk.</li> +<li><tt>CONSOLE</tt> - Write the object summarized out to std out. This is useful to get summary statistics about the data imported. For instance, you could determine how many typosquatted domains there are for the Alexa 10k.</li> +<li><tt>HDFS</tt></li> +</ul></div> +<div class="section"> +<h2><a name="Reading_Summaries_In-Stream"></a>Reading Summaries In-Stream</h2> +<p>These summaries are immutable data and are stored in HDFS. We want to read them in and cache them for later, so a new stellar function called <tt>OBJECT_GET( hdfs_path )</tt> will allow you to read the data from HDFS and deserialize the data into an object which can be used. Subsequent calls for the next 24 hours (by default, defaults of the cache can be changed in the global config) will be read from the static cache.</p> +<p>For instance, if you have used the <tt>flatfile_summarizer.sh</tt> utility described above to write out an object to <tt>/apps/metron/objects/alexa_10k_filter.ser</tt>, you can read and deserialize this object and use the bloom filter to determine if the domain <tt>goggle</tt> is a typosquatted domain:</p> + +<div> +<div> +<pre class="source">BLOOM_EXISTS( OBJECT_GET('/apps/metron/objects/alexa_10k_filter.ser'), 'goggle') +</pre></div></div> + +<p><a name="Example"></a></p> +<h1>Example</h1> +<p>In the following demo, we will:</p> +<ul> + +<li>Generate summary data from the top 10k Alexa domains in a Bloom Filter</li> +<li>Use this to detect potential typosquatting instances in proxy data</li> +</ul></div> +<div class="section"> +<h2><a name="Preliminaries"></a>Preliminaries</h2> +<p>We assume that the following environment variables are set:</p> +<ul> + +<li><tt>METRON_HOME</tt> - the home directory for metron</li> +<li><tt>ZOOKEEPER</tt> - The zookeeper quorum (comma separated with port specified: e.g. <tt>node1:2181</tt> for full-dev)</li> +<li><tt>BROKERLIST</tt> - The Kafka broker list (comma separated with port specified: e.g. <tt>node1:6667</tt> for full-dev)</li> +<li><tt>ES_HOST</tt> - The elasticsearch master (and port) e.g. <tt>node1:9200</tt> for full-dev.</li> +</ul> +<p>Also, this does not assume that you are using a kerberized cluster. If you are, then the parser start command will adjust slightly to include the security protocol.</p> +<p>Before editing configurations, be sure to pull the configs from zookeeper locally via</p> + +<div> +<div> +<pre class="source">$METRON_HOME/bin/zk_load_configs.sh --mode PULL -z $ZOOKEEPER -o $METRON_HOME/config/zookeeper/ -f +</pre></div></div> + +<p>If you are doing this on full-dev, I’d recommend stopping existing parsers and the profiler to free up resources. You can do this in Ambari.</p></div> +<div class="section"> +<h2><a name="Install_Squid_Proxy"></a>Install Squid Proxy</h2> +<p>Before starting, we’re going to need to install and start squid by executing the following commands:</p> +<ul> + +<li><tt>yum install -y squid</tt></li> +<li><tt>service squid start</tt></li> +</ul></div> +<div class="section"> +<h2><a name="Retrieve_Alexa_Data"></a>Retrieve Alexa Data</h2> +<p>From the Metron access node in <tt>~</tt>, retrieve the <a class="externalLink" href="https://en.wikipedia.org/wiki/Alexa_Internet";>Alexa top domains</a> data via:</p> + +<div> +<div> +<pre class="source">cd ~ +wget http://s3.amazonaws.com/alexa-static/top-1m.csv.zip +unzip top-1m.csv.zip +head -n 10000 top-1m.csv > top-10k.csv +</pre></div></div> + +<p>You should now have a file <tt>~/top-10k.csv</tt> which contains the top 10,000 domains as per <a class="externalLink" href="https://en.wikipedia.org/wiki/Alexa_Internet";>Alexa</a>.</p></div> +<div class="section"> +<h2><a name="Summarize"></a>Summarize</h2> +<div class="section"> +<h3><a name="Configure_the_Bloom_Filter"></a>Configure the Bloom Filter</h3> +<p>In order to configure the bloom filter, we need to know two things:</p> +<ol style="list-style-type: decimal"> + +<li>Roughly how many elements are going into the bloom filter (an upper bound will do)</li> +<li>What kind of false positive probability do we want?</li> +</ol> +<p>Both of these are going to inform how large the bloom filter is going to be. We can decide 2, but 1 is going to require some computation. Let’s use the <tt>CONSOLE</tt> output mode of the <tt>flatfile_summarizer.sh</tt> to count the number of typosquatted domains across the entire document.</p> +<p>Create a file <tt>~/extractor_count.json</tt> with the following content:</p> + +<div> +<div> +<pre class="source">{ + "config" : { + "columns" : { + "rank" : 0, + "domain" : 1 + }, + "value_transform" : { + "domain" : "DOMAIN_REMOVE_TLD(domain)" + }, + "value_filter" : "LENGTH(domain) > 0", + "state_init" : "0L", + "state_update" : { + "state" : "state + LENGTH( DOMAIN_TYPOSQUAT( domain ))" + }, + "state_merge" : "REDUCE(states, (s, x) -> s + x, 0)", + "separator" : "," + }, + "extractor" : "CSV" +} +</pre></div></div> + +<p>In this extractor config we are using the CSV extractor with the following config properties:</p> +<ul> + +<li><tt>columns</tt> - Indicates the schema of the CSV. There are 2 columns, <tt>rank</tt> at the first position and <tt>domain</tt> at the second position.</li> +<li><tt>separator</tt> - Use a comma to separate the columns.</li> +<li><tt>value_transform</tt> - For each row, transform each <tt>domain</tt> column by removing the TLD.</li> +<li><tt>value_filter</tt> - Only consider non-empty domains</li> +<li><tt>state_init</tt> - Initialize the state, a long integer, to 0.</li> +<li><tt>state_update</tt> - For each row in the CSV, update the state, which is the running partial sum, with the number of typosquatted domains for the domain</li> +<li><tt>state_merge</tt> - For each thread, we have a partial sum, we want to merge the partial sums into the total.</li> +</ul> +<p>We can run this via:</p> + +<div> +<div> +<pre class="source">$METRON_HOME/bin/flatfile_summarizer.sh -i ~/top-10k.csv -e ~/extractor_count.json -p 5 -om CONSOLE +</pre></div></div> + +<p>The output should be something like:</p> + +<div> +<div> +<pre class="source">17/12/22 17:05:19 WARN extractor.TransformFilterExtractorDecorator: Unable to setup zookeeper client - zk_quorum url not provided. **This will limit some Stellar functionality** + +Processing /root/top-10k.csv +17/12/22 17:05:20 WARN resolver.BaseFunctionResolver: Using System classloader +Processed 9999 - \ +3496552 +</pre></div></div> + +<p>So, we the total number of possible elements in the bloom filter summary, <tt>3,496,552</tt>.</p></div> +<div class="section"> +<h3><a name="Generate_the_Bloom_Filter"></a>Generate the Bloom Filter</h3> +<p>Now we can generate the bloom filter on HDFS. As before, we will adapt our previous extractor config to generate the bloom filter rather than the sum of the typosquatted domains.</p> +<p>Create a file <tt>~/extractor_filter.json</tt> with the following contents:</p> + +<div> +<div> +<pre class="source">{ + "config" : { + "columns" : { + "rank" : 0, + "domain" : 1 + }, + "value_transform" : { + "domain" : "DOMAIN_REMOVE_TLD(domain)" + }, + "value_filter" : "LENGTH(domain) > 0", + "state_init" : "BLOOM_INIT(3496552, 0.001)", + "state_update" : { + "state" : "REDUCE( DOMAIN_TYPOSQUAT( domain ), (s, x) -> BLOOM_ADD(s, x), state)" + }, + "state_merge" : "BLOOM_MERGE(states)", + "separator" : "," + }, + "extractor" : "CSV" +} +</pre></div></div> + +<p>Most of the configs are the same, but there are three that are different:</p> +<ul> + +<li><tt>state_init</tt> - We have changed our state to be a bloom filter, initialized with +<ul> + +<li><tt>3496552</tt> - the size calculated in the previous step</li> +<li><tt>0.001</tt> - The false positive probability (<tt>0.1%</tt>)</li> +</ul> +</li> +<li><tt>state_update</tt> - Update the bloom filter (the <tt>state</tt> variable) with each typosquatted domain</li> +<li><tt>state_merge</tt> - Merge the bloom filters generated per thread into a final, single bloom filter to be written.</li> +</ul> +<p>Now we can generate the bloom filter in HDFS at <tt>/tmp/reference/alexa10k_filter.ser</tt> via</p> + +<div> +<div> +<pre class="source">$METRON_HOME/bin/flatfile_summarizer.sh -i ~/top-10k.csv -o /tmp/reference/alexa10k_filter.ser -e ~/extractor_filter.json -p 5 -om HDFS +</pre></div></div> + +<p>You can try out the object to ensure it functions as expected via the Stellar REPL (<tt>$METRON_HOME/bin/stellar -z $ZOOKEEPER</tt>):</p> + +<div> +<div> +<pre class="source">[Stellar]>>> BLOOM_EXISTS(OBJECT_GET('/tmp/reference/alexa10k_filter.ser'), 'gogle') +true +[Stellar]>>> BLOOM_EXISTS(OBJECT_GET('/tmp/reference/alexa10k_filter.ser'), 'google') +false +[Stellar]>>> BLOOM_EXISTS(OBJECT_GET('/tmp/reference/alexa10k_filter.ser'), 'github') +false +[Stellar]>>> BLOOM_EXISTS(OBJECT_GET('/tmp/reference/alexa10k_filter.ser'), 'gituub') +true +</pre></div></div> + +<p>Notice the lag on the first call is more substantial than the subsequent calls as they are pulled from the cache.</p></div></div> +<div class="section"> +<h2><a name="Parser"></a>Parser</h2> +<p>Start the squid parser via:</p> +<ul> + +<li>Create the squid topic: <tt>/usr/hdp/current/kafka-broker/bin/kafka-topics.sh --zookeeper $ZOOKEEPER --create --topic squid --partitions 1 --replication-factor 1</tt></li> +<li>Start the squid parser: <tt>$METRON_HOME/bin/start_parser_topology.sh -z $ZOOKEEPER -s squid</tt></li> +</ul></div> +<div class="section"> +<h2><a name="Set_up_Enrichment.2C_Threat_Intel_and_Threat_Triage"></a>Set up Enrichment, Threat Intel and Threat Triage</h2> +<p>Now that we have squid parser running, we should create an enrichment to add a field <tt>is_potential_typosquat</tt> which determines if the domain is potentially a typosquatted domain. Furthermore, we should set an alert if it’s so and triage those messages.</p> +<p>We can do this by creating <tt>$METRON_HOME/config/zookeeper/enrichments/squid.json</tt> with the following content:</p> + +<div> +<div> +<pre class="source">{ + "enrichment": { + "fieldMap": { + "stellar" : { + "config" : [ + "domain_without_tld := DOMAIN_REMOVE_TLD(domain_without_subdomains)", + "is_potential_typosquat := BLOOM_EXISTS(OBJECT_GET('/tmp/reference/alexa10k_filter.ser'), domain_without_tld)", + "domain_without_tld := null" + ] + } + } + ,"fieldToTypeMap": { } + }, + "threatIntel": { + "fieldMap": { + "stellar" : { + "config" : [ + "is_alert := (exists(is_alert) && is_alert) || is_potential_typosquat" + ] + } + + }, + "fieldToTypeMap": { }, + "triageConfig" : { + "riskLevelRules" : [ + { + "name" : "Alexa 10k Typosquat Bloom", + "comment" : "Inspect a bloom filter with potentially typosquatted domains from the top Alexa 10k", + "rule" : "is_potential_typosquat != null && is_potential_typosquat", + "score" : 10, + "reason" : "FORMAT('%s is a potential typosquatted domain from the top 10k domains from alexa', domain_without_subdomains)" + } + ], + "aggregator" : "MAX" + } + } +} + +</pre></div></div> + +<p>As you can see, following the pattern of enrichments the following are done:</p> +<ul> + +<li>A new field <tt>is_potential_typosquat</tt> is created which indicates whether the domain sans TLD and subdomains is a typosquatted domain according to our bloom filter of the top 10k Alexa domains</li> +<li><tt>is_alert</tt> is updated based on the <tt>is_potential_typosquat</tt> field</li> +<li>A new threat triage rule is added to give the analyst sufficient context if this alert triggers and a score of 10.</li> +</ul> +<p>Push the configs via <tt>$METRON_HOME/bin/zk_load_configs.sh -m PUSH -i $METRON_HOME/config/zookeeper -z $ZOOKEEPER</tt></p></div> +<div class="section"> +<h2><a name="Setup_Indices"></a>Setup Indices</h2> +<p>We have to adjust the mappings for the indices we just created to add the <tt>alert</tt> nested property and ensure each of our properties gets the right type. One does not want to rely entirely on elasticsearch to guess the right types. We will do that by specifying a template:</p> + +<div> +<div> +<pre class="source">curl -XPOST "http://$ES_HOST/_template/squid_index" -d '{ + "template": "squid_index*", + "mappings": { + "squid_doc": { + "dynamic_templates": [ + { + "timestamps": { + "match": "*:ts", + "match_mapping_type": "*", + "mapping": { + "type": "date", + "format": "epoch_millis" + } + } + }, + { + "threat_triage_score": { + "mapping": { + "type": "float" + }, + "match": "threat:triage:*score", + "match_mapping_type": "*" + } + }, + { + "threat_triage_reason": { + "mapping": { + "type": "text", + "fielddata": "true" + }, + "match": "threat:triage:rules:*:reason", + "match_mapping_type": "*" + } + } + ], + "properties" : { + "action" : { + "type" : "text","fielddata" : true + }, + "bytes" : { + "type" : "long" + }, + "code" : { + "type" : "long" + }, + "domain_without_subdomains" : { + "type" : "text","fielddata" : true + }, + "elapsed" : { + "type" : "long" + }, + "full_hostname" : { + "type" : "text","fielddata" : true + }, + "guid" : { + "type" : "keyword" + }, + "ip_dst_addr" : { + "type" : "ip" + }, + "ip_src_addr" : { + "type" : "ip" + }, + "is_alert" : { + "type" : "text","fielddata" : true + }, + "is_potential_typosquat" : { + "type" : "boolean" + }, + "method" : { + "type" : "text","fielddata" : true + }, + "original_text" : { + "type" : "text","fielddata" : true + }, + "source:type" : { + "type" : "keyword" + }, + "timestamp" : { + "type" : "date", + "format": "epoch_millis" + }, + "url" : { + "type" : "text","fielddata" : true + }, + "alert" : { + "type" : "nested" + } + } + } + } +}' +</pre></div></div> +</div> +<div class="section"> +<h2><a name="Generate_Sample_Data"></a>Generate Sample Data</h2> +<p>We can now use <tt>squidclient</tt> to visit a regular domain and typosquatted domain and send the data to kafka:</p> + +<div> +<div> +<pre class="source">squidclient http://www.github.com +squidclient http://gituub.com/apache/metron +cat /var/log/squid/access.log | /usr/hdp/current/kafka-broker/bin/kafka-console-producer.sh --broker-list $BROKERLIST --topic squid +</pre></div></div> +</div> +<div class="section"> +<h2><a name="Investigate_via_the_Alerts_UI"></a>Investigate via the Alerts UI</h2> +<p>We should now have data in our elasticsearch indices, so let’s investigate via the alerts UI.<br /> +We can visit the Alerts UI (find the link from Ambari if not on full-dev. If on full-dev, go <a class="externalLink" href="http://node1:4201/alerts-list";>here</a>.</p> +<p>From there you should see the following data from squid with one as an alert and the other not</p> +<p><img src="squid_search.png" alt="Alerts" /></p> +<p>Now, if you drill down into the alert, you can see our fields and the reasons specified</p> +<p><img src="drill_down.png" alt="Drill Down" /></p></div> + </div> + </div> + </div> + <hr/> + <footer> + <div class="container-fluid"> + <div class="row-fluid"> +é 2015-2016 The Apache Software Foundation. Apache Metron, Metron, Apache, the Apache feather logo, + and the Apache Metron project logo are trademarks of The Apache Software Foundation. + </div> + </div> + </footer> + </body> +</html> http://git-wip-us.apache.org/repos/asf/metron/blob/ae1d3eb9/site/documentation/index.md ---------------------------------------------------------------------- diff --git a/site/documentation/index.md b/site/documentation/index.md index e44953c..585f656 100644 --- a/site/documentation/index.md +++ b/site/documentation/index.md @@ -74,24 +74,24 @@ title: Apache Metron Documentation <section class="events-section info-block darken" id="releases"> <div class="wrapper downloads"> <div class="text-center"> - <h4>Current Release: 0.4.2</h4> + <h4>Current Release: 0.5.0</h4> </div> <div class="content-960 hover-btn text-center"> <ul> <li> - <a href="http://www.apache.org/dyn/closer.cgi/metron/0.4.2/apache-metron-0.4.2.tar.gz"; target="new"> - apache-metron-0.4.2.tar.gz + <a href="http://www.apache.org/dyn/closer.cgi/metron/0.5.0/apache-metron-0.5.0.tar.gz"; target="new"> + apache-metron-0.5.0.tar.gz </a> - [ <a href="https://dist.apache.org/repos/dist/release/metron/0.4.2/apache-metron-0.4.2.tar.gz.asc"; target="new"> + [ <a href="https://dist.apache.org/repos/dist/release/metron/0.5.0/apache-metron-0.5.0.tar.gz.asc"; target="new"> PGP </a>] - [ <a href="https://dist.apache.org/repos/dist/release/metron/0.4.2/apache-metron-0.4.2.tar.gz.sha1"; target="new"> + [ <a href="https://dist.apache.org/repos/dist/release/metron/0.5.0/apache-metron-0.5.0.tar.gz.sha1"; target="new"> SHA </a>] - [ <a href="https://dist.apache.org/repos/dist/release/metron/0.4.2/apache-metron-0.4.2.tar.gz.sha512"; target="new"> + [ <a href="https://dist.apache.org/repos/dist/release/metron/0.5.0/apache-metron-0.5.0.tar.gz.sha512"; target="new"> SHA512 </a>] - [ <a href="https://dist.apache.org/repos/dist/release/metron/0.4.2/apache-metron-0.4.2.tar.gz.md5"; target="new"> + [ <a href="https://dist.apache.org/repos/dist/release/metron/0.5.0/apache-metron-0.5.0.tar.gz.md5"; target="new"> MD5 </a>] [ <a href="/current-book/index.html" target="new"> Book </a>]
