NetRecon

DNS Intelligence & Network Planning — public DNS lookups, internal DNS resolution, IP calculator with subnet/supernet analysis, and multi-cloud CIDR planning. Self-hosted, zero external dependencies, runs entirely in Docker.

From the makers of Netra — enterprise DNS change management with approval workflows, drift detection, and audit trails for Windows DNS, Route 53, Cloud DNS, Azure DNS, and Cloudflare.

---

Table of Contents

1. Features
2. Architecture
3. Quick Start
4. Configuration
5. File Structure
6. Contributing
7. Troubleshooting

---

Features

DNS / IP Lookup

• Public DNS via Cloudflare DoH (1.1.1.1) — A, AAAA, CNAME, MX, TXT, NS, SOA, CAA resolved in parallel
• Email Security audit — DKIM selector probing (12 common selectors), DMARC policy parsing with enforcement level, SPF mechanism breakdown with color-coded pills
• IP Geolocation — interactive Leaflet map with pin, org/ASN (clickable BGP.he.net link), PTR record, city/region/country, timezone
• IPv4 + IPv6 — full support for both address families including IPv6 PTR lookups
• Clickable IPs — click any A/AAAA result to instantly run a full IP lookup with map
• TLS Certificate check — subject, issuer, SANs, expiry countdown, cipher, protocol version, full chain display
• DNSBL Blacklist check — tests IPs against 10 major blacklists (Spamhaus, SpamCop, Barracuda, SORBS, etc.) in parallel
• Split-brain safe — public tool uses Cloudflare DoH exclusively, never leaks internal records
• Multi-type parallel resolution — all record types resolved in one request (~300ms vs sequential ~6s)

Internal DNS

• Private DNS resolution via your own DNS servers (Microsoft DNS, BIND, Unbound, etc.)
• All record types — A, AAAA, CNAME, MX, SRV, TXT, NS, PTR with TTL display
• Health indicator — real-time proxy connection status in sidebar
• Domain allow-list — optionally restrict which domains can be queried internally
• Configurable quick links — pre-populate common internal hostnames for one-click lookup
• Timeout control — configurable per-query timeout for slow internal DNS servers

IP Calculator

• CIDR analysis — network, broadcast, mask, wildcard, first/last host, usable count
• Binary display — visual bit-level representation of IP, mask, and wildcard with colored network/host bits
• Subnet splits — expandable breakdown into /25, /26, /27, /28 with full details per subnet (click to expand)
• Supernet summary — shows parent networks for route summarization planning (clickable to recalculate)
• RFC classification — RFC 1918, loopback, link-local, multicast, reserved, documentation range detection
• Quick examples — common CIDR entries for fast access

Cloud CIDR Planning

• AWS VPC, GCP VPC, Azure VNet — automatic subnet allocation across AZs/regions
• Configurable tiers — name, prefix size, and color per subnet tier (e.g., public, private, database)
• Color picker — preset palette + custom hex input for visual subnet differentiation
• Architecture notes — provider-specific implementation guidance per plan (reserved IPs, AZ mapping, etc.)
• XLSX export — download the complete subnet plan as an Excel workbook for sharing with teams
• Visual subnet map — color-coded AZ breakdown with subnet names, CIDRs, and host counts

DNS Change Monitoring

• Watched Domains — add any domain (public or internal) to a watch list with configurable poll intervals (5m, 15m, 1h, 6h, 24h)
• Change Detection — compares current records against the last snapshot and surfaces added, removed, or modified entries
• Change History — full audit log per domain showing what changed, when, and the before/after values
• Multi-record support — monitor A, AAAA, MX, TXT, NS, CNAME, SOA, CAA, or all at once
• Public + Internal — watch domains against Cloudflare DoH or your own private DNS servers
• Detail panel — click any watched domain to see its current snapshot, last check time, and full change log

Notifications & Alerting

