GitHub - themains/know-your-ip: Know Your IP: Get location, blacklist status, shodan and censys results, and more.

Know Your IP

Get comprehensive data on IP addresses. Learn where they are located (lat/long, country, city, time zone), whether they are flagged as malicious (by AbuseIPDB, VirusTotal, IPVoid, etc.), which ports are open and what services are running (via Shodan), and network diagnostics (ping, traceroute).

🚀 What's New in v0.2.0

Modern Configuration: TOML-based config with Pydantic validation
VirusTotal API v3: Latest API with enhanced threat intelligence
Embedded Categories: Self-contained AbuseIPDB category mapping
Python 3.11+ Features: Match/case syntax, union types, type safety
Performance Boost: No file I/O for category lookups
Environment Variables: Configuration via KNOW_YOUR_IP_* variables

Quick Start

Installation

Requirements: Python 3.11+

Basic Usage

Command Line

# Analyze single IP
know_your_ip 8.8.8.8

# Analyze from file
know_your_ip --file input.csv --config config.toml

Python Library

from know_your_ip import KnowYourIPConfig, query_ip

# Load configuration
config = KnowYourIPConfig()
config.virustotal.enabled = True
config.virustotal.api_key = "your_api_key"

# Analyze IP
result = query_ip(config, "8.8.8.8")
print(result['virustotal.reputation'])  # 530

Configuration

TOML Configuration File

Create know_your_ip.toml (see examples/know_your_ip.toml for full example):

[maxmind]
enabled = true
db_path = "./db"

[abuseipdb]
enabled = true
api_key = "your_api_key_here"
days = 90

[virustotal]
enabled = true
api_key = "your_api_key_here"

[output]
columns = [
    "ip",
    "maxmind.country.names.en",
    "virustotal.reputation",
    "abuseipdb.categories"
]

Environment Variables

export KNOW_YOUR_IP_VIRUSTOTAL_API_KEY="your_key"
export KNOW_YOUR_IP_VIRUSTOTAL_ENABLED=true
export KNOW_YOUR_IP_ABUSEIPDB_API_KEY="your_key"

Programmatic Configuration

from know_your_ip import KnowYourIPConfig

config = KnowYourIPConfig()
config.virustotal.api_key = "your_api_key"
config.abuseipdb.enabled = True
config.abuseipdb.days = 30

Supported Services

Service	Features	API Required
MaxMind	Geolocation, ASN, ISP	Free database
VirusTotal	Threat reputation, categories	✅ Free/Paid
AbuseIPDB	Abuse reports, categories	✅ Free/Paid
Shodan	Open ports, services	✅ Paid
Censys	Internet scanning data	✅ Free/Paid
IPVoid	Blacklist status	Web scraping
GeoNames	Timezone data	✅ Free
Ping/Traceroute	Network diagnostics	System tools

API Registration Links

VirusTotal - 500 requests/day, 4/min free
AbuseIPDB - 1,000 requests/day free
Shodan - Paid service ($69+/month)
Censys - 250 requests/month free
GeoNames - 10,000 requests/day, 1,000/hour free

Advanced Features

Pandas Integration

import pandas as pd
from know_your_ip import load_config, query_ip

# Load IPs from CSV
df = pd.read_csv('ips.csv')

# Load configuration
config = load_config()

# Analyze all IPs
results = df['ip'].apply(lambda ip: pd.Series(query_ip(config, ip)))
results.to_csv('analysis.csv', index=False)

Custom Analysis

from know_your_ip import maxmind_geocode_ip, virustotal_api

# Get only geolocation
location = maxmind_geocode_ip(config, "8.8.8.8")
print(f"Country: {location['maxmind.country.names.en']}")

# Get only threat intelligence
threat_data = virustotal_api(config, "8.8.8.8")
print(f"Malicious detections: {threat_data['virustotal.malicious']}")

Batch Processing

# Process large files with concurrency
know_your_ip --file large_ips.csv --max-conn 10 --config config.toml

# Process specific range
know_your_ip --file ips.csv --from 100 --to 200

API Reference

Core Functions

query_ip(config, ip) - Complete IP analysis
load_config(path) - Load configuration from file
maxmind_geocode_ip(config, ip) - Geolocation data
virustotal_api(config, ip) - VirusTotal threat intel
abuseipdb_api(config, ip) - Abuse reports
shodan_api(config, ip) - Port/service data
ping(config, ip) - Network latency
traceroute(config, ip) - Network path

Configuration Classes

KnowYourIPConfig - Main configuration
MaxMindConfig - Geolocation settings
VirusTotalConfig - Threat intel settings
AbuseIPDBConfig - Abuse data settings
OutputConfig - Output column configuration

Command Line Reference

usage: know_your_ip [-h] [-f FILE] [-c CONFIG] [-o OUTPUT] [-n MAX_CONN]
                    [--from FROM_ROW] [--to TO] [-v] [--no-header]
                    [ip [ip ...]]

Know Your IP - Comprehensive IP Address Analysis

positional arguments:
  ip                    IP Address(es) to analyze

optional arguments:
  -h, --help            show this help message and exit
  -f FILE, --file FILE  List of IP addresses file
  -c CONFIG, --config CONFIG
                        Configuration file (TOML format)
  -o OUTPUT, --output OUTPUT
                        Output CSV file name
  -n MAX_CONN, --max-conn MAX_CONN
                        Max concurrent connections
  --from FROM_ROW       From row number
  --to TO               To row number
  -v, --verbose         Verbose mode
  --no-header           Output without header

Rate Limits

Service	Free Tier	Paid Tier
VirusTotal	500/day, 4/min	Higher limits
AbuseIPDB	1,000/day	10,000+/day
Censys	250/month, 1 req/2.5s	Higher limits
GeoNames	10,000/day, 1,000/hour	Commercial plans
Shodan	No free API	$69+/month

Examples

See the examples/ directory for:

example.py - Basic usage examples
example.ipynb - Jupyter notebook tutorial
input.csv - Sample input file
output.csv - Sample output

System Requirements

Dependencies

Python 3.11+
System traceroute command (Linux) or tracert (Windows)
Raw socket access for ping (requires admin/root privileges)

Platform Support

✅ Linux
✅ macOS
✅ Windows
✅ Docker/containers

Documentation

For comprehensive documentation, visit: https://themains.github.io/know-your-ip/

Contributing

We welcome contributions! Please see our Contributing Guide and Code of Conduct.

License

Released under the MIT License.

Authors

Security Note: This tool is designed for legitimate security analysis, threat intelligence, and network diagnostics. Please use responsibly and in accordance with applicable laws and service terms of use.