ip-hunt 🔍

Advanced IP Intelligence & Reconnaissance Tool

   _____  .__  __      __________
  /  _  \ |__|/  |_   \______   \ ____  __ __  ____
 /  /_\  \|  \   __\   |     ___//  _ \|  |  \/ __ \
/    |    \  ||  |     |    |   (  <_> )  |  \  ___/
\____|__  /__||__|     |____|    \____/|____/ \___  >
        \/                                        \/

---

📖 Overview

ip-hunt is a powerful CLI utility that aggregates multiple data sources to provide comprehensive IP address intelligence. Built for security professionals, it combines geolocation lookup, threat intelligence, DNS reconnaissance, and risk scoring into a single, easy-to-use tool.

Whether you're investigating IOCs, analyzing network traffic, or conducting authorized penetration tests, ip-hunt delivers actionable intelligence fast.

---

✨ Features

Feature	Description
🌍 Geolocation	Country, city, region, coordinates, ISP, ASN details
🔴 Threat Intel	Tor exit nodes, proxy detection, blacklist status, abuse reports
🕸️ DNS Recon	Reverse DNS lookup, historical records
📊 Risk Scoring	Composite threat score (0-100) with risk level classification
🔄 Bulk Analysis	Process entire IP lists or CIDR ranges
💾 Local Cache	SQLite caching for faster repeated lookups
🖥️ Interactive Menu	User-friendly TUI for non-CLI users
📄 Export Reports	JSON output for automation and incident response

---

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/IncredibleHacker/ip-hunt.git
cd ip-hunt

# Create a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e .

Usage

Interactive Menu Mode (Recommended for Beginners)

ip-hunt --menu

This launches an interactive TUI with options for:

• Single IP lookup
• Bulk IP lookup from file
• CIDR range scanning
• Your public IP info
• Cache history viewing
• Settings management

Command-Line Mode

# Basic IP lookup
ip-hunt 8.8.8.8

# Full detailed report
ip-hunt 8.8.8.8 --full

# Your public IP
ip-hunt --mine

# Bulk lookup from file
ip-hunt --file iocs.txt --output results.json

# CIDR range scan
ip-hunt --cidr 192.168.1.0/24 --output scan.json

# Quiet mode (JSON only)
ip-hunt 8.8.8.8 --quiet

---

📸 Screenshots

Interactive Menu

┌─────────────────────────────────────────────┐
│              🔍 IP-HUNT MAIN MENU           │
├─────────────────────────────────────────────┤
  [1] Single IP Lookup
  [2] Bulk IP Lookup (from file)
  [3] CIDR Range Scan
  [4] My Public IP Info
  [5] View Cache History
  [6] Settings / API Keys
  [7] Clear Cache
  [8] Help / About
  [0] Exit
└─────────────────────────────────────────────┘

Full Report Example

╔═══════════════ 8.8.8.8  |  Risk Score: 0/100 [MINIMAL] ════════════════╗
║ ═══ GEOLOCATION ═══                                                    ║
║   Country:     United States (US)                                      ║
║   Region:      California                                              ║
║   City:        Mountain View                                           ║
║   ISP:         Google LLC                                              ║
║   ASN:         15169 Google LLC                                        ║
║                                                                        ║
║ ═══ THREAT INTELLIGENCE ═══                                            ║
║   Tor Exit Node:     No                                                ║
║   Proxy:             No                                                ║
║   Known Attacker:    No                                                ║
║   Abuse Confidence:  0%                                                ║
║                                                                        ║
║ ═══ RISK ASSESSMENT ═══                                                ║
║   Score:  0/100  |  Level:  MINIMAL                                    ║
╚════════════════════════════════════════════════════════════════════════╝

---

🔧 Configuration

Optional API Keys

ip-hunt works great with free APIs, but you can enhance results with optional API keys:

Service	Purpose	Get Key
VirusTotal	Malware/threat detections	virustotal.com
Shodan	Open port/service data	shodan.io
AbuseIPDB	Abuse reports & confidence	abuseipdb.com

