Contributing to Skill-Security-Scanner

December 29, 2025 · View on GitHub

感谢您对 Skill-Security-Scanner 项目的关注！我们欢迎并感激所有形式的贡献。

本贡献指南适用于由 WellAlly Technology 开发者发起的 Skill-Security-Scanner 项目。

🤝 如何贡献

报告问题

如果您发现了 bug 或有功能建议：

检查 Issues 确保问题尚未被报告
创建新 Issue，使用清晰的标题描述问题
在问题详情中提供：
- 复现步骤
- 预期行为
- 实际行为
- 环境信息（操作系统、Python 版本等）
- 相关日志或截图

Bug 报告模板：

**问题描述**
简要描述遇到的问题

**复现步骤**
1. 步骤一
2. 步骤二
3. 步骤三

**预期行为**
描述您期望发生的情况

**实际行为**
描述实际发生的情况

**环境信息**
- 操作系统: [例如 Windows 11, macOS 14, Ubuntu 22.04]
- Python 版本: [例如 Python 3.11.5]
- 项目版本: [例如 v1.0.0]

**附加信息**
日志、截图或其他有助于解决问题的信息

功能请求模板：

**功能描述**
简要描述您希望添加的功能

**问题描述**
这个功能解决什么问题？为什么需要它？

**建议的解决方案**
描述您认为如何实现这个功能

**替代方案**
描述您考虑过的其他替代解决方案

**附加信息**
其他有助于理解需求的信息

提交代码

开发环境设置

Fork 仓库

访问 https://github.com/huifer/skill-security-scan 并点击右上角的 Fork 按钮

克隆您的 Fork

git clone https://github.com/YOUR_USERNAME/skill-security-scan.git
cd skill-security-scan

安装开发依赖

# 创建虚拟环境（推荐）
python -m venv venv

# 激活虚拟环境
# Windows:
venv\Scripts\activate
# Linux/macOS:
source venv/bin/activate

# 安装开发依赖
pip install -e ".[dev]"

配置开发工具

# 安装 pre-commit hooks（可选）
pip install pre-commit
pre-commit install

开发流程

创建分支
```
git checkout -b feature/your-feature-name
# 或
git checkout -b fix/your-bug-fix
```
分支命名规范：
- feature/ - 新功能
- fix/ - Bug 修复
- docs/ - 文档更新
- refactor/ - 代码重构
- test/ - 测试相关
- chore/ - 构建/工具链相关
编写代码
- 遵循项目的代码风格指南
- 添加必要的注释
- 更新相关文档
- 为新功能添加测试

代码质量检查

# 格式化代码
black src/ tests/

# 检查代码规范
ruff check src/ tests/

# 类型检查
mypy src/

# 运行测试
pytest tests/

# 运行测试并生成覆盖率报告
pytest tests/ --cov=src --cov-report=html

提交更改
```
git add .
git commit -m "feat: add XYZ feature"
```
提交信息规范（使用 Conventional Commits）：
- feat: - 新功能
- fix: - Bug 修复
- docs: - 文档更新
- style: - 代码格式（不影响代码运行的变动）
- refactor: - 重构（既不是新增功能，也不是修复 bug）
- test: - 测试相关
- chore: - 构建过程或辅助工具的变动
示例：
```
feat: add support for custom rule directories
fix: resolve path resolution on Windows
docs: update installation instructions
```

推送到您的 Fork

git push origin feature/your-feature-name

创建 Pull Request

访问原始仓库的 Pull Requests 页面
点击 "New Pull Request"
选择您的分支
填写 PR 描述模板

Pull Request 模板：

## 变更描述
简要描述此 PR 的内容和目的

## 变更类型
- [ ] Bug 修复
- [ ] 新功能
- [ ] 代码重构
- [ ] 文档更新
- [ ] 性能优化
- [ ] 测试相关

## 相关 Issue
关联的相关 Issue (例如: Fixes #123)

## 测试计划
描述您如何测试这些变更

- [ ] 单元测试通过
- [ ] 手动测试完成
- [ ] 文档已更新

## 检查清单
- [ ] 代码遵循项目风格指南
- [ ] 已进行自我审查
- [ ] 添加了必要的注释
- [ ] 代码已通过所有检查（black, ruff, mypy）
- [ ] 已添加或更新测试
- [ ] 所有测试通过
- [ ] 没有引入新的警告
- [ ] 已更新相关文档

## 截图（如适用）
添加截图以展示变更效果

## 附加信息
其他审阅者需要了解的信息

代码审查

所有 Pull Request 需要通过以下审查：

自动检查
- CI/CD 管道测试
- 代码覆盖率检查
- 代码风格检查
人工审查
- 至少一位维护者审查批准
- 解决所有审查意见
- 确保所有讨论达成共识
合并
- 维护者会将您的 PR 合并入主分支
- 请保持耐心，我们会尽快处理

📝 代码规范

Python 代码风格

遵循 PEP 8 规范
使用 Black 进行代码格式化
使用 Ruff 进行代码检查
使用 MyPy 进行类型检查

文档规范

所有公共函数和类必须有 docstring

使用 Google 风格的 docstring

def scan_directory(path: str, recursive: bool = False) -> list:
    """
    扫描指定目录下的文件

    Args:
        path: 要扫描的目录路径
        recursive: 是否递归扫描子目录

    Returns:
        找到的文件列表

    Raises:
        ValueError: 如果路径不存在或不是目录
    """
    pass

更新相关文档（README, API 文档等）

测试规范

为新功能添加单元测试
测试覆盖率不应低于 80%

使用清晰的测试名称

def test_detect_network_exfiltration_with_malicious_url():
    """测试检测恶意 URL 的网络数据外泄"""
    # 测试代码
    pass

🎯 项目特定指南

添加新的安全规则

在 src/rules/ 中创建规则类
继承 SecurityRule 基类
在 config/rules.yaml 中添加规则配置
在 RulesFactory 中注册规则类
添加对应的测试用例

示例：

# src/rules/custom.py
from .base import SecurityRule

class CustomRule(SecurityRule):
    """自定义安全规则"""

    def __init__(self, config: dict):
        super().__init__(
            rule_id=config['id'],
            name=config['name'],
            severity=config['severity'],
            patterns=config['patterns'],
            description=config.get('description', '')
        )

添加新的报告格式

在 src/reporters/ 中创建报告类
实现报告生成逻辑
在 cli.py 中注册新格式

示例：

# src/reporters/custom.py
from .base import BaseReporter

class CustomReporter(BaseReporter):
    """自定义报告生成器"""

    def generate(self, report: dict) -> str:
        # 生成报告逻辑
        pass

国际化支持

在 src/i18n/ 对应语言的 YAML 文件中添加新条目
使用 _('翻译文本') 函数包裹需要翻译的文本
确保中英文翻译准确

📧 联系方式

如有任何问题：

GitHub Issues: https://github.com/huifer/skill-security-scan/issues
Email: huifer97@163.com
Website: https://www.wellally.tech/

📄 许可证

通过贡献代码，您同意您的贡献将根据项目的 MIT License 进行许可。

🙏 致谢

感谢所有为 Skill-Security-Scanner 项目做出贡献的开发者！

特别感谢 WellAlly Technology 对本项目的支持。

📚 资源

Happy Coding! 🚀