Nadzoring (alexeev-prog/nadzoring)

Nadzoring

https://github.com/alexeev-prog/nadzoring
Admin
Nadzoring is a free and open-source command-line tool for detecting website blocks, monitoring...

Tokens:81,830
Snippets:571
Trust Score:8.8
Update:1 week ago
Show doc for...
Context Summary (auto-generated)
Raw
# Nadzoring

Nadzoring (from Russian "надзор" — supervision/oversight + the English "-ing" suffix) is a free and open-source command-line tool and Python library designed for in-depth network diagnostics, service availability monitoring, and website block detection. It provides a comprehensive suite of tools for DNS diagnostics, ARP spoofing monitoring, SSL/TLS certificate analysis, HTTP security header auditing, email security validation (SPF/DKIM/DMARC), subdomain discovery, port scanning, and network path analysis.

Built with AI-friendliness in mind, Nadzoring is fully type-annotated and follows SOLID principles with a modular architecture. The project can be used as a reliable Python library in your own applications or as a powerful standalone CLI tool. All public API functions follow consistent error handling patterns where failures are returned as structured data rather than raised exceptions, making it safe to use in automated scripts.

## DNS Lookup - resolve_with_timer

Perform DNS resolution with timing and structured error handling. Resolves a domain for a specific record type, measuring response time and optionally capturing TTL. All DNS errors are surfaced through the "error" field rather than raised as exceptions.

```python
from nadzoring.dns_lookup.utils import resolve_with_timer, get_public_dns_servers
from nadzoring.utils.timeout import TimeoutConfig

# Basic A record lookup with default settings
result = resolve_with_timer("example.com")
if result["error"]:
    # Possible values:
    # "Domain does not exist"  — NXDOMAIN
    # "No A records"           — NoAnswer
    # "Query timeout"          — Timeout
    print("DNS error:", result["error"])
else:
    print(result["records"])        # ['93.184.216.34']
    print(result["response_time"])  # 42.5 (milliseconds)

# MX lookup with TTL and custom nameserver
result = resolve_with_timer(
    "gmail.com",
    record_type="MX",
    nameserver="8.8.8.8",
    include_ttl=True,
)
if not result["error"]:
    print(result["records"])  # ['10 alt1.gmail-smtp-in.l.google.com', ...]
    print(result["ttl"])      # 3600

# Custom timeout configuration for slow networks
config = TimeoutConfig(connect=3.0, read=8.0, lifetime=20.0)
result = resolve_with_timer("example.com", "A", timeout_config=config)

# Get list of built-in public DNS servers
servers = get_public_dns_servers()
print(servers)  # ['8.8.8.8', '8.8.4.4', '1.1.1.1', '1.0.0.1', ...]
```

## DNS Lookup - reverse_dns

Perform reverse DNS lookup to resolve an IP address to a hostname (PTR record). Supports both IPv4 and IPv6 addresses. The function never raises on DNS errors; all failures are returned in the "error" field.

```python
from nadzoring.dns_lookup.reverse import reverse_dns
from nadzoring.utils.timeout import TimeoutConfig

# IPv4 reverse lookup
result = reverse_dns("8.8.8.8")
if result["error"]:
    # Possible values:
    # "No PTR record"          — IP has no reverse entry
    # "No reverse DNS"         — NXDOMAIN on reverse zone
    # "Query timeout"          — resolver timed out
    # "Invalid IP address: …"  — malformed input
    print("Lookup failed:", result["error"])
else:
    print(result["hostname"])       # 'dns.google'
    print(result["response_time"])  # 25.3 (milliseconds)

# IPv6 reverse lookup
result = reverse_dns("2001:4860:4860::8888")
print(result["hostname"])  # 'dns.google'

# Using a custom nameserver with timeout
config = TimeoutConfig(connect=2.0, read=5.0)
result = reverse_dns("8.8.8.8", nameserver="1.1.1.1", timeout_config=config)

# Compact error-safe pattern
hostname = result["hostname"] or f"[{result['error']}]"
print(f"Resolved: {hostname}")
```

## DNS Health Check - health_check_dns

Perform a comprehensive DNS health check with scoring. Evaluates A, AAAA, MX, NS, TXT, and CNAME records, computes per-type scores, and derives an overall health score (0-100) and status.

