gion-week/Python-Security-Toolkit

# Python 安全工具包 关于 Python 应用于**防御性网络安全**的四阶段实践学习路径：网络侦察、日志分析、威胁情报以及 SIEM/SOAR 集成。 每个阶段都是一个**操作指南**，而不仅仅是一个产物：这是一个旨在通过实践来教授概念的项目。每个阶段的 README 都包含一个 *概念* 部分，解释理解代码所需的理论，以及一个 *已知限制* 部分，说明该工具不能做什么及其原因。即使不运行一行代码，也能学到知识。 参考目标是**蓝队 / 安全运营**。漏洞利用开发、攻击工具和规避技术不在本项目的范围内。 ## 阶段 | # | 项目 | 命令 | 教学内容 | 状态 | |---|---|---|---|---| | 1 | [port-scanner](01-port-scanner/README.md) | `sectoolkit port-scanner` | TCP 握手、端口状态、I/O 密集型并发、banner grabbing | 已完成 | | 2 | log-analyzer | `sectoolkit log-analyzer` | 真实日志解析、时间归一化、滑动窗口异常检测 | 待实现 | | 3 | ioc-enrichment | `sectoolkit ioc-enrichment` | 威胁情报 API 集成、速率限制、缓存、评分 | 待实现 | | 4 | siem-integration | `sectoolkit siem-integration` | 事件生命周期、自动分流、端到端集成 | 待实现 | ## 前置条件 - Python **3.11 或更高版本** - `git` ## 设置 ``` git clone https://github.com/gion-week/Python-Security-Toolkit.git cd Python-Security-Toolkit python -m venv .venv source .venv/bin/activate # Linux / macOS .venv\Scripts\Activate.ps1 # Windows PowerShell pip install -e ".[dev]" cp .env.example .env ``` 使用 `-e` (*可编辑*) 安装会注册指向源码的包，而不是复制它们：对代码的修改会立即生效，无需重新安装。这也是使得 `sectoolkit` 命令可用的原因，并且允许一个阶段导入另一个阶段的模块。 如果你不想安装任何东西，每个命令也可以通过在仓库根目录下执行 `python -m sectoolkit ...` 的形式来运行。 ### 依赖项存放在两个地方，这不是错误 | 文件 | 声明内容 | 用途 | |---|---|---| | `pyproject.toml` | **包**正常运行所需的依赖，带有最低版本限制 (`colorama>=0.4.6`) | 这是项目的契约：安装它的人至少必须拥有这些版本 | | `requirements.txt` | 精确的运行时**环境**，带有锁定的版本 (`colorama==0.4.6`) | 可重复性：重建项目测试时所用的环境 | | `requirements-dev.txt` | 用于开发和测试的精确环境 (`pytest`、`ruff` 及其传递依赖) | 确保 CI 和开发环境的可重复性 | 要使用该工具包，只需 `pyproject.toml` 即可。这两个 requirements 文件用于当你想要 *完全相同* 的环境，而不是一个等效的环境时。 ## 用法 ``` sectoolkit --help sectoolkit port-scanner --help ``` **全局** flag 适用于整个工具包，并且必须放在子命令名称之**前**；特定于工具的 flag 放在后面： ``` sectoolkit --quiet port-scanner 192.0.2.1 -p 22,80 # corretto sectoolkit port-scanner 192.0.2.1 -p 22,80 --quiet # errore ``` | 全局 Flag | 效果 | |---|---| | `--verbose` | 在 stderr 输出调试信息 | | `--quiet` | 仅在 stderr 输出警告和错误 | | `--version` | 工具包版本 | ### 输出通道 **数据输出到 stdout，诊断信息输出到 stderr。** 这正是使得管道可用的原因： ``` sectoolkit port-scanner 192.0.2.1 -p 1-1024 --format json | jq '.ports' ``` JSON 数据会被干净地传递给 `jq`，同时进度日志仍然在终端中可见。 ### 退出代码 | 代码 | 含义 | |---|---| | `0` | 执行成功 | | `1` | 执行错误（I/O、网络、缺少配置） | | `2` | 使用错误：参数无效 | | `3` | 阳性检测 —— **仅**在请求使用 `--exit-on-findings` 时 | 默认情况下，发现某些内容的分析被视为执行成功并返回 `0`。代码 `3` 适用于那些希望在出现结果时让 pipeline 失败的人。 ## 测试与代码质量 ``` pytest ruff check . ruff format --check . ``` `pytest` 运行所有阶段的测试套件。**没有任何测试会打开真实的网络连接**：外部调用总是被 mock 替代，因此该套件运行速度快、具有确定性，并且可以在没有网络的 CI 环境中运行。需要激活外部服务的测试被标记为 `@pytest.mark.integration`，并在默认执行中被排除。 每次推送和拉取请求时，CI 中都会运行同样的三项检查。 ## 真实示例 每个阶段都有一个 `esempi/` 文件夹，其中包含工具的真实执行记录：确切的命令、生成的输出、产生的文件以及每个案例所证明的分析。它们不是装饰性的截图，而是展示工具在不同情况下的行为的部分——包括那些什么都没发现的情况，这往往比其他情况更能教会我们一些东西。 → [阶段 1 示例](01-port-scanner/esempi/README.md) ## 仓库结构 ``` python-security-toolkit/ ├── pyproject.toml # metadata, dipendenze, config di ruff e pytest, entrypoint CLI ├── requirements.txt # ambiente runtime riproducibile ├── requirements-dev.txt # ambiente di sviluppo riproducibile ├── .env.example # variabili d'ambiente di tutte le fasi ├── sectoolkit/ # entrypoint CLI: solo dispatch, nessuna logica di dominio ├── tests/ # test di sectoolkit ├── 01-port-scanner/ # Fase 1: package, test, esempi, README └── CLAUDE.md # convenzioni e specifiche tecniche del progetto ``` 阶段文件夹带有数字前缀，以便直接从目录树中 readable 路径的顺序。它们不是 Python 包（以数字开头的名称不是有效的标识符）：包位于文件夹内部并使用下划线，因此 `01-port-scanner/port_scanner/` 被导入为 `port_scanner`。 ### 添加一个阶段 每个新阶段必须在 **四个** 位置进行声明，并且它们必须保持一致： | 位置 | 内容 | |---|---| | `pyproject.toml` → `[tool.setuptools.packages.find]` | `where` 中的文件夹，`include` 中的包 | | `pyproject.toml` → `[tool.ruff] src` | 文件夹，否则 isort 会将该包视为第三方库 | | `pyproject.toml` → `[tool.pytest.ini_options] testpaths` | 测试文件夹 | | `sectoolkit/cli.py` → `_PHASE_CLI_MODULES` | 该阶段的 `cli` 模块 | 修改 `packages.find` 后，需要执行 `pip install -e ".[dev]"` 才能使新包可导入：可编辑安装会注册在安装时找到的包。 ## 许可证 MIT — 见 [LICENSE](LICENSE)。

标签：BurpSuite集成, Python, SIEM/SOAR, 动态分析, 威胁情报, 安全规则引擎, 开发者工具, 插件系统, 教程, 文档结构分析, 无后门, 网络安全, 逆向工具, 隐私保护