MrUnknownDE/utools
1
0
Fork 0
mirror of https://github.com/MrUnknownDE/utools.git synced 2026-04-06 00:32:04 +02:00
Code Issues 1 Packages Projects Releases Wiki Activity

chore: update README.md

Browse Source
This commit is contained in:
MrUnknownDE
2026-01-02 18:03:10 +01:00
parent a0ea88b2dd
commit 7f3566888d
1 changed files with 55 additions and 129 deletions
Download Patch File Download Diff File Expand all files Collapse all files

184
README.md
View File

@@ -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.
<!-- Optional: Füge hier einen Screenshot hinzu -->
<!-- ![Screenshot](link/to/your/screenshot.png) -->
### 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.
MIT License.