lush-sentryx-core 0.1.0__tar.gz

lush_sentryx_core-0.1.0/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.3
+Name: lush-sentryx-core
+Version: 0.1.0
+Summary: Core scrubbing and masking utilities for Sentry events, SDK-agnostic.
+Author: straydragon
+Requires-Dist: sentry-sdk>=2.0.0 ; extra == 'typing'
+Requires-Python: >=3.10
+Provides-Extra: typing
+Description-Content-Type: text/markdown
+
+# lush-sentryx-core
+
+只做一件事: 对数据做脱敏/过滤.
+
+它不依赖 `sentry-sdk`. 你可以把它接到 Sentry 的 `before_send` 上,也可以单独用在日志/审计/任务系统里.
+
+## 例子
+
+```python
+from lush_sentryx_core import SENTRY_DEFAULT_DENYLIST, deep_scrub_sensitive_data
+
+data = {"password": "secret", "profile": {"token": "xxx", "name": "demo"}}
+deep_scrub_sensitive_data(data, SENTRY_DEFAULT_DENYLIST)
+```
+
+## 开发
+
+```bash
+uv sync -p 3.10 --frozen
+uv run -p 3.10 pytest
+```

lush_sentryx_core-0.1.0/README.md

@@ -0,0 +1,21 @@
+# lush-sentryx-core
+
+只做一件事: 对数据做脱敏/过滤.
+
+它不依赖 `sentry-sdk`. 你可以把它接到 Sentry 的 `before_send` 上,也可以单独用在日志/审计/任务系统里.
+
+## 例子
+
+```python
+from lush_sentryx_core import SENTRY_DEFAULT_DENYLIST, deep_scrub_sensitive_data
+
+data = {"password": "secret", "profile": {"token": "xxx", "name": "demo"}}
+deep_scrub_sensitive_data(data, SENTRY_DEFAULT_DENYLIST)
+```
+
+## 开发
+
+```bash
+uv sync -p 3.10 --frozen
+uv run -p 3.10 pytest
+```

lush_sentryx_core-0.1.0/pyproject.toml

