📖 Overview

ipcriminal-python is an easy-to-use, feature-packed Python SDK for interacting with the Criminal IP Threat Intelligence search engine. It empowers security analysts, red teamers, and threat intelligence practitioners to automate asset discovery, IP reputation scoring, domain threat scanning, exploit lookup, and banner searching directly within their Python workflows.

✨ Key Features

• 🌐 IP & Asset Intelligence: Query comprehensive reports, open ports, VPN detection, hosting status, malicious histories, and privacy threats.
• 🔍 Domain Security Analysis: Perform Full and Lite domain scans, retrieve scan progress, check malicious vs. trusted domain hashes, and list historical scan reports.
• 🛡️ Exploit & Banner Search: Search exposed services across global network banners and look up CVE vulnerability data.
• 🔄 Automated Pagination: Built-in offset management for endpoints like assest_search, banner_search, domain_reports, and exploit_search.
• 🔑 Clean Authentication: Seamless API key management with header-based request handling.

🚀 Installation

Install directly from GitHub via pip:

pip install git+https://github.com/Xeroxxhah/ipcriminal-python.git

Or clone the repository locally and install the dependencies:

git clone https://github.com/Xeroxxhah/ipcriminal-python.git
cd ipcriminal-python
pip install .

🛠️ Quick Start

1. Obtain Your API Key

Sign up or log into your account at Criminal IP and grab your API Key from the developer dashboard.

2. Initialize the Client

from criminalip.criminalip import CriminalIP

# Initialize the API client with your token
client = CriminalIP(api_token="YOUR_CRIMINAL_IP_API_KEY")

3. Usage Examples

# Check credit balance and subscription tier
account_data = client.account_info()
print(account_data)

# Get a comprehensive report on a target IP
ip_report = client.ip_asset_report(ip_address="1.1.1.1", full=True)

# Fetch summarized security issues, open ports, and risk score
summary = client.ip_assest_report_summary(ip_address="1.1.1.1")

# Check if an IP is a known VPN, hosting server, or privacy threat
is_vpn = client.ip_vpn(ip_address="1.1.1.1")
privacy_threat = client.ip_privacy_threats(ip_address="1.1.1.1")

print(f"VPN Status: {is_vpn}")

# Initiate a private domain scan
scan_response = client.domain_scan(domain="example.com")

# Request a fast 2-5 second Lite Scan
lite_scan = client.domain_lite_scan(domain="example.com")

# Check if a domain is connected to a malicious website
quick_mal_check = client.domain_quick_mal_view(domain="example.com")
print(quick_mal_check)

# Search banners with automatic pagination (fetches up to offset count)
banners = client.banner_search(query="port: 22", offset=20)

# Search CVE exploit details
exploits = client.exploit_search(query="CVE-2023-23397", offset=10)
print(exploits)

📚 API Reference

👤 Account Management

🌐 IP & Asset Intelligence

🌐 Domain Intelligence

💥 Exploits, Banners & Threat Intelligence

🛡️ Error Handling

If an API call is made without providing an API key, the SDK raises a custom ApiKeyError:

from criminalip import CriminalIP
from criminalip.exceptions import ApiKeyError

try:
    client = CriminalIP()  # No token passed
    client.account_info()
except ApiKeyError as e:
    print(f"Authentication Error: {e}")

🤝 Contributing

Contributions, bug reports, and feature requests are very welcome!

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

📄 License

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