```python
from nadzoring.dns_lookup.health import health_check_dns, check_dns
from nadzoring.utils.timeout import TimeoutConfig

# Basic DNS health check
result = health_check_dns("example.com")
print(f"Score: {result['score']}/100")    # Score: 85/100
print(f"Status: {result['status']}")      # Status: healthy | degraded | unhealthy

# View per-record-type scores
for rtype, score in result["record_scores"].items():
    print(f"  {rtype}: {score}/100")

# Check for issues and warnings
for issue in result["issues"]:
    print(f"CRITICAL: {issue}")
for warning in result["warnings"]:
    print(f"WARNING: {warning}")

# Detailed DNS check with MX and TXT validation
result = check_dns(
    "gmail.com",
    record_types=["MX", "TXT", "A"],
    validate_mx=True,
    validate_txt=True,
)
print(result["records"])       # {'MX': ['10 alt1.gmail-smtp-in...'], 'A': [...]}
print(result["errors"])        # {'AAAA': 'No AAAA records'} — only failed types
print(result["response_times"])  # {'MX': 32.1, 'TXT': 28.5, 'A': 15.2}
print(result["validations"])   # {'mx': {'valid': True, 'issues': [], 'warnings': []}}
```

## Network Ping - ping_addr

Check reachability of an IP address or hostname using ICMP ping. Normalizes URLs before pinging so values like "https://example.com" are handled transparently.

```python
from nadzoring.network_base.ping_address import ping_addr

# Check if host is reachable
if ping_addr("8.8.8.8"):
    print("Google DNS is reachable")
else:
    print("Google DNS is unreachable")

# Ping a hostname
alive = ping_addr("google.com")
print(f"google.com reachable: {alive}")  # True

# URLs are normalized automatically
alive = ping_addr("https://github.com")
print(f"github.com reachable: {alive}")  # True

# Note: Some hosts block ICMP and will always return False
if not ping_addr("192.168.1.1"):
    print("Host unreachable or ICMP blocked")
```

## HTTP Ping - http_ping

Perform an HTTP request and collect detailed timing metrics including DNS resolution time, time-to-first-byte (TTFB), and total download duration.

```python
from nadzoring.network_base.http_ping import http_ping
from nadzoring.utils.timeout import TimeoutConfig

# Basic HTTP ping
result = http_ping("https://example.com")
if result.error:
    print(f"Request failed: {result.error}")
else:
    print(f"Status: {result.status_code}")        # 200
    print(f"DNS time: {result.dns_ms} ms")        # 15.2
    print(f"TTFB: {result.ttfb_ms} ms")           # 85.3
    print(f"Total time: {result.total_ms} ms")   # 120.5
    print(f"Content size: {result.content_length} bytes")

# Check for redirects
if result.final_url:
    print(f"Redirected to: {result.final_url}")

# With custom timeout and SSL verification disabled
config = TimeoutConfig(connect=3.0, read=10.0)
result = http_ping(
    "https://self-signed.example.com",
    timeout_config=config,
    verify_ssl=False,
    follow_redirects=True,
    include_headers=True,
)
if not result.error:
    for header, value in result.headers.items():
        print(f"{header}: {value}")
```

## Port Scanner - scan_ports

Scan multiple targets for open TCP/UDP ports with multi-threading support, banner grabbing, and service identification.

```python
from nadzoring.network_base.port_scanner import ScanConfig, scan_ports
from nadzoring.utils.timeout import TimeoutConfig

# Fast scan of common ports
config = ScanConfig(
    targets=["example.com"],
    mode="fast",  # fast | full | custom
    protocol="tcp",
)
results = scan_ports(config)

for scan in results:
    print(f"Target: {scan.target} ({scan.target_ip})")
    print(f"Duration: {scan.duration:.2f} seconds")
    print(f"Open ports: {scan.open_ports}")  # [80, 443, ...]

    for port in scan.open_ports:
        result = scan.results[port]
        print(f"  {port}/tcp - {result.service} - {result.response_time}ms")
        if result.banner:
            print(f"    Banner: {result.banner[:60]}...")

# Custom port scan with timeout
timeout = TimeoutConfig(connect=1.5, read=5.0, lifetime=60.0)
config = ScanConfig(
    targets=["192.168.1.1", "192.168.1.254"],
    mode="custom",
    custom_ports=[22, 80, 443, 8080, 3306, 5432],
    timeout_config=timeout,
    max_workers=100,
    grab_banner=True,
)
results = scan_ports(config)

# Full port scan (1-65535)
config = ScanConfig(
    targets=["target.example.com"],
    mode="full",
    protocol="tcp",
    max_workers=200,
)
results = scan_ports(config)
```

