add geoip

Signed-off-by: ale <ale@manalejandro.com>

README.md

@@ -8,8 +8,7 @@ A Node.js-based network packet capture tool that captures packets from network i
 - 🎯 **Flexible filtering**: Filter by protocol (TCP/UDP/ICMP), ports, and port ranges
 - 🔒 **Promiscuous mode support**: Optionally capture all packets on the network segment
 - 📊 **Elasticsearch integration**: Automatic indexing with optimized mapping
-- <20> **Failover cache**: In-memory cache for packets when Elasticsearch is unavailable
-- <20>📝 **Content extraction**: Captures and indexes readable (ASCII) packet content
+- <20> **Failover cache**: In-memory cache for packets when Elasticsearch is unavailable- 🌍 **GeoIP enrichment**: Automatic geolocation data for remote IP addresses- <20>📝 **Content extraction**: Captures and indexes readable (ASCII) packet content
 - 🚀 **Smart content handling**: Automatically skips large binary content while preserving packet metadata
 - 📈 **Real-time statistics**: Track capture performance and statistics
 - ⚙️ **Highly configurable**: Environment variables and config file support
@@ -52,6 +51,8 @@ cd /path/to/netpcap
 npm install
 ```
 
+**Note**: The `geoip-lite` package will download a GeoIP database on first install. This may take a few moments.
+
 3. Copy the example environment file and configure:
 ```bash
 cp .env.example .env
@@ -146,6 +147,52 @@ CACHE_CHECK_INTERVAL=5000
 - If cache reaches maximum size, oldest documents are removed (FIFO)
 - On graceful shutdown (SIGINT/SIGTERM), the system attempts to flush all cached documents
 
+## GeoIP Enrichment
+
+The application automatically enriches captured packets with geolocation data for remote IP addresses:
+
+**Features:**
+- Automatically detects the server's public IP address
+- Identifies private/local IP addresses (RFC 1918, link-local, etc.)
+- Only enriches remote public IP addresses
+- Uses local GeoIP database (no external API calls during capture)
+- Adds geolocation data for both source and destination IPs
+
+**GeoIP Data Included:**
+- Country code and name
+- Region/state
+- City
+- Timezone
+- Geographic coordinates (latitude/longitude)
+- Geo-point data for Elasticsearch geo queries
+
+**How it works:**
+1. On startup, the application detects its public IP using an external service (ipify.org)
+2. For each packet, it identifies if source/destination IPs are remote
+3. Remote IPs are enriched with GeoIP data from the local database
+4. Private IPs, loopback, and the server's own IP are excluded
+
+**Example GeoIP document structure:**
+```json
+{
+  "geoip_src": {
+    "country": "US",
+    "region": "CA",
+    "city": "San Francisco",
+    "timezone": "America/Los_Angeles",
+    "location": {
+      "lat": 37.7749,
+      "lon": -122.4194
+    }
+  },
+  "geoip_dst": {
+    "country": "DE",
+    "city": "Frankfurt",
+    ...
+  }
+}
+```
+
 ## Usage
 
 ### Basic Usage
@@ -229,6 +276,18 @@ The tool creates an index with the following document structure:
     "ack_seq": 0,
     "window": 65535
   },
+  "geoip_dst": {
+    "country": "US",
+    "country_name": "US",
+    "region": "CA",
+    "city": "Mountain View",
+    "timezone": "America/Los_Angeles",
+    "location": {
+      "lat": 37.4056,
+      "lon": -122.0775
+    },
+    "coordinates": [-122.0775, 37.4056]
+  },
   "content": "GET / HTTP/1.1\r\nHost: example.com\r\n",
   "content_length": 1024,
   "content_type": "binary"
@@ -281,6 +340,52 @@ curl -X GET "localhost:9200/network-packets/_search?pretty" -H 'Content-Type: ap
 '
 ```
 
+**Find packets from a specific country:**
+```bash
+curl -X GET "localhost:9200/network-packets/_search?pretty" -H 'Content-Type: application/json' -d'
+{
+  "query": {
+    "term": {
+      "geoip_src.country": "US"
+    }
+  }
+}
+'
+```
+
+**Find packets to/from a specific geographic area:**
+```bash
+curl -X GET "localhost:9200/network-packets/_search?pretty" -H 'Content-Type: application/json' -d'
+{
+  "query": {
+    "geo_distance": {
+      "distance": "100km",
+      "geoip_dst.location": {
+        "lat": 37.7749,
+        "lon": -122.4194
+      }
+    }
+  }
+}
+'
+```
+
+**Aggregate packets by destination country:**
+```bash
+curl -X GET "localhost:9200/network-packets/_search?pretty" -H 'Content-Type: application/json' -d'
+{
+  "size": 0,
+  "aggs": {
+    "countries": {
+      "terms": {
+        "field": "geoip_dst.country"
+      }
+    }
+  }
+}
+'
+```
+
 ## Performance Considerations
 
 - **Promiscuous mode** can generate high packet volumes on busy networks
@@ -327,11 +432,13 @@ curl -X GET "localhost:9200"
 ⚠️ **Important Security Notes:**
 
 - This tool captures network traffic and may contain sensitive information
+- GeoIP data reveals geographic locations of communication endpoints
 - Store Elasticsearch credentials securely
 - Restrict access to the Elasticsearch index
 - Be aware of privacy and legal implications when capturing network traffic
 - Use encryption for Elasticsearch connections in production
-- Comply with applicable laws and regulations
+- The public IP detection makes an external HTTPS call to ipify.org on startup
+- Comply with applicable laws and regulations regarding network monitoring and data retention
 
 ## License