From 7f3566888d2488c6ce451319763705534ca35453 Mon Sep 17 00:00:00 2001 From: MrUnknownDE Date: Fri, 2 Jan 2026 18:03:10 +0100 Subject: [PATCH] chore: update README.md --- README.md | 184 ++++++++++++++++-------------------------------------- 1 file changed, 55 insertions(+), 129 deletions(-) diff --git a/README.md b/README.md index 233dae0..51886e5 100755 --- a/README.md +++ b/README.md @@ -5,9 +5,6 @@ A modern web application that displays detailed information about a client's IP address, including geolocation, ASN, rDNS, and provides network diagnostic tools like Ping, Traceroute, DNS Lookup, Subnet Calculation, and WHOIS Lookup. It also allows looking up information for any public IP address. - - - ### Preview: https://utools.mrunk.de ## 🚀 Features @@ -16,155 +13,84 @@ A modern web application that displays detailed information about a client's IP * **Geolocation:** Shows Country, Region, City, Postal Code, Coordinates, and Timezone based on the IP. * **ASN Information:** Displays the Autonomous System Number (ASN) and organization name. * **Reverse DNS (rDNS):** Performs a reverse DNS lookup for the IP address. -* **Interactive Map:** Visualizes the geolocation on an OpenStreetMap. +* **Interactive Dark Mode Map:** Visualizes the geolocation on a dark-themed OpenStreetMap/CartoDB map. +* **Glassmorphism UI:** Features a premium, modern transparent design with animated gradients. * **IP Lookup:** Allows users to enter any public IP address to retrieve its Geo, ASN, and rDNS information. -* **Traceroute:** Initiates a server-side traceroute (via SSE stream) to the client's IP (on click) or a looked-up IP. +* **Traceroute:** Initiates a server-side traceroute (via SSE stream) to the client's IP or a looked-up IP. * **Ping:** Performs a server-side ping test to a looked-up IP. * **DNS Lookup:** Performs various DNS record lookups (A, AAAA, MX, NS, TXT, SOA) for a given domain. -* **Subnet Calculator:** Calculates network details (Network Address, Broadcast Address, Usable Hosts, etc.) for a given IP and CIDR or Subnet Mask. +* **Subnet Calculator:** Calculates network details (address ranges, usable hosts) for IPv4 subnets. * **WHOIS Lookup:** Retrieves WHOIS information for a given domain or IP address. -* **Dockerized:** Both frontend and backend are containerized for easy deployment. -* **Modern UI:** Built with Tailwind CSS for a clean and responsive interface. +* **MAC Address Lookup:** Identifies the vendor/manufacturer of a network interface using OUI data. +* **Port Scan:** Scans common ports of a target IP (via SSE stream). +* **Dockerized:** both frontend and backend are containerized for easy deployment. + +## 📚 API Usage + +The backend exposes several RESTful endpoints that return JSON data. + +| Endpoint | Method | Params | Description | +| :--- | :--- | :--- | :--- | +| `/api/ipinfo` | `GET` | None | Returns info for the requestor's IP. | +| `/api/lookup` | `GET` | `targetIp` | Returns Geo/ASN info for a specific IP. | +| `/api/dns-lookup` | `GET` | `domain`, `type` | Resolves DNS records (A, AAAA, MX, etc.). | +| `/api/whois-lookup` | `GET` | `query` | Performs a WHOIS lookup for a domain or IP. | +| `/api/mac-lookup` | `GET` | `mac` | Returns the vendor for a MAC address. | +| `/api/ping` | `GET` | `targetIp` | Pings an IP address (returns 4 packets). | +| `/api/traceroute` | `GET` | `targetIp` | Streams traceroute hops via Server-Sent Events (SSE). | +| `/api/port-scan` | `GET` | `targetIp` | Streams port scan results via Server-Sent Events (SSE). | + +### Examples + +**Lookup an IP:** +```bash +curl "http://localhost:3000/api/lookup?targetIp=8.8.8.8" +``` + +**DNS Lookup:** +```bash +curl "http://localhost:3000/api/dns-lookup?domain=google.com&type=A" +``` + +**MAC Vendor Lookup:** +```bash +curl "http://localhost:3000/api/mac-lookup?mac=00:50:56:C0:00:08" +``` ## 🛠️ Tech Stack -* **Backend:** - * Node.js - * Express.js - * MaxMind GeoLite2 Databases (for GeoIP and ASN) - * Pino (for logging) - * `whois-json` (for WHOIS lookups) - * `net`, `dns`, `child_process` (Node.js built-ins for Ping, Traceroute, rDNS, DNS Lookup) - * `@sentry/node` (optional error tracking) -* **Frontend:** - * Vanilla JavaScript (ES6+) - * Tailwind CSS (via Play CDN for simplicity, can be built) - * Leaflet.js (for OpenStreetMap) - * Nginx (for serving static files and as a reverse proxy) -* **Deployment:** - * Docker & Docker Compose - * GitHub Actions (for CI/CD - building and pushing images to GHCR) +* **Backend:** Node.js, Express.js, MaxMind GeoLite2, `oui`, `whois-json`, `@sentry/node`. +* **Frontend:** Vanilla JS, Tailwind CSS, Leaflet.js. +* **Deployment:** Docker, GitHub Actions. ## 🏁 Getting Started -You can run this application easily using Docker and Docker Compose. - -### Prerequisites - -* [Docker](https://docs.docker.com/get-docker/) installed -* [Docker Compose](https://docs.docker.com/compose/install/) installed (usually included with Docker Desktop) - -### Option 1: Using Pre-built Images (Recommended) - -This method uses the Docker images automatically built and pushed to GitHub Container Registry (GHCR) by the GitHub Actions workflow. +### Using Pre-built Images (Recommended) 1. **Create `compose.yml`:** - Save the following content as `compose.yml` in a new directory on your machine: + (See provided `compose.yml` in repository) - ```yaml - services: - # Backend Service (Node.js App) - backend: - # Verwendet ein bereits gebautes Image - image: ghcr.io/mrunknownde/utools-backend:latest - container_name: utools_backend - restart: unless-stopped - environment: - # Setze Umgebungsvariablen für das Backend - NODE_ENV: production # Wichtig für Performance und Logging - PORT: 3000 # Port innerhalb des Containers - LOG_LEVEL: info # Oder 'warn' für weniger Logs in Produktion - PING_COUNT: 4 - # Sentry DSN aus der Umgebung/ .env Datei übernehmen - SENTRY_DSN: "https://7ea70caba68f548fb96482a573006a7b@o447623.ingest.us.sentry.io/4509062020333568" # Wichtig für die Laufzeit - dns: - - 1.1.1.1 # Cloudflare DNS - - 1.0.0.1 # Cloudflare DNS - - 8.8.8.8 # Google DNS - - 8.8.4.4 # Google DNS - networks: - - utools_network # Verbinde mit unserem benutzerdefinierten Netzwerk - - # Frontend Service (Nginx) - frontend: - # Verwendet ein bereits gebautes Image - image: ghcr.io/mrunknownde/utools-frontend:latest - container_name: utools_frontend - restart: unless-stopped - ports: - # Mappe Port 8080 vom Host auf Port 80 im Container (wo Nginx lauscht) - # Zugriff von außen (Browser) erfolgt über localhost:8080 - - "8080:80" - depends_on: - - backend # Stellt sicher, dass Backend gestartet wird (aber nicht unbedingt bereit ist) - networks: - - utools_network # Verbinde mit unserem benutzerdefinierten Netzwerk - - # Definiere ein benutzerdefiniertes Netzwerk (gute Praxis) - networks: - utools_network: - driver: bridge - ``` - -2. **Start the Application:** - Open a terminal in the directory where you saved the `compose.yml` file and run: +2. **Start:** ```bash docker compose up -d ``` - *(Note: Use `docker-compose` (with hyphen) if you have an older version)* - This will download the images (if not already present) and start the containers in the background. -3. **Access the Webapp:** - Open your web browser and navigate to `http://localhost:8080`. - -### Option 2: Building Images from Source - -If you want to modify the code or build the images yourself, the project is now split into a build and a run configuration. - -1. **Clone the Repository:** - ```bash - git clone https://github.com/mrunknownde/utools.git - cd utools - ``` -2. **Build and Start:** - First, you build the images using `compose.build.yml`. Then, you start the services using the main `compose.yml`. - - ```bash - # Set GIT_COMMIT_SHA for the build process - export GIT_COMMIT_SHA=$(git rev-parse --short HEAD) - - # 1. Build the images - docker compose -f compose.build.yml build - - # 2. Run the services using the newly built images - docker compose -f compose.yml up -d - ``` - You can also use the provided `build.sh` script which does these steps for you. - -3. **Access the Webapp:** - Open your web browser and navigate to `http://localhost:8080`. +3. **Access:** `http://localhost:8080` ## ⚙️ Configuration -The application is configured mainly through environment variables set in the `compose.yml` file for the `backend` service: - -* `NODE_ENV`: Set to `production` for optimal performance and JSON logging. -* `PORT`: The internal port the Node.js application listens on (default: `3000`). -* `LOG_LEVEL`: Controls the logging verbosity (e.g., `debug`, `info`, `warn`, `error`). -* `PING_COUNT`: Number of ping packets to send (default: `4`). -* `SENTRY_DSN` (Optional): Your Sentry Data Source Name for error tracking. Can be set during build via args or at runtime via environment variable. -* `dns` (in compose): Specifies DNS servers for the backend container, crucial for reliable rDNS lookups. - -The MaxMind database paths (`GEOIP_CITY_DB`, `GEOIP_ASN_DB`) are set within the backend's Dockerfile but could potentially be overridden if needed (e.g., using volumes). +Key environment variables for the backend: +* `NODE_ENV`: `production` or `development`. +* `PORT`: Internal port (default 3000). +* `RATE_LIMIT_MAX`: Requests per window (e.g., 50). +* `SENTRY_DSN`: Optional Sentry integration. ## 🌐 Data Sources -* **Geolocation & ASN:** This tool uses GeoLite2 data created by MaxMind, available from [https://www.maxmind.com](https://www.maxmind.com). - * **Important:** The GeoLite2 databases require periodic updates. You need a MaxMind account (free) to download them. The Docker images contain the databases at build time. For long-term use, you should implement a process to update the `.mmdb` files within the `backend/data` directory (if using volumes) or rebuild the backend image regularly using the provided GitHub Action workflow (`maxmind-update.yml`). -* **Map Tiles:** Provided by OpenStreetMap contributors. -* **WHOIS Data:** Retrieved in real-time using the `whois-json` library, which queries standard WHOIS servers. -* **DNS Data:** Retrieved in real-time using Node.js' built-in `dns` module. +* **Geolocation:** [MaxMind GeoLite2](https://www.maxmind.com). +* **Map Tiles:** [OpenStreetMap](https://www.openstreetmap.org) & [CartoDB](https://carto.com). +* **MAC Data:** [IEEE OUI](https://standards.ieee.org/products-services/regauth/oui/index.html). ## 📜 License -This project is licensed under the MIT License. See the `LICENSE` file for details. \ No newline at end of file +MIT License. \ No newline at end of file