| <!DOCTYPE html> |
| <!-- |
| | Generated by Apache Maven Doxia Site Renderer 1.8 from src/site/markdown/metron-interface/metron-alerts/index.md at 2018-12-14 |
| | 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="20181214" /> |
| <meta http-equiv="Content-Language" content="en" /> |
| <title>Metron – </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 "></li> |
| <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2018-12-14</li> |
| <li id="projectVersion" class="pull-right">Version: 0.7.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 class="active"><a href="#"><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-right"></span>Use-cases</a></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. |
| --> |
| <ul> |
| |
| <li><a href="#Caveats">Caveats</a></li> |
| <li><a href="#Prerequisites">Prerequisites</a></li> |
| <li><a href="#Development_Setup">Development Setup</a></li> |
| <li><a href="#E2E_Tests">E2E Tests</a></li> |
| <li><a href="#Mpack_Integration">Mpack Integration</a></li> |
| <li><a href="#Installing_on_an_existing_Cluster">Installing on an existing Cluster</a></li> |
| </ul> |
| <div class="section"> |
| <h2><a name="Caveats"></a>Caveats</h2> |
| <div class="section"> |
| <h3><a name="Local_Storage"></a>Local Storage</h3> |
| <p>UI uses local storage to save all the data. A middleware needs to be designed and developed for persisting the data</p></div> |
| <div class="section"> |
| <h3><a name="Search_for_Alert_GUIDs"></a>Search for Alert GUIDs</h3> |
| <p>Alert GUIDs must be double-quoted when being searched on to ensure correctness of results, e.g. guid:“id1”.</p></div> |
| <div class="section"> |
| <h3><a name="Search_for_Comments"></a>Search for Comments</h3> |
| <p>Users cannot search for the contents of the comment’s in the Alerts-UI</p></div> |
| <div class="section"> |
| <h3><a name="Meta_alerts"></a>Meta alerts</h3> |
| <p>Grouping/faceting requests and other aggregations do not return meta alerts. This is because it’s not clear what the intended results should be when there are multiple matching items.</p> |
| <p>Sorting has a similar caveat, in that if we are matching on multiple alerts, there is no well defined sort.</p> |
| <p>Alerts that are contained in a a meta alert are generally excluded from search results, because a user has already grouped them in a meaningful way.</p></div></div> |
| <div class="section"> |
| <h2><a name="Prerequisites"></a>Prerequisites</h2> |
| <ul> |
| |
| <li>The Metron REST application should be up and running</li> |
| <li>Elasticsearch or Solr should have some alerts populated by Metron topologies, depending on which real-time store is enabled</li> |
| <li>The Management UI should be installed (which includes <a class="externalLink" href="https://expressjs.com/">Express</a>)</li> |
| <li>The alerts can be populated using Full Dev or any other setup</li> |
| <li>UI is developed using Angular 6 and uses Angular CLI.</li> |
| <li>nvm (or a similar node verison manager) should be installed. The node version required for this project is listed in the <a class="externalLink" href="https://github.com/creationix/nvm#nvmrc">.nvmrc</a> file.</li> |
| </ul></div> |
| <div class="section"> |
| <h2><a name="Installation"></a>Installation</h2> |
| <div class="section"> |
| <h3><a name="From_Source"></a>From Source</h3> |
| <ol style="list-style-type: decimal"> |
| |
| <li> |
| |
| <p>Package the application with Maven:</p> |
| |
| <div> |
| <div> |
| <pre class="source">cd metron-interface/metron-alerts |
| mvn clean package |
| </pre></div></div> |
| </li> |
| <li> |
| |
| <p>Untar the archive in the $METRON_HOME directory. The directory structure will look like:</p> |
| |
| <div> |
| <div> |
| <pre class="source">bin |
| metron-alerts-ui |
| web |
| expressjs |
| alerts-server.js |
| alerts-ui |
| web assets (html, css, js, ...) |
| </pre></div></div> |
| </li> |
| <li> |
| |
| <p>Copy the <tt>$METRON_HOME/bin/metron-alerts-ui</tt> script to <tt>/etc/init.d/metron-alerts-ui</tt></p> |
| </li> |
| <li> |
| |
| <p><a class="externalLink" href="https://expressjs.com/">Express</a> is installed at <tt>$METRON_HOME/web/expressjs/</tt> as part of the Management UI installation process. The Management UI should be installed first on the same host as the Alerts UI.</p> |
| </li> |
| </ol></div> |
| <div class="section"> |
| <h3><a name="From_Package_Manager"></a>From Package Manager</h3> |
| <ol style="list-style-type: decimal"> |
| |
| <li> |
| |
| <p>Deploy the RPM at <tt>/metron/metron-deployment/packaging/docker/rpm-docker/target/RPMS/noarch/metron-alerts-$METRON_VERSION-*.noarch.rpm</tt></p> |
| </li> |
| <li> |
| |
| <p>Install the RPM with:</p> |
| |
| <div> |
| <div> |
| <pre class="source">rpm -ih metron-alerts-$METRON_VERSION-*.noarch.rpm |
| </pre></div></div> |
| </li> |
| </ol></div> |
| <div class="section"> |
| <h3><a name="From_Ambari_MPack"></a>From Ambari MPack</h3> |
| <p>The Alerts UI is included in the Metron Ambari MPack. It can be accessed through the Quick Links in the Metron service.</p></div></div> |
| <div class="section"> |
| <h2><a name="Configuration"></a>Configuration</h2> |
| <p>The Alerts UI is configured in the <tt>$METRON_HOME/config/alerts_ui.yml</tt> file. Create this file and set the values to match your environment:</p> |
| |
| <div> |
| <div> |
| <pre class="source">port: port the alerts UI will run on |
| |
| rest: |
| host: REST application host |
| port: REST applciation port |
| </pre></div></div> |
| </div> |
| <div class="section"> |
| <h2><a name="Global_Configuration_Properties"></a>Global Configuration Properties</h2> |
| <div class="section"> |
| <h3><a name="source.type.field"></a><tt>source.type.field</tt></h3> |
| <p>The source type field name used in the real-time store. Defaults to <tt>source:type</tt>.</p></div> |
| <div class="section"> |
| <h3><a name="threat.triage.score.field"></a><tt>threat.triage.score.field</tt></h3> |
| <p>The threat triage score field name used in the real-time store. Defaults to <tt>threat:triage:score</tt>.</p></div></div> |
| <div class="section"> |
| <h2><a name="Usage"></a>Usage</h2> |
| <p>After configuration is complete, the Management UI can be managed as a service:</p> |
| |
| <div> |
| <div> |
| <pre class="source">service metron-alerts-ui start |
| </pre></div></div> |
| |
| <p>The application will be available at <a class="externalLink" href="http://host:4201">http://host:4201</a> assuming the port is set to <tt>4201</tt>. Logs can be found at <tt>/var/log/metron/metron-alerts-ui.log</tt>.</p></div> |
| <div class="section"> |
| <h2><a name="Development_Setup"></a>Development Setup</h2> |
| <ol style="list-style-type: decimal"> |
| |
| <li> |
| |
| <p>Switch to the correct node version and install all the dependent node_modules using the following commands</p> |
| |
| <div> |
| <div> |
| <pre class="source">cd metron/metron-interface/metron-alerts |
| nvm use |
| npm ci |
| </pre></div></div> |
| |
| <p>You’re probably wondering why we use the <tt>ci</tt> command instead of <tt>install</tt>. By design, <tt>npm install</tt> will change the lock file every time it is ran. This happens whether or not dependencies have a new release or not because <tt>npm install</tt> still updates a unique identifier within the lock file.</p> |
| <p>To prevent the lock file from being changed, run the <tt>ci</tt> command. This installs the modules listed in the lock file without updating it. The only case when you should run <tt>npm install</tt> is when you want to add a new dependency to the application. You can update dependencies with the <tt>npm update</tt> command.</p> |
| <p><tt>nvm use</tt> will ensure your local node version matches the one specified in the <tt>.nvmrc</tt> file. It doesn’t necessarily mean that you’ll have an npm version installed which includes the <tt>ci</tt> command. Make sure you have the latest npm version which comes with the <tt>ci</tt> command.</p> |
| </li> |
| <li> |
| |
| <p>UI can be run by using the following command</p> |
| |
| <div> |
| <div> |
| <pre class="source">./scripts/start-dev.sh |
| </pre></div></div> |
| </li> |
| <li>You can view the GUI @<a class="externalLink" href="http://localhost:4201">http://localhost:4201</a>. The default credentials for login are admin/password</li> |
| </ol> |
| <p><b>NOTE</b>: <i>In the development mode ui by default connects to REST at <a class="externalLink" href="http://node1:8082">http://node1:8082</a> for fetching data. If you wish to change it you can change the REST url at metron/metron-interface/metron-alerts/proxy.conf.json</i></p></div> |
| <div class="section"> |
| <h2><a name="E2E_Tests"></a>E2E Tests</h2> |
| <div class="section"> |
| <h3><a name="Caveats"></a>Caveats</h3> |
| <ol style="list-style-type: decimal"> |
| |
| <li> |
| |
| <p>E2E tests uses data from full-dev wherever applicable. The tests assume rest-api’s are available @<a class="externalLink" href="http://node1:8082">http://node1:8082</a>. It is recommended to shutdown all other Metron services while running the E2E tests including Parsers, Enrichment, Indexing and the Profiler.</p> |
| </li> |
| <li> |
| |
| <p>E2E tests are run on headless chrome. To see the chrome browser in action, remove the ‘–headless’ parameter of chromeOptions in metron/metron-interface/metron-alerts/protractor.conf.js file</p> |
| </li> |
| <li> |
| |
| <p>E2E tests delete all the data in HBase table ‘metron_update’ and Elastic search index ‘meta_alerts_index’ for testing against its test data</p> |
| </li> |
| <li> |
| |
| <p>E2E tests use <a class="externalLink" href="https://github.com/NickTomlin/protractor-flake">protractor-flake</a> to re-run flaky tests.</p> |
| </li> |
| </ol></div> |
| <div class="section"> |
| <h3><a name="Steps_to_run"></a>Steps to run</h3> |
| <ol style="list-style-type: decimal"> |
| |
| <li> |
| |
| <p>An Express.js server is available for accessing the rest api. Run the e2e webserver:</p> |
| |
| <div> |
| <div> |
| <pre class="source">cd metron/metron-interface/metron-alerts |
| sh ./scripts/start-server-for-e2e.sh |
| </pre></div></div> |
| </li> |
| <li> |
| |
| <p>Run e2e tests using the following command:</p> |
| |
| <div> |
| <div> |
| <pre class="source">cd metron/metron-interface/metron-alerts |
| npm run e2e |
| </pre></div></div> |
| </li> |
| </ol> |
| <p><b>NOTE</b>: <i>e2e tests cover all the general workflows and we will extend them as we need</i></p></div></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> |