# DNS lookup API:  Intelligence & Security Analyzer (`njoylab/apify-dns`) Actor

A powerful DNS intelligence tool that performs multi-record lookups, global propagation checks, reverse DNS, SSL/TLS inspection, email security analysis, and rich metadata extraction all in one automated workflow

- **URL**: https://apify.com/njoylab/apify-dns.md
- **Developed by:** [njoylab](https://apify.com/njoylab) (community)
- **Categories:** Developer tools, Automation, Other
- **Features:** Limited permissions
- **Stats:** 41 total users, 2 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## DNS Intelligence & SSL Inspection Actor

A robust and comprehensive DNS intelligence Actor for the Apify platform that performs multi-record DNS queries, bulk domain processing, global propagation checks, reverse DNS lookups, SSL/TLS inspection, and advanced enrichment with email-security and metadata analysis — all with automatic retries and structured output.

#### Highlights

- Multi-record DNS lookup (A, AAAA, MX, TXT, NS, etc.)
- Global propagation and consistency check
- Reverse DNS and PTR record analysis
- SSL/TLS certificate fetch and expiry alert
- SPF/DMARC/DKIM parsing and email-security scoring
- JSON-structured output for easy integration

### Features

#### Core Capabilities

- **Comprehensive DNS Record Support**: Query all major DNS record types including A, AAAA, MX, CNAME, TXT, NS, PTR, SOA, CAA, and SRV records
- **Reverse DNS Lookup**: Automatic IP → hostname resolution using PTR records for network reconnaissance and validation
- **Bulk DNS Lookup Processing**: Handle multiple domains simultaneously, saving time and computational resources
- **Real-time DNS Propagation Checking**: Verify DNS changes across multiple global DNS servers (Google DNS, Cloudflare, OpenDNS, Quad9, etc.)
- **Automatic Retry Mechanisms**: Built-in retry logic with exponential backoff for failed queries
- **Rich Metadata**: Include TTL values, response times, and detailed error information
- **Structured JSON Output**: Easy integration with existing workflows and data pipelines

#### Advanced Features

- **DNS Enrichment & Email Security**: Intelligent SPF/DMARC/DKIM parsing, MX provider detection, email security scoring (0-100), and actionable recommendations
- **TLS/SSL Certificate Insights**: Fetches live certificate metadata (issuer, SANs, expiry, cipher/protocol) and highlights risky configurations
- **Quick Access Fields**: Top-level convenience fields (mx_provider, spf_valid, dmarc_policy, has_dkim, etc.) for easy data access
- Configurable timeout settings
- Customizable retry attempts and delays
- Support for both domain names and IP addresses (including PTR lookups)
- Parallel processing for improved performance
- Detailed logging and error handling
- Propagation consistency analysis
- TTL categorization and analysis

### Use Cases

This Actor is designed for:

- **Cybersecurity Professionals**: Conducting domain reconnaissance and security assessments
- **Web Developers**: Validating DNS configurations and troubleshooting connectivity issues
- **IT Administrators**: Monitoring network infrastructure and DNS health
- **Digital Marketers**: Researching competitor domains and infrastructure
- **Data Analysts**: Gathering DNS intelligence for various data analysis projects
- **DevOps Teams**: Automating DNS verification in CI/CD pipelines

### Input Parameters

#### Required Parameters

- **domains** (array of strings): List of domain names or IP addresses to perform DNS lookups on. Minimum 1 domain required.

#### Optional Parameters

- **recordTypes** (array): DNS record types to query. Default: `["A", "AAAA", "MX", "CNAME", "TXT", "NS"]`
  - Available types: A, AAAA, MX, CNAME, TXT, NS, PTR, SOA, CAA, SRV

- **checkPropagation** (boolean): Enable real-time DNS propagation checking across multiple global DNS servers. Default: `false`

- **propagationServers** (array of strings): List of DNS servers for propagation checking. Default: Google DNS, Cloudflare, OpenDNS, Quad9
  - Default servers: `["8.8.8.8", "1.1.1.1", "208.67.222.222", "9.9.9.9", "8.8.4.4"]`

- **performReverseLookup** (boolean): Automatically perform reverse DNS lookup (IP → hostname) for IP addresses. Default: `true`

- **enableEnrichment** (boolean): Enable intelligent analysis of DNS records including SPF/DMARC/DKIM parsing, MX provider detection, TTL categorization, and email security scoring. Default: `true`

- **enableSslInspection** (boolean): Toggle the TLS/SSL certificate fetch step independently from the rest of the enrichment pipeline. Default: `true`

- **timeout** (integer): Query timeout in milliseconds. Range: 1000-30000. Default: `5000`

- **maxRetries** (integer): Maximum retry attempts for failed queries. Range: 0-10. Default: `3`

- **retryDelay** (integer): Delay between retry attempts in milliseconds. Range: 100-10000. Default: `1000`

### Input Examples

#### Basic DNS Lookup

```json
{
  "domains": ["example.com", "google.com"],
  "recordTypes": ["A", "AAAA", "MX"]
}
```

#### Reverse DNS Lookup (IP → Hostname)

```json
{
  "domains": ["8.8.8.8", "1.1.1.1", "142.250.184.206"],
  "performReverseLookup": true,
  "recordTypes": ["A"]
}
```

#### DNS Propagation Check

```json
{
  "domains": ["newdomain.com"],
  "recordTypes": ["A", "AAAA", "CNAME"],
  "checkPropagation": true,
  "propagationServers": [
    "8.8.8.8",
    "1.1.1.1",
    "208.67.222.222",
    "9.9.9.9"
  ]
}
```

#### Comprehensive Lookup with All Options

```json
{
  "domains": [
    "example.com",
    "test.org",
    "8.8.8.8"
  ],
  "recordTypes": ["A", "AAAA", "MX", "CNAME", "TXT", "NS", "SOA"],
  "checkPropagation": true,
  "timeout": 10000,
  "maxRetries": 5,
  "retryDelay": 2000
}
```

#### Bulk Domain Research

```json
{
  "domains": [
    "competitor1.com",
    "competitor2.com",
    "competitor3.com",
    "competitor4.com",
    "competitor5.com"
  ],
  "recordTypes": ["A", "MX", "TXT", "NS"]
}
```

#### DNS Enrichment with Email & SSL Analysis

```json
{
  "domains": ["example.com", "company.org"],
  "recordTypes": ["A", "MX", "TXT", "NS"],
  "enableEnrichment": true,
  "enableSslInspection": true
}
```

### Output Format

The Actor outputs structured JSON data for each domain:

#### Standard Lookup Result

```json
{
  "domain": "example.com",
  "lookupResult": {
    "domain": "example.com",
    "timestamp": "2024-01-15T10:30:00.000Z",
    "records": {
      "A": [
        {
          "type": "A",
          "address": "93.184.216.34",
          "ttl": 3600
        }
      ],
      "AAAA": [
        {
          "type": "AAAA",
          "address": "2606:2800:220:1:248:1893:25c8:1946",
          "ttl": 3600
        }
      ],
      "MX": [
        {
          "type": "MX",
          "exchange": "mail.example.com",
          "priority": 10
        }
      ],
      "TXT": [
        {
          "type": "TXT",
          "entries": ["v=spf1 include:_spf.example.com ~all"]
        }
      ]
    },
    "mx_provider": "Example Mail",
    "spf_valid": true,
    "ssl_certificate_expires_at": "2024-06-01T12:00:00.000Z",
    "ssl_days_until_expiry": 120,
    "metadata": {
      "queryTime": 125,
      "totalRecords": 4
    }
  }
}
```

#### Reverse DNS Lookup Result

```json
{
  "domain": "8.8.8.8",
  "lookupResult": {
    "domain": "8.8.8.8",
    "timestamp": "2024-01-15T10:30:00.000Z",
    "records": {},
    "reverseLookup": {
      "hostnames": ["dns.google"],
      "responseTime": 45
    },
    "metadata": {
      "queryTime": 50,
      "totalRecords": 0
    }
  }
}
```

#### TLS/SSL Enrichment Block

When TLS inspection is enabled (via `enableSslInspection`) and the domain serves HTTPS traffic, the Actor augments the output with a structured TLS report under `lookupResult.enrichment.ssl`:

```json
{
  "lookupResult": {
    "enrichment": {
      "ssl": {
        "certificate": {
          "subject": {
            "commonName": "example.com"
          },
          "issuer": {
            "commonName": "Example CA"
          },
          "validFrom": "2024-03-01T00:00:00.000Z",
          "validTo": "2024-06-01T12:00:00.000Z",
          "daysUntilExpiry": 120,
          "subjectAlternativeNames": [
            "example.com",
            "www.example.com"
          ],
          "isSelfSigned": false
        },
        "protocol": "TLSv1.3",
        "cipher": "TLS_AES_256_GCM_SHA384",
        "warnings": []
      }
    }
  }
}
```

#### Propagation Check Result

```json
{
  "domain": "example.com",
  "lookupResult": { ... },
  "propagationResults": [
    {
      "domain": "example.com",
      "recordType": "A",
      "timestamp": "2024-01-15T10:30:00.000Z",
      "servers": {
        "8.8.8.8": {
          "records": [
            {
              "type": "A",
              "address": "93.184.216.34"
            }
          ],
          "responseTime": 45
        },
        "1.1.1.1": {
          "records": [
            {
              "type": "A",
              "address": "93.184.216.34"
            }
          ],
          "responseTime": 38
        }
      },
      "isPropagated": true,
      "consistencyPercentage": 100
    }
  ]
}
```

#### DNS Enrichment Result

When enrichment is enabled, the output includes quick-access fields at the top level and detailed analysis in the `enrichment` object:

```json
{
  "domain": "example.com",
  "lookupResult": {
    "domain": "example.com",
    "timestamp": "2024-01-15T10:30:00.000Z",
    "records": {
      "A": [{ "type": "A", "address": "93.184.216.34", "ttl": 3600 }],
      "MX": [
        {
          "type": "MX",
          "exchange": "aspmx.l.google.com",
          "priority": 1,
          "ttl": 3600
        }
      ],
      "TXT": [
        {
          "type": "TXT",
          "entries": ["v=spf1 include:_spf.google.com ~all"],
          "ttl": 3600
        }
      ]
    },
    "mx_provider": "Google Workspace",
    "spf_valid": true,
    "spf_strict": false,
    "dmarc_policy": "quarantine",
    "has_dkim": true,
    "email_security_score": 85,
    "enrichment": {
      "emailSecurity": {
        "spf": {
          "version": "v=spf1",
          "mechanisms": [
            { "type": "include", "qualifier": "+", "value": "_spf.google.com" },
            { "type": "all", "qualifier": "~" }
          ],
          "isValid": true,
          "warnings": [],
          "lookupCount": 1
        },
        "dmarc": {
          "version": "DMARC1",
          "policy": "quarantine",
          "reportingEmails": {
            "aggregate": ["dmarc@example.com"]
          },
          "isValid": true,
          "warnings": []
        },
        "dkim": [
          { "selector": "google", "exists": true, "record": "v=DKIM1; k=rsa; p=..." }
        ],
        "mx": {
          "totalServers": 1,
          "primaryServer": "aspmx.l.google.com",
          "provider": { "name": "Google Workspace", "confidence": "high" },
          "hasBackup": false,
          "priorities": [1],
          "servers": [
            {
              "hostname": "aspmx.l.google.com",
              "priority": 1,
              "isBackup": false
            }
          ]
        },
        "score": 85,
        "recommendations": [
          "Consider upgrading DMARC policy to \"reject\" for maximum protection",
          "Add backup MX records for email redundancy"
        ]
      },
      "ttlAnalysis": {
        "A": {
          "value": 3600,
          "category": "normal",
          "description": "Normal TTL - standard configuration"
        }
      }
    },
    "metadata": {
      "queryTime": 450,
      "totalRecords": 3
    }
  }
}
```

**Quick Access Fields** (available at top level when enrichment is enabled):

- `mx_provider`: Email provider name (e.g., "Google Workspace", "Microsoft 365")
- `spf_valid`: SPF record validation status (true/false)
- `spf_strict`: Whether SPF has strict policy with `-all` (true/false)
- `dmarc_policy`: DMARC policy level ("none", "quarantine", or "reject")
- `has_dkim`: DKIM configuration presence (true/false)
- `email_security_score`: Overall email security score (0-100)
- `ssl_certificate_expires_at`: Certificate expiration timestamp
- `ssl_days_until_expiry`: Days until certificate expires (negative if expired)
- `warnings`: Aggregated warnings from SSL and email security analysis (array of strings)
- `recommendations`: Actionable security recommendations (array of strings)

**Detailed Enrichment Data** (available in `enrichment` object):

- **emailSecurity**: Comprehensive email security analysis including SPF mechanisms, DMARC policies, DKIM selectors, MX analysis, scoring, and recommendations
- **ttlAnalysis**: TTL categorization for each record type (very-short, short, normal, long, very-long)

### Performance Considerations

- **Bulk Processing**: The Actor processes domains sequentially to avoid overwhelming DNS servers
- **Timeout Settings**: Adjust timeout based on your network conditions (higher for unreliable networks)
- **Retry Logic**: Uses exponential backoff to handle transient failures gracefully
- **Parallel Queries**: Multiple record types are queried in parallel for each domain

### Error Handling

The Actor includes robust error handling:

- Invalid domains are logged but don't stop execution
- Failed queries are retried automatically based on configuration
- Errors are captured and included in the output for debugging
- Each domain's results are independent (one failure doesn't affect others)

