Web Service Article Meta Filters

Security analysts want to find relevant IPs and other data from messages in existing records, so that they can save time for investigating by using the meta data collector web service interfaces, rather than wasting time for manually searching for existing matches of received IPs or other data, whenever messages contain data for investigation.

The principle of this feature is the same as other article meta filters. Some regular expressions can be defined to call a web service invoker. Depending on the web service and on the external server what the web service calls, the response will contain a list of results. The list of results should come in a particular format so that OTRS can understand. It is highly recommended to use an XSLT mapping for this invoker, so it can convert the results got from the external provider to what we can understand in OTRS.

Setup

The feature can be enabled with the AgentFrontend::TicketDetailView::ArticleMeta setting. This setting is required for the meta filters built in the OTRS framework, but this is also required to the web service article meta filter.

There are three examples in the AgentFrontend::TicketDetailView::ArticleMetaFilters::WebService###0001-OTRSSTORM setting, but all of them are inactive by default. To activate any of them, just change the value of the Active key to 1. It is also necessary to set the correct values for the WebService, Invoker and Payload keys to match the current system.

The first example will search for host names, the second example will search for servers, and the third example will search for IP addresses. You can see what regular expressions are defined in the RegExp array.

There is an other setting AgentFrontend::TicketDetailView::ArticleMetaFilters::WebService###0002-Custom where the administrators can define custom meta filters.

Note

It is not recommended to change or extend the examples, because the built in examples can be changed in the future. Please use the custom setting to define the own meta filters.

In the configuration is needed to specify which web service and which invoker is going to be called. The remote server should return a list of elements. This list will be displayed in a popup window in the article, if the article has some keywords that matches with the configured regular expression. The Payload is the information that OTRS sends to the remote server. This information is specified by the remote web service provider and it could contain static data or the match or matching groups specified in the RegExp array.

It is possible to configure a URL for each item in the list, so the agent has the possibility to go to a website directly with just one click.

STORM comes a builtin invoker type called Generic::ArticleMetaFilter to be used in web services for this specific purpose. Only this type of invoker can be used for this functionality.

Usage

To properly display the results of the article meta filter requests it is highly recommended to add or extend the XSLT inbound mapping to include the list of results in tags called Items consisting in a single or multiple tags.

Example for one item:

<Items>Result 1</Items>

Example for more items:

<Items>Result 1</Items>
<Items>Result 2</Items>
<Items>Result 3</Items>

To search for IP addresses:

  1. Create a web service with the XSLT mapping above to call an external server with the IP addresses. The web service should return a list of something, for example a list of host names associated to the passed IP addresses.
  2. Create a new ticket.
  3. Fill in the required fields.
  4. Enter the following text in the body: Your IP address is 192.168.0.1 and your subnet mask is 255.255.255.0.
  5. Go to the ticket detail view of the newly created ticket.
  6. Expand the first article in the Communication Stream widget to see the buttons below the article.

The web service will search for all possible IP addresses in the article as configured by the regular expression and return a list of host names.

The buttons point to the search results of a web service. This should be returned the same search results when an agent calls the web service with the given IP addresses. The text for the buttons (IP Address in this example) comes from the Label key of the underlying system configuration setting.

If the agents hover the mouse over a button, they will get a preview of the list of results returned by the web service. Clicking on the buttons could open a URL associated to the results.

This feature works for all articles of a ticket.