| Name | ipfindx JSON |
| Version |
3.0.1
JSON |
| download |
| home_page | https://github.com/VritraSecz/IPFindX |
| Summary | Advanced IP Intelligence Toolkit for cybersecurity professionals |
| upload_time | 2025-08-06 18:35:13 |
| maintainer | None |
| docs_url | None |
| author | Alex Butler |
| requires_python | >=3.7 |
| license | MIT License
Copyright (c) 2025 Alex Butler (Vritra Security Organization)
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
|
| keywords |
ip
intelligence
geolocation
osint
cybersecurity
network
security
threat-intelligence
ip-lookup
cybersec
infosec
penetration-testing
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<div align="center">
# 🌐 IPFindX - Advanced IP Intelligence Toolkit
<p>
<img src="https://img.shields.io/badge/💎-Premium%20OSINT%20Tool-blueviolet?style=for-the-badge" alt="Premium Tool">
<img src="https://img.shields.io/badge/🎯-Cybersecurity%20Professional-red?style=for-the-badge" alt="Professional">
<img src="https://img.shields.io/badge/⚡-Lightning%20Fast-yellow?style=for-the-badge" alt="Fast">
</p>
### 🚀 *The Ultimate IP Intelligence Reconnaissance Platform for Security Professionals*
**Unleash the power of advanced IP geolocation, threat intelligence, and network forensics in a single, elegant command-line interface. Built by cybersecurity experts, for cybersecurity experts.**
[](https://www.python.org/downloads/)
[](LICENSE)
[](#compatibility)
[](#overview)
[](#overview)
[](#contributing)
[](https://github.com/VritraSecz/IPFindX)
[](https://github.com/VritraSecz/IPFindX)
[](https://github.com/VritraSecz/IPFindX/issues)
[](https://github.com/VritraSecz/IPFindX/graphs/contributors)
[](https://github.com/VritraSecz/IPFindX)
[](https://github.com/VritraSecz/IPFindX)
</div>
---
## 📋 Table of Contents
- [Overview](#-overview)
- [Features](#-features)
- [Requirements](#-requirements)
- [Installation](#-installation)
- [Usage](#-usage)
- [Output Examples](#️-output-examples)
- [Screenshots](#-screenshots)
- [Use Cases](#-use-cases)
- [Project Structure](#-project-structure)
- [API Integration](#-api-integration)
- [Performance](#-performance)
- [Compatibility](#-compatibility)
- [Security Considerations](#-security-considerations)
- [Contributing](#-contributing)
- [Roadmap](#-roadmap)
- [Developer](#-developer)
- [License](#-license)
- [Acknowledgements](#-acknowledgements)
## 🔮 Overview
**IPFindX** is a professional-grade command-line IP intelligence toolkit designed for cybersecurity professionals, network administrators, threat hunters, and OSINT researchers. It provides comprehensive geolocation data, ISP information, security threat indicators, and detailed network intelligence for any public IP address with enterprise-level accuracy.
With its beautifully designed terminal interface and powerful data processing capabilities, IPFindX transforms complex IP reconnaissance into an efficient, streamlined process, delivering actionable intelligence in seconds.
### Key Highlights
- 🎯 **Enterprise-Grade Intelligence**: Detailed geolocation, ISP, organization, and network data with high accuracy
- 🎨 **Elegant CLI Interface**: Rich terminal output with color-coded information and professionally designed tables
- 💾 **Seamless Data Persistence**: All results automatically saved as timestamped JSON files for future analysis
- 📊 **Advanced Batch Processing**: Scan multiple IPs from a file with intelligent progress tracking
- 🛡️ **Sophisticated Validation**: Automatically validates IP addresses and filters private/reserved ranges
- 🗺️ **Integrated Geographic Visualization**: Direct Google Maps integration for precise location mapping
- 🔄 **Real-time Data**: Always up-to-date information from trusted IP intelligence sources
- ⚙️ **Zero Configuration**: Works out of the box with no complex setup or configuration required
## ✨ Features
### Core Functionality
- **Single IP Lookup**: Get comprehensive information for any public IP address
- **Batch IP Scanning**: Process multiple IPs from a text file
- **Geolocation Data**: Country, region, city, coordinates, and timezone information
- **Network Intelligence**: ISP, organization, AS number, and hosting detection
- **Security Indicators**: Proxy, mobile, and hosting status detection
- **DNS Resolution**: Reverse DNS lookup for hostname identification
### Advanced Features
- **Smart IP Validation**: Automatically detects and rejects private/reserved IP ranges
- **Geographic Mapping**: Direct integration with Google Maps for location visualization
- **Timestamped Output**: Organized output files with date/time stamps
- **Progress Tracking**: Real-time status updates for long-running operations
- **Error Handling**: Robust error handling with informative user feedback
### User Experience
- **Rich Terminal Output**: Beautiful tables and panels with syntax highlighting
- **Responsive Design**: Adapts to different terminal sizes with fallback layouts
- **Color-coded Results**: Status indicators and field highlighting for easy reading
- **Organized Storage**: Automatic creation of output directories and file management
## 📋 Requirements
### System Requirements
- **Python**: Version 3.7 or higher
- **Operating System**: Linux, macOS, Windows
- **Internet Connection**: Required for IP-API access
- **Terminal**: Any modern terminal with UTF-8 support
### Python Dependencies
```bash
requests
rich
```
## 🚀 Installation
### Method 1: PyPI (Recommended)
```bash
# Install from PyPI
pip install ipfindx
```
### Method 2: Git Clone
```bash
# Clone the repository
git clone https://github.com/VritraSecz/IPFindX.git
# Navigate to project directory
cd IPFindX
# Install dependencies
pip install -r requirements.txt
# Run the application
python ipfindx.py --help
```
## 🎯 Usage
IPFindX is a command-line tool with intuitive options for different use cases:
### Single IP Lookup
```bash
# Basic IP lookup
ipfindx -i 8.8.8.8
# Using Python directly (if cloned from Git)
python ipfindx.py -i 1.1.1.1
```
### Batch IP Scanning
```bash
# Scan multiple IPs from a file
ipfindx -l ip_list.txt
# File format (one IP per line):
# 8.8.8.8
# 1.1.1.1
# 208.67.222.222
```
### Information and Help
```bash
# Show detailed information about the tool
ipfindx --about
# Display developer contact information
ipfindx --connect
# Show help message
ipfindx --help
```
### Output Management
All scans automatically save results to the `output-ipfindx/` directory with timestamped filenames:
- Format: `{IP_ADDRESS}-{DDMMYYYY-HHMMSS}.json`
- Example: `8.8.8.8-06082025-225328.json`
## 🖼️ Output Examples
### Terminal Display
```
IP Details for 8.8.8.8
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┓
┃ Field ┃ Value ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━┩
│ • Status │ success │
│ • Continent │ North America │
│ • Continentcode │ NA │
│ • Country │ United States │
│ • Countrycode │ US │
│ • Region │ VA │
│ • Regionname │ Virginia │
│ • City │ Ashburn │
│ • District │ │
│ • Zip │ 20149 │
│ • Lat │ 39.03 │
│ • Lon │ -77.5 │
│ • Timezone │ America/New_York │
│ • Offset │ -14400 │
│ • Currency │ USD │
│ • Isp │ Google LLC │
│ • Org │ Google Public DNS │
│ • As │ AS15169 Google LLC │
│ • Asname │ GOOGLE │
│ • Reverse │ dns.google │
│ • Mobile │ False │
│ • Proxy │ False │
│ • Hosting │ True │
│ • Query │ 8.8.8.8 │
└───────────────────────────┴────────────────────┘
```
### JSON Output Structure
```json
{
"status": "success",
"continent": "North America",
"continentCode": "NA",
"country": "United States",
"countryCode": "US",
"region": "VA",
"regionName": "Virginia",
"city": "Ashburn",
"district": "",
"zip": "20149",
"lat": 39.03,
"lon": -77.5,
"timezone": "America/New_York",
"offset": -14400,
"currency": "USD",
"isp": "Google LLC",
"org": "Google Public DNS",
"as": "AS15169 Google LLC",
"asname": "GOOGLE",
"reverse": "dns.google",
"mobile": false,
"proxy": false,
"hosting": true,
"query": "8.8.8.8"
}
```
## 📸 Screenshots
<div align="center">
### Single IP Lookup
### Tool Information Display
</div>
## 🔍 Use Cases
### Cybersecurity Operations
- **Threat Intelligence**: Rapidly investigate suspicious IP addresses during security incidents
- **SOC Analysis**: Integrate into Security Operations Center workflows for faster response
- **Malware Investigation**: Determine the origin of malicious connections or command servers
- **Log Analysis**: Quickly enrich log data with geographic and network context
### Network Administration
- **Traffic Analysis**: Identify the source of unusual network traffic patterns
- **Access Control**: Verify the location of connection attempts for geofencing policies
- **Service Deployment**: Test IP geolocation for CDN and service deployment planning
- **Network Troubleshooting**: Diagnose connectivity issues with detailed IP information
### OSINT Research
- **Digital Investigations**: Gather intelligence on network infrastructure
- **Attribution Research**: Help identify the origin of online activities
- **Geographic Mapping**: Plot network infrastructure on maps for visual analysis
- **Data Enrichment**: Add geolocation context to existing datasets
## 📁 Project Structure
```
IPFindX/
├── ipfindx.py # Main application script
├── requirements.txt # Python dependencies
├── README.md # Project documentation
├── LICENSE # MIT License
└── output-ipfindx/ # Auto-generated output directory
└── *.json # Timestamped result files
```
### File Descriptions
- **`ipfindx.py`**: Main application containing all core functionality, CLI parsing, and output formatting
- **`requirements.txt`**: Lists required Python packages (requests, rich)
- **`README.md`**: Comprehensive documentation and usage guide
- **`LICENSE`**: MIT License detail
- **`output-ipfindx/`**: Auto-created directory for storing JSON results
## 🔌 API Integration
IPFindX uses the IP-API.com service for IP intelligence data. The tool intelligently handles API rate limiting and connection issues to ensure reliable operation. Key API features include:
- **Comprehensive Data Fields**: Access to 25+ data points for each IP address
- **High Accuracy**: Enterprise-grade geolocation and network data
- **Optimized Requests**: Efficient API calls with minimal overhead
- **Error Handling**: Graceful handling of API limitations and service disruptions
For high-volume usage, consider [IP-API Pro plans](https://ip-api.com/docs/premium).
## ⚡ Performance
IPFindX is engineered for optimal performance across various environments:
- **Lookup Speed**: ~0.3 seconds per IP address (network dependent)
- **Batch Processing**: Efficiently handles thousands of IPs with minimal resource usage
- **Memory Footprint**: Typically under 50MB RAM even during large batch operations
- **Disk Usage**: Minimal with efficient JSON storage format
- **CPU Utilization**: Low CPU requirements, works well on resource-constrained systems
## 🖥️ Compatibility
### Tested Environments
- **Linux**: Ubuntu 20.04+, Debian 10+, CentOS 8+, Kali Linux, Arch Linux
- **macOS**: Monterey (12.0+), Ventura (13.0+), Sonoma (14.0+)
- **Windows**: Windows 10/11, Windows Server 2019/2022
- **Android**: Termux on Samsung Galaxy S24 Ultra (One UI 7)
### Terminal Compatibility
- **Linux**: GNOME Terminal, Konsole, Alacritty, Terminator, iTerm2
- **macOS**: Terminal.app, iTerm2, Alacritty
- **Windows**: Windows Terminal, PowerShell, Command Prompt, ConEmu, Cmder
- **Android**: Termux Terminal (tested on Samsung Galaxy S24 Ultra One UI 7)
## 🔒 Security Considerations
IPFindX is designed with security in mind:
- **No Sensitive Data Storage**: IP information is only saved locally
- **Input Validation**: All user inputs are validated to prevent injection attacks
- **No External Scripts**: Self-contained operation without external scripts
- **Network Security**: Uses HTTPS for all API communications
- **Minimal Dependencies**: Limited external libraries to reduce attack surface
- **Public IP Focus**: Automatically rejects private/internal IP scanning attempts
## 🔄 Enhanced Features
### Extended Functionality
- **Single IP Lookup**: Get comprehensive information for any public IP address with a single command
- **Batch IP Scanning**: Process multiple IPs from a text file with optimized parallel processing
- **Geolocation Data**: Precise country, region, city, coordinates, and timezone information
- **Network Intelligence**: Detailed ISP, organization, AS number, and hosting detection
- **Security Indicators**: Advanced proxy, mobile, and hosting status detection for threat assessment
- **DNS Resolution**: Reverse DNS lookup for hostname identification and verification
### Advanced Capabilities
- **Smart IP Validation**: Sophisticated detection and filtering of private/reserved IP ranges
- **Geographic Mapping**: Seamless integration with Google Maps for visual location reconnaissance
- **Structured Data Output**: Organized JSON output with consistent field naming for easy parsing
- **Timestamped Records**: Intelligent file naming with precise date/time stamps for audit trails
- **Progress Visualization**: Real-time status updates and progress bars for long-running operations
- **Error Management**: Enterprise-grade error handling with comprehensive user feedback
- **Cross-Platform Support**: Full functionality across Linux, macOS, and Windows environments
- **Memory-Efficient Design**: Optimized resource usage even when processing large IP lists
### Professional User Experience
- **Rich Terminal Visualization**: Beautiful tables and panels with syntax highlighting and UTF-8 characters
- **Responsive Design**: Intelligent terminal size detection with adaptive layout for any screen size
- **Color-coded Indicators**: Intuitive status indicators and field highlighting for rapid information assessment
- **Automatic Storage Management**: Smart creation of output directories and organized file management
- **Command-line Ergonomics**: Intuitive arguments and flags designed for maximum efficiency
- **Comprehensive Help System**: Detailed help messages and usage examples built right in
## 🗺️ Roadmap
Future development plans for IPFindX:
- **Advanced Threat Intelligence**: Integration with threat intelligence databases
- **Expanded Data Sources**: Additional IP intelligence providers
- **Export Formats**: Support for CSV, XML, and other export formats
- **Custom API Keys**: Support for user-provided API keys
- **Interactive Mode**: Terminal-based interactive interface for multiple lookups
- **IP Range Scanning**: Support for CIDR notation and IP ranges
- **Historical Data**: Tracking changes in IP intelligence over time
- **Integration APIs**: Python library interface for integration with other tools
- **Visualization**: Built-in data visualization capabilities
- **Docker Container**: Official Docker image for containerized deployment
## 🤝 Contributing
We welcome contributions from the community! Here's how you can help:
### Ways to Contribute
- 🐛 **Bug Reports**: Submit detailed issue reports with reproduction steps
- 💡 **Feature Requests**: Suggest new functionality or improvements
- 🔧 **Code Contributions**: Submit pull requests with enhancements
- 📚 **Documentation**: Improve documentation, examples, and tutorials
- 🧪 **Testing**: Help test the tool across different platforms and scenarios
- 🌐 **Internationalization**: Assist with translations and localization
### Development Setup
```bash
# Fork the repository on GitHub
# Clone your fork
git clone https://github.com/yourusername/IPFindX.git
# Create a feature branch
git checkout -b feature/your-feature-name
# Install development dependencies
pip install -r requirements.txt
# Make changes and test thoroughly
python ipfindx.py -i 8.8.8.8
# Commit with descriptive messages
git commit -m "Add: new feature description"
# Push to your fork and create pull request
git push origin feature/your-feature-name
```
### Coding Guidelines
- Follow PEP 8 style guidelines
- Add docstrings to all functions
- Include error handling for edge cases
- Test with various IP address types
- Maintain compatibility with Python 3.7+
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
```
MIT License
Copyright (c) 2025 Alex Butler (Vritra Security Organization)
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```
## 👨💻 Developer
<div align="center">
### Alex Butler
**Vritra Security Organization**
[](https://github.com/VritraSecz)
[](https://vritrasec.com)
[](https://instagram.com/haxorlex)
[](https://youtube.com/@Technolex)
### 📱 Telegram Channels
[](https://t.me/LinkCentralX)
[](https://t.me/VritraSec)
[](https://t.me/VritraSecz)
[](https://t.me/ethicxbot)
</div>
## 🙏 Acknowledgements
- [IP-API](https://ip-api.com/) - For providing the robust IP geolocation API
- [Rich](https://github.com/Textualize/rich) - For the beautiful terminal formatting
- [Requests](https://docs.python-requests.org/) - For reliable HTTP client functionality
---
<div align="center">
### 🌟 Support the Project
If you find IPFindX helpful, please consider:
- ⭐ Starring the repository
- 🍴 Forking and contributing
- 📢 Sharing with others
- 🐛 Reporting issues
- 💡 Suggesting new features
**Made with ❤️ by the <a href="https://vritrasec.com">Vritra Security Organization</a>**
</div>
Raw data
{
"_id": null,
"home_page": "https://github.com/VritraSecz/IPFindX",
"name": "ipfindx",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "ip, intelligence, geolocation, osint, cybersecurity, network, security, threat-intelligence, ip-lookup, cybersec, infosec, penetration-testing",
"author": "Alex Butler",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/42/9b/062b65371a1a9e85704fe744e7f253af8a9eed7b00d963ba8cd4a624cc8b/ipfindx-3.0.1.tar.gz",
"platform": "any",
"description": "<div align=\"center\">\n\n# \ud83c\udf10 IPFindX - Advanced IP Intelligence Toolkit\n\n<p>\n<img src=\"https://img.shields.io/badge/\ud83d\udc8e-Premium%20OSINT%20Tool-blueviolet?style=for-the-badge\" alt=\"Premium Tool\">\n<img src=\"https://img.shields.io/badge/\ud83c\udfaf-Cybersecurity%20Professional-red?style=for-the-badge\" alt=\"Professional\">\n<img src=\"https://img.shields.io/badge/\u26a1-Lightning%20Fast-yellow?style=for-the-badge\" alt=\"Fast\">\n</p>\n\n### \ud83d\ude80 *The Ultimate IP Intelligence Reconnaissance Platform for Security Professionals*\n\n**Unleash the power of advanced IP geolocation, threat intelligence, and network forensics in a single, elegant command-line interface. Built by cybersecurity experts, for cybersecurity experts.**\n\n[](https://www.python.org/downloads/)\n[](LICENSE)\n[](#compatibility)\n[](#overview)\n[](#overview)\n[](#contributing)\n[](https://github.com/VritraSecz/IPFindX)\n[](https://github.com/VritraSecz/IPFindX)\n[](https://github.com/VritraSecz/IPFindX/issues)\n[](https://github.com/VritraSecz/IPFindX/graphs/contributors)\n[](https://github.com/VritraSecz/IPFindX)\n[](https://github.com/VritraSecz/IPFindX)\n\n</div>\n\n---\n\n## \ud83d\udccb Table of Contents\n\n- [Overview](#-overview)\n- [Features](#-features)\n- [Requirements](#-requirements)\n- [Installation](#-installation)\n- [Usage](#-usage)\n- [Output Examples](#\ufe0f-output-examples)\n- [Screenshots](#-screenshots)\n- [Use Cases](#-use-cases)\n- [Project Structure](#-project-structure)\n- [API Integration](#-api-integration)\n- [Performance](#-performance)\n- [Compatibility](#-compatibility)\n- [Security Considerations](#-security-considerations)\n- [Contributing](#-contributing)\n- [Roadmap](#-roadmap)\n- [Developer](#-developer)\n- [License](#-license)\n- [Acknowledgements](#-acknowledgements)\n\n\n## \ud83d\udd2e Overview\n\n**IPFindX** is a professional-grade command-line IP intelligence toolkit designed for cybersecurity professionals, network administrators, threat hunters, and OSINT researchers. It provides comprehensive geolocation data, ISP information, security threat indicators, and detailed network intelligence for any public IP address with enterprise-level accuracy.\n\nWith its beautifully designed terminal interface and powerful data processing capabilities, IPFindX transforms complex IP reconnaissance into an efficient, streamlined process, delivering actionable intelligence in seconds.\n\n### Key Highlights\n\n- \ud83c\udfaf **Enterprise-Grade Intelligence**: Detailed geolocation, ISP, organization, and network data with high accuracy\n- \ud83c\udfa8 **Elegant CLI Interface**: Rich terminal output with color-coded information and professionally designed tables\n- \ud83d\udcbe **Seamless Data Persistence**: All results automatically saved as timestamped JSON files for future analysis\n- \ud83d\udcca **Advanced Batch Processing**: Scan multiple IPs from a file with intelligent progress tracking\n- \ud83d\udee1\ufe0f **Sophisticated Validation**: Automatically validates IP addresses and filters private/reserved ranges\n- \ud83d\uddfa\ufe0f **Integrated Geographic Visualization**: Direct Google Maps integration for precise location mapping\n- \ud83d\udd04 **Real-time Data**: Always up-to-date information from trusted IP intelligence sources\n- \u2699\ufe0f **Zero Configuration**: Works out of the box with no complex setup or configuration required\n\n## \u2728 Features\n\n### Core Functionality\n- **Single IP Lookup**: Get comprehensive information for any public IP address\n- **Batch IP Scanning**: Process multiple IPs from a text file\n- **Geolocation Data**: Country, region, city, coordinates, and timezone information\n- **Network Intelligence**: ISP, organization, AS number, and hosting detection\n- **Security Indicators**: Proxy, mobile, and hosting status detection\n- **DNS Resolution**: Reverse DNS lookup for hostname identification\n\n### Advanced Features\n- **Smart IP Validation**: Automatically detects and rejects private/reserved IP ranges\n- **Geographic Mapping**: Direct integration with Google Maps for location visualization\n- **Timestamped Output**: Organized output files with date/time stamps\n- **Progress Tracking**: Real-time status updates for long-running operations\n- **Error Handling**: Robust error handling with informative user feedback\n\n### User Experience\n- **Rich Terminal Output**: Beautiful tables and panels with syntax highlighting\n- **Responsive Design**: Adapts to different terminal sizes with fallback layouts\n- **Color-coded Results**: Status indicators and field highlighting for easy reading\n- **Organized Storage**: Automatic creation of output directories and file management\n\n## \ud83d\udccb Requirements\n\n### System Requirements\n- **Python**: Version 3.7 or higher\n- **Operating System**: Linux, macOS, Windows\n- **Internet Connection**: Required for IP-API access\n- **Terminal**: Any modern terminal with UTF-8 support\n\n### Python Dependencies\n```bash\nrequests\nrich\n```\n\n## \ud83d\ude80 Installation\n\n### Method 1: PyPI (Recommended)\n```bash\n# Install from PyPI\npip install ipfindx\n```\n\n### Method 2: Git Clone\n```bash\n# Clone the repository\ngit clone https://github.com/VritraSecz/IPFindX.git\n\n# Navigate to project directory\ncd IPFindX\n\n# Install dependencies\npip install -r requirements.txt\n\n# Run the application\npython ipfindx.py --help\n```\n\n## \ud83c\udfaf Usage\n\nIPFindX is a command-line tool with intuitive options for different use cases:\n\n### Single IP Lookup\n```bash\n# Basic IP lookup\nipfindx -i 8.8.8.8\n\n# Using Python directly (if cloned from Git)\npython ipfindx.py -i 1.1.1.1\n```\n\n### Batch IP Scanning\n```bash\n# Scan multiple IPs from a file\nipfindx -l ip_list.txt\n\n# File format (one IP per line):\n# 8.8.8.8\n# 1.1.1.1\n# 208.67.222.222\n```\n\n### Information and Help\n```bash\n# Show detailed information about the tool\nipfindx --about\n\n# Display developer contact information\nipfindx --connect\n\n# Show help message\nipfindx --help\n```\n\n### Output Management\nAll scans automatically save results to the `output-ipfindx/` directory with timestamped filenames:\n- Format: `{IP_ADDRESS}-{DDMMYYYY-HHMMSS}.json`\n- Example: `8.8.8.8-06082025-225328.json`\n\n## \ud83d\uddbc\ufe0f Output Examples\n\n### Terminal Display\n```\n IP Details for 8.8.8.8\n\u250f\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2513\n\u2503 Field \u2503 Value \u2503\n\u2521\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2529\n\u2502 \u2022 Status \u2502 success \u2502\n\u2502 \u2022 Continent \u2502 North America \u2502\n\u2502 \u2022 Continentcode \u2502 NA \u2502\n\u2502 \u2022 Country \u2502 United States \u2502\n\u2502 \u2022 Countrycode \u2502 US \u2502\n\u2502 \u2022 Region \u2502 VA \u2502\n\u2502 \u2022 Regionname \u2502 Virginia \u2502\n\u2502 \u2022 City \u2502 Ashburn \u2502\n\u2502 \u2022 District \u2502 \u2502\n\u2502 \u2022 Zip \u2502 20149 \u2502\n\u2502 \u2022 Lat \u2502 39.03 \u2502\n\u2502 \u2022 Lon \u2502 -77.5 \u2502\n\u2502 \u2022 Timezone \u2502 America/New_York \u2502\n\u2502 \u2022 Offset \u2502 -14400 \u2502\n\u2502 \u2022 Currency \u2502 USD \u2502\n\u2502 \u2022 Isp \u2502 Google LLC \u2502\n\u2502 \u2022 Org \u2502 Google Public DNS \u2502\n\u2502 \u2022 As \u2502 AS15169 Google LLC \u2502\n\u2502 \u2022 Asname \u2502 GOOGLE \u2502\n\u2502 \u2022 Reverse \u2502 dns.google \u2502\n\u2502 \u2022 Mobile \u2502 False \u2502\n\u2502 \u2022 Proxy \u2502 False \u2502\n\u2502 \u2022 Hosting \u2502 True \u2502\n\u2502 \u2022 Query \u2502 8.8.8.8 \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n### JSON Output Structure\n```json\n{\n \"status\": \"success\",\n \"continent\": \"North America\",\n \"continentCode\": \"NA\",\n \"country\": \"United States\",\n \"countryCode\": \"US\",\n \"region\": \"VA\",\n \"regionName\": \"Virginia\",\n \"city\": \"Ashburn\",\n \"district\": \"\",\n \"zip\": \"20149\",\n \"lat\": 39.03,\n \"lon\": -77.5,\n \"timezone\": \"America/New_York\",\n \"offset\": -14400,\n \"currency\": \"USD\",\n \"isp\": \"Google LLC\",\n \"org\": \"Google Public DNS\",\n \"as\": \"AS15169 Google LLC\",\n \"asname\": \"GOOGLE\",\n \"reverse\": \"dns.google\",\n \"mobile\": false,\n \"proxy\": false,\n \"hosting\": true,\n \"query\": \"8.8.8.8\"\n}\n```\n\n## \ud83d\udcf8 Screenshots\n\n<div align=\"center\">\n\n### Single IP Lookup\n\n\n### Tool Information Display\n\n\n</div>\n\n\n## \ud83d\udd0d Use Cases\n\n### Cybersecurity Operations\n- **Threat Intelligence**: Rapidly investigate suspicious IP addresses during security incidents\n- **SOC Analysis**: Integrate into Security Operations Center workflows for faster response\n- **Malware Investigation**: Determine the origin of malicious connections or command servers\n- **Log Analysis**: Quickly enrich log data with geographic and network context\n\n### Network Administration\n- **Traffic Analysis**: Identify the source of unusual network traffic patterns\n- **Access Control**: Verify the location of connection attempts for geofencing policies\n- **Service Deployment**: Test IP geolocation for CDN and service deployment planning\n- **Network Troubleshooting**: Diagnose connectivity issues with detailed IP information\n\n### OSINT Research\n- **Digital Investigations**: Gather intelligence on network infrastructure\n- **Attribution Research**: Help identify the origin of online activities\n- **Geographic Mapping**: Plot network infrastructure on maps for visual analysis\n- **Data Enrichment**: Add geolocation context to existing datasets\n\n## \ud83d\udcc1 Project Structure\n\n```\nIPFindX/\n\u251c\u2500\u2500 ipfindx.py # Main application script\n\u251c\u2500\u2500 requirements.txt # Python dependencies\n\u251c\u2500\u2500 README.md # Project documentation\n\u251c\u2500\u2500 LICENSE # MIT License\n\u2514\u2500\u2500 output-ipfindx/ # Auto-generated output directory\n \u2514\u2500\u2500 *.json # Timestamped result files\n```\n\n### File Descriptions\n\n- **`ipfindx.py`**: Main application containing all core functionality, CLI parsing, and output formatting\n- **`requirements.txt`**: Lists required Python packages (requests, rich)\n- **`README.md`**: Comprehensive documentation and usage guide\n- **`LICENSE`**: MIT License detail\n- **`output-ipfindx/`**: Auto-created directory for storing JSON results\n\n## \ud83d\udd0c API Integration\n\nIPFindX uses the IP-API.com service for IP intelligence data. The tool intelligently handles API rate limiting and connection issues to ensure reliable operation. Key API features include:\n\n- **Comprehensive Data Fields**: Access to 25+ data points for each IP address\n- **High Accuracy**: Enterprise-grade geolocation and network data\n- **Optimized Requests**: Efficient API calls with minimal overhead\n- **Error Handling**: Graceful handling of API limitations and service disruptions\n\nFor high-volume usage, consider [IP-API Pro plans](https://ip-api.com/docs/premium).\n\n## \u26a1 Performance\n\nIPFindX is engineered for optimal performance across various environments:\n\n- **Lookup Speed**: ~0.3 seconds per IP address (network dependent)\n- **Batch Processing**: Efficiently handles thousands of IPs with minimal resource usage\n- **Memory Footprint**: Typically under 50MB RAM even during large batch operations\n- **Disk Usage**: Minimal with efficient JSON storage format\n- **CPU Utilization**: Low CPU requirements, works well on resource-constrained systems\n\n## \ud83d\udda5\ufe0f Compatibility\n\n### Tested Environments\n- **Linux**: Ubuntu 20.04+, Debian 10+, CentOS 8+, Kali Linux, Arch Linux\n- **macOS**: Monterey (12.0+), Ventura (13.0+), Sonoma (14.0+)\n- **Windows**: Windows 10/11, Windows Server 2019/2022\n- **Android**: Termux on Samsung Galaxy S24 Ultra (One UI 7)\n\n### Terminal Compatibility\n- **Linux**: GNOME Terminal, Konsole, Alacritty, Terminator, iTerm2\n- **macOS**: Terminal.app, iTerm2, Alacritty\n- **Windows**: Windows Terminal, PowerShell, Command Prompt, ConEmu, Cmder\n- **Android**: Termux Terminal (tested on Samsung Galaxy S24 Ultra One UI 7)\n\n## \ud83d\udd12 Security Considerations\n\nIPFindX is designed with security in mind:\n\n- **No Sensitive Data Storage**: IP information is only saved locally\n- **Input Validation**: All user inputs are validated to prevent injection attacks\n- **No External Scripts**: Self-contained operation without external scripts\n- **Network Security**: Uses HTTPS for all API communications\n- **Minimal Dependencies**: Limited external libraries to reduce attack surface\n- **Public IP Focus**: Automatically rejects private/internal IP scanning attempts\n\n## \ud83d\udd04 Enhanced Features\n\n### Extended Functionality\n- **Single IP Lookup**: Get comprehensive information for any public IP address with a single command\n- **Batch IP Scanning**: Process multiple IPs from a text file with optimized parallel processing\n- **Geolocation Data**: Precise country, region, city, coordinates, and timezone information\n- **Network Intelligence**: Detailed ISP, organization, AS number, and hosting detection\n- **Security Indicators**: Advanced proxy, mobile, and hosting status detection for threat assessment\n- **DNS Resolution**: Reverse DNS lookup for hostname identification and verification\n\n### Advanced Capabilities\n- **Smart IP Validation**: Sophisticated detection and filtering of private/reserved IP ranges\n- **Geographic Mapping**: Seamless integration with Google Maps for visual location reconnaissance\n- **Structured Data Output**: Organized JSON output with consistent field naming for easy parsing\n- **Timestamped Records**: Intelligent file naming with precise date/time stamps for audit trails\n- **Progress Visualization**: Real-time status updates and progress bars for long-running operations\n- **Error Management**: Enterprise-grade error handling with comprehensive user feedback\n- **Cross-Platform Support**: Full functionality across Linux, macOS, and Windows environments\n- **Memory-Efficient Design**: Optimized resource usage even when processing large IP lists\n\n### Professional User Experience\n- **Rich Terminal Visualization**: Beautiful tables and panels with syntax highlighting and UTF-8 characters\n- **Responsive Design**: Intelligent terminal size detection with adaptive layout for any screen size\n- **Color-coded Indicators**: Intuitive status indicators and field highlighting for rapid information assessment\n- **Automatic Storage Management**: Smart creation of output directories and organized file management\n- **Command-line Ergonomics**: Intuitive arguments and flags designed for maximum efficiency\n- **Comprehensive Help System**: Detailed help messages and usage examples built right in\n\n## \ud83d\uddfa\ufe0f Roadmap\n\nFuture development plans for IPFindX:\n\n- **Advanced Threat Intelligence**: Integration with threat intelligence databases\n- **Expanded Data Sources**: Additional IP intelligence providers\n- **Export Formats**: Support for CSV, XML, and other export formats\n- **Custom API Keys**: Support for user-provided API keys\n- **Interactive Mode**: Terminal-based interactive interface for multiple lookups\n- **IP Range Scanning**: Support for CIDR notation and IP ranges\n- **Historical Data**: Tracking changes in IP intelligence over time\n- **Integration APIs**: Python library interface for integration with other tools\n- **Visualization**: Built-in data visualization capabilities\n- **Docker Container**: Official Docker image for containerized deployment\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions from the community! Here's how you can help:\n\n### Ways to Contribute\n- \ud83d\udc1b **Bug Reports**: Submit detailed issue reports with reproduction steps\n- \ud83d\udca1 **Feature Requests**: Suggest new functionality or improvements\n- \ud83d\udd27 **Code Contributions**: Submit pull requests with enhancements\n- \ud83d\udcda **Documentation**: Improve documentation, examples, and tutorials\n- \ud83e\uddea **Testing**: Help test the tool across different platforms and scenarios\n- \ud83c\udf10 **Internationalization**: Assist with translations and localization\n\n### Development Setup\n```bash\n# Fork the repository on GitHub\n# Clone your fork\ngit clone https://github.com/yourusername/IPFindX.git\n\n# Create a feature branch\ngit checkout -b feature/your-feature-name\n\n# Install development dependencies\npip install -r requirements.txt\n\n# Make changes and test thoroughly\npython ipfindx.py -i 8.8.8.8\n\n# Commit with descriptive messages\ngit commit -m \"Add: new feature description\"\n\n# Push to your fork and create pull request\ngit push origin feature/your-feature-name\n```\n\n### Coding Guidelines\n- Follow PEP 8 style guidelines\n- Add docstrings to all functions\n- Include error handling for edge cases\n- Test with various IP address types\n- Maintain compatibility with Python 3.7+\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n```\nMIT License\n\nCopyright (c) 2025 Alex Butler (Vritra Security Organization)\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n```\n\n## \ud83d\udc68\u200d\ud83d\udcbb Developer\n\n<div align=\"center\">\n\n### Alex Butler\n**Vritra Security Organization**\n\n[](https://github.com/VritraSecz)\n[](https://vritrasec.com)\n[](https://instagram.com/haxorlex)\n[](https://youtube.com/@Technolex)\n\n### \ud83d\udcf1 Telegram Channels\n[](https://t.me/LinkCentralX)\n[](https://t.me/VritraSec)\n[](https://t.me/VritraSecz)\n[](https://t.me/ethicxbot)\n\n</div>\n\n## \ud83d\ude4f Acknowledgements\n\n- [IP-API](https://ip-api.com/) - For providing the robust IP geolocation API\n- [Rich](https://github.com/Textualize/rich) - For the beautiful terminal formatting\n- [Requests](https://docs.python-requests.org/) - For reliable HTTP client functionality\n\n---\n\n<div align=\"center\">\n\n### \ud83c\udf1f Support the Project\n\nIf you find IPFindX helpful, please consider:\n- \u2b50 Starring the repository\n- \ud83c\udf74 Forking and contributing\n- \ud83d\udce2 Sharing with others\n- \ud83d\udc1b Reporting issues\n- \ud83d\udca1 Suggesting new features\n\n**Made with \u2764\ufe0f by the <a href=\"https://vritrasec.com\">Vritra Security Organization</a>**\n\n</div>\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 Alex Butler (Vritra Security Organization)\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.\n ",
"summary": "Advanced IP Intelligence Toolkit for cybersecurity professionals",
"version": "3.0.1",
"project_urls": {
"Bug Reports": "https://github.com/VritraSecz/IPFindX/issues",
"Documentation": "https://github.com/VritraSecz/IPFindX#readme",
"Homepage": "https://github.com/VritraSecz/IPFindX",
"Source": "https://github.com/VritraSecz/IPFindX",
"Website": "https://vritrasec.com"
},
"split_keywords": [
"ip",
" intelligence",
" geolocation",
" osint",
" cybersecurity",
" network",
" security",
" threat-intelligence",
" ip-lookup",
" cybersec",
" infosec",
" penetration-testing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7b53318af9ff6be7be1f8788a4ec84da990a572c34eae323cc97d795a613fd64",
"md5": "f42ec5a92e571f25cbba4268ab38cdb7",
"sha256": "37e27730f8a569357869cdac0332833ba6f87a37cb0de6c2c55c71ab1cdd6612"
},
"downloads": -1,
"filename": "ipfindx-3.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f42ec5a92e571f25cbba4268ab38cdb7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 14521,
"upload_time": "2025-08-06T18:35:10",
"upload_time_iso_8601": "2025-08-06T18:35:10.967055Z",
"url": "https://files.pythonhosted.org/packages/7b/53/318af9ff6be7be1f8788a4ec84da990a572c34eae323cc97d795a613fd64/ipfindx-3.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "429b062b65371a1a9e85704fe744e7f253af8a9eed7b00d963ba8cd4a624cc8b",
"md5": "02aa388d2ae8fc79e8f677d32597ec55",
"sha256": "8d7452a374a83ce8e62f04e39806f7c8607d04d6e1994fcd99f1be2896ce6c6a"
},
"downloads": -1,
"filename": "ipfindx-3.0.1.tar.gz",
"has_sig": false,
"md5_digest": "02aa388d2ae8fc79e8f677d32597ec55",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 13906,
"upload_time": "2025-08-06T18:35:13",
"upload_time_iso_8601": "2025-08-06T18:35:13.013060Z",
"url": "https://files.pythonhosted.org/packages/42/9b/062b65371a1a9e85704fe744e7f253af8a9eed7b00d963ba8cd4a624cc8b/ipfindx-3.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-06 18:35:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "VritraSecz",
"github_project": "IPFindX",
"github_not_found": true,
"lcname": "ipfindx"
}
