ownasquare/patchscope

# PatchScope PatchScope 可将源代码转化为有据可查且具可操作性的审查结果。粘贴代码、上传源文件或 ZIP 压缩包，或输入公开的 GitHub pull request；PatchScope 会查找 bug、安全风险、性能问题和可读性问题，然后展示稳妥的重构预览。 它在本地运行，无需 API key。提交的代码将作为数据进行分析，绝不会被执行，也绝不会 PatchScope 被修改。  ## 三步开始 前置要求：Python 3.12 和 [uv](https://docs.astral.sh/uv/)。从克隆的代码库中执行： 1. 安装项目。 uv sync 2. 同时启动 API 和工作台。 uv run patchscope start 3. 打开 `http://127.0.0.1:8501`，选择 **Load example review**，然后选择 **Run review**。 此流程不需要 `.env` 文件或服务商凭证。在 PatchScope 运行期间，可通过 `http://127.0.0.1:8787/docs` 访问 API 参考文档。

使用标准的 Python 虚拟环境代替 uv

这将安装当前检出的代码；此处并未将 PatchScope 作为 PyPI 包提供。 ``` python3.12 -m venv .venv source .venv/bin/activate python -m pip install . patchscope start ``` 在 Windows PowerShell 中，使用 `.venv\Scripts\Activate.ps1` 激活环境。

使用 Docker 运行

``` docker compose up --build ``` 打开 `http://127.0.0.1:8501`。参考栈将审查结果存储在命名卷中，并将两个服务仅绑定到本地回环地址。

## 核心工作流 1. **选择代码** — 粘贴一个文件、上传源文件或有限的 ZIP 压缩包，或输入规范的公开 pull request URL。 2. **运行审查** — PatchScope 验证输入边界，然后在不执行提交代码的情况下运行可用的分析层。 3. **根据证据操作** — 检查与源代码关联的发现和仅用于预览的 diff，记录分类决策，并导出 Markdown 或 SARIF。 每一条发现都包含严重程度、类别、位置、证据、修复指导和分析器来源。PatchScope 绝不会将建议的修改写回提交的源代码中。 ### 输入与结果 | 输入 | 最适用于 | |---|---| | 粘贴的代码 | 单个重点文件或小型的复现用例 | | 源文件 | 单个本地实现文件 | | ZIP 压缩包 | 不运行仓库代码的、有限的多文件变更 | | 公开的 GitHub PR | 审查来自规范公开 pull request 的新增代码行 | 支持的源代码包括 Python、JavaScript、TypeScript、TSX、Java、Go、Rust、C/C++、C#、Kotlin、PHP、Ruby、Scala、Swift、shell 和 SQL，以及常见的标记和配置文件。Python 会接受额外的 Ruff 和 mypy 分析。其他语言使用可用的 Tree-sitter 结构、跨语言规则和可选的 Semgrep 覆盖范围；分析器的可用性始终会明确显示，而不会被视为测试通过。 ## 使用 CLI 运行免凭证示例或审查单个本地文件： ``` uv run patchscope demo uv run patchscope review examples/insecure_checkout.py uv run patchscope analyzers ``` 当需要机器可读的结果时，可向 `demo`、`review` 或 `analyzers` 添加 `--json`。 ## 可选的 AI 合成 PatchScope 的确定性审查无需凭证即可运行。仅在需要更改服务器端存储或分析限制、允许其他浏览器源，或选择加入服务商支持的合成时，才将 `.env.example` 复制为 `.env`。启动器的地址和端口是明确的命令选项；运行 `uv run patchscope start --help` 即可查看。 | 模式 | 行为 | |---|---| | `offline` | 仅进行本地解析、确定性规则和可用的静态分析器 | | `auto` | 仅在配置了 PatchScope 服务器端 key 时使用 OpenAI；否则保持离线状态 | | `openai` | 需要 server-side key，并且在合成无法运行时会明确报错 | 服务商的输出无法抹除确定性的发现，并且必须与提交的路径、行范围和确切的源证据相匹配。服务商上下文默认上限为 120,000 个字符，补全输出默认上限为 4,096 个 token；任何上下文截断都会被明确标记，且绝不会从最终审查中移除本地的静态发现。密钥仅属于 API 进程；浏览器客户端永远不需要它们。 Semgrep 也是可选的，并与应用程序环境隔离： ``` uv tool install "semgrep>=1.170,<2" ``` 使用 `patchscope analyzers` 查看哪些分析层可用。 ## 数据、隐私和部署边界 - SQLite 审查历史记录默认存储在 `.data/patchscope.db` 中。请将其视为敏感数据，因为它包含提交的源代码快照。仅用于检出的可选 PostgreSQL 设置及其限制记录在[架构指南](docs/architecture.md#optional-postgresql-storage)中。 - PatchScope 默认不执行任何遥测。 - 导入的源代码、测试、hooks、plugins、构建和包管理器永远不会被执行。 - 公开的 pull request 无需 token 即可工作。`PATCHSCOPE_GITHUB_TOKEN` 是一个可选的服务器端凭证，用于经过身份验证的 GitHub 读取；私有仓库的行为不属于受支持或经验证的 `0.1.x` 合约的一部分。 - 内置的服务器和 Compose 栈是本地单用户参考。它们不是经过强化的公开多用户托管配置；参考的 Compose 镜像使用 SQLite。 在处理敏感代码或将 PatchScope 改造为共享基础设施之前，请阅读[安全设计](docs/security.md)。 ## 扩展或集成 PatchScope 对分析器、发现、解析、重构预览、API schema 和持久化都有明确的合约。它刻意不在 runtime 加载第三方或归仓库所有的 plugins；扩展均属于经过审查的源代码变更。 - [扩展指南](docs/extending.md) — 添加分析器、规则、语言、重构或 API 字段 - [API 指南](docs/api.md) — 请求示例、路由、限制和导出 - [架构](docs/architecture.md) — 组件与信任边界 - [贡献](CONTRIBUTING.md) — 设置、测试和 pull request 预期 ## 帮助和项目政策 - [支持](SUPPORT.md)说明了在哪里提问以及应包含哪些诊断信息。 - [安全政策](SECURITY.md)说明了私有漏洞报告方式。 - [行为准则](CODE_OF_CONDUCT.md)设定了社区期望。 PatchScope 基于 [MIT 许可证](LICENSE) 提供。

标签：Kubernetes, SOC Prime, 云安全监控, 代码审查, 代码重构, 开发工具, 本地部署, 测试用例, 请求拦截, 逆向工具, 静态分析