Integrations

Nanitor is able to collaborate and share information with other third-party tools and communication platforms such as email. Not all IT security personnel or other responsible staff may use Nanitor on a daily basis, but it is important to be able to keep them informed of security incidents. Being able to react to newly detected security threats without manually opening the software increases the efficiency of Nanitor as a vulnerability management solution and improves the security of your company.

Nanitor offers some native integrations that allow pushing information directly to other applications. These native integrations are limited to Slack at the moment with more to come in the future. The ability to push notifications via email makes it possible to work with applications that support email import.

Another option to communicate with other applications is through the available public API. The public API makes it possible to pull information on monitored assets and detected issues from Nanitor. Leveraging the public API offers a broader range of use cases and presents no limit to the applications that Nanitor can communicate with, as long as those applications are able to import data from an API endpoint. In order to be able to retrieve information from a Nanitor API endpoint you will need an API key.

This article briefly describes how to use these integrations by setting up notification rules that will push information from Nanitor to the integrated applications. There will also be a short guide on how to leverage and use the public API. This should help you get started for a better-integrated way of working with Nanitor and sharing critical information with other stakeholders.

Slack

Slack is a commonly used communication platform. It is often used for internal communications and can be leveraged to link multiple organizations together by sharing Slack channels. Slack channels can be either private or public.

When setting up an integration to Slack you need to choose a dedicated Slack channel to which Nanitor should publish its alerts. It is best to set up the Slack integration as a Slack application for the Slack workspace being used by the organization. Detailed information on how that can be achieved can be found in the help center article for setting up the Slack integration.

Alerts

Nanitor has a powerful event bus that can be leveraged to push information to integrated applications (e.g. Slack), a custom webhook URL, or one or more email addresses. Note that to be alerted via a Slack channel, you will first have to set up a Slack application and a dedicated Slack channel to receive alerts, as described above.

Alert rules can be set up from Organization Management -> Alert rules. They are generally used to send alerts about issues being found or resolved, either in the organization as a whole or on assets with a specific label, and can be filtered by priority (for example, to get alerts only about P0 issues). It is also possible to set up alert rules for particular Nanitor remediation projects, to be notified when issues assigned to that project are added or resolved.

To create a new alert rule, click Create rule. In the pop-up window, define a rule set that the Nanitor event bus should listen to and where the notification should be sent. This can be one or more email addresses, a Slack webhook, or a custom webhook URL.

You can click the Send test alert button to send a test alert to all defined recipients, or the envelope icon on a particular recipient to send a test alert to only that recipient for troubleshooting.

More detailed information on exactly how to set up and configure an alert rule can be found in the help center documentation.

Custom alert webhooks

If you choose to create a custom webhook alert rule, Nanitor will send a POST request to the given webhook URL when an alert is triggered. The payload of the POST request will be JSON, which will look something like this:

{
  "subject": "...",
  "markdown_text": "...",
  "plain_text": "...",
  "events": [{
    "time": "xxxx-xx-xxTxx:xx:xxZ",
    "event_name": "...",
    "message": "...",
    "event_type": "...",
    "event_trigger": "...",
    "event_data": {
      ...
    },
    "severity": "...",
    "address": "x.x.x.x",
    "device": {
      "id": 123,
      "hostname": "...",
      "hostname_display": "...",
      "fqdn": "...",
      "ip_addresses": ["x.x.x.x", ...]
    },
    "user": {
      "id": 12,
      "email": "...",
      "full_name": "..."
    },
    "sub_events": [
      {
        ...
      }
    ]
  }]
}

Note that this payload format is not designed to be plugged directly into any particular webhook API. In most cases, it will be necessary to create a custom webhook handler service that forwards whatever data is desired to whatever third-party service your organization wishes to integrate with. Nanitor support may be able to assist with your particular integration.

The JSON properties are as follows:

subject

The subject of the alert. This will be a simple plaintext line that will match the subject of an e-mail alert, summarizing what the alert is about. It will include the slug of the affected organization and a summary line such as "3 issues created". This is suitable to use as a short, single-line text notification that could be posted to a general channel in a chat application or used as a push notification.

markdown_text

The full text of the alert, formatted in Markdown. The text will vary depending on the alert; it may for example list newly created issues and link to them, list a set of related events, or list more detail about a single event. This is suitable for posting to something like a dedicated channel for alerts in a chat application that supports Markdown.

plain_text

A plaintext representation of the alert, usually a simple text representation. This will match the subject for an alert representing a single event, while otherwise it will list the hypothetical subjects of individual alerts for those events, if they had been sent out individually. This is generally suitable for posting to a dedicated channel for alerts in a chat application that does not support Markdown.

events

A list of events this alert is for. If a number of issues are opened simultaneously or near-simultaneously, for instance, then only a single alert will be sent, but the events property will contain the events for each of those issues. Events attached to alerts are the same as the events logged in Nanitor's Activity Log.

Each event has a number of properties:

events.time

The UTC timestamp of the event, in ISO 8601 format.

events.event_name

A string representing the type of event this is, such as patch_incident_created or device_decommissioned. These generally resemble the title of the event in Nanitor's Activity Log.

events.message

A text message representing this event, matching the message in Nanitor's Activity Log.

events.event_type

Either "security" or "audit". Security events are events indicating a security-related incident on an asset, whereas audit events exist to create a trail for auditing purposes.

events.event_trigger

Either "user" or "system". User events are triggered when a user performs an action within the Nanitor system, while system events are triggered automatically by the system.

events.event_data

An object of event data. This data will vary depending on the event; see the Nanitor Activity Log for examples of the type of data included.

events.severity

Either "high", "medium" or "low", depending on how important this event is considered to be.

events.address

The IP address that triggered this event, either the IP address of the user session that performed a user action or the IP address of the asset that triggered a system event.

events.device

The device (asset) that triggered this event (may be empty, for an event not associated with a device). The device has its own properties, if present:

events.device.id

The ID of the device in Nanitor's system.

events.device.hostname

The true hostname reported by the device.

events.device.hostname_display

The display hostname used within Nanitor's system (may have been manually overridden by a Nanitor user).

events.device.fqdn

The fully qualified domain name of the device, if any.

events.device.ip_addresses

A list of internal IP addresses used by this device.

events.user

The Nanitor user who triggered the event, if any. The user has their own properties, if present:

events.user.id

The ID of the user in Nanitor's system.

events.user.emeail

The e-mail address of the user in Nanitor's system.

events.user.full_name

The full name of the user in Nanitor's system.

events.sub_events

Sometimes multiple events of different types are associated with the same concrete event. For instance, if an all-new patch issue is discovered on some devices simultaneously or near-simultaneously, then the system will create both a set of patch events, each indicating that the status of a patch has changed on a given device, and a patch_incident_created event indicating that a new patch issue has been opened. The alert sent out would be primarily about the more important patch_incident_created event, but the associated patch events will also be included under sub_events. Each sub-event has the same properties as a top-level event.

Public API

The public API is another way to bring information from Nanitor to a third-party application. Any application can use the Nanitor REST API to pull information on monitored assets or detected issues in a programmatic way. Leveraging the REST API requires an API key for authentication purposes. Obtaining an API key is described in detail in the corresponding article in the help center.

All available REST API endpoints are documented in the Nanaitor REST API documentation. Currently, there are three available endpoints for assets and two for issues.