## SSL Certificate Check - check_ssl_certificate

Comprehensive SSL/TLS certificate check for a domain including expiration, issuer information, subject details, domain matching, key strength, and TLS protocol support.

```python
from nadzoring.security.check_website_ssl_cert import (
    check_ssl_certificate,
    check_ssl_expiry,
    check_ssl_expiry_with_fallback,
)
from nadzoring.utils.timeout import TimeoutConfig

# Comprehensive SSL check
result = check_ssl_certificate("example.com", days_before=14)

print(f"Status: {result['status']}")  # valid | warning | expired | error
print(f"Remaining days: {result['remaining_days']}")
print(f"Expiry date: {result['expiry_date']}")
print(f"Verification: {result['verification']}")  # verified | unverified | failed

# Subject and issuer information
print(f"Subject CN: {result.get('subject', {}).get('CN')}")
print(f"Issuer: {result.get('issuer', {}).get('CN')}")
print(f"Organization: {result.get('issuer', {}).get('O')}")

# Subject Alternative Names
for san in result.get("san", []):
    print(f"SAN: {san}")  # DNS:example.com, DNS:www.example.com

# Domain matching
print(f"Domain match: {result['domain_match']}")
print(f"Matched names: {result.get('matched_names', [])}")

# Key strength analysis
key = result.get("public_key", {})
print(f"Algorithm: {key.get('algorithm')}")  # RSA | EC | Ed25519
print(f"Key size: {key.get('key_size')}")    # 2048 (RSA/DSA)
print(f"Strength: {key.get('strength')}")    # weak | good | strong

# TLS protocol support
protocols = result.get("protocols", {})
print(f"Supported: {protocols.get('supported')}")   # ['TLSv1.2', 'TLSv1.3']
print(f"Has outdated: {protocols.get('has_outdated')}")  # True if TLSv1.0/1.1

# Automatic fallback for self-signed certificates
result = check_ssl_expiry_with_fallback("self-signed.example.com")
if result["verification"] == "unverified":
    print("Warning: Certificate verification was disabled")
```

## HTTP Security Headers - check_http_security_headers

Analyze HTTP security headers for a URL. Checks for eleven recommended headers, flags deprecated headers, identifies information-leaking headers, and produces a 0-100 coverage score.

```python
from nadzoring.security.http_headers import check_http_security_headers
from nadzoring.utils.timeout import TimeoutConfig

# Analyze security headers
result = check_http_security_headers("https://example.com")

print(f"URL: {result['url']}")
print(f"Status: {result['status_code']}")
print(f"Score: {result['score']}/100")

# Present security headers
print("\nPresent headers:")
for header, value in result["present"].items():
    print(f"  ✓ {header}: {value[:50]}...")

# Missing recommended headers
print("\nMissing headers:")
for header in result["missing"]:
    print(f"  ✗ {header}")

# Deprecated headers (e.g., X-XSS-Protection)
for header in result["deprecated"]:
    print(f"  ⚠ Deprecated: {header}")

# Information-leaking headers
for header, value in result["leaking"].items():
    print(f"  ⚠ Leaking: {header} = {value}")

# Error handling
if result["error"]:
    print(f"Request failed: {result['error']}")

# With custom timeout and SSL verification disabled
config = TimeoutConfig(connect=5.0, read=15.0)
result = check_http_security_headers(
    "https://internal.example.com",
    timeout_config=config,
    verify_ssl=False,
)
```

## ARP Cache - ARPCache

Retrieve and parse ARP cache entries from Linux, Windows, and macOS systems. Automatically detects the current platform and uses the appropriate command and parser.

