Skip to content

Commit

Permalink
v2.0.0 is finally here
Browse files Browse the repository at this point in the history
  • Loading branch information
lc committed Oct 4, 2024
1 parent e821dab commit 74da00e
Show file tree
Hide file tree
Showing 5 changed files with 366 additions and 289 deletions.
2 changes: 1 addition & 1 deletion LICENSE
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
Copyright (c) 2018-2023 LeakCheck Security Services LTD
Copyright (c) 2018-2024 LeakCheck Security Services LTD

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
Expand Down
292 changes: 173 additions & 119 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,121 +1,175 @@
# LeakCheck API
# LeakCheck API Python Wrapper v2.0.0

![LeakCheck <3 Python](https://i.imgur.com/G30V91m.png)
<p align="center">
<img alt="Discord" src="https://img.shields.io/discord/626798391162175528">
<img alt="PyPI - Downloads" src="https://img.shields.io/pypi/dm/leakcheck">
<img alt="PyPI" src="https://img.shields.io/pypi/v/leakcheck">
<img alt="Uptime Robot ratio (30 days)" src="https://img.shields.io/uptimerobot/ratio/m787582856-3411c8623fccb7e99d3dfc1f">
<img alt="GitHub" src="https://img.shields.io/github/license/leakcheck/leakcheck-api">
</p>
This Python wrapper allows you to interact with the LeakCheck API for checking leaked data using the official API. It includes support for both the private (authenticated) API and the public (unauthenticated) API endpoints. This wrapper has been updated to work with API v2.

## Dependencies:

- Python >= 3.5
- requests
- tabulate
- pysocks
- setuptools
- wheel

## Installation:

pip3 install leakcheck

Or download tarball / `git clone` and execute

python3 setup.py install

## First start:

To start working with this package you need to obtain personal API key [from here](https://leakcheck.net/api_s) and link IP address of your server or personal computer. It can be IPv6 as well as IPv4.

Public API can be used without IP linking.

Package automatically creates ".pylcapi" file in the home directory on the first startup. Then, API key and/or proxy settings can be loaded from there.

## Using as a CLI:

usage: leakcheck [-h] [--key KEY] [--proxy PROXY] [--type TYPE] [-lo] [-p]
query

CLI version of LeakCheck API (v1.0.2). Licensed under MIT license

positional arguments:
query What are we going to search?

optional arguments:
-h, --help show this help message and exit
--key KEY Set an API key (taken from config by default)
--proxy PROXY Set proxy (supported: HTTP/HTTPS/SOCKS4/SOCKS5, default:
empty)
--type TYPE Set a type of the query (default: auto)
-lo Print lines only (default: False
-p Lookup privately (hashes data with SHA256, then truncates
hash to 24 characters; works for email, pass_email only,
default: False)
## Using as a library:

from leakcheck import LeakCheckAPI

# Initialising API class
api = LeakCheckAPI()

# API key setting
api.set_key("YOUR_KEY")

# Now we're ready to make our first request
# A lookup type is detected automatically. To explicitly set it, see below
result = api.lookup("example@example.com") # list of dicts

# A request with the lookup type
result = api.lookup("example@example.com", "email") # list of dicts

## Using a proxy:

# HTTP/HTTPS/SOCKS4/SOCKS5 supported
# Handled by requests[proxy], requests[socks]
api.set_proxy("socks5://127.0.0.1:8123")

## Getting your IP:

from leakcheck import LeakCheckAPI

# Initialising API class
api = LeakCheckAPI()

ip = api.getIP() # string

## Getting your limits:

from leakcheck import LeakCheckAPI

# Initialising API class
api = LeakCheckAPI()

# API key setting
api.set_key("YOUR_KEY")

limits = api.getLimits() # dict

## Response errors:

| Error | Description |
|--|--|
| Missing params (key, check, type) | Some params haven't passed in the request |
| Invalid type | Type you provide is invalid |
| API Key is wrong | Key you provide is invalid |
| API Key is blocked | Your key is blocked due to some reasons, contact support |
| No license on this key | Key you provide does not have a license |
| Your query contains invalid characters | There are some forbidden characters in your query |
| Enter at least 3 characters to search | Query passed without minimal number of characters |
| Invalid email | E-mail type is specified, but your query is not a mail |
| IP linking is required | IPs are not linked or invalid |
| Not found | There are no results |
| Too many entries, try to concretize your query | You made a search that contains too many entries, try to search "alex@" instead of "alex" |

## Server Errors:
| Error | Description | Resolution |
|--|--|--|
| 429 Too Many Requests | Your server is sending too many automated requests. API is limited by 3 requests/second per one IP. | Try to reduce amount of sendings.
## Features

- Lookup email addresses, usernames, and other identifiers against leaked databases.
- Supports both the **private API v2** (authenticated via API key) and the **public API**.
- Proxy support for both HTTP and HTTPS queries.
- Customizable request limits and offsets for paginated queries.

## Installation

You can install the wrapper using `pip`:

```bash
pip install leakcheck
```

## Usage

### Private API (Authenticated) - `LeakCheckAPI_v2`

To use the private API, you need an API key from LeakCheck. You can pass the API key directly or set it via an environment variable.

#### Example:

```python
from leakcheck_api import LeakCheckAPI_v2

# Initialize with API key (or set LEAKCHECK_APIKEY in environment variables)
api = LeakCheckAPI_v2(api_key='your_api_key_here')

# Perform a lookup
result = api.lookup(query="example@example.com", query_type="email", limit=100)

print(result)
```

#### Environment Variables

You can set the following environment variables for better flexibility:
- `LEAKCHECK_APIKEY`: Your API key for authentication (must be at least 40 characters long).
- `LEAKCHECK_PROXY`: Optional, to route your requests through a proxy.

#### Parameters for `lookup()`:

- `query`: The identifier to look up (email, username, etc.).
- `query_type`: (Optional) Specify the type of query (e.g., "email", "username"). If not provided, it will be auto-detected.
- `limit`: (Optional) Limit the number of results (maximum 1000, default is 100).
- `offset`: (Optional) Offset for the results (maximum 2500, default is 0).

#### Error Handling

- If the API key is invalid or not provided, an error will be raised.
- The method checks for valid `limit` and `offset` parameters.
- Handles exceptions related to network or request issues.

### Public API (Unauthenticated) - `LeakCheckAPI_Public`

The public API does not require authentication but offers limited access. You can use this for simple email or username queries.

#### Example:

```python
from leakcheck_api import LeakCheckAPI_Public

# Initialize without an API key
public_api = LeakCheckAPI_Public()

# Perform a public lookup
result = public_api.lookup(query="example@example.com")

print(result)
```

#### Parameters for `lookup()`:

- `query`: The identifier to look up (email, email hash, or username).

### Proxy Support

Both the private and public API wrappers support proxy configurations. You can set the proxy by calling `set_proxy()`:

```python
# Set proxy for private API
api.set_proxy("http://proxy.example.com:8080")

# Set proxy for public API
public_api.set_proxy("http://proxy.example.com:8080")
```

## Accepted Data Types for Lookup Queries

The **LeakCheck API v2** accepts the following data types for lookups. Some data types can be automatically detected, while others must be explicitly specified.

| **Query Type** | **Sample** | **Notes** |
|----------------|--------------------------------------------|--------------------------------------------------------------------------------------------|
| **auto** | `example@example.com`, `example`, `12345678`, `31c5543c1734d25c7206f5fd` | Automatically detects email, username, phone number, and hash. Other types must be explicit.|
| **email** | `example@example.com` | |
| **domain** | `gmail.com` | |
| **keyword** | `example` | |
| **username** | `example` | |
| **phone** | `12063428631` | |
| **hash** | `31c5543c1734d25c7206f5fd` | SHA256 hash of lower-cased email, can be truncated to 24 characters. |
| **phash** | `31c5543c1734d25c7206f5fd` | SHA256 hash of password, can be truncated to 24 characters (Enterprise only). |
| **origin** | `example.com` | For Enterprise accounts only. |
| **password** | `example` | For Enterprise accounts only. |

### Example Queries:

```python
# Auto-detect type
result = api.lookup(query="example@example.com")

# Lookup by email
result = api.lookup(query="example@example.com", query_type="email")

# Lookup by domain
result = api.lookup(query="gmail.com", query_type="domain")

# Lookup by phone
result = api.lookup(query="12063428631", query_type="phone")

# Lookup by SHA256 hash
result = api.lookup(query="31c5543c1734d25c7206f5fd", query_type="hash")
```

### Auto-Detection of Query Types

If the `query_type` parameter is not provided, the API will attempt to auto-detect the type of query based on the input format. For instance, if the query looks like an email, the API will treat it as such.

## Error Handling and Returned Errors

The **LeakCheck API v2** provides detailed error messages in case something goes wrong with your query. These error messages are based on specific conditions. Below are common error codes and their corresponding descriptions:

| **Error Code** | **Description** | **Notes** |
|----------------|---------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------|
| **401** | Missing X-API-Key | No API key provided in the request header. |
| **400** | Invalid X-API-Key | The API key provided is invalid. |
| **400** | Invalid type | The `query_type` parameter is not valid. |
| **400** | Invalid email | The email format is incorrect. |
| **400** | Invalid query | The query format is invalid. |
| **400** | Invalid domain | The domain format is invalid. |
| **400** | Too short query (< 3 characters) | The query must be at least 3 characters long. |
| **400** | Invalid characters in query | The query contains invalid characters. |
| **429** | Too many requests | You have exceeded the rate limit. |
| **403** | Active plan required | A paid plan is required to make this request. |
| **403** | Limit reached | You have reached your plan’s usage limit. |
| **422** | Could not determine search type automatically | The system was unable to automatically detect the query type, requiring an explicit type. |

### Example of Error Handling in Code:

```python
try:
result = api.lookup(query="example@example.com", query_type="email", limit=100)
print(result)
except ValueError as e:
print(f"An error occurred: {str(e)}")
```

The `lookup()` function raises a `ValueError` when the API returns an error. This makes it easy to handle and debug any issues that arise from invalid requests or API responses.

## API Endpoints

- **Private API Base URL (v2):** `https://leakcheck.io/api/v2`
- **Public API Base URL:** `https://leakcheck.io/api/public`

## Version

This wrapper supports **LeakCheck API v2**.

## License

This project is licensed under the MIT License.
Loading

0 comments on commit 74da00e

Please sign in to comment.