@@ -0,0 +1,220 @@
+[project]
+name = "lush-sentryx-core"
+version = "0.1.0"
+description = "Core scrubbing and masking utilities for Sentry events, SDK-agnostic."
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "straydragon" }]
+dependencies = []                                                                     # 无外部依赖,纯 Python 实现
+
+[project.optional-dependencies]
+typing = ["sentry-sdk>=2.0.0"]
+
+[build-system]
+requires = ["uv_build>=0.10.12,<0.11.0"]
+build-backend = "uv_build"
+
+[tool.uv]
+package = true
+
+[dependency-groups]
+dev = ["pytest>=8.4.1", "pytest-asyncio>=1.1.0", "pytest-cov>=6.2.1"]
+
+[tool.pytest.ini_options]
+addopts = "--import-mode=importlib --cov=lush_sentryx_core --cov-report=term-missing"
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+asyncio_default_test_loop_scope = "function"
+
+[tool.ruff]
+line-length = 140
+indent-width = 4
+target-version = "py310"
+
+[tool.ruff.lint]
+fixable = ["F401", "ALL"]
+unfixable = []
+
+dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+
+select = ["ALL"]
+ignore = [
+    # === 代码质量与复杂性 ===
+    "C901",    # 函数复杂度过高,影响可读性
+    "PLR0912", # 函数分支过多,建议重构
+    "PLR0913", # 函数参数过多,难以维护
+    "PLR0915", # 函数语句过多,建议拆分
+    "PLR0911", # 函数返回语句过多,逻辑复杂
+    "PLR2004", # 使用魔术数值,建议使用常量
+    "SIM108",  # 更倾向于使用ifelse表达式,而不是if/else语句
+
+    # === 类型注解 ===
+    "ANN002", # 函数*args参数缺少类型注解
+    "ANN003", # 函数**kwargs参数缺少类型注解
+    "ANN401", # 使用Any类型,建议使用具体类型
+
+    # === 函数参数设计 ===
+    "FBT001", # 布尔类型位置参数,易混淆
+    "FBT002", # 布尔默认值位置参数,易误用
+    "N805",   # 第一个方法参数命名问题, 先忽略
+
+    # === 异常处理 ===
+    "BLE001", # 捕获所有异常,隐藏问题
+    "TRY003", # 异常消息应在类中定义
+    "TRY004", # 类型检查应抛出TypeError
+
+    # === 代码简化 ===
+    "SIM102", # 可折叠的if语句,简化代码
+
+    # === 格式规范 ===
+    "COM812", # 缺少尾随逗号,影响diff
+    "E501",   # 行长度过长,影响可读性
+
+    # === 日志记录 ===
+    "G004", # 日志使用f-string,影响性能
+
+    # === 类型检查优化 ===
+    "TC001", # 仅用于类型检查的导入,优化性能
+    "TC002", # 仅用于类型检查的导入,优化性能
+    "TC003", # 仅用于类型检查的导入,优化性能
+
+    # === 代码清理 ===
+    "ERA001", # 注释掉的代码,应删除
+
+    # === 私有成员访问 ===
+    "SLF001", # 访问私有成员,破坏封装
+
+    # === 日期时间处理 ===
+    "DTZ001", # datetime缺少时区信息
+    "DTZ005", # datetime.now()缺少时区
+
+    # === 调试代码 ===
+    "T201", # print语句调试代码,生产环境禁用
+
+    # === T O D O管理 ===
+    "TD002", # 缺少作者信息
+    "TD003", # 缺少问题链接
+
+    # === 其他 ===
+    "D",  # 文档字符串相关规则
+    "EM", # 错误消息相关规则
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = [
+    # === 测试代码质量 ===
+    "B011",    # assert False应改为raise AssertionError
+    "B008",    # 函数调用作为默认参数
+    "ARG001",  # 未使用的函数参数
+    "ARG002",  # 未使用的方法参数
+    "ARG005",  # lambda中未使用的参数
+    "F841",    # 未使用的变量
+    "B018",    # 无用的表达式
+    "N806",    # 函数中非小写变量名
+    "W293",    # 空行包含空格
+    "N802",    # 函数名不规范
+    "PERF401", # 性能相关
+    "PT",      # assert 相关
+
+    # === 测试安全相关 ===
+    "S101", # assert语句(测试中使用)
+    "S105", # 硬编码密码字符串
+    "S201", # Flask debug=True
+    "S301", # 可疑的pickle使用
+    "S311", # 非加密安全的随机数
+
+    # === 测试异常处理 ===
+    "BLE001", # 捕获所有异常
+    "B017",   # assertRaises捕获Exception
+    "PT011",  # pytest.raises缺少match参数
+    "PT017",  # except中的assert语句
+    "EM101",  # 异常中的原始字符串
+
+    # === 测试代码复杂度 ===
+    "C901",    # 函数复杂度过高
+    "PLR2004", # 魔术数值
+
+    # === 测试导入相关 ===
+    "PLC0415", # 函数内import语句
+    "ANN",     # 类型注解(测试中宽松)
+    "TC",      # 类型检查的导入
+
+    # === 测试参数设计 ===
+    "FBT001", # 布尔类型位置参数
+    "FBT002", # 布尔默认值位置参数
+    "FBT003", # 布尔位置参数调用
+
+    # === 测试异常处理 ===
+    "TRY003", # 异常消息定义
+
+    # === 测试代码简化 ===
+    "SIM117", # 多个连续的with语句
+
+    # === 测试格式规范 ===
+    "E501", # 行长度过长
+
+    # === 测试日志处理 ===
+    "G004", # 日志使用f-string
+
+    # === 测试调试代码 ===
+    "T201", # print语句
+
+    # === 测试文档相关 ===
+    "D", # 文档字符串
+
+    # === 测试私有访问 ===
+    "SLF001", # 私有成员访问
+
+    # === 测试Unicode ===
+    "RUF001", # 模糊的Unicode字符
+
+    # === 测试路径处理 ===
+    "PTH", # pathlib相关规则
+
+    # === 测试日期时间 ===
+    "DTZ001", # datetime缺少时区
+    "DTZ005", # datetime.now()缺少时区
+
+    # === 测试代码清理 ===
+    "ERA001", # 注释掉的代码
+
+    "RUF",
+]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"
+docstring-code-format = true
+docstring-code-line-length = "dynamic"
+
+# ============================================================================
+# basedpyright 配置 - 独立包配置
+# ============================================================================
+[tool.basedpyright]
+pythonVersion = "3.10"
+
+reportUnannotatedClassAttribute = "none"
+reportUnreachable = "none"
+reportUnnecessaryIsInstance = "none"
+reportAny = "none"
+reportExplicitAny = "none"
+reportConstantRedefinition = "none"
+reportUnnecessaryComparison = "none"
+
+[[tool.basedpyright.executionEnvironments]]
+root = "tests"
+reportUnusedCallResult = false
+reportUnknownArgumentType = false
+reportArgumentType = false
+reportUnusedFunction = false
+reportUnusedParameter = false
+reportExplicitAny = "none"
+reportAny = "none"
+reportCallIssue = "none"
+reportUnnecessaryTypeIgnoreComment = "none"
+
+[[tool.basedpyright.executionEnvironments]]
+root = "src"

lush_sentryx_core-0.1.0/src/lush_sentryx_core/__init__.py

@@ -0,0 +1,105 @@
+"""Sentryx Core - Sentry 敏感数据过滤核心库
+
+这是一个独立的敏感数据过滤和脱敏核心库,不依赖 sentry-sdk.
+可被任何版本的 Sentry SDK (1.x 或 2.x) 使用,也可独立用于其他数据脱敏场景.
+
+主要特性:
+    - 纯 Python 实现,无外部依赖
+    - 深度递归清理嵌套数据结构
+    - 支持自定义敏感字段列表
+    - 提供 URL 参数清理、邮箱脱敏等工具函数
+    - 兼容 Sentry SDK 1.x 和 2.x 的事件结构
+    - 提供类型定义用于类型检查
+
+使用方式:
+
+    1. 推荐方式 - 通过版本命名空间导入 (明确 SDK 版本):
+        >>> from lush_sentryx_core.sdk.v2 import create_additional_filter, SENTRY_DEFAULT_DENYLIST
+        >>> from lush_sentryx_core.sdk.v2.types import Event, Hint
+
+    2. 简化方式 - 直接导入 (默认使用 v2):
+        >>> from lush_sentryx_core import create_additional_filter, SENTRY_DEFAULT_DENYLIST
+
+    3. 独立使用 (数据脱敏):
+        >>> from lush_sentryx_core import deep_scrub_sensitive_data, SENTRY_DEFAULT_DENYLIST
+        >>> data = {"password": "secret", "config": {"token": "xxx"}}
+        >>> deep_scrub_sensitive_data(data, SENTRY_DEFAULT_DENYLIST)
+        >>> data
+        {'password': '[Filtered]', 'config': {'token': '[Filtered]'}}
+
+    4. 配合 Sentry SDK 使用:
+        >>> from lush_sentryx_core.sdk.v2 import create_additional_filter, SENTRY_DEFAULT_DENYLIST
+        >>> import sentry_sdk
+        >>> sentry_sdk.init(
+        ...     dsn="...",
+        ...     before_send=create_additional_filter(SENTRY_DEFAULT_DENYLIST),
+        ... )
+
+Note:
+    - 当前默认导出的是 SDK v2 版本的实现
+    - 如果需要支持 SDK 1.x,可以在 sdk 目录下添加 v1 模块
+"""
+
+# 导入 sdk 命名空间
+from lush_sentryx_core import sdk
+
+# 从 v2 重新导出常用 API (保持向后兼容)
+from lush_sentryx_core.sdk.v2 import (
+    # 常量
+    BUSINESS_SENSITIVE_FIELDS,
+    FILTERED_PLACEHOLDER,
+    SENSITIVE_URL_PATTERNS,
+    SENTRY_DEFAULT_DENYLIST,
+    # 类型 (类型检查时使用 sentry-sdk 原生类型)
+    Breadcrumb,
+    Event,
+    EventProcessor,
+    ExcInfo,
+    Hint,
+    SensitiveFields,
+    TransactionProcessor,
+    # 过滤器工厂 (返回 EventProcessor/TransactionProcessor 类型)
+    create_additional_filter,
+    create_transaction_filter,
+    # 工具函数
+    custom_repr,
+    # 数据清理函数
+    deep_scrub_sensitive_data,
+    mask_email_partially,
+    mask_string_partially,
+    mask_user_email_partially,
+    parameterize_request_urls,
+    scrub_dict_keys,
+    scrub_stacktrace_vars,
+)
+
+__all__ = [  # noqa: RUF022
+    # SDK 命名空间
+    "sdk",
+    # 类型 (类型检查时使用 sentry-sdk 原生类型,确保与 sentry_sdk.init() 完全兼容)
+    "Breadcrumb",
+    "Event",
+    "EventProcessor",
+    "ExcInfo",
+    "Hint",
+    "SensitiveFields",
+    "TransactionProcessor",
+    # 常量
+    "BUSINESS_SENSITIVE_FIELDS",
+    "FILTERED_PLACEHOLDER",
+    "SENSITIVE_URL_PATTERNS",
+    "SENTRY_DEFAULT_DENYLIST",
+    # 过滤器工厂 (返回 EventProcessor/TransactionProcessor 类型)
+    "create_additional_filter",
+    "create_transaction_filter",
+    # 数据清理函数
+    "deep_scrub_sensitive_data",
+    "scrub_dict_keys",
+    "scrub_stacktrace_vars",
+    # 工具函数
+    "custom_repr",
+    "mask_email_partially",
+    "mask_string_partially",
+    "mask_user_email_partially",
+    "parameterize_request_urls",
+]

lush_sentryx_core-0.1.0/src/lush_sentryx_core/sdk/__init__.py

@@ -0,0 +1,8 @@
+"""Sentryx Core SDK 版本命名空间
+
+提供不同 Sentry SDK 版本的类型定义和过滤器实现.
+"""
+
+from lush_sentryx_core.sdk import v2
+
+__all__ = ["v2"]

lush_sentryx_core-0.1.0/src/lush_sentryx_core/sdk/v2/__init__.py

@@ -0,0 +1,89 @@
+"""Sentryx Core SDK v2 - 适用于 Sentry SDK 2.x
+
+此模块提供与 Sentry SDK 2.x 兼容的类型定义、过滤器和工具函数.
+
+主要特性:
+    - 类型定义: Event, Hint, Breadcrumb 等类型别名
+    - 过滤器工厂: before_send, before_send_transaction 过滤器
+    - 数据清理: 深度递归清理敏感数据
+    - 工具函数: 邮箱脱敏、URL 清理等
+
+Example:
+    基本使用:
+        >>> from lush_sentryx_core.sdk.v2 import create_additional_filter, SENTRY_DEFAULT_DENYLIST
+        >>> import sentry_sdk
+        >>> sentry_sdk.init(
+        ...     dsn="...",
+        ...     before_send=create_additional_filter(SENTRY_DEFAULT_DENYLIST),
+        ... )
+
+    类型提示:
+        >>> from lush_sentryx_core.sdk.v2.types import Event, Hint
+        >>> def my_filter(event: Event, hint: Hint) -> Event | None:
+        ...     return event
+
+Note:
+    - 此模块不依赖 sentry-sdk,但类型定义与 sentry-sdk 2.x 兼容
+    - 如果需要使用 sentry-sdk 的原生类型,可以在运行时导入
+"""
+
+from lush_sentryx_core.sdk.v2.const import (
+    BUSINESS_SENSITIVE_FIELDS,
+    FILTERED_PLACEHOLDER,
+    SENSITIVE_URL_PATTERNS,
+    SENTRY_DEFAULT_DENYLIST,
+)
+from lush_sentryx_core.sdk.v2.filters import (
+    create_additional_filter,
+    create_transaction_filter,
+)
+from lush_sentryx_core.sdk.v2.scrubbers import (
+    deep_scrub_sensitive_data,
+    scrub_dict_keys,
+    scrub_stacktrace_vars,
+)
+from lush_sentryx_core.sdk.v2.types import (
+    Breadcrumb,
+    Event,
+    EventProcessor,
+    ExcInfo,
+    Hint,
+    SensitiveFields,
+    TransactionProcessor,
+)
+from lush_sentryx_core.sdk.v2.utils import (
+    custom_repr,
+    mask_email_partially,
+    mask_string_partially,
+    mask_user_email_partially,
+    parameterize_request_urls,
+)
+
+__all__ = [  # noqa: RUF022
+    # 类型 (类型检查时使用 sentry-sdk 原生类型)
+    "Breadcrumb",
+    "Event",
+    "EventProcessor",
+    "ExcInfo",
+    "Hint",
+    "SensitiveFields",
+    "TransactionProcessor",
+    # 常量
+    "BUSINESS_SENSITIVE_FIELDS",
+    "FILTERED_PLACEHOLDER",
+    "SENSITIVE_URL_PATTERNS",
+    "SENTRY_DEFAULT_DENYLIST",
+    # 过滤器工厂 (返回 EventProcessor/TransactionProcessor 类型)
+    "create_additional_filter",
+    "create_transaction_filter",
+    # 数据清理函数
+    "deep_scrub_sensitive_data",
+    "scrub_dict_keys",
+    "scrub_stacktrace_vars",
+    # 工具函数
+    "custom_repr",
+    "mask_email_partially",
+    "mask_string_partially",
+    "mask_user_email_partially",
+    "parameterize_request_urls",
+]

lush_sentryx_core-0.1.0/src/lush_sentryx_core/sdk/v2/const.py

@@ -0,0 +1,87 @@
+"""Sentryx Core SDK v2 常量定义
+
+包含敏感数据字段列表、URL 模式等常量.
+此模块不依赖 sentry-sdk, 可被任何 Sentry SDK 版本使用.
+"""
+
+import re
+from re import Pattern
+from typing import Final
+
+# Sentry SDK 2.x 默认的敏感字段列表
+# 参考: https://github.com/getsentry/sentry-python/blob/master/sentry_sdk/scrubber.py
+#
+# 这些字段在 EventScrubber 中使用子串匹配 (不区分大小写)
+# 例如: 'token' 会匹配 'access_token', 'user_token', 'my_token_field' 等
+SENTRY_DEFAULT_DENYLIST: Final[frozenset[str]] = frozenset(
+    {
+        # 认证相关
+        "password",
+        "passwd",
+        "secret",
+        "api_key",
+        "apikey",
+        "access_token",
+        "auth",
+        "credentials",
+        "token",
+        "api_secret",
+        "app_secret",
+        "client_secret",
+        "private_key",
+        "public_key",
+        "signing_key",
+        "encryption_key",
+        "session_key",
+        "session_id",
+        "sessionid",
+        # HTTP Headers
+        "authorization",
+        "cookie",
+        "set-cookie",
+        "x-api-key",
+        "x-auth-token",
+        "x-csrf-token",
+        "x-forwarded-for",
+        "x-real-ip",
+        # 个人身份信息
+        "email",
+        "phone",
+        "ssn",
+        "social_security",
+        "credit_card",
+        "card_number",
+        "cvv",
+        "pin",
+        # 数据库连接
+        "mysql_pwd",
+        "postgres_password",
+        "db_password",
+        "database_url",
+        "connection_string",
+        # 其他敏感信息
+        "jwt",
+        "bearer",
+        "oauth",
+        "refresh_token",
+        "id_token",
+    }
+)
+
+# 业务特定的敏感数据字段列表
+#
+# 匹配规则: 使用 **子串匹配** (.*xxx.*, 不区分大小写)
+# - 'token' 会匹配: access_token, user_token, my_token_field 等
+# - 'secret' 会匹配: user_secret, api_secret, secret_key 等
+# - 'corpid' 会匹配: corpid, CorpId, CORPID, my_corpid 等
+#
+# 这里添加业务特定的敏感字段,包括企业微信相关字段
+BUSINESS_SENSITIVE_FIELDS: Final[frozenset[str]] = frozenset()
+
+# URL中可能包含敏感信息的模式
+SENSITIVE_URL_PATTERNS: Final[list[Pattern[str]]] = [
+    re.compile(r"[\?&](?:token|key|secret|password|api_key)=[\w\-\.]+", re.IGNORECASE),
+]
+
+# 默认的过滤替换值
+FILTERED_PLACEHOLDER: Final[str] = "[Filtered]"

lush_sentryx_core-0.1.0/src/lush_sentryx_core/sdk/v2/filters.py

@@ -0,0 +1,123 @@
+"""Sentryx Core SDK v2 事件过滤器
+
+提供事件的额外过滤和清理功能.
+此模块不依赖 sentry-sdk, 可被任何 Sentry SDK 版本使用.
+
+类型兼容性:
+    - create_additional_filter 返回 EventProcessor 类型
+    - create_transaction_filter 返回 TransactionProcessor 类型
+    - 这两个类型在类型检查时与 sentry_sdk.init() 的参数类型完全匹配
+"""
+
+import re
+
+from lush_sentryx_core.sdk.v2.const import SENSITIVE_URL_PATTERNS
+from lush_sentryx_core.sdk.v2.scrubbers import deep_scrub_sensitive_data, scrub_stacktrace_vars
+from lush_sentryx_core.sdk.v2.types import Event, EventProcessor, Hint, SensitiveFields, TransactionProcessor
+from lush_sentryx_core.sdk.v2.utils import mask_user_email_partially, parameterize_request_urls
+
+
+def create_additional_filter(
+    sensitive_fields: SensitiveFields,
+) -> EventProcessor:
+    """创建轻量级事件过滤器,补充 EventScrubber 未覆盖的场景
+
+    EventScrubber 已自动处理标准的敏感字段清理,这个过滤器处理:
+    - URL 查询参数清理 (移除包含 token/key/secret 的查询参数)
+    - 用户邮箱脱敏处理 (保留部分信息用于识别)
+    - 深度递归清理嵌套数据结构 (extra, contexts 等)
+    - 其他 EventScrubber 无法自动处理的场景
+
+    Args:
+        sensitive_fields: 敏感字段名的集合 (用于深度清理)
+
+    Returns:
+        callable: before_send 过滤器函数,签名为 (Event, Hint) -> Event | None
+
+    Note:
+        - 这是一个工厂函数,返回实际的过滤器函数
+        - 兼容 Sentry SDK 2.x 的 before_send 回调
+
+    Example:
+        >>> from lush_sentryx_core.sdk.v2 import create_additional_filter, SENTRY_DEFAULT_DENYLIST
+        >>> import sentry_sdk
+        >>> sentry_sdk.init(
+        ...     dsn="...",
+        ...     before_send=create_additional_filter(SENTRY_DEFAULT_DENYLIST),
+        ... )
+    """
+
+    def additional_filter(event: Event, hint: Hint) -> Event | None:  # noqa: ARG001  # pyright: ignore[reportUnusedParameter]
+        """轻量级事件过滤器:处理 EventScrubber 未覆盖的场景"""
+        try:
+            # 1. 清理 URL 中的敏感查询参数
+            request = event.get("request", {})
+            if request:
+                parameterize_request_urls(request)
+
+            # 2. 用户邮箱脱敏处理 (保留部分信息用于识别)
+            user = event.get("user", {})
+            if user:
+                mask_user_email_partially(user)
+
+            # 3. 深度清理 extra 数据 (补充 EventScrubber 的清理)
+            if "extra" in event:
+                deep_scrub_sensitive_data(event["extra"], sensitive_fields)
+
+            # 4. 深度清理 contexts 数据
+            if "contexts" in event:
+                deep_scrub_sensitive_data(event["contexts"], sensitive_fields)
+
+            # 5. 深度清理堆栈帧中的局部变量 (EventScrubber 不能递归处理嵌套对象)
+            scrub_stacktrace_vars(event, sensitive_fields)
+
+        except Exception:
+            # 出现异常时返回None,避免发送可能包含敏感数据的事件
+            return None
+        else:
+            return event
+
+    return additional_filter
+
+
+def create_transaction_filter() -> TransactionProcessor:
+    """创建事务名称过滤器, 防止事务名称中包含敏感信息
+
+    Returns:
+        callable: before_send_transaction 过滤器函数,签名为 (Event, Hint) -> Event | None
+
+    Note:
+        - 这是一个工厂函数,返回实际的过滤器函数
+        - 兼容 Sentry SDK 2.x 的 before_send_transaction 回调
+
+    Example:
+        >>> from lush_sentryx_core.sdk.v2 import create_transaction_filter
+        >>> import sentry_sdk
+        >>> sentry_sdk.init(
+        ...     dsn="...",
+        ...     before_send_transaction=create_transaction_filter(),
+        ... )
+    """
+
+    def transaction_filter(event: Event, hint: Hint) -> Event | None:  # noqa: ARG001  # pyright: ignore[reportUnusedParameter]
+        """过滤事务名称中的敏感信息"""
+        try:
+            transaction_name = event.get("transaction")
+            if transaction_name and isinstance(transaction_name, str):
+                for pattern in SENSITIVE_URL_PATTERNS:
+                    if pattern.search(transaction_name):
+                        transaction_name = re.sub(
+                            r"[\?&](?:token|key|secret|password|api_key)=[\w\-\.]+",
+                            r"?[Filtered]",
+                            transaction_name,
+                            flags=re.IGNORECASE,
+                        )
+                        event["transaction"] = transaction_name
+                        break
+
+        except Exception:
+            return event
+        else:
+            return event
+
+    return transaction_filter

lush_sentryx_core-0.1.0/src/lush_sentryx_core/sdk/v2/scrubbers.py

@@ -0,0 +1,145 @@
+"""Sentryx Core SDK v2 数据清理器
+
+提供敏感数据清理功能,确保事件不包含敏感信息.
+此模块不依赖 sentry-sdk, 可被任何 Sentry SDK 版本使用.
+"""
+
+import contextlib
+from typing import Any
+
+from lush_sentryx_core.sdk.v2.const import FILTERED_PLACEHOLDER
+from lush_sentryx_core.sdk.v2.types import Event, SensitiveFields
+
+
+def deep_scrub_sensitive_data(
+    data: Any,
+    sensitive_fields: SensitiveFields,
+    max_depth: int = 10,
+    _current_depth: int = 0,
+    placeholder: str = FILTERED_PLACEHOLDER,
+) -> None:
+    """深度递归清理敏感数据
+
+    此函数用于递归遍历数据结构,将包含敏感字段名的值替换为占位符.
+    适用于任何需要清理敏感数据的场景,不限于 Sentry.
+
+    Args:
+        data: 要清理的数据(字典、列表或其他类型)
+        sensitive_fields: 敏感字段名的集合
+        max_depth: 最大递归深度,防止无限递归 (默认 10 层)
+        _current_depth: 当前递归深度(内部使用,不应手动设置)
+        placeholder: 替换敏感数据的占位符
+
+    Note:
+        - 仅处理 dict 和 list/tuple 类型,其他类型保持不变
+        - 使用子串不区分大小写匹配检查字段名
+        - 性能考虑: 限制最大递归深度避免栈溢出
+        - 会原地修改传入的数据结构
+
+    Example:
+        >>> data = {"config": {"corpid": "ww123", "access_token": "secret", "normal": "value"}}
+        >>> fields = {"corpid", "access_token", "password"}
+        >>> deep_scrub_sensitive_data(data, fields)
+        >>> data
+        {'config': {'corpid': '[Filtered]', 'access_token': '[Filtered]', 'normal': 'value'}}
+    """
+    if _current_depth >= max_depth:
+        return
+
+    if isinstance(data, dict):
+        keys_to_scrub: list[str] = []
+        for key in list(data.keys()):  # pyright: ignore[reportUnknownVariableType, reportUnknownArgumentType]
+            key_str = str(key).lower()  # pyright: ignore[reportUnknownArgumentType]
+            is_sensitive = any(deny.lower() in key_str or key_str in deny.lower() for deny in sensitive_fields)
+
+            if is_sensitive:
+                keys_to_scrub.append(key)  # pyright: ignore[reportUnknownArgumentType]
+            else:
+                deep_scrub_sensitive_data(data[key], sensitive_fields, max_depth, _current_depth + 1, placeholder)
+
+        for key in keys_to_scrub:
+            data[key] = placeholder
+
+    elif isinstance(data, (list, tuple)):
+        for item in data:  # pyright: ignore[reportUnknownVariableType]
+            deep_scrub_sensitive_data(item, sensitive_fields, max_depth, _current_depth + 1, placeholder)
+
+
+def scrub_stacktrace_vars(
+    event: Event,
+    sensitive_fields: SensitiveFields,
+    placeholder: str = FILTERED_PLACEHOLDER,
+) -> None:
+    """清理堆栈帧中局部变量的嵌套敏感数据
+
+    此函数遍历 Sentry 事件中的所有堆栈帧,对每个局部变量进行深度清理.
+    适用于 Sentry SDK 2.x 的事件结构.
+
+    Args:
+        event: Sentry 事件对象 (符合 SDK 2.x 结构)
+        sensitive_fields: 敏感字段名的集合
+        placeholder: 替换敏感数据的占位符
+
+    Note:
+        - 处理 exception 和 threads 中的 stacktrace
+        - 原地修改局部变量的值
+        - 保留变量结构,只过滤敏感字段
+
+    Example:
+        局部变量 wecom_config = {'corpid': 'ww123', 'name': 'test'}
+        会被处理为: {'corpid': '[Filtered]', 'name': 'test'}
+    """
+    with contextlib.suppress(Exception):  # 静默处理异常,避免影响主流程
+        # 处理异常堆栈帧中的局部变量
+        if "exception" in event:
+            exception_data = event["exception"]
+            values = exception_data.get("values", [])
+            for exception_value in values:
+                stacktrace = exception_value.get("stacktrace", {})
+                frames = stacktrace.get("frames", [])
+                for frame in frames:
+                    if "vars" in frame and isinstance(frame["vars"], dict):
+                        for _var_name, var_value in list(frame["vars"].items()):
+                            if isinstance(var_value, (dict, list)):
+                                deep_scrub_sensitive_data(var_value, sensitive_fields, placeholder=placeholder)
+
+        # 处理线程堆栈 (如果有)
+        if "threads" in event:
+            threads_data = event["threads"]
+            values = threads_data.get("values", [])
+            for thread_value in values:
+                stacktrace = thread_value.get("stacktrace", {})
+                frames = stacktrace.get("frames", [])
+                for frame in frames:
+                    if "vars" in frame and isinstance(frame["vars"], dict):
+                        for _var_name, var_value in list(frame["vars"].items()):
+                            if isinstance(var_value, (dict, list)):
+                                deep_scrub_sensitive_data(var_value, sensitive_fields, placeholder=placeholder)
+
+
+def scrub_dict_keys(
+    data: dict[str, Any],
+    sensitive_fields: SensitiveFields,
+    placeholder: str = FILTERED_PLACEHOLDER,
+) -> dict[str, Any]:
+    """清理字典中的敏感字段 (非递归,仅顶层)
+
+    Args:
+        data: 要清理的字典
+        sensitive_fields: 敏感字段名的集合
+        placeholder: 替换敏感数据的占位符
+
+    Returns:
+        清理后的字典副本
+
+    Example:
+        >>> data = {"password": "secret", "username": "john"}
+        >>> scrub_dict_keys(data, {"password"})
+        {'password': '[Filtered]', 'username': 'john'}
+    """
+    result = dict(data)
+    for key in result:
+        key_str = str(key).lower()
+        if any(deny.lower() in key_str or key_str in deny.lower() for deny in sensitive_fields):
+            result[key] = placeholder
+    return result

lush_sentryx_core-0.1.0/src/lush_sentryx_core/sdk/v2/types.py

@@ -0,0 +1,109 @@
+"""Sentryx Core SDK v2 类型定义
+
+定义与 Sentry SDK 2.x 兼容的类型别名.
+
+类型导入策略:
+    - 类型检查时 (TYPE_CHECKING=True): 从 sentry-sdk 导入原生类型,获得完整的类型检查
+    - 运行时: 使用本模块定义的类型别名,无需依赖 sentry-sdk
+
+这样设计的好处:
+    1. 类型检查器能获得与 sentry-sdk 完全匹配的类型定义
+    2. 运行时不强制依赖 sentry-sdk,保持核心库的独立性
+    3. 传递给 sentry_sdk.init() 的回调函数类型完全兼容
+
+使用示例:
+    >>> from lush_sentryx_core.sdk.v2.types import Event, Hint
+    >>> def my_filter(event: Event, hint: Hint) -> Event | None:
+    ...     return event
+
+Note:
+    - 需要在环境中安装 sentry-sdk>=2.0.0 才能获得正确的类型检查
+    - 运行时这些类型是 Any 的别名,不会影响代码执行
+"""
+
+from typing import TYPE_CHECKING, Any, TypedDict
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from sentry_sdk._types import (
+        Breadcrumb as SentryBreadcrumb,
+    )
+    from sentry_sdk._types import (
+        Event as SentryEvent,
+    )
+    from sentry_sdk._types import (
+        EventProcessor as SentryEventProcessor,
+    )
+    from sentry_sdk._types import (
+        ExcInfo as SentryExcInfo,
+    )
+    from sentry_sdk._types import (
+        Hint as SentryHint,
+    )
+    from sentry_sdk._types import (
+        TransactionProcessor as SentryTransactionProcessor,
+    )
+else:
+    from collections.abc import Callable
+
+# region 基础类型别名
+
+SensitiveFields = set[str] | frozenset[str]
+"""敏感字段集合类型"""
+
+# endregion
+
+
+# region 条件类型导出 (TYPE_CHECKING 时使用 sentry-sdk 原生类型)
+
+if TYPE_CHECKING:
+    # 类型检查时: 使用 sentry-sdk 原生类型
+    # 这确保 create_additional_filter 等函数返回的类型与
+    # sentry_sdk.init(before_send=...) 期望的类型完全匹配
+    Event = SentryEvent
+    Hint = SentryHint
+    ExcInfo = SentryExcInfo
+    Breadcrumb = SentryBreadcrumb
+    EventProcessor = SentryEventProcessor
+    TransactionProcessor = SentryTransactionProcessor
+else:
+    # 运行时: 使用 Any 别名,不需要 sentry-sdk 依赖
+    Event = dict[str, Any]
+    Hint = dict[str, Any]
+    ExcInfo = tuple[type[BaseException], BaseException, Any] | tuple[None, None, None]
+    Breadcrumb = dict[str, Any]
+    EventProcessor = Callable[[dict[str, Any], dict[str, Any]], dict[str, Any] | None]
+    TransactionProcessor = Callable[[dict[str, Any], dict[str, Any]], dict[str, Any] | None]
+
+# endregion
+
+
+# region 内部辅助类型 (用于 utils.py 等模块的类型注解)
+
+
+class Request(TypedDict, total=False):
+    """请求数据结构"""
+
+    url: str
+    method: str
+    query_string: str
+    data: dict[str, Any] | str
+    cookies: dict[str, str]
+    headers: dict[str, str]
+    env: dict[str, str]
+
+
+class User(TypedDict, total=False):
+    """用户数据结构"""
+
+    id: str
+    username: str
+    email: str
+    ip_address: str
+    name: str
+    geo: dict[str, Any]
+    data: dict[str, Any]
+
+
+# endregion

lush_sentryx_core-0.1.0/src/lush_sentryx_core/sdk/v2/utils.py

@@ -0,0 +1,187 @@
+"""Sentryx Core SDK v2 工具函数
+
+包含数据序列化、脱敏处理等辅助函数.
+此模块不依赖 sentry-sdk, 可被任何 Sentry SDK 版本使用.
+"""
+
+from typing import Any
+
+from lush_sentryx_core.sdk.v2.const import SENSITIVE_URL_PATTERNS
+from lush_sentryx_core.sdk.v2.types import Request, User
+
+
+def custom_repr(value: Any) -> str | None:
+    """创建自定义变量序列化函数,保持基本类型的清晰展示
+
+    Sentry SDK 默认使用 repr() 序列化局部变量,这会导致:
+    - 字符串 "hello" → "'hello'" (多了引号)
+    - 布尔值 False → "'False'" (变成字符串)
+    - 数字 123 → "'123'" (变成字符串)
+
+    此函数提供自定义序列化逻辑,对基本 JSON 可序列化类型保持清晰的原始格式,
+    同时让复杂对象继续使用默认的 repr() 表示.
+
+    Args:
+        value: 需要序列化的任意值
+
+    Returns:
+        str | None: 序列化后的字符串,或 None (让调用者使用默认处理)
+
+    Note:
+        此函数用于 sentry_sdk.init() 的 custom_repr 参数 (SDK 2.12.0+)
+
+    Example:
+        >>> custom_repr(True)
+        'True'
+        >>> custom_repr(123)
+        '123'
+        >>> custom_repr("hello")
+        'hello'
+        >>> custom_repr(None)
+        'None'
+        >>> custom_repr([1, 2])
+        None
+    """
+    if isinstance(value, (dict, list, tuple, set)):
+        return None
+
+    # 注意: bool 必须在 int 之前检查,因为 bool 是 int 的子类
+    if isinstance(value, bool):
+        return str(value)
+    if isinstance(value, (int, float)):
+        return str(value)
+    if isinstance(value, str):
+        return value
+    if value is None:
+        return "None"
+
+    return None
+
+
+def mask_email_partially(email: str) -> str:
+    """对邮箱进行部分脱敏,保留识别性
+
+    将 user@example.com 转换为 use***@example.com,
+    在保护隐私的同时保留一定的识别能力.
+
+    Args:
+        email: 邮箱地址字符串
+
+    Returns:
+        脱敏后的邮箱地址
+
+    Example:
+        >>> mask_email_partially("user@example.com")
+        'use***@example.com'
+        >>> mask_email_partially("ab@example.com")
+        '***@example.com'
+        >>> mask_email_partially("invalid-email")
+        'invalid-email'
+    """
+    if "@" not in email:
+        return email
+
+    username, domain = email.split("@", 1)
+    if len(username) > 3:
+        return username[:3] + "***@" + domain
+    return "***@" + domain
+
+
+def mask_user_email_partially(user: User | dict[str, Any]) -> None:
+    """对用户字典中的邮箱进行部分脱敏,保留识别性
+
+    将 user@example.com 转换为 use***@example.com,
+    在保护隐私的同时保留一定的识别能力.
+
+    Args:
+        user: 用户数据字典 (符合 Sentry User 结构),可能包含 'email' 或 'mail' 字段
+
+    Note:
+        - 此函数会原地修改传入的 user 字典
+        - 如果邮箱格式无效或为空,保持不变
+        - 支持 'email' 和 'mail' 两种字段名
+
+    Example:
+        >>> user = {"email": "user@example.com", "id": "123"}
+        >>> mask_user_email_partially(user)
+        >>> user["email"]
+        'use***@example.com'
+    """
+    for field_name in ["email", "mail"]:
+        if field_name not in user:
+            continue
+
+        value = user[field_name]  # pyright: ignore[reportUnknownVariableType]
+        if not isinstance(value, str) or "@" not in value:
+            continue
+
+        user[field_name] = mask_email_partially(value)
+
+
+def parameterize_request_urls(request: Request | dict[str, Any]) -> None:
+    """清理请求 URL 中的敏感查询参数
+
+    将 /api/endpoint?token=secret123 转换为 /api/endpoint (移除查询参数),
+    防止敏感信息泄露到事件中.
+
+    Args:
+        request: 请求数据字典 (符合 Sentry Request 结构)
+
+    Note:
+        - 此函数会原地修改传入的 request 字典
+        - 只有当 URL 包含敏感查询参数时才会修改
+        - 会同时移除 url 中的查询字符串和 query_string 字段
+
+    Example:
+        >>> request = {"url": "https://api.example.com/users?token=secret123", "query_string": "token=secret123"}
+        >>> parameterize_request_urls(request)
+        >>> request["url"]
+        'https://api.example.com/users'
+        >>> "query_string" in request
+        False
+    """
+    url = request.get("url", "")
+    if not isinstance(url, str):
+        return
+
+    for pattern in SENSITIVE_URL_PATTERNS:
+        if pattern.search(url):
+            _ = request.pop("query_string", None)
+            if "?" in url:
+                url = url.split("?")[0]
+                request["url"] = url
+            break
+
+
+def mask_string_partially(
+    value: str,
+    visible_prefix: int = 3,
+    visible_suffix: int = 0,
+    mask_char: str = "*",
+    min_mask_length: int = 3,
+) -> str:
+    """对字符串进行部分脱敏
+
+    Args:
+        value: 要脱敏的字符串
+        visible_prefix: 保留前缀的字符数
+        visible_suffix: 保留后缀的字符数
+        mask_char: 脱敏字符
+        min_mask_length: 最小脱敏字符数
+
+    Returns:
+        脱敏后的字符串
+
+    Example:
+        >>> mask_string_partially("1234567890", visible_prefix=3, visible_suffix=2)
+        '123*****90'
+        >>> mask_string_partially("abc", visible_prefix=3)
+        '***'
+    """
+    if len(value) <= visible_prefix + visible_suffix:
+        return mask_char * min_mask_length
+
+    masked_length = max(len(value) - visible_prefix - visible_suffix, min_mask_length)
+    prefix = value[:visible_prefix] if visible_prefix > 0 else ""
+    suffix = value[-visible_suffix:] if visible_suffix > 0 else ""
+    return prefix + (mask_char * masked_length) + suffix