DNS Armor generates threat logs when suspicious or malicious activity is
detected. You can use Cloud Logging to view and analyze the threat logs and
gain actionable insight. Additionally, when you have a
[DNS threat detector](https://docs.cloud.google.com/dns/docs/threat-detection) monitoring
your VPC network, the detector exports metrics that can be
examined with [Cloud Monitoring metrics](https://docs.cloud.google.com/dns/docs/monitoring#monitor_metrics).

Two metrics are available:

- `networksecurity.googleapis.com/dnsthreatdetector/sent_dns_log_count`: Count of logs that are sent to your provider for inspection.
- `networksecurity.googleapis.com/dnsthreatdetector/received_dns_threat_count`: The number of threat logs detected. This metric includes severity and the type of threat.

These metrics contain filters that let you analyze information more
effectively such as filtering for logs generated by a specific DNS Armor
instance through its threat detector ID or location.

## Before you begin

Verify that the following have been completed before you view DNS threat logs:

- [Enable](https://console.cloud.google.com/apis/library/networksecurity.googleapis.com) the [Network Security API](https://docs.cloud.google.com/firewall/docs/reference/network-security/rest) in your project.
- Verify that you have the `DNS Threat Detector Viewer` role.

Threat logs are written to Cloud Logging and can result in additional
storage costs. See [Use logging and monitoring: Pricing](https://docs.cloud.google.com/dns/docs/monitoring#pricing)
or [Pricing for Google Cloud Observability: Cloud Logging](https://cloud.google.com/stackdriver/pricing).

#### Permissions required for this task

To perform this task, you must have been granted the following permissions
*or* the following IAM roles.

**Permissions**

- `resourcemanager.projects.get`
- `resourcemanager.projects.list`
- `networksecurity.dnsThreatDetectors.get`
- `networksecurity.dnsThreatDetectors.list`

**Roles**

- `roles/networksecurity.dnsThreatDetectorViewer`
- `roles/logging.viewer`

### View threat logs

You can view logs in the Google Cloud console.

Each log entry includes details to identify the corresponding DNS query and
threat.

### Console

1. In the Google Cloud console, go to the **Logs Explorer** page.

   [Go to Logs Explorer](https://console.cloud.google.com/logs/viewer?resource=dns_query)
2. Filter the logs for `networksecurity.googleapis.com/DnsThreatDetector`.

## Threat log record fields

Every threat log has the following fields.

| Name | Type | Description |
|---|---|---|
| `detectionTime` | string | Time when the threat is detected in UTC. The timestamp is in ISO 8601 format. |
| `dnsQuery` | DnsLog | Cloud DNS Log format. |
| `partnerId` | string | Unique partner identifier. |
| `threatInfo` | threatInfo | The details of threat detected. |

<br />

### Threat info field

The following table describes the format of the `threatInfo` field.

| Name | Type | Description |
|---|---|---|
| `threatID` | string | Unique threat identifier. |
| `threat` | string | The name of the threat detected. |
| `threatDescription` | string | A detailed description of the threat detected. |
| `category` | string | The subtype of the threat detected. |
| `type` | string | The type of the threat detected. For example, DNS_Tunnel, DGA (Domain Generation Algorithms), or C2 (Command and Control). |
| `severity` | string | The severity, (High, Medium, Low, or Info), associated with the threat detected. For more information, see Infoblox's [Severity Level Definition](https://docs.infoblox.com/space/BloxOneThreatDefense/1640103988/Severity+and+Confidence+Levels#Severity-Level-Definition). |
| `confidence` | string | Confidence of the threat prediction (high, medium, low). For more information, see Infoblox's [Confidence Level Definition](https://docs.infoblox.com/space/BloxOneThreatDefense/1640103988/Severity+and+Confidence+Levels#Confidence-Level-Definition). |
| `threatFeed` | string | Threat feed that triggered this threat alert. |
| `indicatorType` | string | The type of indicator that triggered this threat alert. For example, URL, IP, Hash, or Host. |
| `threatIndicator` | string | The threat indicator that triggered this alert. |

### DNS Query field

The following table describes the format of the `DnsQuery` field.

| Name | Type | Description |
|---|---|---|
| `projectNumber` | string | Source project number. |
| `location` | string | Google Cloud region, for example `us-east1`, from which the response was served. |
| `queryName` | string | DNS query name, [RFC 1035 4.1.2](https://datatracker.ietf.org/doc/html/rfc1035#section-4.1.2). |
| `queryType` | string | DNS query type, [IANA DNS Parameters: Resource Record (RR) TYPEs](https://www.iana.org/assignments/dns-parameters/dns-parameters.xhtml#dns-parameters-4). |
| `responseCode` | string | Response code, [IANA DNS Parameters: DNS RCODEs](https://www.iana.org/assignments/dns-parameters/dns-parameters.xhtml#dns-parameters-6). |
| `rdata` | string | DNS answer in presentation format, [IANA DNS Parameters: Resource Record (RR) TYPEs](https://www.iana.org/assignments/dns-parameters/dns-parameters.xhtml#dns-parameters-4), truncated to 260 bytes. |
| `authAnswer` | string | Authoritative answer, [IANA DNS Parameters: DNS Header Flags](https://www.iana.org/assignments/dns-parameters/dns-parameters.xhtml#dns-parameters-12). |
| `sourceIp` | string | IP originating the query. |
| `destinationIp` | string | Target IP address, only applicable for forwarding cases. |
| `protocol` | string | `TCP` or `UDP`. |
| `queryTime` | string | Timestamp for when the DNS query was sent. |
| `vmInstanceId` | string | Compute Engine VM instance name, only applicable to queries initiated by Compute Engine VMs. |
| `vmProjectNumber` | string | Google Cloud project ID of the network from which the query was sent, only applicable to queries initiated by Compute Engine VM instances. |
| `serverlessInstanceId` | string | Serverless instance ID from which the query was sent, only applicable to queries initiated by Serverless. |

## Monitor threat logs

You can visualize your log data by creating [log-based metrics](https://docs.cloud.google.com/logging/docs/alerting/monitoring-logs#lbm)
and a [custom dashboard](https://docs.cloud.google.com/monitoring/charts/dashboards) in Cloud Monitoring.

For a step-by-step guide on how to create a custom dashboard for
DNS Armor, see the
[Visualizing DNS Armor's Advanced Threat Detection Logs using Log-Based Metrics and Custom Dashboard tutorial](https://codelabs.developers.google.com/dns-armor-monitoring-dashboard#0).
The example custom dashboard in this tutorial includes the following widgets:

- **Threat Logs**: the generated threat logs for all included networks within a project.
- **Threat Logs per region**: the threat logs grouped by region.
- **Group by Threat**: categorizes threat logs based on the threat type.
- **Top List - ThreatID**: the top 30 threat IDs.
- **Group by Severity**: grouping threat logs by severity level.
- **Top List - Source**: the top 30 instance IDs (source VMs).
- **Group by Domains**: groups threat logs by the domain names found in the queries.

[![Example of a custom dashboard made for DNS Armor.](https://docs.cloud.google.com/static/dns/images/armor-custom-dashboard.png)](https://docs.cloud.google.com/static/dns/images/armor-custom-dashboard.png) A custom DNS Armor dashboard with widgets.

> [!NOTE]
> **Note:** To avoid incurring future charges, make sure to delete all resources you created after completing the codelab tutorial.

Considerations:

- Log-based metrics have higher ingestion delays and are unsuitable for real-time
  monitoring or sensitive alerts. There might also be delays in showing the correct
  log count due to a potential delay for log ingestion.

- When configuring alerting for log-based metrics, we recommend setting the
  alignment period to at least five minutes. The alignment period helps prevent
  minor fluctuations from triggering alerts.

- During periods of heavy load, there could be delays in sending logs to
  Cloud Logging or in receiving and displaying the logs. For more information
  see [Troubleshoot Logs Explorer](https://docs.cloud.google.com/logging/docs/view/troubleshoot#no_log_entries_with_query).

For more information about Cloud Monitoring dashboards, see [Dashboards overview](https://docs.cloud.google.com/monitoring/dashboards).

## What's next

- Learn more about how to [Use logging and monitoring](https://docs.cloud.google.com/dns/docs/monitoring), including how to enable logging for your VPC networks.

- Learn more about [Advanced threat detection](https://docs.cloud.google.com/dns/docs/threat-detection).

- To find solutions for common issues that you might encounter when using
  threat monitoring, see [Troubleshooting](https://docs.cloud.google.com/dns/docs/troubleshooting#threat-detection).

- To learn how to be alerted when a threat is detected, see [Alerting overview](https://docs.cloud.google.com/monitoring/alerts).