Set API keys via environment variables:

export IPHUNT_VIRUSTOTAL_KEY="your_vt_key"
export IPHUNT_SHODAN_KEY="your_shodan_key"
export IPHUNT_ABUSEIPDB_KEY="your_abuseipdb_key"

Add these to your ~/.bashrc or ~/.zshrc for persistence.

---

📁 Project Structure

ip-hunt/
├── ip_hunt/
│   ├── __init__.py       # Package info
│   ├── cli.py            # CLI entry point (click-based)
│   ├── menu.py           # Interactive menu system
│   ├── intel.py          # IP intelligence engine
│   ├── models.py         # Data models (dataclasses)
│   └── formatters.py     # Rich terminal output
├── tests/
│   ├── __init__.py
│   └── test_intel.py     # Unit tests
├── data/                 # Data storage directory
├── pyproject.toml        # Package configuration
├── README.md             # This file
├── LICENSE               # MIT License
└── example_iocs.txt      # Sample IOC list

---

🧪 Running Tests

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

---

📊 Risk Scoring

ip-hunt calculates a composite risk score (0-100) based on:

Factor	Weight
Tor exit node	+20
Known attacker	+30
Known abuser	+25
Threat listed (VT)	+20
Blacklist count	+10 per list (max 30)
Abuse confidence	30% of score

Risk Levels:

• CRITICAL (80-100)
• HIGH (60-79)
• MEDIUM (40-59)
• LOW (20-39)
• MINIMAL (0-19)

---

🔌 API Integration

Data Sources

ip-hunt queries multiple sources for comprehensive intelligence:

Source	Type	Auth Required
ip-api.com	Geolocation	No
ipwho.is	Geolocation (fallback)	No
Tor Project	Tor exit node list	No
VirusTotal	Threat detections	Yes (optional)
AbuseIPDB	Abuse reports	Yes (optional)
Shodan	Service enumeration	Yes (optional)

---

💡 Use Cases

1. SOC Analysis

# Investigate suspicious IPs from SIEM alerts
ip-hunt 185.220.101.1 --full --output incident_001.json

2. Threat Intelligence Enrichment

# Bulk process IOCs from threat feed
ip-hunt --file threat_feed_iocs.txt --output enriched_iocs.json

3. Incident Response

# Quick lookup during incident handling
ip-hunt --menu  # Use interactive mode for speed

4. Network Reconnaissance

# Scan subnet for external-facing hosts
ip-hunt --cidr 10.0.0.0/24 --output network_audit.json

---

🛠️ Development

Setting Up Development Environment

# Clone and setup
git clone https://github.com/IncredibleHacker/ip-hunt.git
cd ip-hunt
python -m venv venv
source venv/bin/activate

# Install with dev dependencies
pip install -e ".[dev]"

# Run linting
ruff check ip_hunt/
black --check ip_hunt/

# Run tests
pytest tests/ -v

Building from Source

# Build wheel
pip install build
python -m build

# Install locally
pip install dist/ip_hunt-*.whl

---

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

⚠️ Disclaimer

This tool is for educational and authorized security testing only.

• Always obtain proper authorization before scanning networks
• Respect rate limits of free APIs
• Do not use for malicious purposes
• The developers are not responsible for misuse

---

🤝 Contributing

Contributions are welcome! Here's how you can help:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Areas for Contribution

• Additional data sources/API integrations
• Report templates (HTML, PDF)
• Advanced filtering options
• Performance improvements
• Documentation enhancements

---

📧 Contact

• GitHub: @IncredibleHacker
• Project Link: https://github.com/IncredibleHacker/ip-hunt

---

🙏 Acknowledgments

• ip-api.com - Free geolocation API
• ipwho.is - IP geolocation service
• Tor Project - Tor exit node list
• VirusTotal - Threat intelligence
• AbuseIPDB - Abuse reports database

---

Made with ❤️ for the security community

⭐ Star this repo if you find it useful!