This article contains information and instructions for implementing NS1 DNS Insights. Refer to Intro to NS1 DNS Insights for more information about NS1's network observability solution for NS1 Managed DNS and Dedicated DNS networks.
Note
NS1 DNS Insights is available to purchase for all NS1 Managed DNS and NS1 Dedicated DNS customers. Contact your NS1 Customer Success Manager or complete a contact form here.
During initial implementation, you will create a data sink containing the credentials for the TSDB to which DNS Insights agents will push data. NS1 will use this information to complete the data sink configuration.
If using Grafana for data visualization, you can load the Grafana dashboard provided by NS1 to view DNS Insights data. Alternatively, you can configure your dashboards using your preferred data visualization tools.
-
Option 1: Grafana Cloud (via Prometheus data source)
-
Option 2: Grafana Enterprise Stack (via Prometheus data source)
-
Option 3: Grafana and Prometheus (open-source)
-
Option 4: Other TSDB that supports Prometheus "remote write" (connected to your preferred data visualization tool)
Implementation details may vary depending on the option you choose.
Warning
You must develop your dashboard and analytical tools if you plan to use a TSDB other than Prometheus via Grafana Cloud, open-source versions of Grafana, or Grafana Enterprise. If using an alternative TSDB, NS1’s ability to support you may be limited.
Before implementing DNS Insights, please review the following prerequisites and considerations:
-
You must use a Prometheus or Prometheus-compatible TSDB that supports “remote write” functionality.
-
If using Grafana as your data visualization tool, you must add Prometheus to the appropriate Grafana stack.
-
NS1 DNS Insights provides basic authentication for connections to Prometheus instances. When configuring the integration, you will enter the relevant Prometheus API credentials to enable data pushing from NS1 agents to your TSDB. If you use a TSDB other than Prometheus, you must work directly with NS1 to determine which credentials are required for implementation.
Note
LEVEL OF ACCESS REQUIRED FOR NS1
Prometheus: Orb requires the necessary credentials to perform remote_write operations on the target time series database instance. If you’re using Grafana Cloud, this would be a Grafana Cloud API key with the MetricsPublisher role. This role only provides permission to send log and metric data to Grafana Cloud.
HOW NS1 WILL USE THIS CREDENTIAL
The system will use the access to send data from the DNS Insights service.
DISCLAIMER TEXT
Customers (i) must not provide any greater level of access than described for this feature and (ii) must ensure that no additional data is contained in the environments accessible using the provided credentials than what is required to enable this feature. Customers should review the terms of their agreements with third-party cloud providers that will transmit data to NS1 or receive data from NS1 using this feature to determine whether such third party will impose any fees for the use, transmission, storage, and/or export of such data. NS1 disclaims any and all liability resulting from the provision of credentials to NS1, NS1’s storage of such credentials, and/or the use of such credentials by NS1, including, without limitation, any fees imposed on a Customer’s account with any third party resulting from use of this feature.
Follow the instructions below to configure the DNS Insights integration to begin pushing data to your TSDB and then importing the dashboard(s) to view the collected data in Grafana.
Note
The instructions below reflect the implementation process for Grafana Cloud customers utilizing the built-in Prometheus TSDB. Instructions will vary for those using Grafana Enterprise, open-sourced versions of Grafana and Prometheus, or another TSDB.
Note
Skip this step if you have already configured the Prometheus "remote write" endpoint. Upon creating an account, Grafana will walk you through the creation of a stack, including the Prometheus remote write endpoint, so you may already have one.
-
Log into the Grafana Labs portal.
-
Click an existing stack (or click + Add Stack to create a new stack) on the left sidebar to view and manage the applications within your Grafana stack.
-
Next to the Prometheus application card, click Send Metrics.
The Prometheus instance configuration page displays the URL for the remote write endpoint and your Prometheus username (instance ID).
Note
Note the name of this Prometheus data source at the top of the page. You must select it when importing the DNS Insights dashboard.
-
Scroll down to "Password/API key" and click Generate now.
-
In the "Create an API key" window, enter an API key name (e.g., "ns1_dns_insights_push").
-
Under "Role," select MetricsPublisher.
-
Click Create API key, and then record the autogenerated API key secret. You must apply this token on the NS1 platform during the initial configuration.
-
Click Close.
-
Scroll down to the "Sending Metrics" section. Copy the code under "Prometheus remote_write Configuration" and save the code snippet. The code includes the credentials necessary for NS1 to configure DNS Insights in the next step.
Using the information gathered in the previous step, create a new data sink via the NS1 portal or API. This information is then passed securely to the NS1 team to complete the configuration and push the agents' data to your TSDB.
Note
Grafana users must provide NS1 with the username (instance ID), password (API key), and the remote write endpoint URL for the relevant Prometheus instance. If you are using a TSDB other than Prometheus, work with the NS1 team directly to identify the necessary credentials for setup.
Follow the steps below to add the DNS Insights integration (effectively, sharing your credentials with NS1 so we can complete the configuration) via the NS1 portal.
-
Log into the NS1 portal (https://my.nsone.net) and navigate to DNS > DNS Insights.
-
In the "Add integration" dialog box, enter the following information:
-
Next to Name, enter a name for the integration (for your internal reference only).
-
Under Integration type, select DNS Insights from the drop-down.
-
Under DNS Insights credentials, under Sink type, select Prometheus from the drop-down.
-
Enter your Username / instance ID for the Prometheus instance within your Grafana stack.
-
Enter the Password / API key for your Prometheus instance configured in Step 1.
-
-
Click Add integration.
A green banner indicates the integration was created successfully, and your credentials have been shared with the NS1 team.
NS1 will configure your data sink and the relevant policies with this information. Typically, this takes up to one business day. Once complete, you will receive an email from NS1 customer support.
Run the PUT request below to create the DNS Insights integration (effectively, share your credentials with NS1 so we can complete the configuration) via the NS1 API. You must include a valid NS1 API key in the request header.
curl -X PUT -H "X-NSONE-Key: $NSONE_API_KEY" -d '
{
"name": "string",
"backend": "prometheus",
"description": "string",
"config": {
"remote_host": "example.com",
"username": "string",
"password": "string"
}
}' https://api.nsone.net/v1/insights/sinks
Request body parameters:
|
name string |
(Required) Name of this data sink for internal reference |
|
description string |
A description of this data sink for internal reference. |
|
backend string (enum) |
(Required) Indicates the TSDB to which the DNS Insights agents will send data. Currently, the only supported value is "prometheus". |
|
config object |
(Required) Object containing details and credentials for your TSDB. |
|
remote_host string |
(Required) URL for the Prometheus remote host to which DNS Insights agents will send metrics. |
|
username string |
(Required) Your Prometheus username. |
|
password string |
(Required) A valid API key to access your Prometheus database. If using Grafana, note that the API key must have the “MetricsPublisher” role. |
Follow the steps below to import the DNS Insights dashboard provided by NS1 into your Grafana application.
Note
The screenshots below are of the Grafana Cloud portal; however, the import process is similar for Grafana Enterprise and open-source users.
-
Log into the Grafana Cloud portal or your hosted Grafana instance.
-
Click the + (add) icon from the toolbar on the left and select the Import option.
-
Under "Import via grafana.com," enter the dashboard ID for the relevant DNS Insights dashboard.
-
Enter 17170 for the primary DNS Insights dashboard, which includes all general, DNS-related metrics.
-
Enter 17171 for the DNS Insights dashboard, which focuses on DNS metrics related to detecting DDOS attacks.
-
-
Click Load.
-
Under Theranos Query Frontend, select the name of the relevant Prometheus data source from the drop-down menu. This is the Prometheus data source for which you generated an API key in step 1.
-
Click Import.
The imported dashboard appears.