• Multi-channel — Slack (Block Kit), Microsoft Teams (Adaptive Cards), Discord (Embeds), generic webhooks, and email
• Simultaneous delivery — alerts fire to all configured channels in parallel
• DNS change alerts — notified immediately when a watched domain's records change
• Delivery log — rolling log of the last 200 delivery attempts with success/failure status and duration
• Per-channel test — verify each integration with a one-click test button
• SMTP support — send email alerts through your own relay (no external dependencies)
• Webhook secret — optional X-Webhook-Secret header for verifying inbound requests at your endpoint

Stats Dashboard

• Usage tracking — per-tool counters, recent lookups, top queried domains
• DNS proxy health — response time, server status, nginx connection metrics
• Hourly volume chart — 24-hour query volume visualization
• Record type distribution — breakdown of which DNS record types are queried most
• Error tracking — NXDOMAIN, timeouts, and other failures counted and displayed
• Login protected — SHA-256 hashed credentials, session-based auth

General

• First-run setup wizard — browser-based setup on first launch, no config files to edit
• Zero-config Docker deployment — docker compose up -d and open the browser
• All settings in the UI — DNS servers, notifications, password, quick links — all configurable without restarting
• Hot-reload — DNS resolver reconfigures instantly when settings change
• Dark / Light / System theme toggle with persistence
• Collapsible sidebar — collapse to icon-only mode, state remembered across sessions
• Mobile responsive — full breakpoint support for tablets and phones
• Keyboard shortcuts — Enter to search, sidebar navigation
• Rate limited — nginx rate limiting on all API endpoints prevents abuse
• Security hardened — CSP headers, no inline scripts, non-root containers, request size limits, input validation
• Zero npm dependencies — dns-proxy uses only Node.js built-ins (no supply chain risk)
• Persistent data — all settings, stats, watched domains, and notification logs survive container restarts

---

Architecture

┌─────────────────────────────────────────────────────┐
│                     Browser                         │
└──────────────────────┬──────────────────────────────┘
                       │ HTTPS
