Prepare ByteGeist Toolbox v1.0.0 release
This commit is contained in:
Keith Casko
@@ -0,0 +1,245 @@
|
||||
# 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](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
|
||||
|
||||
```text
|
||||
.
|
||||
|-- 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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
Run tests:
|
||||
|
||||
```bash
|
||||
npm test
|
||||
```
|
||||
|
||||
Start local development with nodemon:
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Start without nodemon:
|
||||
|
||||
```bash
|
||||
npm start
|
||||
```
|
||||
|
||||
The app listens on port `3001` by default. The health endpoint is:
|
||||
|
||||
```text
|
||||
GET /health
|
||||
```
|
||||
|
||||
It returns JSON shaped like:
|
||||
|
||||
```json
|
||||
{"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:
|
||||
|
||||
```bash
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
Check status:
|
||||
|
||||
```bash
|
||||
docker compose ps
|
||||
docker compose logs --tail=100
|
||||
```
|
||||
|
||||
Stop the service:
|
||||
|
||||
```bash
|
||||
docker compose down
|
||||
```
|
||||
|
||||
The container runs the production start command:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```text
|
||||
nginx-proxy-manager_default
|
||||
```
|
||||
|
||||
Nginx Proxy Manager should proxy to:
|
||||
|
||||
```text
|
||||
http://bytegeist-toolbox:3001
|
||||
```
|
||||
|
||||
Do not assume the Nginx Proxy Manager container name. Confirm container names with:
|
||||
|
||||
```bash
|
||||
docker ps
|
||||
```
|
||||
|
||||
## Repository Workflow
|
||||
|
||||
The configured remotes are:
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```text
|
||||
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
|
||||
|
||||
Reference in New Issue
Block a user