Metadata-Version: 2.4
Name: keyscore-py
Version: 1.0.0
Summary: Python client for keysco.re API - Search and lookup data across multiple sources
Author-email: esson <esson@riseup.net>
Maintainer-email: esson <esson@riseup.net>
License: Apache-2.0
Project-URL: homepage, https://keysco.re/
Project-URL: repository, https://github.com/keysco-re/keyscore-py
Project-URL: documentation, https://docs.keysco.re/
Project-URL: bug-tracker, https://github.com/keysco-re/keyscore-py/issues
Keywords: keysco.re,api,client,osint,lookup,search,intelligence
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Networking
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Dynamic: license-file

# keyscore-py

Python client library for the [keysco.re](https://keysco.re/) API - Search and lookup data across multiple sources for OSINT and threat intelligence.

## Installation

```bash
pip install keyscore-py
```

## Quick Start

```python
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="example@domain.com", limit=10)
for result in results:
    print(f"Found: {result.value} from {result.source}")
```

## Authentication

Most API endpoints require authentication. Set your API key:

```python
# 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.

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

#### `sources()`
Get available data sources and their capabilities.

```python
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.

```python
# Count across all sources
total = client.count("example@domain.com")
print(f"Total results: {total}")

# Count from specific sources
total = client.count("example@domain.com", sources=["source1", "source2"])
```

#### `count_detailed(query, sources=None)`
Get detailed count breakdown by source.

```python
counts = client.count_detailed("example@domain.com")
for count in counts:
    print(f"{count.source}: {count.count} results")
```

#### `search(query, sources=None, limit=100, offset=0)`
Search for data across sources.

```python
# Basic search
results = client.search("example@domain.com")

# Search with pagination
results = client.search("example@domain.com", limit=50, offset=100)

# Search specific sources
results = client.search("example@domain.com", 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.

```python
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.

```python
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.

```python
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.

```python
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

```python
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: esson@riseup.net