### Best Practices

1. **Start Small**: Test with a few domains before running bulk lookups
2. **Use Propagation Checking Wisely**: Enable only when needed (e.g., after DNS changes)
3. **Adjust Timeouts**: Increase timeout for domains with slow DNS servers
4. **Monitor Costs**: Bulk lookups consume more compute units
5. **Filter Record Types**: Only query needed record types to improve performance

### DNS Record Types Reference

- **A**: IPv4 address records
- **AAAA**: IPv6 address records
- **MX**: Mail exchange servers
- **CNAME**: Canonical name (alias) records
- **TXT**: Text records (often used for verification, SPF, DKIM)
- **NS**: Nameserver records
- **PTR**: Pointer records (reverse DNS)
- **SOA**: Start of Authority records
- **CAA**: Certification Authority Authorization
- **SRV**: Service location records

### Limitations

- Maximum 10 retry attempts per query
- Timeout range: 1-30 seconds
- Some DNS servers may rate-limit queries
- Propagation checking increases execution time

**Note**: This Actor respects DNS server rate limits and implements responsible querying practices. For high-volume DNS lookups, consider implementing additional delays between requests.

# Actor input Schema

## `domains` (type: `array`):

List of domain names or IP addresses to perform DNS lookups on. For bulk processing, provide multiple entries.

