@tallerweb/web-audit

Lightweight web security configuration audit engine. Analyzes HTTPS, TLS certificates, security headers, cookies, DNS records, and HTTP configuration to provide a security score and actionable findings.

Features

• HTTPS/TLS Analysis - Verifies HTTPS usage, redirect chains, and certificate validity
• Security Headers - Checks HSTS, CSP, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy
• Cookie Security - Validates Secure, HttpOnly, and SameSite attributes
• DNS Analysis - Basic DNS check with optional deep analysis (A, AAAA, MX, SPF, DMARC records)
• HTTP Configuration - Detects redirect chains, mixed protocols, exposed sensitive paths, clickjacking protection
• Scoring - Weighted severity-based scoring (0-100) with labels: Critical, Poor, Needs Improvement, Good, Strong
• SSRF Protection - Blocks private IPs, localhost, metadata endpoints, and DNS rebinding attacks
• Runtime Agnostic - Core engine works in Edge, Node.js, Bun, Deno (optional features require Node.js)

Installation

npm install @tallerweb/web-audit
# or
pnpm add @tallerweb/web-audit
# or
yarn add @tallerweb/web-audit

Quick Start

import { auditWebsite } from '@tallerweb/web-audit';

const result = await auditWebsite('https://example.com');

console.log(result.score);        // 0-100
console.log(result.scoreLabel);   // 'Strong' | 'Good' | 'Needs improvement' | 'Poor' | 'Critical'
console.log(result.summary);      // Human-readable summary
console.log(result.highlights);   // Top non-info findings

Options

const result = await auditWebsite('https://example.com', {
  timeout: 10000,           // Request timeout in ms (default: 8000)
  maxRedirects: 5,          // Max redirect hops (default: 5)
  maxResponseSize: 1024 * 1024, // Max response body size (default: 1MB)
  userAgent: 'MyApp/1.0',   // Custom User-Agent (default: 'TallerWeb-SecurityScanner/1.0')
  deepDns: false,           // Enable deep DNS analysis (Node.js only, default: false)
  fetchCert: false,         // Fetch full TLS certificate (Node.js only, default: false)
});

Result Format

interface AuditResult {
  url: string;
  score: number;                    // 0-100
  scoreLabel: string;               // 'Strong' | 'Good' | 'Needs improvement' | 'Poor' | 'Critical'
  summary: string;                  // Human-readable summary
  counts: Record<Severity, number>; // { critical, high, medium, low, info }
  highlights: PublicHighlight[];    // Top 10 non-info findings
  findings?: AuditFinding[];        // All detailed findings (optional)
  certificate?: CertificateInfo;    // TLS cert details (when fetchCert: true)
  dnsRecords?: DnsRecords;          // DNS records (when deepDns: true)
}

Audit Rules

HTTPS

• https-enabled (info) - Site uses HTTPS
• https-not-used (high) - Site only accessible via HTTP
• http-redirects-to-https (info) - HTTP correctly redirects to HTTPS
• http-no-redirect-to-https (medium) - HTTP does not redirect to HTTPS

TLS

• tls-cert-expired (critical) - Certificate has expired
• tls-cert-expiring-soon (high) - Certificate expires within 30 days
• tls-cert-valid (info) - Certificate is valid
• tls-cert-details-unavailable (info) - Full cert details require fetchCert: true
• tls-cert-fetch-failed (info) - Failed to fetch certificate

Headers

• hsts-header (high/info) - HSTS configured / missing / misconfigured
• csp-header (high/info) - CSP configured / missing / has unsafe directives
• x-content-type-options-header (medium/info) - nosniff configured / missing
• x-frame-options-header (medium/info) - DENY/SAMEORIGIN configured / missing
• referrer-policy-header (low/info) - Valid policy configured / missing
• permissions-policy-header (low/info) - Policy configured / missing
• server-header-exposed (info) - Server header reveals version info
• info-header-* (info) - Technology fingerprinting headers (X-Powered-By, etc.)

Cookies

• cookie-secure-{name} (info) - Cookie has Secure, HttpOnly, SameSite
• cookie-insecure-{name} (medium/low) - Cookie missing security attributes

DNS (deepDns: true)

• dns-a-records / dns-no-a-records (info/medium) - IPv4 resolution
• dns-aaaa-records (info) - IPv6 resolution
• dns-mx-records / dns-no-mx-records (info/low) - Mail exchangers
• dns-spf-record / dns-no-spf-record (info/medium) - SPF record
• dns-dmarc-record / dns-no-dmarc-record (info/medium) - DMARC record
• dns-dnssec-status (info) - DNSSEC status

HTTP Configuration

• redirect-chain-mixed-protocols (low) - Redirect chain mixes HTTP/HTTPS
• redirect-chain-long (low) - More than 3 redirect hops
• html-over-http (medium) - HTML served over unencrypted HTTP
• exposed-sensitive-path-* (medium) - Paths like /.git/, /admin/, /.env exposed
• no-framing-protection (medium) - No X-Frame-Options or CSP frame-ancestors

Error Handling

import { auditWebsite, ValidationError, HttpError } from '@tallerweb/web-audit';

try {
  const result = await auditWebsite('https://example.com');
} catch (err) {
  if (err instanceof ValidationError) {
    // Invalid URL, blocked hostname, private IP, etc.
    console.error(err.code, err.message);
  } else if (err instanceof HttpError) {
    // Network error, timeout, response too large
    console.error(err.code, err.message);
  } else {
    throw err;
  }
}

Security Considerations

SSRF Protection

The package implements multiple layers of SSRF protection:

1. Protocol validation - Only http: and https: allowed
2. Hostname blocking - localhost, .local, .internal, metadata endpoints
3. Private IP blocking - RFC1918 (10.x, 172.16-31.x, 192.168.x), loopback (127.x), link-local (169.254.x), IPv6 ULA (fc00::/7)
4. DNS rebinding protection - Resolves hostname and verifies IPs aren't private
5. URL length limits - Maximum 2048 characters

Node.js-Only Features

The following features require Node.js runtime (not available in Edge/Bun/Deno):

• deepDns: true - Uses dns/promises for A, AAAA, MX, TXT, SPF, DMARC resolution
• fetchCert: true - Uses tls.connect() to fetch full certificate details

These options are safely ignored in non-Node environments with informative findings.

What This Is NOT

• ❌ Not a vulnerability scanner (no SQLi, XSS, RCE detection)
• ❌ Not a penetration testing tool
• ❌ Not a replacement for professional security audits
• ❌ Does not scan for malware or backend vulnerabilities
• ❌ Does not authenticate or test authenticated endpoints

This is a configuration audit - it analyzes what's visible from the outside (headers, certificates, cookies, DNS).

License

MIT