XposedOrNot/XposedOrNot-Python

# XposedOrNot Python 客户端 一个用于 [XposedOrNot API](https://xposedornot.com) 的 Python 客户端，用于检查数据泄露和暴露的凭据。 ## 安装 ``` pip install xposedornot ``` ## 快速开始 ### 免费 API（无需 API 密钥） ``` from xposedornot import XposedOrNot # 初始化 client xon = XposedOrNot() # 检查 email 是否已泄露（仅返回 breach 名称） result = xon.check_email("test@example.com") print(f"Found in {len(result.breaches)} breaches: {result.breaches}") # 获取详细的 breach 分析 analytics = xon.breach_analytics("test@example.com") print(f"Total exposures: {analytics.exposures_count}") print(f"First breach: {analytics.first_breach}") for breach in analytics.breaches_details: print(f" - {breach.breach}: {breach.xposed_records} records") # 获取所有已知 breach breaches = xon.get_breaches() print(f"Total breaches in database: {len(breaches)}") # 按 domain 过滤 breach adobe_breaches = xon.get_breaches(domain="adobe.com") # 检查 password 是否已泄露 # 安全：Password 在本地进行 hash 处理，仅将部分 hash 发送至 API pwd_result = xon.check_password("password123") print(f"Password exposed {pwd_result.count} times") ``` ### xonPlus API（需要 API 密钥） 如需具备更高速率限制和详细泄露信息的商业用途，请从 [console.xposedornot.com](https://console.xposedornot.com) 获取 API 密钥。 ``` from xposedornot import XposedOrNot # 使用 API key 初始化 - 自动使用 Plus API 进行 email 检查 xon = XposedOrNot(api_key="your-api-key") # 检查 email - 返回详细的 breach 信息 result = xon.check_email("test@example.com") print(f"Status: {result.status}") print(f"Email: {result.email}") for breach in result.breaches: print(f" - {breach.breach_id}") print(f" Domain: {breach.domain}") print(f" Records: {breach.xposed_records}") print(f" Risk: {breach.password_risk}") print(f" Data exposed: {breach.xposed_data}") ``` ## 功能 - **邮箱泄露检查**：检查邮箱是否在已知的数据泄露中遭到暴露 - **xonPlus 集成**：提供详细泄露信息和更高速率限制的商业 API - **泄露分析**：获取详细的分析数据，包括按行业、风险等级和年份统计的指标 - **泄露数据库**：访问包含过滤功能的已知泄露完整数据库 - **安全密码检查**：在不暴露密码的情况下检查密码——使用 k-anonymity（在本地对密码进行哈希处理，仅发送部分哈希值） - **类型提示**：提供完整的类型注解以支持 IDE ## API 参考 ### XposedOrNot 客户端 ``` from xposedornot import XposedOrNot # 基本初始化（free API） xon = XposedOrNot() # 使用 API key（Plus API - 更高速率限制，详细响应） xon = XposedOrNot( api_key="your-api-key", # From console.xposedornot.com timeout=30.0, # Request timeout in seconds ) # 作为 context manager 使用 with XposedOrNot() as xon: result = xon.check_email("test@example.com") ``` **速率限制**： - **免费 API**（无密钥）：客户端强制执行每秒 1 次请求，此外 API 还有每小时/每日的上限 - **Plus API**（带密钥）：无客户端限流——由服务器执行您的套餐限制（根据套餐不同，为 50-5000 RPM） - **自动重试**：遇到 429 错误时，客户端会自动最多重试 3 次，并采用指数退避策略（1秒、2秒、4秒） - 商业套餐请访问 [plus.xposedornot.com/products/api](https://plus.xposedornot.com/products/api) ### 方法 #### `check_email(email: str, include_details: bool = False) -> EmailBreachResponse | EmailBreachDetailedResponse` 检查邮箱是否在数据泄露中遭到暴露。 - **无 API 密钥**：使用免费 API，返回仅包含泄露名称的 `EmailBreachResponse`。传递 `include_details=True` 以请求详细的泄露信息。 - **有 API 密钥**：使用 Plus API（`plus-api.xposedornot.com`），返回包含完整泄露详情的 `EmailBreachDetailedResponse`（`include_details` 将被忽略——Plus API 始终会查询详细结果） ``` # Free API（无 key） xon = XposedOrNot() result = xon.check_email("test@example.com") print(result.breaches) # ['Adobe', 'LinkedIn', ...] # Plus API（带 key） xon = XposedOrNot(api_key="your-key") result = xon.check_email("test@example.com") print(result.breaches[0].breach_id) # 'Adobe' print(result.breaches[0].xposed_records) # 152000000 ``` #### `breach_analytics(email: str, token: str = None) -> BreachAnalyticsResponse` 获取邮箱的详细泄露分析。传递 `token` 以访问敏感的泄露数据。 ``` analytics = xon.breach_analytics("test@example.com") print(analytics.breaches_count) # Number of breaches print(analytics.breach_names) # Names of breaches the email was found in print(analytics.breaches_details) # List of BreachDetails print(analytics.metrics) # BreachMetrics with industry, risk, etc. ``` #### `get_breaches(domain: str = None, breach_id: str = None) -> list[Breach]` 获取所有已知的泄露事件，可通过域名或泄露 ID 进行可选过滤。 ``` # 所有 breach all_breaches = xon.get_breaches() # 按 domain 过滤 adobe = xon.get_breaches(domain="adobe.com") # 根据 ID 获取特定 breach adobe = xon.get_breaches(breach_id="Adobe") ``` #### `get_domain_breaches() -> DomainBreachesResponse` 获取根据您的 API 密钥验证的域名的泄露信息（需要在 [console.xposedornot.com](https://console.xposedornot.com) 配置已验证的域名并拥有 API 密钥）。 ``` xon = XposedOrNot(api_key="your-key") report = xon.get_domain_breaches() print(report.domain_summary) # Breach counts per domain print(report.yearly_metrics) # Breach counts by year print(report.top10_breaches) # Top 10 largest breaches for record in report.breaches_details: print(record.email, record.domain, record.breach) ``` #### `check_password(password: str) -> PasswordCheckResponse` 检查密码是否在数据泄露中遭到暴露。 **安全提示：您的密码绝不会通过网络发送。** 此方法使用 k-anonymity 保护： 1. 密码在本地使用 Keccak-512 进行哈希处理 2. 仅将哈希值的前 10 个字符发送到 API 3. API 返回与该哈希前缀匹配的结果 4. 您的实际密码永远不会离开您的计算机 ``` # 您的 password 是安全的 - 仅发送部分 hash，绝不发送 password 本身 result = xon.check_password("mypassword") print(result.count) # Times this password was found in breaches print(result.characteristics) # Password traits (length, digits, etc.) ``` ## 错误处理 ``` from xposedornot import ( XposedOrNot, NotFoundError, RateLimitError, ValidationError, ) xon = XposedOrNot() try: result = xon.check_email("test@example.com") except NotFoundError: print("Email not found in any breaches") except RateLimitError: print("Rate limit exceeded, please wait") except ValidationError as e: print(f"Invalid input: {e}") ``` ## 响应模型 所有响应均为类型化的 dataclass： - `EmailBreachResponse` - 包含泄露名称列表（免费 API） - `EmailBreachDetailedResponse` - 包含元数据的详细泄露信息（Plus API） - `BreachInfo` - 来自 Plus API 的单独泄露详情（breach_id、domain、password_risk 等） - `BreachAnalyticsResponse` - 包含各项指标的详细分析 - `BreachDetails` - 来自分析端点的单独泄露信息 - `BreachMetrics` - 分析数据细目 - `Breach` - 泄露数据库条目 - `PasswordCheckResponse` - 密码暴露数据 ## 链接 - [XposedOrNot 官网](https://xposedornot.com) - [API 文档](https://xposedornot.com/api_doc) - [GitHub 仓库](https://github.com/XposedOrNot/XposedOrNot-Python) ## 许可证 MIT 许可证

标签：API客户端, Python, SOC工具, StruQ, 凭据暴露, 无后门, 漏洞发现, 逆向工具