## `recordTypes` (type: `array`):

Types of DNS records to query. Leave empty to query all supported types.

## `checkPropagation` (type: `boolean`):

Enable real-time DNS propagation checking across multiple global DNS servers.

## `propagationServers` (type: `array`):

List of DNS servers to use for propagation checking. Only used if 'Check DNS Propagation' is enabled.

## `performReverseLookup` (type: `boolean`):

Automatically perform reverse DNS lookup (IP → hostname) for IP addresses. This will resolve IP addresses to their associated hostnames using PTR records.

## `enableEnrichment` (type: `boolean`):

Enable intelligent analysis of DNS records including SPF/DMARC/DKIM parsing, MX provider detection, TTL categorization, and email security scoring.

## `enableSslInspection` (type: `boolean`):

Fetch live TLS certificate metadata (issuer, SANs, expiry, cipher/protocol) for each domain served on HTTPS.

## `timeout` (type: `integer`):

Timeout in milliseconds for each DNS query.

## `maxRetries` (type: `integer`):

Maximum number of retry attempts for failed DNS queries.

## `retryDelay` (type: `integer`):

Delay in milliseconds between retry attempts.

## Actor input object example

```json
{
  "domains": [
    "github.com"
  ],
  "recordTypes": [
    "A",
    "AAAA",
    "MX",
    "CNAME",
    "TXT",
    "NS"
  ],
  "checkPropagation": false,
  "propagationServers": [
    "8.8.8.8",
    "1.1.1.1",
    "208.67.222.222",
    "9.9.9.9",
    "8.8.4.4"
  ],
  "performReverseLookup": true,
  "enableEnrichment": true,
  "enableSslInspection": true,
  "timeout": 5000,
  "maxRetries": 3,
  "retryDelay": 1000
}
```

# Actor output Schema

## `summary` (type: `string`):

High-level numbers taken from the OUTPUT record written by main.ts.

## `resultsUrl` (type: `string`):

Download every dataset item as JSON; change the format query param to fetch CSV/XLSX if needed.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "domains": [
        "github.com"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("njoylab/apify-dns").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "domains": ["github.com"] }

# Run the Actor and wait for it to finish
run = client.actor("njoylab/apify-dns").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "domains": [
    "github.com"
  ]
}' |
apify call njoylab/apify-dns --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,njoylab/apify-dns"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/ipNGf4Mu0wjn43L7P/builds/devC8UaItiVpAs41e/openapi.json