```python
from nadzoring.arp.cache import ARPCache, ARPCacheRetrievalError
from nadzoring.arp.detector import ARPSpoofingDetector

# Get ARP cache entries
try:
    cache = ARPCache()
    entries = cache.get_cache()

    for entry in entries:
        print(f"{entry.ip_address} -> {entry.mac_address}")
        print(f"  Interface: {entry.interface}")
        print(f"  State: {entry.state.value}")  # reachable | stale | permanent | ...

except ARPCacheRetrievalError as exc:
    print(f"Cannot read ARP cache: {exc}")
    # Error includes platform-specific troubleshooting suggestions

# Detect ARP spoofing
try:
    cache = ARPCache()
    detector = ARPSpoofingDetector(cache)
    alerts = detector.detect()

    if not alerts:
        print("No spoofing detected")
    for alert in alerts:
        print(f"[{alert.alert_type}] {alert.description}")
        # alert_type: duplicate_mac | duplicate_ip

except ARPCacheRetrievalError as exc:
    print(f"ARP cache error: {exc}")
```

## CLI Usage Examples

The nadzoring CLI provides a hierarchical command structure with four main groups: dns, network-base, security, and arp.

```bash
# DNS Commands
nadzoring dns resolve google.com
nadzoring dns resolve -t MX -t TXT -n 8.8.8.8 example.com
nadzoring dns reverse 8.8.8.8 1.1.1.1
nadzoring dns health example.com
nadzoring dns trace example.com
nadzoring dns compare -t A -s 8.8.8.8 -s 1.1.1.1 example.com
nadzoring dns benchmark --queries 20 --parallel
nadzoring dns poisoning twitter.com

# Network Base Commands
nadzoring network-base ping 8.8.8.8 google.com
nadzoring network-base http-ping --show-headers https://example.com
nadzoring network-base port-scan --mode fast example.com
nadzoring network-base port-scan --mode custom --ports 22,80,443,8080 example.com
nadzoring network-base geolocation 8.8.8.8
nadzoring network-base traceroute google.com
nadzoring network-base domain-info example.com
nadzoring network-base whois example.com

# Security Commands
nadzoring security check-ssl example.com
nadzoring security check-ssl --days-before 30 --full google.com
nadzoring security check-headers https://example.com
nadzoring security check-email gmail.com
nadzoring security subdomains example.com
nadzoring security watch-ssl --interval 3600 example.com

# ARP Commands
nadzoring arp cache
nadzoring arp detect-spoofing
nadzoring arp monitor-spoofing --interface eth0

# Output Formats
nadzoring dns health -o json example.com
nadzoring dns health -o csv --save health.csv example.com
nadzoring security check-ssl -o html --save ssl_report.html example.com
nadzoring network-base port-scan -o yaml example.com

# Global Options
nadzoring --verbose dns resolve example.com
nadzoring --quiet --timeout 60 dns health example.com
nadzoring --connect-timeout 5 --read-timeout 10 dns resolve example.com
```

## Timeout Configuration

Nadzoring provides a unified timeout configuration system with three timeout types: connect (connection establishment), read (read operations), and lifetime (total operation limit).

```python
from nadzoring.utils.timeout import (
    TimeoutConfig,
    OperationTimeoutError,
    timeout_context,
    with_lifetime_timeout,
)

# Create timeout configuration
config = TimeoutConfig(
    connect=3.0,   # connection phase timeout
    read=8.0,      # read operations timeout
    lifetime=30.0, # total operation limit
)

# Use with any nadzoring function
from nadzoring.dns_lookup.utils import resolve_with_timer
result = resolve_with_timer("example.com", "A", timeout_config=config)

# Context manager for lifetime timeout
try:
    with timeout_context(config):
        result = long_running_operation()
except OperationTimeoutError:
    print("Operation exceeded lifetime timeout")

# Decorator for lifetime timeout
@with_lifetime_timeout(config)
def fetch_data():
    return expensive_network_operation()
```

## Summary

Nadzoring is particularly useful for network administrators, security professionals, and DevOps engineers who need to diagnose connectivity issues, monitor service availability, audit security configurations, and detect potential network attacks. Common use cases include DNS health monitoring for web services, SSL certificate expiration monitoring, HTTP security header auditing for compliance, port scanning for vulnerability assessment, and ARP spoofing detection for network security.

The library follows a consistent integration pattern where all public functions return structured dictionaries with error information rather than raising exceptions on expected failures. This makes it easy to integrate into automated monitoring systems, CI/CD pipelines, and alerting infrastructure. For long-running operations, the unified TimeoutConfig system provides fine-grained control over connection, read, and total operation timeouts, ensuring reliable behavior in production environments.