┌──────────────────────▼──────────────────────────────┐
│                    nginx                            │
│  • Serves static frontend                           │
│  • Proxies /api/* → dns-proxy                       │
│  • Rate limiting, CSP headers, gzip                 │
└──────────────────────┬──────────────────────────────┘
                       │ Internal network only
┌──────────────────────▼──────────────────────────────┐
│                  dns-proxy (Node.js)                │
│  • Public DNS  → Cloudflare DoH (1.1.1.1)           │
│  • Internal DNS → your DNS_SERVERS (UDP)            │
│  • IP Geolocation → ipinfo.io / ip-api.com          │
│  • Stats persistence → /data/stats.json             │
└─────────────────────────────────────────────────────┘

Zero external dependencies — the dns-proxy uses only Node.js built-ins (dns, http, https, fs). No npm packages required.

---

Quick Start

Prerequisites

• Docker + Docker Compose
• Your internal DNS server IPs (for the Internal DNS tool)

1. Create the project directory

mkdir netrecon && cd netrecon

2. Create docker-compose.yml

services:
  netrecon:
    image: ghcr.io/netradns/netrecon:latest
    container_name: netrecon
    restart: unless-stopped
    ports:
      - "8085:80"
    networks:
      - netrecon-internal
    depends_on:
      - dns-proxy

  dns-proxy:
    image: ghcr.io/netradns/netrecon-dns-proxy:latest
    container_name: netrecon-dns-proxy
    restart: unless-stopped
    volumes:
      - ./data:/data
    networks:
      - netrecon-internal
    expose:
      - "3053"

networks:
  netrecon-internal:
    driver: bridge

3. Start

mkdir -p ./data
docker compose up -d

4. Complete Setup

Open http://localhost:8085 — the setup wizard will guide you through:

• Setting an admin password
• Optionally configuring internal DNS servers

All settings can be changed later in the admin panel (Settings → Server).

Without Docker Compose

docker network create netrecon-internal

mkdir -p /docker/netrecon/data

docker run -d --name netrecon-dns-proxy \
  --network netrecon-internal \
  -v /docker/netrecon/data:/data \
  --expose 3053 \
  --restart unless-stopped \
  ghcr.io/netradns/netrecon-dns-proxy:latest

docker run -d --name netrecon \
  --network netrecon-internal \
  -p 8085:80 \
  --restart unless-stopped \
  ghcr.io/netradns/netrecon:latest

3. Access

URL	Description
http://localhost:8085	Main application
http://localhost:8085/admin	Admin panel — usage stats, watched domains, settings (login: admin / admin)

Change the admin password — log in to the admin panel and go to Settings → Security → Change Password. Takes effect immediately, no container restart needed.

---

Configuration

All configuration is managed through the web UI — no environment variables or file editing required.

On first launch, a setup wizard guides you through the initial configuration. After that, all settings are available in the admin panel under Settings → Server.

Setting	Where to Configure	Description
Admin password	Setup wizard / Settings → Security	Password for the admin panel
Internal DNS servers	Setup wizard / Settings → Server	Your private DNS server IPs
Public DNS	Settings → Server	Public DNS for connectivity tests (default: 1.1.1.1, 8.8.8.8)
Allowed domains	Settings → Server	Restrict internal DNS to specific domains
DNS timeout	Settings → Server	Internal DNS query timeout in ms
Internal DNS toggle	Settings → General	Show/hide the Internal DNS tool
Notifications	Settings → Notifications	Slack, Teams, Discord, Webhook, Email alerts
Quick links	Settings → General	Customize the quick-link chips on lookup pages

All changes take effect immediately — no container restart required.

Customizing Quick Links

Public DNS — edit frontend/js/dns/dns.js:

var DNS_QUICK_LINKS = ['example.com', 'google.com', 'cloudflare.com'];

Internal DNS — edit frontend/js/idns/idns.js:

var IDNS_QUICK_LINKS = [
  { label: 'intranet.corp.local', value: 'intranet.corp.local' },
];

Customizing Cloud Defaults

Edit frontend/js/cloud/cloud-data.js to change default subnet tiers for each provider.

---

File Structure

netrecon/
├── docker-compose.yml          # Production deployment
├── docker-compose.example.yml  # Template for new deployments
├── Dockerfile                  # nginx container
├── nginx.conf                  # Reverse proxy + security headers
├── dns-proxy/
│   ├── server.js               # Entry point (routing only)
│   ├── Dockerfile
│   └── lib/
│       ├── config.js           # All environment variables
│       ├── resolver.js         # DoH + UDP DNS resolution
│       ├── handlers.js         # HTTP route handlers
│       ├── stats.js            # Stats persistence
│       ├── admin/
│       │   ├── config-store.js # Runtime config I/O (/data/config.json)
│       │   ├── password.js     # Password hash/verify logic
│       │   └── handlers.js     # HTTP handlers for /admin/* routes
│       ├── notify/
│       │   ├── dispatcher.js   # Routes events to all configured channels
│       │   ├── format.js       # Shared color/timestamp helpers
│       │   ├── log.js          # Delivery log persistence
│       │   └── channels/
│       │       ├── slack.js    # Slack Block Kit sender
│       │       ├── teams.js    # Teams Adaptive Card sender
│       │       ├── discord.js  # Discord embed sender
│       │       ├── webhook.js  # Generic JSON POST sender
│       │       └── email.js    # Raw SMTP sender (no dependencies)
│       └── watcher/
│           ├── index.js        # Scheduler — single interval, per-domain check
│           ├── snapshot.js     # Watched domains state I/O (/data/watched.json)
│           ├── poller.js       # Resolves a single domain, returns records
│           ├── diff.js         # Pure function: compares two record sets
│           └── alerts.js       # Formats + dispatches change notifications
└── frontend/
    ├── index.html              # Main application
    ├── admin.html              # Admin panel (dashboard, watched domains, settings)
    ├── style.css               # All styles
    └── js/
        ├── core/
        │   ├── utils.js        # Shared helpers, IP math, TTL formatting
        │   ├── theme.js        # Light/dark/system theme
        │   ├── nav.js          # Page routing, hash-based deep links
        │   ├── routing.js      # URL hash routing + copy buttons
        │   └── custom-select.js # App-native dropdown component
        ├── dns/
        │   ├── dns.js          # DNS/IP lookup logic
        │   └── dns-render.js   # Results rendering (10 record type cards)
        ├── idns/
        │   ├── idns.js         # Internal DNS logic
        │   └── idns-render.js  # Results rendering
        ├── calc/
        │   ├── calc.js         # CIDR calculation logic
        │   └── calc-render.js  # Binary display, subnet splits, supernets
        ├── cloud/
        │   ├── cloud-data.js   # Default tier presets (AWS/GCP/Azure)
        │   ├── cloud.js        # Planning logic, color picker
        │   └── cloud-render.js # VPC/VNet rendering, XLSX export
        ├── stats/              # Dashboard stats modules (loaded by admin.html)
        │   ├── stats.js        # Orchestration + auto-refresh
        │   ├── stats-proxy.js  # DNS proxy health
        │   ├── stats-nginx.js  # Nginx metrics
        │   ├── stats-server.js # Server info
        │   ├── stats-usage.js  # Tool usage bars
        │   ├── stats-queries.js # Top queries + recent lookups
        │   ├── stats-records.js # Record type distribution
        │   ├── stats-errors.js  # Error tracking
        │   └── stats-chart.js   # Hourly volume chart
        └── admin/              # Admin panel modules
            ├── admin.js        # Page orchestrator
            ├── admin-auth.js   # Login gate + authenticated fetch helper
            ├── admin-nav.js    # Tab routing (Dashboard / Watched / Settings)
            ├── settings/
            │   ├── settings.js # Settings page orchestrator + tab switching
            │   ├── general.js  # Internal DNS toggle
            │   ├── notify.js   # Notification channel list (Slack/Teams/Discord/Webhook/Email)
            │   ├── smtp.js     # SMTP configuration
            │   ├── password.js # Change admin password
            │   └── guides.js   # Collapsible setup guides per channel type
            └── watched/
                ├── watched.js       # Watched domains page orchestrator
                ├── watched-table.js # Domain list table + remove
                ├── watched-detail.js # Domain detail slide-in panel
                └── watched-form.js  # Add domain form + validation

---

Contributing

Contributions are welcome. The codebase is intentionally modular — each feature lives in its own directory with a clear separation between logic and rendering.

Adding a new tool

1. Create frontend/js/mytool/mytool.js and mytool-render.js
2. Add a page div to frontend/index.html
3. Add a sidebar nav item in index.html
4. Update PAGE_TITLES in frontend/js/core/nav.js
5. Load the scripts at the bottom of index.html

Code style

• 'use strict'; at the top of every file
• Plain ES5-compatible JavaScript (no build step, no transpiler)
• Comments on anything non-obvious
• Small, single-purpose functions
• No external npm packages in the frontend

Before submitting a PR

• Test in light and dark themes
• Test on mobile viewport
• Check browser console for errors
• Verify the stats page still works

---

Troubleshooting

Public DNS returns no results

• Check outbound HTTPS (port 443) is allowed from the container to 1.1.1.1
• Run docker logs netrecon-dns-proxy and look for DoH errors

Internal DNS not working

• Verify DNS_SERVERS are reachable from the container network
• Check port 53 UDP is open between the container and your DNS servers
• Run docker logs netrecon-dns-proxy for connectivity test results

Stats page permission error

• The ./data directory needs to exist before starting: mkdir -p ./data
• If issues persist, check: docker logs netrecon-dns-proxy

Port conflict

• Change 8085:80 in docker-compose.yml to any available port

---

License

MIT — see LICENSE for details.

---

_{A free tool by the makers of Netra — enterprise DNS change management with approval workflows, drift detection, and audit trails.}