bytegeist-toolbox/README.md

ByteGeist Toolbox

ByteGeist Toolbox is a plain Node.js and Express web app that provides practical website and network inspection tools from a single browser page.

Live site: https://toolbox.casko.dev

Tools

1. Website Status Checker

   • Accepts a public HTTP or HTTPS URL.
   • Returns online status, HTTP status code, response time, redirect count, final URL, and check timestamp.

2. DNS Lookup

   • Accepts a public hostname or pasted website URL.
   • Returns A, AAAA, CNAME, MX, TXT, and NS records plus a check timestamp.

3. SSL Certificate Checker

   • Accepts a public hostname or pasted website URL.
   • Returns certificate trust status, subject, issuer, validity dates, days remaining, TLS protocol, cipher, resolved address, SHA-256 fingerprint, authorization error when present, and check timestamp.

4. HTTP Headers Checker

   • Accepts a public HTTP or HTTPS URL.
   • Returns HTTP status, redirect count, final URL, all response headers, and whether common security headers are present.
   • The header review is informational. It is not a complete website security grade.

Technology Stack

• Plain HTML
• Plain CSS
• Plain browser JavaScript
• Node.js
• Express
• Docker and Docker Compose
• Node's built-in test runner

Project Structure

.
|-- Dockerfile
|-- docker-compose.yml
|-- LICENSE
|-- package-lock.json
|-- package.json
|-- README.md
|-- docs
|   |-- DEPLOYMENT.md
|   |-- PORTFOLIO.md
|   |-- RELEASE_CHECKLIST.md
|   `-- screenshots
|       `-- .gitkeep
|-- public
|   |-- app.js
|   |-- index.html
|   `-- styles.css
|-- src
|   |-- middleware
|   |   |-- rateLimit.js
|   |   `-- validateHostname.js
|   |-- routes
|   |   |-- dns.js
|   |   |-- headers.js
|   |   |-- ssl.js
|   |   `-- uptime.js
|   |-- server.js
|   `-- services
|       |-- dnsService.js
|       |-- headersService.js
|       |-- sslService.js
|       |-- uptimeService.js
|       `-- urlSecurityService.js
`-- tests
    |-- dnsService.test.js
    |-- headersService.test.js
    |-- sslService.test.js
    |-- urlSecurityService.test.js
    `-- validateHostname.test.js

Security Controls

The code implements these controls for server-side outbound requests:

• Allows only http: and https: URLs for URL-based tools.
• Blocks credentials in submitted URLs.
• Allows only standard ports 80 and 443 for URL-based tools.
• Blocks common local hostnames including localhost, .localhost, .local, and host.docker.internal.
• Resolves hostnames before outbound requests and blocks loopback, private, link-local, unique-local, multicast, unspecified, reserved, broadcast, and carrier-grade NAT addresses.
• Revalidates every redirect destination before following it.
• Limits redirects to 5.
• Uses 5 second network timeouts for HTTP and TLS checks.
• Applies Express rate limiting of 30 requests per IP per 15 minutes on tool API routes.
• Returns safe client-facing error messages instead of raw low-level network errors.
• Uses Node DNS, Fetch, and TLS APIs without shell execution.

Tests

Current test command:

npm test

Current automated test count: 62 tests.

Baseline verified result: 62 pass, 0 fail, 0 skipped.

The current npm test suite includes public-network integration checks for DNS, SSL, and HTTP headers. Internet access is required for the full suite as currently organized.

Local Development

Install dependencies:

npm install

Run tests:

npm test

Start local development with nodemon:

npm run dev

Start without nodemon:

npm start

The app listens on port 3001 by default. The health endpoint is:

GET /health

It returns JSON shaped like:

{"status":"ok","service":"bytegeist-toolbox","timestamp":"2026-07-23T10:03:36.388Z"}

The timestamp is generated at request time.

Docker

Build and run with Docker Compose:

docker compose up -d --build

Check status:

docker compose ps
docker compose logs --tail=100

Stop the service:

docker compose down

The container runs the production start command:

npm start

The production application port is 3001.

Production Deployment

Production is intended to run as a Docker Compose service named bytegeist-toolbox on port 3001, behind Nginx Proxy Manager.

The Compose file attaches the application to the external Docker network:

nginx-proxy-manager_default

Nginx Proxy Manager should proxy to:

http://bytegeist-toolbox:3001

Do not assume the Nginx Proxy Manager container name. Confirm container names with:

docker ps

Repository Workflow

The configured remotes are:

origin  https://git.casko.dev/keith/bytegeist-toolbox.git
github  https://github.com/kcasko/bytegeist-toolbox.git

Use origin for the primary Gitea repository and github for the GitHub mirror.

Screenshots

No screenshot image files currently exist under docs/screenshots/.

Expected screenshot filenames for the v1.0.0 README are:

docs/screenshots/status-checker.png
docs/screenshots/dns-lookup.png
docs/screenshots/ssl-checker.png
docs/screenshots/http-headers.png

Add image references to this README only after those files exist.

Current Limitations

• The automated test suite mixes local helper tests with public-network integration tests.
• DNS and network integration tests depend on external DNS and public websites being reachable.
• The HTTP Headers Checker reports common header presence only; it does not evaluate full security posture.
• The app checks public endpoints only and intentionally blocks local, private, reserved, and nonstandard-port destinations.
• Screenshots have not yet been captured for README display.

Planned Improvements

• Split public-network integration tests from local unit tests while preserving coverage.
• Add screenshot images for all four tools.
• Add local mock-based route tests for API responses and error paths.
• Add manual release evidence for mobile screenshots and production verification.

Author

Keith Casko