| <!DOCTYPE html> |
| <!-- |
| | Generated by Apache Maven Doxia Site Renderer 1.8 from src/site/markdown/metron-interface/metron-alerts/index.md at 2019-05-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="20190514" /> |
| <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: 2019-05-14</li> |
| <li id="projectVersion" class="pull-right">Version: 0.7.1</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/index.html" title="Interface"><span class="icon-chevron-down"></span>Interface</a> |
| <ul class="nav nav-list"> |
| <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> |
| </ul> |
| </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="#Cypress_Tests">Cypress 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 class="section"> |
| <h2><a name="Cypress_Tests"></a>Cypress Tests</h2> |
| <p>Cypress is a test framework that allows developers and test engineers to create E2E or Integration tests and run them inside the browser. It differs from other testing tools by choosing to not use selenium webdriver to control the browser.</p> |
| <p>Cypress is added to our project as a developer dependency. This means it’s installed when you run:</p> |
| |
| <div> |
| <div> |
| <pre class="source">npm ci |
| </pre></div></div> |
| |
| <p>or</p> |
| |
| <div> |
| <div> |
| <pre class="source">npm install |
| </pre></div></div> |
| |
| <p>Currently both Protractor and Cypress tests are available, so the previous section of this text is still relevant. However, in the near future we’re planning to migrate fully to Cypress. You can find the public discussion about this in the following link: <a class="externalLink" href="https://lists.apache.org/thread.html/b6a0272c7809c05e8b7aff20171720e8ec76f8a0e9481169c37a4a4a@%3Cdev.metron.apache.org%3E">Discussion thread</a></p> |
| <div class="section"> |
| <h3><a name="Steps_to_run"></a>Steps to run</h3> |
| <p>The easiest way to run Cypress locally is with the following command:</p> |
| |
| <div> |
| <div> |
| <pre class="source">npm run cypress:ci |
| </pre></div></div> |
| |
| <p>The same command runs on Travis CI as part of our build process.</p> |
| <p>If you would like to get some additional information or run test suites one by one you could start the test server manually</p> |
| |
| <div> |
| <div> |
| <pre class="source">npm run build && npm run start:ci |
| </pre></div></div> |
| |
| <p>and then you can reach the Cypress Dashboard locally with the following command</p> |
| |
| <div> |
| <div> |
| <pre class="source">npm run cypress:open |
| </pre></div></div> |
| |
| <p>From the dashboard, you’ll be able to run tests separately and reach additional information about the test runs.</p></div> |
| <div class="section"> |
| <h3><a name="Learn_more"></a>Learn more</h3> |
| <p>If you like to learn more about Cypress based tests please visit <a class="externalLink" href="http://cypress.io">Cypress.io</a>. You can find more information about debuggin in this <a class="externalLink" href="https://docs.cypress.io/guides/guides/debugging.html#Using-debugger">section of the official documentation</a>.</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> |
