Gabriel-Dakinah-Vincent/obfuscation-toolbox

# 混淆工具箱 [](https://pypi.org/project/obfuscation-toolbox/) [](https://pypi.org/project/obfuscation-toolbox/) [](https://opensource.org/licenses/MIT) [](https://pypi.org/project/obfuscation-toolbox/) 专业的 Python 代码混淆库，包含 12 种以上技术。利用业界标准的混淆方法保护您的源代码免受逆向工程。 ## 🚀 快速开始 ### 安装 ``` pip install obfuscation-toolbox ``` ### 基本用法 ``` from obfuscation_toolit import obfuscate, deobfuscate # 混淆字符串 code = "print('Hello, World!')" obfuscated = obfuscate('string', code, level=2) print(obfuscated) # Output: cHJpbnQoJ0hlbGxvLCBXb3JsZCEnKQ== # 反混淆还原 original = deobfuscate('string', obfuscated, level=2) print(original) # Output: print('Hello, World!') ``` ## 📚 目录 - [安装说明](#installation) - [可用方法](#available-methods) - [使用指南](#usage-guide) - [Python API](#python-api) - [命令行接口](#command-line-interface) - [教程：从入门到精通](#tutorial-beginner-to-advanced) - [实际应用场景](#real-world-scenarios) - [最佳实践](#best-practices) - [安全注意事项](#security-considerations) ## 🛠️ 可用方法 | 方法 | 描述 | 参数 | 可逆性 | |--------|-------------|------------|------------| | `string` | Base64 编码 | `level` (int): 编码迭代次数 | ✅ | | `hex` | 十六进制编码 | 无 | ✅ | | `xor` | XOR 密码加密 | `key` (int): XOR 密钥 | ✅ | | `variable` | 变量重命名 | `length` (int): 随机名称长度 | ⚠️ | | `function_rename` | 函数重命名 | `length` (int): 随机名称长度 | ⚠️ | | `class_rename` | 类重命名 | `length` (int): 随机名称长度 | ⚠️ | | `control_flow` | 哑代码注入 | `complexity` (int): 每行的哑代码行数 | ✅ | | `comment` | 注释注入 | `density` (int): 每行的注释数 | ✅ | | `minify` | 代码压缩 | 无 | ⚠️ | | `opaque_predicate` | 不透明谓词 | `complexity` (int): 谓词数量 | ✅ | | `dead_code` | 死代码插入 | `intensity` (int): 死代码行数 | ✅ | | `arithmetic` | 算术混淆 | 无 | ❌ | ⚠️ = 部分可逆 | ❌ = 不可逆 ## 📖 使用指南 ### Python API #### 基础混淆 ``` from obfuscation_toolit import obfuscate # 字符串编码 code = "password = 'secret123'" obfuscated = obfuscate('string', code, level=3) # 变量重命名 code = "username = 'admin'\npassword = 'pass'" obfuscated = obfuscate('variable', code, length=12) # XOR 加密 code = "API_KEY = 'abc123'" obfuscated = obfuscate('xor', code, key=255) ``` #### 组合多种技术 ``` from obfuscation_toolit import obfuscate code = """ def authenticate(username, password): if username == 'admin' and password == 'secret': return True return False """ # 步骤 1：重命名函数 code = obfuscate('function_rename', code, length=10) # 步骤 2：重命名变量 code = obfuscate('variable', code, length=8) # 步骤 3：添加控制流混淆 code = obfuscate('control_flow', code, complexity=2) # 步骤 4：添加死代码 code = obfuscate('dead_code', code, intensity=3) print(code) ``` #### 文件操作 ``` from obfuscation_toolit import obfuscate # 从文件读取 with open('script.py', 'r') as f: code = f.read() # 混淆 obfuscated = obfuscate('variable', code, length=10) # 写入新文件 with open('obfuscated_script.py', 'w') as f: f.write(obfuscated) ``` ### 命令行接口 #### 列出可用方法 ``` veil list ``` #### 直接混淆文本 ``` # 字符串编码 veil obfuscate string "print('hello')" --level 2 # XOR 加密 veil obfuscate xor "secret_data" --key 42 # 算术混淆 veil obfuscate arithmetic "x = 100" ``` #### 混淆文件 ``` # 基本文件混淆 veil obfuscate variable --input-file script.py --output-file obfuscated.py --length 10 # 控制流混淆 veil obfuscate control_flow --input-file app.py --output-file app_obf.py --complexity 3 # 死代码插入 veil obfuscate dead_code --input-file main.py --output-file main_obf.py --intensity 5 ``` #### 原地修改 ``` # 直接修改文件（谨慎使用！） veil obfuscate minify --input-file script.py --in-place ``` #### 反混淆文件 ``` # 反混淆字符串 veil deobfuscate string --input-file obfuscated.txt --output-file original.txt --level 2 # 反混淆 XOR veil deobfuscate xor --input-file encrypted.txt --in-place --key 42 ``` ## 🎓 教程：从入门到精通 ### Level 1：初级 - 简单字符串保护 **目标**：隐藏代码中的敏感字符串 ``` from obfuscation_toolit import obfuscate, deobfuscate # 包含敏感数据的原始代码 code = "API_KEY = 'sk_live_abc123xyz'" # 方法 1：Base64 编码（最简单） obfuscated = obfuscate('string', code, level=1) print("Base64:", obfuscated) # 方法 2：Hex 编码 obfuscated = obfuscate('hex', code) print("Hex:", obfuscated) # 方法 3：XOR 加密（更安全） obfuscated = obfuscate('xor', code, key=123) print("XOR:", obfuscated) # 需要时反混淆 original = deobfuscate('xor', obfuscated, key=123) print("Original:", original) ``` **应用场景**：保护 API 密钥、密码或配置字符串。 ### Level 2：中级 - 代码结构混淆 **目标**：通过重命名标识符增加代码理解难度 ``` from obfuscation_toolit import obfuscate # 原始可读代码 code = """ class UserManager: def __init__(self): self.users = [] def add_user(self, username, email): user = {'name': username, 'email': email} self.users.append(user) return True """ # 步骤 1：重命名类 step1 = obfuscate('class_rename', code, length=12) print("After class rename:") print(step1) # 步骤 2：重命名函数 step2 = obfuscate('function_rename', step1, length=10) print("\nAfter function rename:") print(step2) # 步骤 3：重命名变量 step3 = obfuscate('variable', step2, length=8) print("\nFinal obfuscated:") print(step3) ``` **应用场景**：在分发的 Python 应用程序中保护知识产权。 ### Level 3：高级 - 多层保护 **目标**：利用多种技术实现最大程度的混淆 ``` from obfuscation_toolit import obfuscate # 复杂业务逻辑 code = """ def calculate_price(base_price, discount, tax_rate): discounted = base_price * (1 - discount) final_price = discounted * (1 + tax_rate) return final_price result = calculate_price(100, 0.2, 0.15) print(result) """ # 第 1 层：算术混淆（隐藏数字） layer1 = obfuscate('arithmetic', code) print("Layer 1 - Arithmetic:") print(layer1) print() # 第 2 层：函数重命名 layer2 = obfuscate('function_rename', layer1, length=15) print("Layer 2 - Function rename:") print(layer2) print() # 第 3 层：变量重命名 layer3 = obfuscate('variable', layer2, length=12) print("Layer 3 - Variable rename:") print(layer3) print() # 第 4 层：控制流混淆 layer4 = obfuscate('control_flow', layer3, complexity=2) print("Layer 4 - Control flow:") print(layer4) print() # 第 5 层：死代码插入 layer5 = obfuscate('dead_code', layer4, intensity=3) print("Layer 5 - Dead code:") print(layer5) print() # 第 6 层：不透明谓词 final = obfuscate('opaque_predicate', layer5, complexity=2) print("Final obfuscated code:") print(final) ``` **应用场景**：保护专有算法、授权系统或反作弊机制。 ### Level 4：专家 - 自动化流水线 **目标**：创建可复用的混淆流水线 ``` from obfuscation_toolit import obfuscate import os class ObfuscationPipeline: def __init__(self): self.techniques = [] def add_technique(self, method, **params): self.techniques.append((method, params)) return self def process(self, code): result = code for method, params in self.techniques: result = obfuscate(method, result, **params) return result def process_file(self, input_path, output_path): with open(input_path, 'r') as f: code = f.read() obfuscated = self.process(code) with open(output_path, 'w') as f: f.write(obfuscated) print(f"Obfuscated {input_path} -> {output_path}") # 创建 pipeline pipeline = ObfuscationPipeline() pipeline.add_technique('arithmetic') pipeline.add_technique('function_rename', length=12) pipeline.add_technique('variable', length=10) pipeline.add_technique('control_flow', complexity=2) pipeline.add_technique('dead_code', intensity=3) # 处理单个文件 pipeline.process_file('app.py', 'app_obfuscated.py') # 处理整个目录 for filename in os.listdir('src'): if filename.endswith('.py'): input_path = os.path.join('src', filename) output_path = os.path.join('obfuscated', filename) pipeline.process_file(input_path, output_path) ``` **应用场景**：生产部署、CI/CD 集成、自动化构建。 ## 🌍 实际应用场景 ### 场景 1：保护 Web 爬虫 ``` from obfuscation_toolit import obfuscate code = """ import requests API_KEY = 'secret_key_12345' BASE_URL = 'https://api.example.com' def fetch_data(endpoint): headers = {'Authorization': f'Bearer {API_KEY}'} response = requests.get(f'{BASE_URL}/{endpoint}', headers=headers) return response.json() """ # 保护 API 密钥和 URL protected = obfuscate('xor', code, key=77) protected = obfuscate('function_rename', protected, length=10) protected = obfuscate('variable', protected, length=8) with open('scraper_protected.py', 'w') as f: f.write(protected) ``` ### 场景 2：许可证密钥验证 ``` from obfuscation_toolit import obfuscate code = """ def validate_license(key): valid_keys = ['ABC-123-XYZ', 'DEF-456-UVW'] return key in valid_keys def check_expiry(license_key): expiry_date = '2025-12-31' # validation logic return True """ # 许可逻辑的最大保护 protected = obfuscate('arithmetic', code) protected = obfuscate('function_rename', protected, length=15) protected = obfuscate('variable', protected, length=12) protected = obfuscate('control_flow', protected, complexity=3) protected = obfuscate('opaque_predicate', protected, complexity=3) protected = obfuscate('dead_code', protected, intensity=5) with open('license_validator.py', 'w') as f: f.write(protected) ``` ### 场景 3：配置文件保护 ``` from obfuscation_toolit import obfuscate, deobfuscate import json # 敏感配置 config = { 'database': 'postgresql://user:pass@localhost/db', 'secret_key': 'django-secret-key-xyz', 'api_keys': {'stripe': 'sk_live_abc', 'aws': 'AKIA123'} } # 转换为字符串并混淆 config_str = json.dumps(config) obfuscated = obfuscate('xor', config_str, key=199) # 保存混淆后的配置 with open('config.obf', 'w') as f: f.write(obfuscated) # 运行时加载并反混淆 with open('config.obf', 'r') as f: obfuscated_data = f.read() config_str = deobfuscate('xor', obfuscated_data, key=199) config = json.loads(config_str) print(config) ``` ### 场景 4：分发 Python 工具 ``` # 分发前混淆 veil obfuscate variable --input-file mytool.py --output-file mytool_dist.py --length 15 veil obfuscate control_flow --input-file mytool_dist.py --in-place --complexity 3 veil obfuscate dead_code --input-file mytool_dist.py --in-place --intensity 4 # 打包并分发 python setup.py sdist bdist_wheel ``` ## ✅ 最佳实践 ### 1. 选择合适的技术 ``` # 对于字符串和数据：使用 XOR 或 Base64 obfuscate('xor', sensitive_data, key=42) # 对于代码结构：使用重命名 obfuscate('variable', code, length=10) # 为了最大程度保护：组合多种技术 ``` ### 2. 安全保管混淆密钥 ``` # ❌ 错误：源代码中硬编码密钥 key = 42 obfuscated = obfuscate('xor', data, key=key) # ✅ 正确：从环境变量获取密钥 import os key = int(os.environ.get('OBFUSCATION_KEY', 42)) obfuscated = obfuscate('xor', data, key=key) ``` ### 3. 测试混淆后的代码 ``` # 始终验证混淆后的代码有效 original_code = "x = 5\nprint(x)" obfuscated = obfuscate('variable', original_code, length=8) # 测试执行 try: exec(obfuscated) print("✅ Obfuscated code works") except Exception as e: print(f"❌ Error: {e}") ``` ### 4. 版本控制策略 ``` # 将原始源代码保留在私有 repo 中 git add src/ # 为了公开发布进行混淆 veil obfuscate variable --input-file src/app.py --output-file dist/app.py --length 12 # 仅将混淆后的版本提交到公共 repo cd public-repo git add dist/ git commit -m "Release obfuscated version" ``` ### 5. 性能考量 ``` # 混淆会增加开销 - 衡量影响 import time original = "x = sum(range(1000))" obfuscated = obfuscate('arithmetic', original) start = time.time() exec(original) original_time = time.time() - start start = time.time() exec(obfuscated) obfuscated_time = time.time() - start print(f"Overhead: {(obfuscated_time/original_time - 1) * 100:.2f}%") ``` ### 6. 分层安全 ``` # 将混淆与其他安全措施结合 from obfuscation_toolit import obfuscate import hashlib code = "secret_algorithm()" # 第 1 层：混淆 obfuscated = obfuscate('variable', code, length=10) # 第 2 层：添加完整性检查 checksum = hashlib.sha256(obfuscated.encode()).hexdigest() # 第 3 层：如需要则加密 # 对敏感数据使用适当的加密库 ``` ### 7. 文档记录 ``` # 记录您的混淆策略 """ Obfuscation Strategy: - Technique: variable + control_flow + dead_code - Parameters: length=12, complexity=3, intensity=4 - Key storage: Environment variable OBFUSCATION_KEY - Deobfuscation: Not required for production - Last updated: 2024-01-15 """ ``` ## 🔒 安全注意事项 ### 重要警告 1. **混淆 ≠ 加密**：混淆提供的是晦涩性，而非密码学安全性 2. **可逆性**：只要投入足够精力，大多数技术都可以被逆向 3. **不适用于机密**：不要仅依赖混淆来保护敏感数据 4. **性能**：混淆会增加运行时开销 5. **维护**：混淆后的代码更难调试和维护 ### 何时使用混淆 ✅ **适用场景：** - 保护知识产权 - 增加逆向工程难度 - 隐藏业务逻辑 - 防篡改措施 - 许可证验证系统 ❌ **不适用场景：** - 存储密码（请使用适当的哈希算法） - 保护加密密钥（请使用密钥管理） - 保护 API Token（请使用环境变量） - 隐藏安全漏洞 ### 推荐的安全技术栈 ``` # 1. 对敏感数据进行适当加密 from cryptography.fernet import Fernet key = Fernet.generate_key() cipher = Fernet(key) encrypted = cipher.encrypt(b"sensitive_data") # 2. 使用混淆保护代码 from obfuscation_toolit import obfuscate obfuscated_code = obfuscate('variable', code, length=12) # 3. 使用环境变量进行配置 import os api_key = os.environ.get('API_KEY') # 4. 代码签名以保证完整性 # 使用 sigstore 或 GPG 等工具 ``` ## 📦 集成示例 ### CI/CD 流水线 (GitHub Actions) ``` name: Build and Obfuscate on: [push] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Install dependencies run: pip install veilbox - name: Obfuscate code run: | veil obfuscate variable --input-file src/app.py --output-file dist/app.py --length 12 - name: Upload artifact uses: actions/upload-artifact@v3 with: name: obfuscated-code path: dist/ ``` ### Pre-commit Hook ``` #!/bin/bash # .git/hooks/pre-commit veil obfuscate variable --input-file src/main.py --output-file dist/main.py --length 10 git add dist/main.py ``` ## 🤝 贡献 欢迎贡献代码！请先阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 📄 许可证 MIT 许可证 - 详情请参见 [LICENSE](LICENSE) 文件。 ## ⚠️ 免责声明 本工具仅用于教育和合法目的。用户需自行承担遵守适用法律法规的责任。混淆不得用于隐藏恶意代码或违反软件许可协议。 ## 🔗 资源 - [文档](https://github.com/yourusername/obfuscation-toolbox/wiki) - [问题追踪](https://github.com/yourusername/obfuscation-toolbox/issues) - [更新日志](CHANGELOG.md) ## 📋 详细技术参考 ### 1. 字符串混淆 (`string`) - **描述**：多层级 Base64 编码 - **参数**：`level` (int) - 编码迭代次数 - **应用场景**：隐藏字符串字面量 - **示例**：`obfuscate('string', "hello", level=2)` ### 2. 十六进制编码 (`hex`) - **描述**：十六进制编码 - **参数**：无 - **应用场景**：简单字符串编码 - **示例**：`obfuscate('hex', "hello")` ### 3. XOR 编码 (`xor`) - **描述**：使用自定义密钥的 XOR 密码 - **参数**：`key` (int) - XOR 密钥值 - **应用场景**：对称加密 - **示例**：`obfuscate('xor', "hello", key=42)` ### 4. 变量重命名 (`variable`) - **描述**：将所有变量重命名为随机字符串 - **参数**：`length` (int) - 随机名称的长度 - **应用场景**：隐藏变量名 - **示例**：`obfuscate('variable', "x = 5", length=10)` ### 5. 函数重命名 (`function_rename`) - **描述**：将所有函数重命名为随机字符串 - **参数**：`length` (int) - 随机名称的长度 - **应用场景**：隐藏函数名 - **示例**：`obfuscate('function_rename', "def test(): pass", length=10)` ### 6. 类重命名 (`class_rename`) - **描述**：将所有类重命名为随机字符串 - **参数**：`length` (int) - 随机名称的长度 - **应用场景**：隐藏类名 - **示例**：`obfuscate('class_rename', "class MyClass: pass", length=10)` ### 7. 控制流混淆 (`control_flow`) - **描述**：在代码行之间插入哑代码 - **参数**：`complexity` (int) - 每行对应的哑代码行数 - **应用场景**：干扰控制流分析 - **示例**：`obfuscate('control_flow', "x = 1", complexity=3)` ### 8. 注释注入 (`comment`) - **描述**：插入随机注释 - **参数**：`density` (int) - 每行的注释数量 - **应用场景**：为代码增加噪声 - **示例**：`obfuscate('comment', "x = 1", density=2)` ### 9. 代码压缩 (`minify`) - **描述**：移除空白字符和注释 - **参数**：无 - **应用场景**：减小代码体积 - **示例**：`obfuscate('minify', "x = 5\\ny = 10")` ### 10. 不透明谓词 (`opaque_predicate`) - **描述**：插入恒为真/假的条件 - **参数**：`complexity` (int) - 谓词数量 - **应用场景**：干扰静态分析 - **示例**：`obfuscate('opaque_predicate', "x = 1", complexity=2)` ### 11. 死代码插入 (`dead_code`) - **描述**：插入不可达代码 - **参数**：`intensity` (int) - 死代码行数 - **应用场景**：增加噪声和混淆 - **示例**：`obfuscate('dead_code', "x = 1", intensity=3)` ### 12. 算术混淆 (`arithmetic`) - **描述**：将数字替换为算术表达式 - **参数**：无 - **应用场景**：隐藏数字常量 - **示例**：`obfuscate('arithmetic', "x = 5")` ## 🔄 反混淆能力 ### 完全可逆 ✅ **这些技术可以完美还原原始代码：** 1. **String** - `deobfuscate('string', obfuscated, level=2)` 2. **Hex** - `deobfuscate('hex', obfuscated)` 3. **XOR** - `deobfuscate('xor', obfuscated, key=42)` (需要相同的密钥) 4. **Control Flow** - `deobfuscate('control_flow', obfuscated, complexity=2)` 5. **Comment** - `deobfuscate('comment', obfuscated, density=2)` 6. **Dead Code** - `deobfuscate('dead_code', obfuscated, intensity=3)` 7. **Opaque Predicates** - `deobfuscate('opaque_predicate', obfuscated, complexity=2)` 8. **Minify** - `deobfuscate('minify', obfuscated)` (恢复结构) ### 部分可逆 ⚠️ **这些技术需要相同的混淆器实例（不支持跨会话）：** 9. **Variable** - 需要带有映射关系的相同实例 10. **Function Rename** - 需要带有映射关系的相同实例 11. **Class Rename** - 需要带有映射关系的相同实例 ``` # 同会话反混淆示例 from obfuscation_toolit.techniques.variable import VariableObfuscator obfuscator = VariableObfuscator(length=10) obfuscated = obfuscator.obfuscate("x = 5") deobfuscated = obfuscator.deobfuscate(obfuscated) # Works! ``` ### 不可逆 ❌ 12. **Arithmetic** - 设计为不可逆（数字变为表达式） ``` # 算术是单向的 code = "x = 5" obfuscated = obfuscate('arithmetic', code) # 结果："x = (9 - 4)" 或类似 # 无法还原为原始的 "5" ```

标签：Base64编码, DNS 反向解析, DNS 解析, PyPI库, Python, TLS抓取, XOR加密, 二进制发布, 代码保护, 代码混淆, 函数重命名, 加密工具, 十六进制编码, 反逆向工程, 变量重命名, 开源工具, 文档结构分析, 无后门, 知识产权保护, 软件安全, 逆向工具, 静态分析防御