.. index:: !Alert

Alerts
======

With the use of alerts the state and results of a scan can be sent to others systems automatically.
Alerts are anchored within the system in a way that each configured event will trigger an action, for example, when a task is started or completed.
Additionally this can be tied to a condition.
This could be the discovery of a vulnerability of a severity greater than 9.
If met, an email or a SNMP trap can be triggered.

To create an alert change to :gos:webui:`Configuration`/:gos:webui:`Alerts`.
Now add a new alert |new|.

.. figure:: images-3.1/new-alert.png
   :align: center
   :width: 100%

   Alerts offer various alerting options.

Now, the following can be defined:

Name:
   The name, describing the alert, can be freely chosen

Comment:
   The optional comment can contain additional information.

Event:
   Here the event, for which the alert message is being sent, is being defined.
   For example, this can occur when the status of a task changes.

Condition:
   Here additional conditions, that have to be met, are being defined.
   The alert message can occur:

   * Always
   * Only when at minimum a specific severity level is reached.
   * If the severity level changes, increases or decreases.

   .. _fig:alert_activation:

   .. figure:: images-3.1/alert-task.png
      :align: center
      :width: 70%

      Alerts must be activated in their respective task.

Method:
   Here the method for the alert is selected.
   Only one method per alert can be chosen.
   If different alerts for the same event should be triggered, multiple alerts must be created and linked to the same task.

   Email
      This is the most powerful and most used method.
      To use this method the mailserver to be used must be defined in the GSM command line (see section :ref:`mail_server`).
      Then you can chose between the following options:

      To Address:
         This is the email address to which the email should be sent to.

      From Address:
         This is the sender address of the generated email.

      Subject:
         This is the subject of the email. You can use variables like $n (task name) and $e (event description).
	 
      Content:
         Here the content of the email can be defined:

         Simple Notice:
            This is only a simple description of the event.

         Include Report:
            If the event for the completion of the task (Default: Done) is selected the report can be included in the email.
            Here a report format that uses the content type :mimetype:`text/\*` can be chosen as an email does not support binary content directly.
	    Additionally you can modify the contents of the email message. 
	    Within the message you may use variables:

	      * $c condtion description
	      *	$e event description
	      *	$F name of filter
	      *	$f filter term
	      *	$H host summary
	      *	$i report text
	      *	$n task name
	      *	$r report format name
	      *	$t a note if the report was truncated
	      *	$z timezone
		
         Attach Report:
            If the event for the completion of the task (Default: Done) is selected the report can be attached to the email.
            Here any report format can be chosen.
            The report will be attached in its correct MIME type to the generated email.
            PDF is possible as well.
	    Additionally you can modify the contents of the email message. The same variables may be used.

   System Logger
      This method allows for the sending of the alert to a Syslog daemon or via a SNMP trap automatically.
      The Syslog server as well as the SNMP trap service are defined via the command line (see section :ref:`central_logging` and :ref:`SNMP`).

   HTTP Get
      With the HTTP Get method, for example, an SMS text message or a message to a trouble ticket system can be sent automatically.
      The following variables can be used when specifying the URL:

      * ``$n``: Name of the task
      * ``$e``: Description of the event (Start, Stop, Done)
      * ``$c``: Description of the condition that occurred
      * ``$$``: The $ symbol

   .. _fig:alert_task2:

   .. figure:: images-3.0/alert-task2.png
      :align: center
      :width: 100%

      In an alert its use within different tasks can be referenced.

   Sourcefire Connector
      Here the data can be sent automatically to a Sourcefire Defense Center.
      For more information see section :ref:`sourcefire`.

   verinice.PRO Connector
      Here the data can be sent automatically to a verinice.PRO installation.
      For more information see section :ref:`verinice`.


Report Result Filter
   Finally the results can be limited with an additional filter.
   A filter must be created and saved prior (see section :ref:`Powerfilter`).


For the alert to be used afterwards, a specific task definition must be created (see figure :ref:`fig:alert_activation`).
To do so edit the respective task.
This change of the task is also allowed for already defined and used tasks as it does not have any effect on already created reports.

Afterwards the respective alert displays that it is in use as well (see figure :ref:`fig:alert_task2`).