keyscore-py 1.0.0

Python client for keysco.re API - Search and lookup data across multiple sources

keyscore-py

Python client library for the keysco.re API - Search and lookup data across multiple sources for OSINT and threat intelligence.

Installation

pip install keyscore-py

Quick Start

from keyscore import Client

# Initialize the client
client = Client(base_url="https://api.keysco.re", api_key="your-api-key")

# Check API health
health = client.health()
print(f"API Status: {health.status}")

# Get available data sources
sources = client.sources()
print(f"Available sources: {len(sources)}")

# Search for data
results = client.search(query="[e-mail]", limit=10)
for result in results:
    print(f"Found: {result.value} from {result.source}")

Authentication

Most API endpoints require authentication. Set your API key:

# Method 1: Pass directly to client
client = Client(base_url="https://api.keysco.re", api_key="your-api-key")

# Method 2: Set environment variable
import os
os.environ['KEYSCORE_API_KEY'] = 'your-api-key'
client = Client(base_url="https://api.keysco.re")

API Reference

Client Methods

health()

Check API health status.

health = client.health()
print(health.status)  # "ok"

sources()

Get available data sources and their capabilities.

sources = client.sources()
for source in sources:
    print(f"{source.name}: {source.description}")
    print(f"Types: {source.allowedTypes}")

count(query, sources=None)

Get total count of results for a query.

# Count across all sources
total = client.count("[e-mail]")
print(f"Total results: {total}")

# Count from specific sources
total = client.count("[e-mail]", sources=["source1", "source2"])

count_detailed(query, sources=None)

Get detailed count breakdown by source.

counts = client.count_detailed("[e-mail]")
for count in counts:
    print(f"{count.source}: {count.count} results")

search(query, sources=None, limit=100, offset=0)

Search for data across sources.

# Basic search
results = client.search("[e-mail]")

# Search with pagination
results = client.search("[e-mail]", limit=50, offset=100)

# Search specific sources
results = client.search("[e-mail]", sources=["source1"])

for result in results:
    print(f"Value: {result.value}")
    print(f"Source: {result.source}")
    print(f"Type: {result.type}")
    print(f"Date: {result.date}")

hash_lookup(hash_value)

Lookup information about a file hash.

hash_info = client.hash_lookup("d41d8cd98f00b204e9800998ecf8427e")
if hash_info:
    print(f"Hash: {hash_info.hash}")
    print(f"Algorithm: {hash_info.algorithm}")
    print(f"Filename: {hash_info.filename}")

ip_lookup(ip_address)

Lookup information about an IP address.

ip_info = client.ip_lookup("8.8.8.8")
if ip_info:
    print(f"IP: {ip_info.ip}")
    print(f"Country: {ip_info.country}")
    print(f"ISP: {ip_info.isp}")

machine_info(uuid)

Get machine information by UUID.

machine = client.machine_info("550e8400-e29b-41d4-a716-446655440000")
if machine:
    print(f"Computer: {machine.computerName}")
    print(f"OS: {machine.operationSystem}")
    print(f"User: {machine.userName}")

download(uuid, file_path)

Download a file by UUID.

success = client.download("550e8400-e29b-41d4-a716-446655440000", "./downloaded_file")
if success:
    print("File downloaded successfully")

Data Models

The library includes typed data models for all API responses:

• HealthResponse - API health status
• SourceInfo - Data source information
• SearchResult - Search result item
• CountResponse - Result count by source
• HashRecord - File hash information
• IPInfo - IP address information
• MachineInfo - Machine/system information
• HashLookupRequest - Hash lookup request

Error Handling

from keyscore import Client, APIError

try:
    client = Client(base_url="https://api.keysco.re", api_key="invalid-key")
    results = client.search("test")
except APIError as e:
    print(f"API Error: {e.message} (Status: {e.status_code})")
except Exception as e:
    print(f"Unexpected error: {e}")

Examples

See the examples/ directory for complete usage examples:

• test_client.py - Basic API testing script

Requirements

• Python 3.8+
• requests >= 2.31.0

License

Apache License 2.0

Support

For support and questions:

• Documentation: https://docs.keysco.re/
• Issues: https://github.com/keysco-re/keyscore-py/issues
• Email: [e-mail]