一款高精度静态分析工具，集死代码检测、安全漏洞扫描和 AI 代码防护于一体，支持 Python、TypeScript 和 Go，可快速集成到 CI/CD 流程中作为 PR 质量门禁。
Skylos: Dead Code and Security PR Gate for Modern Codebases
Find dead code, secrets, and exploitable flows in Python, TypeScript, and Go. Add a pull request gate in minutes.
[](https://codecov.io/gh/duriantaco/skylos)
[](https://discord.gg/Ftn9t9tErf)
📖 **[网站](https://skylos.dev)** · **[文档](https://docs.skylos.dev)** · **[博客](https://skylos.dev/blog)** · **[VS Code 扩展](https://marketplace.visualstudio.com/items?itemName=oha.skylos-vscode-extension)**
# 什么是 Skylos？
Skylos 是一款优先本地运行的扫描器，支持 Python、TypeScript 和 Go，帮助团队在死代码、敏感信息泄露和可利用漏洞流入 `main` 分支之前将其捕获。
其核心用例非常直接：在本地运行，将其添加到 CI 中，并利用 GitHub 注释和审查评论对 PR 进行基于真实发现的门控。高级功能如 AI 防御、修复 Agent、VS Code、MCP 和云端上传均已提供，但您不需要这些功能即可从 Skylos 中获得价值。
### 从这里开始
| 目标 | 命令 | 获得内容 |
|:---|:---|:---|
| **扫描仓库** | `skylos . -a` | 死代码、风险流程、敏感信息以及代码质量发现 |
| **门控 Pull Request** | `skylos cicd init` | 一个具备质量门控和内联注释的 GitHub Actions 工作流 |
| **审计 LLM 应用** | `skylos defend .` | 针对Python LLM集成的可选 AI 防御检查 |
### 团队为何选择它
1. **针对真实框架提供更好的死代码信号：** Skylos 理解 FastAPI、Django、Flask、pytest、Next.js、React 等，因此动态代码产生的噪音更少。
2. **一个工作流代替三个工具：** 死代码检测、安全扫描和 PR 门控共存于同一个 CLI 和 CI 流程中。
3. **默认优先本地：** 您可以将扫描保留在本地机器上，并在以后需要时添加可选的 AI 或云功能。
### 为什么选择 Skylos 而不是 Vulture？
| | Skylos | Vulture |
|:---|:---|:---|
| **召回率** | **98.1%** (51/52) | 84.6% (44/52) |
| **误报** | **220** | 644 |
| **框架感知** (FastAPI, Django, pytest) | 是 | 否 |
| **安全扫描** (敏感信息, SQLi, SSRF) | 是 | 否 |
| **AI 驱动分析** | 是 | 否 |
| **CI/CD 质量门控** | 是 | 否 |
| **TypeScript + Go 支持** | 是 | 否 |
### 🚀 **Skylos 新手？从 CI/CD 集成开始**
```
# 30 秒生成 GitHub Actions 工作流
skylos cicd init
# 提交并推送以激活
git add .github/workflows/skylos.yml && git push
```
**您将获得：**
- 对每个 PR 进行自动死代码检测
- 安全漏洞扫描（SQLi、敏感信息、危险模式）
- 在出现严重问题时中断构建的质量门控
- 带有 file:line 链接的内联 PR 审查评论
- 在 "Files Changed" 标签页中可见的 GitHub 注释
**无需配置** - 开箱即用，具备合理的默认设置。有关自定义设置，请参阅 [CI/CD 部分](#cicd)。
## 目录
- [什么是 Skylos？](#what-is-skylos)
- [快速开始](#quick-start)
- [核心能力](#key-capabilities)
- [安装](#installation)
- [Skylos 与 Vulture 对比](#skylos-vs-vulture-benchmark)
- [使用 Skylos 的项目](#projects-using-skylos)
- [工作原理](#how-it-works)
- [高级工作流](#advanced-workflows)
- [CI/CD](#cicd)
- [MCP Server](#mcp-server)
- [基线追踪](#baseline-tracking)
- [门控](#gating)
- [VS Code 扩展](#vs-code-extension)
- [集成与生态](#integration-and-ecosystem)
- [审计与精度](#auditing-and-precision)
- [覆盖率集成](#coverage-integration)
- [过滤](#filtering)
- [CLI 选项](#cli-options)
- [常见问题](#faq)
- [限制与故障排除](#limitations-and-troubleshooting)
- [贡献](#contributing)
- [路线图](#roadmap)
- [许可证](#license)
- [联系方式](#contact)
## 快速开始
如果您正在评估 Skylos，请从下面的核心工作流开始。LLM 和 AI 防御命令是可选的。
### 核心工作流
| 目的 | 命令 | 结果 |
| :--- | :--- | :--- |
| **首次扫描** | `skylos .` | 带置信度评分的死代码发现 |
| **审计风险与质量** | `skylos . -a` | 死代码、风险流程、敏感信息、质量及 SCA 发现 |
| **更高置信度的死代码** | `skylos . --trace` | 将静态发现与运行时活动进行交叉验证 |
| **仅审查更改的行** | `skylos . --diff origin/main` | 将发现集中在当前工作而非遗留债务上 |
| **本地门控** | `skylos --gate` | 在代码离开您的机器之前根据发现中断 |
| **设置 CI/CD** | `skylos cicd init` | 在 30 秒内生成一个 GitHub Actions 工作流 |
| **CI 中门控** | `skylos cicd gate --input results.json` | 当问题超过阈值时中断构建 |
### 可选工作流
| 目的 | 命令 | 结果 |
| :--- | :--- | :--- |
| **检测未使用的 Pytest Fixture** | `skylos . --pytest-fixtures` | 在测试文件 + conftest 中查找未使用的 `@pytest.fixture` |
| **AI 驱动分析** | `skylos agent analyze . --model gpt-4.1` | 静态优先分析，加上 judge-all LLM 死代码验证 |
| **死代码验证** | `skylos agent verify . --model gpt-4.1` | 仅针对死代码的第二轮检查：由 LLM 审查静态发现 |
| **AI 审计** | `skylos agent security-audit .` | 深度 LLM 审查，支持交互式文件选择 |
| **自动修复** | `skylos agent remediate . --auto-pr` | 扫描、修复、测试并开启 PR —— 端到端完成 |
| **PR 审查** | `skylos agent review` | 仅分析 git 变更的文件 |
| **PR 审查 (JSON)** | `skylos agent review . --model claude-sonnet-4-20250514 --format json -o results.json` | LLM 审查，提供代码级修复建议 |
| **本地 LLM** | `skylos agent analyze . --base-url http://localhost:11434/v1 --model codellama` | 使用 Ollama/LM Studio（无需 API key） |
| **PR 审查 (CI)** | `skylos cicd review -i results.json` | 在 PR 上发布内联评论 |
| **AI 防御：发现** | `skylos discover .` | 映射代码库中的所有 LLM 集成 |
| **AI 防御：防御** | `skylos defend .` | 检查 LLM 集成是否缺少防护栏 |
| **AI 防御：CI 门控** | `skylos defend . --fail-on critical --min-score 70` | 阻断存在严重 AI 防御缺陷的 PR |
| **白名单** | `skylos whitelist 'handle_*'` | 抑制已知的动态模式 |
### 演示
[](https://www.youtube.com/watch?v=BjMdSP2zZl8)
备用 (GitHub): https://github.com/duriantaco/skylos/discussions/82
## 核心能力
核心产品是死代码检测、安全扫描和 PR 门控。下面列出的 AI 重点关注功能是在该基准工作流之上的可选层。
### 安全扫描 (SAST)
* **污点分析：** 追踪从 API 端点到数据库的不可信输入，以防止 SQL 注入和 XSS。
* **敏感信息检测：** 在提交前搜寻硬编码的 API 密钥（AWS、Stripe、OpenAI）和私有凭证。
* **漏洞检查：** 标记危险模式，如 `eval()`、不安全的 `pickle` 和弱加密。
### AI 生成代码防护栏
Skylos 还可以标记常见的 AI 生成代码错误。每个发现都包含 `vibe_category` 和 `ai_likelihood`（高/中/低）元数据，以便您可以根据需要单独过滤它们。
* **幽灵调用检测：** 捕获对从未定义或导入的安全函数（`sanitize_input`、`validate_token`、`check_permission` 等）的调用 —— AI 经常臆造这些。`hallucinated_reference, high`
* **幽灵装饰器检测：** 捕获从未定义或导入的安全装饰器（`@require_auth`、`@rate_limit`、`@authenticate` 等）。`hallucinated_reference, high`
* **未完成的生成：** 检测仅包含 `pass`、`...` 或 `raise NotImplementedError` 的函数 —— AI 生成的存根在生产环境中静默地什么都不做。`incomplete_generation, medium`
* **未定义配置：** 标记引用了项目中从未定义的功能标志的 `os.getenv("ENABLE_X")`。`ghost_config, medium`
* **过时 Mock 检测：** 捕获 `mock.patch("app.email.send_email")`，其中 `send_email` 已不存在 —— AI 重命名了函数但保留了指向旧名称的测试。`stale_reference, medium`
* **安全 TODO 扫描器：** 标记 AI 留下的且无人完成的 `# TODO: add auth` 占位符。
* **禁用的安全控制：** 检测 `verify=False`、`@csrf_exempt`、`DEBUG=True` 和 `ALLOWED_HOSTS=["*"]`。
* **凭证与随机性检查：** 捕获硬编码密码和用于安全敏感值（如 token 和 OTP）的 `random.choice()`。
### 提示注入与内容扫描
这些检查在 `--danger` 下运行，查找仓库内容中的提示注入模式或混淆指令。
* **多文件提示注入扫描器：** 扫描 Python、Markdown、YAML、JSON、TOML 和 `.env` 文件中的隐藏指令负载 —— 指令覆盖（"ignore previous instructions"）、角色劫持、针对 AI 的抑制（"do not flag"、"skip security"）、数据外泄提示以及针对 AI 的短语。
* **文本规范化引擎：** NFKC 规范化、空白折叠和易混淆字符替换在模式匹配前中和混淆。
* **零宽与不可见 Unicode：** 检测零宽空格、连接符、BOM 和双向覆盖（U+200B–U+202E），这些对人类审查者隐藏了负载。
* **Base64 混淆检测：** 自动解码 base64 编码的字符串并重新扫描注入内容。
* **同形字/混合脚本检测：** 标记与拉丁文本混合的西里尔文和希腊文字符（例如 `password` 中的西里尔字母 'а'），这些会绕过视觉审查。
* **位置感知严重性：** README 文件、HTML 注释和 YAML 提示字段中的发现会提升严重性。测试文件会自动跳过。
### 高级：针对 LLM 应用的 AI 防御
针对 AI 应用安全的静态分析，映射 Python 代码库中的每个 LLM 调用并检查缺失的防护栏。**仅支持 Python**（计划支持 TypeScript/Go）。
```
# 探索所有 LLM 集成
skylos discover .
# 检查防御并获得评分报告
skylos defend .
# CI 关卡：出现严重缺口时失败，要求 70% 的防御分数
skylos defend . --fail-on critical --min-score 70
# 用于仪表板和流水线的 JSON 输出
skylos defend . --json -o defense-report.json
# 按 OWASP LLM Top 10 类别筛选
skylos defend . --owasp LLM01,LLM04
```
**涵盖防御和运维的 13 项检查：**
| 检查项 | 严重性 | OWASP | 检测内容 |
|:---|:---|:---|:---|
| `no-dangerous-sink` | Critical | LLM02 | LLM 输出流向 eval/exec/sub |
| `untrusted-input-to-prompt` | Critical | LLM01 | 提示词中包含原始用户输入且无处理 |
| `tool-scope` | Critical | LLM04 | Agent 工具包含危险的系统调用 |
| `tool-schema-present` | Critical | LLM04 | Agent 工具缺少类型化 schema |
| `output-validation` | High | LLM02 | LLM 输出在使用前未经过结构化验证 |
| `prompt-delimiter` | High | LLM01 | 提示词中的用户输入缺少分隔符 |
| `rag-context-isolation` | High | LLM01 | RAG 上下文注入时未隔离 |
| `output-pii-filter` | High | LLM06 | 面向用户的 LLM 输出无 PII 过滤 |
| `model-pinned` | Medium | LLM03 | 模型版本未固定（浮动别名） |
| `input-length-limit` | Low | LLM01 | LLM 调用前无输入长度检查 |
| `logging-present` | Medium | Ops | LLM 调用周围无日志记录 |
| `cost-controls` | Medium | Ops | LLM 调用未设置 max_tokens |
| `rate-limiting` | Medium | Ops | LLM 端点无速率限制 |
**防御和运维评分分开追踪** —— 添加日志不会抬高您的安全评分。
**通过 `skylos-defend.yaml` 进行自定义策略：**
```
rules:
model-pinned:
severity: critical # Upgrade severity
input-length-limit:
enabled: false # Disable check
gate:
min_score: 70
fail_on: high
```
支持 OpenAI, Anthropic, Google Gemini, Cohere, Mistral, Ollama, Together AI, Groq, Fireworks, Replicate, LiteLLM, LangChain, LlamaIndex, CrewAI, 和 AutoGen。
### 死代码检测与清理
* **查找未使用代码：** 识别不可达函数、孤立类和未使用的导入，并提供置信度评分。
* **智能追踪：** 区分真正的死代码和动态框架（Flask/Django 路由, Pytest fixture）。
* **安全修剪：** 使用 LibCST 安全地移除死代码而不破坏语法。
### 高级：Agent、审查和修复
* **上下文感知审计：** 结合静态分析的速度与 LLM 推理来验证发现并过滤噪音。
* **修复工作流：** `skylos agent remediate` 可以扫描、生成修复、运行测试并选择性地开启 PR。
* **本地模型支持：** 如果您希望代码保留在本地机器上，支持 Ollama 和其他兼容 OpenAI 的本地端点。
### CI/CD 与 PR 门控
* **30 秒工作流设置：** `skylos cicd init` 生成具有合理默认值的 GitHub Actions 工作流。
* **差异感知强制执行：** 仅门控更改的行，根据严重性阈值中断，并通过基线管理遗留债务。
* **PR 原生反馈：** GitHub 注释、内联审查评论和可选的仪表板上传，将发现保留在团队已经工作的位置。
### 安全清理与工作流控制
* **CST 安全移除：** 使用 LibCST 移除选定的导入或函数（处理多行导入、别名、装饰器、async 等）
* **逻辑感知：** 对 Python 框架和 TypeScript (Tree-sitter) 的深度集成，以识别活跃路由和依赖关系。
* **细粒度过滤：** 跳过标记有 `# pragma: no skylos`、`# pragma: no cover` 或 `# noqa` 的行
### 运维治理与运行时
* **覆盖率集成：** 自动检测 `.skylos-trace` 文件以用运行时数据验证死代码
* **质量门控：** 通过 `pyproject.toml` 执行复杂度、嵌套和安全风险的硬阈值，以阻断不合规的 PR
* **交互式 CLI：** 通过基于 `inquirer` 的终端界面手动验证和移除/注释发现
* **安全审计模式：** 利用独立的推理循环识别安全漏洞
### Pytest 卫生
* **未使用 Fixture 检测：** 在 `test_*.py` 和 `conftest.py` 中查找未使用的 `@pytest.fixture` 定义
* **跨文件解析：** 追踪跨模块使用的 fixture，而不仅仅是在同一文件内
### 多语言支持
| 语言 | 解析器 | 死代码 | 安全 | 质量 |
|----------|--------|-----------|----------|---------|
| Python | AST | ✅ | ✅ | ✅ |
| TypeScript/TSX | Tree-sitter | ✅ | ✅ | ✅ |
| Go | Standalone binary | ✅ | - | - |
无需 Node.js —— TypeScript 解析器通过 Tree-sitter 内置。语言通过文件扩展名自动检测。混合语言仓库（如 Python + TypeScript）开箱即用。
#### TypeScript 规则
| 规则 | ID | 捕获内容 |
|------|-----|-----------------|
| **死代码** | | |
| Functions | - | 未使用的函数、箭头函数和重载 |
| Classes | - | 未使用的类、接口、枚举和类型别名 |
| Imports | - | 未使用的命名、默认和命名空间导入 |
| Methods | - | 未使用的方法（生命周期方法除外） |
| **安全** | | |
| eval() | SKY-D201 | `eval()` 使用 |
| Dynamic exec | SKY-D202 | `exec()`, `new Function()`, `setTimeout` 使用字符串 |
| XSS | SKY-D226 | `innerHTML`, `outerHTML`, `document.write()`, `dangerouslySetInnerHTML` |
| SQL injection | SKY-D211 | SQL 查询中的模板字面量 / f-string |
| Command injection | SKY-D212 | `child_process.exec()`, `os.system()` |
| SSRF | SKY-D216 | `fetch()`/`axios` 使用变量 URL |
| Open redirect | SKY-D230 | `res.redirect()` 使用变量参数 |
| Weak hash | SKY-D207/D208 | MD5 / SHA1 使用 |
| Prototype pollution | SKY-D510 | `__proto__` 访问 |
| Dynamic require | SKY-D245 | `require()` 使用变量参数 |
| JWT bypass | SKY-D246 | `jwt.decode()` 无验证 |
| CORS wildcard | SKY-D247 | `cors({ origin: '*' })` |
| Internal URL | SKY-D248 | 硬编码的 `localhost`/`127.0.0.1` URL |
| Insecure random | SKY-D250 | `Math.random()` 用于安全敏感操作 |
| Sensitive logs | SKY-D251 | 密码/token 传递给 `console.log()` |
| Insecure cookie | SKY-D252 | 缺少 `httpOnly`/`secure` 标志 |
| Timing attack | SKY-D253 | 使用 `===`/`==` 比较机密信息 |
| Storage tokens | SKY-D270 | `localStorage`/`sessionStorage` 中的敏感数据 |
| Error disclosure | SKY-D271 | HTTP 响应中发送 `error.stack`/`.sql` |
| Secrets | SKY-S101 | 硬编码 API 密钥 + 高熵字符串 |
| **质量** | | |
| Complexity | SKY-Q301 | 圈复杂度超过阈值 |
| Nesting depth | SKY-Q302 | 嵌套层级过多 |
| Function length | SKY-C304 | 函数超过行数限制 |
| Too many params | SKY-C303 | 函数参数过多 |
| Duplicate condition | SKY-Q305 | if-else-if 链中有相同条件 |
| Await in loop | SKY-Q402 | for/while 循环中有 `await` |
| Unreachable code | SKY-UC002 | return/throw/break/continue 后的代码 |
**框架感知：** Next.js 约定导出（`page.tsx`、`layout.tsx`、`route.ts`、`middleware.ts`）、配置导出（`getServerSideProps`、`generateMetadata`、`revalidate`）、React 模式（`memo`、`forwardRef`）和导出的自定义 hook（`use*`）会自动从死代码报告中排除。
TypeScript 死代码检测追踪：回调、类型注释、泛型、装饰器、继承（`extends`）、对象简写、展开、重新导出和 `typeof` 引用。基准测试显示在存活代码上具有 95% 的召回率和 0 个误报。
## 安装
### 基础安装
```
## 从 pypi
pip install skylos
## 或从源码
git clone https://github.com/duriantaco/skylos.git
cd skylos
pip install .
```
### 🎯 接下来做什么？
安装后，我们建议：
1. **设置 CI/CD（30 秒）：**
skylos cicd init
git add .github/workflows/skylos.yml && git push
这将自动扫描每个 PR 以查找死代码和安全问题。
2. **运行您的第一次扫描：**
skylos . # 仅死代码
skylos . --danger --secrets # 包含安全检查
3. **保持扫描集中在当前工作上：**
skylos . --diff origin/main
4. **仅在需要时尝试高级工作流：**
skylos agent review . --model gpt-4.1
skylos defend .
[在快速开始表中查看所有命令](#quick-start)
## Skylos 与 Vulture 基准测试
我们在 GitHub 上 **9 个最受欢迎的 Python 仓库** 上对 Skylos 和 Vulture 进行了基准测试 —— 合计 35 万+ star，涵盖 HTTP 客户端、Web 框架、CLI 工具、数据验证、终端 UI 和进度条。每一个发现都经过与源代码的**人工验证**。没有自动标记，没有挑选数据。
### 为什么是这 9 个仓库？
我们特意选择了以不同方式对死代码检测进行压力测试的项目：
| 仓库 | Stars | 测试内容 |
|:---|---:|:---|
| [psf/requests](https://github.com/psf/requests) | 53k | `__init__.py` 重新导出、Sphinx conf、pytest 类 |
| [pallets/click](https://github.com/pallets/click) | 17k | IO 协议方法（`io.RawIOBase` 子类）、nonlocal 闭包 |
| [encode/starlette](https://github.com/encode/starlette) | 10k | ASGI 接口参数、多态分发、公共 API 方法 |
| [Textualize/rich](https://github.com/Textualize/rich) | 51k | `__rich_console__` 协议、通过 `f_locals` 的哨兵变量、元类 |
| [encode/httpx](https://github.com/encode/httpx) | 14k | Transport/auth 协议方法、零死代码（纯 FP 测试） |
| [pallets/flask](https://github.com/pallets/flask) | 69k | Jinja2 模板全局变量、Werkzeug 协议方法、扩展钩子 |
| [pydantic/pydantic](https://github.com/pydantic/pydantic) | 23k | Mypy 插件钩子、hypothesis `@resolves`、`__getattr__` 配置 |
| [fastapi/fastapi](https://github.com/fastapi/fastapi) | 82k | 100+ OpenAPI 规范模型字段、Starlette 基类覆盖 |
| [tqdm/tqdm](https://github.com/tqdm/tqdm) | 30k | Keras/Dask 回调、Rich 列渲染、pandas monkey-patching |
没有仓库因为结果不利而被排除。我们包括了 Vulture 击败 Skylos 的仓库。
### 结果
| 仓库 | 死代码项 | Skylos TP | Skylos FP | Vulture TP | Vulture FP |
|:---|---:|---:|---:|---:|---:|
| psf/requests | 6 | 6 | 35 | 6 | 58 |
| pallets/click | 7 | 7 | 8 | 6 | 6 |
| encode/starlette | 1 | 1 | 4 | 1 | 2 |
| Textualize/rich | 13 | 13 | 14 | 10 | 8 |
| encode/httpx | 0 | 0 | 6 | 0 | 59 |
| pallets/flask | 7 | 7 | 12 | 6 | 260 |
| pydantic/pydantic | 11 | 11 | 93 | 10 | 112 |
| fastapi/fastapi | 6 | 6 | 30 | 4 | 102 |
| tqdm/tqdm | 1 | 0 | 18 | 1 | 37 |
| **Total** | **52** | **51** | **220** | **44** | **644** |
| 指标 | Skylos | Vulture |
|:---|:---|:---|
| **Recall** | **98.1%** (51/52) | 84.6% (44/52) |
| **False Positives** | **220** | 644 |
| **Dead items found** | **51** | 44 |
Skylos 比 Vulture **多发现 7 个死代码项**，且**误报减少 3 倍**。
### 为什么 Skylos 产生的误报更少
Vulture 使用扁平名称匹配 —— 如果裸名 `X` 作为字符串或标识符出现在任何地方，名为 `X` 的定义都被视为已使用。这对简单情况有效，但在框架密集型代码库中会淹没在噪音中：
- **Flask**（260 Vulture FP）：Vulture 标记每个 Jinja2 模板全局变量、Werkzeug 协议方法和 Flask 扩展钩子。Skylos 识别 Flask/Werkzeug 模式。
- **Pydantic**（112 Vulture FP）：Vulture 标记所有配置类注释、`TYPE_CHECKING` 导入和 mypy 插件钩子。Skylos 理解 Pydantic 模型字段和 `__getattr__` 动态访问。
- **FastAPI**（102 Vulture FP）：Vulture 标记 100+ OpenAPI 规范模型字段（Pydantic `BaseModel` 属性如 `maxLength`、`exclusiveMinimum`）。Skylos 将这些识别为 schema 定义。
- **httpx**（59 Vulture FP）：Vulture 标记每个 transport 和 auth 协议方法。Skylos 抑制接口实现。
### Skylos 仍然落后的地方（老实说）
- **click**（8 vs 6 FP）：`io.RawIOBase` 子类上的 IO 协议方法（`readable`、`readinto`） —— 由 Python 的 IO 栈调用，而不是由直接调用站点调用。
- **starlette**（4 vs 2 FP）：跨文件的实例方法调用（`obj.method()`）未解析回类定义。
- **tqdm**（18 vs 37 FP, 0 vs 1 TP）：Skylos 漏掉了 `__init__.py` 中的 1 个死函数，因为它将 `__init__.py` 定义抑制为潜在的重新导出。
### Skylos 与 Knip (TypeScript) 对比
我们还在一个真实的 TypeScript 库上对 Skylos 和 [Knip](https://knip.dev) 进行了基准测试：
| | [unjs/consola](https://github.com/unjs/consola) (7k stars, 21 files, ~2,050 LOC) |
|:---|:---|
| **Dead items** | 4 (整个孤立的 `src/utils/format.ts` 模块) |
| 指标 | Skylos | Knip |
|:---|:---|:---|
| **Recall** | **100%** (4/4) | **100%** (4/4) |
| **Precision** | **36.4%** | 7.5% |
| **F1 Score** | **53.3%** | 14.0% |
| **Speed** | **6.83s** | 11.08s |
两个工具都找到了所有死代码。Skylos 具有 **~5 倍更好的精度** —— Knip 错误地将包入口点标记为死文件（其 `package.json` 导出指向 `dist/` 而非 `src/`）并将公共 API 重新导出报告为未使用。
## 使用 Skylos 的项目
如果您在公共仓库中使用 Skylos，请开启一个 issue 并在此添加。此列表基于自我提交，因此在更多团队公开加入之前，它将保持较少。
[](https://github.com/duriantaco/skylos)
| 项目 | 描述 |
|---------|-------------|
| [Skylos](https://github.com/duriantaco/skylos) | 在自身上使用 Skylos 进行死代码检测、安全和 CI 门控 |
| *在此添加您的项目* | [添加您的](https://github.com/duriantaco/skylos/issues/new?title=Add%20my%20project%20to%20showcase&body=Project:%20%0AURL:%20%0ADescription:%20) |
[添加您的项目 →](https://github.com/duriantaco/skylos/issues/new?title=Add%20my%20project%20to%20showcase&body=Project:%20%0AURL:%20%0ADescription:%20)
## 工作原理
Skylos 为您的整个代码库构建引用图 —— 谁定义了什么，谁调用了什么，跨所有文件。
```
Parse all files -> Build definition map -> Track references -> Find orphans (zero refs = dead)
```
### 高精度与置信度评分
静态分析通常难以应对 Python 的动态特性（例如 `getattr`、`pytest.fixture`）。Skylos 通过以下方式最大限度地减少误报：
1. **置信度评分：** 对发现进行分级（高/中/低），以便您只看到重要的内容。
2. **混合验证：** 在报告之前使用 LLM 推理双重检查静态发现。
3. **运行时追踪：** 可选的 `--trace` 模式根据实际运行时执行验证“死”代码。
| 置信度 | 含义 | 操作 |
|------------|---------|--------|
| 100 | 确定未使用 | 可以安全删除 |
| 60 | 可能未使用（默认阈值） | 先审查 |
| 40 | 也许未使用（框架助手） | 可能是误报 |
| 20 | 可能未使用（装饰器/路由） | 几乎肯定被使用 |
| 0 | 显示所有 | 调试模式 |
```
skylos . -c 60 # Default: high-confidence findings only
skylos . -c 30 # Include framework helpers
skylos . -c 0 # Everything
```
### 框架检测
当 Skylos 看到 Flask、Django、FastAPI、Next.js 或 React 导入时，它会自动调整评分：
| 模式 | 处理方式 |
|---------|----------|
| `@app.route`, `@router.get` | 入口点 → 标记为已使用 |
| `@pytest.fixture` | 视为 pytest 入口点，但如果从未引用则可报告为未使用 |
| `@celery.task` | 入口点 → 标记为已使用 |
| `getattr(mod, "func")` | 追踪动态引用 |
| `getattr(mod, f"handle_{x}")` | 追踪模式 `handle_*` |
| Next.js `page.tsx`, `layout.tsx`, `route.ts` | 默认/命名导出 → 标记为已使用 |
| Next.js `getServerSideProps`, `generateMetadata` | 配置导出 → 标记为已使用 |
| `React.memo()`, `forwardRef()` | 包装的组件 → 标记为已使用 |
| 导出的 `use*` hooks | 自定义 hooks → 标记为已使用 |
### 测试文件排除
测试以奇怪的方式调用代码，看起来像死代码。默认情况下，Skylos 排除：
| 检测方式 | 示例 |
|-------------|----------|
| Path | `/tests/`, `/test/`, `*_test.py` |
| Imports | `pytest`, `unittest`, `mock` |
| Decorators | `@pytest.fixture`, `@patch` |
```
# 这些会被自动排除（置信度设为 0）
/project/tests/test_user.py
/project/test/helper.py
# 这些会被正常分析
/project/user.py
/project/test_data.py # Doesn't end with _test.py
```
想要包含测试文件？使用 `--include-folder tests`。
### 理念
框架端点在外部被调用（HTTP、信号）。名称解析处理别名。当事情变得不清楚时，我们倾向于谨慎。
## 未使用的 Pytest Fixture
Skylos 可以检测已定义但从未使用的 pytest fixture。
```
skylos . --pytest-fixtures
```
这包括 conftest.py 内部的 fixture，因为 conftest.py 是存储共享测试 fixture 的标准位置。
## 高级工作流
这些命令是可选的。当您希望在核心扫描器和 CI 门控之上使用 LLM 辅助审查、修复或 AI 防御时使用它们。
Skylos 使用**混合架构**，结合了静态分析与 LLM 推理：
### 为什么混合？
| 方法 | Recall | Precision | 逻辑错误 |
|----------|--------|-----------|------------|
| Static only | Low | High | ❌ |
| LLM only | High | Medium | ✅ |
| **Hybrid** | **Highest** | **High** | ✅ |
研究表明，LLM 可以发现静态分析遗漏的漏洞，而静态分析可以验证 LLM 的建议。然而，如果要求 LLM 仅从原始源代码中编造发现，它们在死代码方面容易产生误报。
对于死代码，Skylos 现在使用更严格的契约：
- 静态分析生成候选列表
- 围绕每个候选者收集仓库事实和图证据
- `skylos agent analyze`、`skylos agent audit` 和 `skylos agent verify` 在 `judge_all` 模式下将几乎每个 `references == 0` 的候选者发送给 LLM
- 确定性抑制器仍然存在，但在 `judge_all` 模式下，它们作为证据附加，而不是默默地决定结果
如果您想要更便宜的确定性优先路径而不是默认的 judge-all 审查，请使用 `--verification-mode production`。
### Agent 命令
| 命令 | 描述 |
|---------|-------------|
| `skylos agent analyze PATH` | 完整的混合管道，包含修复建议和 judge-all 死代码验证 |
| `skylos agent audit PATH` | 与 `analyze` 相同的混合管道，但默认关闭修复建议 |
| `skylos agent verify PATH` | 仅针对静态发现的死代码验证检查 |
| `skylos agent security-audit PATH` | 安全审计，支持交互式文件选择 |
| `skylos agent review` | 仅分析 git 变更的文件，提供代码级修复建议 |
| `skylos agent remediate PATH` | 端到端：扫描、修复、测试并创建 PR |
### Provider 配置
Skylos 支持云端和本地 LLM provider：
```
# 云端 - OpenAI（根据模型名称自动检测）
skylos agent analyze . --model gpt-4.1
# 云端 - Anthropic（根据模型名称自动检测）
skylos agent analyze . --model claude-sonnet-4-20250514
# 本地 - Ollama
skylos agent analyze . \
--provider openai \
--base-url http://localhost:11434/v1 \
--model qwen2.5-coder:7b
# 成本更低的死代码验证路径
skylos agent verify . \
--model claude-sonnet-4-20250514 \
--verification-mode production
```
**注意**：您可以使用 `--model` 标志指定您想要的模型。我们支持 Gemini、Groq、Anthropic、ChatGPT 和 Mistral。
### Key 与配置
Skylos 可以使用来自 **(1) `skylos key`** 或 **(2) 环境变量** 的 API key。
#### 推荐（交互式）
```
skylos key
# 打开菜单：
# - 列出密钥
# - 添加密钥 (openai / anthropic / google / groq / mistral / ...)
# - 移除密钥
```
### 环境变量
设置默认值以避免重复标志：
```
# API Keys
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
# 默认使用本地 Ollama
export SKYLOS_LLM_PROVIDER=openai
export SKYLOS_LLM_BASE_URL=http://localhost:11434/v1
```
### LLM PR 审查
`skylos agent review` 分析 git 变更的文件，运行静态分析，然后使用 LLM 为每个发现（安全、质量和死代码）生成代码级修复建议。
```
# 运行 LLM 审查并输出 JSON
skylos agent review . --model claude-sonnet-4-20250514 --format json -o llm-results.json
# 配合 cicd review 在 PR 上发布行内评论
skylos cicd review --input results.json --llm-input llm-results.json
```
混合管道分阶段运行：
1. **静态分析** —— 发现安全、质量和死代码问题
2. **死代码验证** —— LLM 使用图证据、仓库事实和周围上下文判断静态死代码候选者
3. **附加 LLM 分析** —— 扫描静态分析可能遗漏的逻辑/安全问题
4. **代码修复生成** —— 对于每个报告的发现，生成有问题的代码片段和更正版本
每个 PR 评论都显示确切的易受攻击行和直接替换的修复。
### LLM 分析检测什么
| 类别 | 示例 |
|----------|----------|
| **幻觉** | 对不存在的函数的调用 |
| **逻辑错误** | 差一错误、不正确的条件、缺失的边缘情况 |
| **业务逻辑** | 认证绕过、破坏的访问控制 |
| **上下文问题** | 需要理解意图的问题 |
### 本地 LLM 设置
```
# 安装 Ollama
curl -fsSL https://ollama.com/install.sh | sh
# 拉取代码模型
ollama pull qwen2.5-coder:7b
# 配合 Skylos 使用
skylos agent analyze ./src \
--provider openai \
--base-url http://localhost:11434/v1 \
--model qwen2.5-coder:7b
```
### 修复 Agent
修复 Agent 自动化完整的修复生命周期。它扫描您的项目，优先处理发现，通过 LLM 生成修复，通过运行测试套件验证每个修复，并可选择开启 PR。
```
# 预览将要修复的内容（安全，无更改）
skylos agent remediate . --dry-run
# 修复最多 5 个严重/高危问题，并通过测试验证
skylos agent remediate . --max-fixes 5 --severity high
# 全自动：修复、测试、创建 PR
skylos agent remediate . --auto-pr --model gpt-4.1
# 使用自定义测试命令
skylos agent remediate . --test-cmd "pytest test/ -x"
```
**安全防护栏：**
- 默认为试运行 —— 使用 `--dry-run` 预览而不触碰文件
- 破坏测试的修复会自动回滚
- 跳过低置信度的修复
- 应用修复后，Skylos 重新扫描以确认发现确实消失
- `--auto-pr` 始终在新的分支上工作，绝不触碰 main
- `--max-fixes` 防止失控的更改（默认 10）
### 推荐模型
| 模型 | Provider | 用例 |
|-------|----------|----------|
| `gpt-4.1` | OpenAI | 最佳准确度 |
| `claude-sonnet-4-20250514` | Anthropic | 最佳推理 |
| `qwen2.5-coder:7b` | Ollama | 快速本地分析 |
| `codellama:13b` | Ollama | 更好的本地准确度 |
# CI/CD
在您的 CI 管道中运行 Skylos，具备质量门控、GitHub 注释和 PR 审查评论。
## 快速开始（30 秒）
```
# 自动生成 GitHub Actions 工作流
skylos cicd init
# 提交并激活
git add .github/workflows/skylos.yml && git push
```
就是这样！您的下一个 PR 将包含：
- 死代码检测
- 安全扫描（SQLi、SSRF、敏感信息）
- 质量检查
- 带有可点击 file:line 链接的内联 PR 评论
- 在出现严重问题时中断构建的质量门控
**想要 PR 上的 AI 驱动代码修复？**
```
skylos cicd init --llm --model claude-sonnet-4-20250514
```
这添加了一个 LLM 步骤，生成代码级修复建议 —— 在 PR 上内联显示易受攻击的代码和更正版本。
**可选 GitHub Secrets**
对于默认的 `skylos cicd init` 工作流，您不需要任何 Skylos 特定的 secret。只有在 GitHub Actions 中启用匹配功能时才添加这些（**Settings > Secrets and variables > Actions**）：
| Secret | 何时需要 | 描述 |
|--------|-------------|-------------|
| `ANTHROPIC_API_KEY` | 如果使用 Claude 模型 | 您的 Anthropic API key |
| `OPENAI_API_KEY` | 如果使用 GPT 模型 | 您的 OpenAI API key |
| `SKYLOS_API_KEY` | 对于 Skylos Cloud 功能 | 从 [skylos.dev](https://skylos.dev) 获取 |
| `SKYLOS_TOKEN` | 如果使用 `--upload` | 从 [skylos.dev/dashboard/settings](https://skylos.dev/dashboard/settings) 获取的上传 token |
`GH_TOKEN` 由 GitHub Actions 自动提供 —— PR 评论无需设置## 命令
### `skylos cicd init`
生成一个即用型 GitHub Actions 工作流。
```
skylos cicd init
skylos cicd init --triggers pull_request schedule
skylos cicd init --analysis security quality
skylos cicd init --python-version 3.11
skylos cicd init --llm --model gpt-4.1
skylos cicd init --upload # include --upload step + SKYLOS_TOKEN env
skylos cicd init --upload --llm --model claude-sonnet-4-20250514 # upload + LLM
skylos cicd init --defend # add AI Defense check step
skylos cicd init --defend --upload # defend + upload results to cloud
skylos cicd init --no-baseline
skylos cicd init -o .github/workflows/security.yml
```
### `skylos cicd gate`
根据您的质量门控检查发现。退出 `0`（通过）或 `1`（失败）。使用与 `skylos . --gate` 相同的 `check_gate()`。
```
skylos . --danger --quality --secrets --json > results.json 2>/dev/null
skylos cicd gate --input results.json
skylos cicd gate --input results.json --strict
skylos cicd gate --input results.json --summary
```
您也可以直接使用主 CLI：
```
skylos . --gate --summary
```
在 `pyproject.toml` 中配置阈值：
```
[tool.skylos.gate]
fail_on_critical = true
max_critical = 0
max_high = 5
max_security = 10
max_quality = 10
```
### `skylos cicd annotate`
发出 GitHub Actions 注释（`::error`、`::warning`、`::notice`）。使用与 `skylos . --github` 相同的 `_emit_github_annotations()`，具有排序和 50 个注释上限。
```
skylos cicd annotate --input results.json
skylos cicd annotate --input results.json --severity high
skylos cicd annotate --input results.json --max 30
skylos . --github
```
### `skylos cicd review`
通过 `gh` CLI 发布内联 PR 审查评论和摘要。仅评论 PR 中更改的行。
```
skylos cicd review --input results.json
skylos cicd review --input results.json --pr 20
skylos cicd review --input results.json --summary-only
skylos cicd review --input results.json --max-comments 10
skylos cicd review --input results.json --diff-base origin/develop
# 采用 LLM 生成的代码修复（易受攻击代码 → 已修复代码）
skylos cicd review --input results.json --llm-input llm-results.json
```
当提供 `--llm-input` 时，每个内联评论都显示有问题的代码和更正版本：
```
🔴 CRITICAL SKY-D211
Possible SQL injection: tainted or string-built query.
Why: User input is concatenated directly into the SQL query string.
Vulnerable code:
results = conn.execute(f"SELECT * FROM users WHERE name LIKE '%{q}%'").fetchall()
Fixed code:
results = conn.execute("SELECT * FROM users WHERE name LIKE ?", (f"%{q}%",)).fetchall()
```
在 GitHub Actions 中，PR 编号和仓库会自动检测。需要 `GH_TOKEN`。
## 如何协同工作
门控和注释逻辑位于核心 Skylos 模块（`gatekeeper.py` 和 `cli.py`）中。`cicd` 命令是便捷的包装器，从 JSON 文件读取并调用相同的函数：
| `skylos cicd` 命令 | 调用 |
|-----------------------|-------|
| `gate` | `gatekeeper.run_gate_interaction(summary=True)` |
| `annotate` | `cli._emit_github_annotations(max_annotations=50)` |
| `review` | New — `cicd/review.py` (PR comments via `gh api`) |
| `init` | New — `cicd/workflow.py` (YAML generation) |
## 技巧
- **运行一次分析，多次使用** —— 使用 `--json > results.json 2>/dev/null` 然后将 `--input results.json` 传递给每个子命令。
- **基线** —— 运行 `skylos baseline .` 快照现有发现，然后在 CI 中使用 `--baseline` 仅标记新问题。
- **本地测试** —— 所有命令都在本地工作。`gate` 和 `annotate` 打印到 stdout。`review` 需要 `gh` CLI。
## MCP Server
mcp-name: io.github.duriantaco/skylos
Skylos 将其分析能力作为 MCP (Model Context Protocol) 服务器公开，允许像 Claude Desktop 这样的 AI 助手直接扫描您的代码库。
### 设置
```
pip install skylos
```
添加到您的 Claude Desktop 配置（Linux 上为 `~/.config/claude/claude_desktop_config.json`，macOS 上为 `~/Library/Application Support/Claude/claude_desktop_config.json`）：
```
{
"mcpServers": {
"skylos": {
"command": "python",
"args": ["-m", "skylos_mcp.server"]
}
}
}
```
### 可用工具
| 工具 | 描述 |
|------|-------------|
| `analyze` | 死代码检测（未使用的函数、导入、类、变量） |
| `security_scan` | 安全漏洞扫描（`--danger` 等效） |
| `quality_check` | 代码质量和复杂度分析（`--quality` 等效） |
| `secrets_scan` | 硬编码敏感信息检测（`--secrets` 等效） |
| `remediate` | 端到端：扫描、生成 LLM 修复、用测试验证 |
### 可用资源
| 资源 | URI | 描述 |
|----------|-----|-------------|
| Latest result | `skylos://results/latest` | 最近的分析运行 |
| Result by ID | `skylos://results/{run_id}` | 特定的分析运行 |
| List results | `skylos://results` | 所有存储的分析运行 |
### 在 Claude Desktop 中使用
配置后，您可以要求 Claude：
- "扫描我的项目中的安全问题" → 调用 `security_scan`
- "检查 src/ 中的代码质量" → 调用 `quality_check`
- "查找硬编码的敏感信息" → 调用 `secrets_scan`
- "修复我项目中的安全问题" → 调用 `remediate`
## 基线追踪
基线追踪允许您快照现有发现，以便 CI 仅标记由 PR 引入的**新**问题。
```
# 根据当前状态创建基线
skylos baseline .
# 运行分析，仅显示不在基线中的发现
skylos . --danger --secrets --quality --baseline
# 在 CI 中：与基线对比
skylos . --danger --baseline --gate
```
基线存储在 `.skylos/baseline.json` 中。将此文件提交到您的仓库，以便 CI 可以使用它。
## VS Code 扩展
直接在编辑器中进行实时 AI 驱动的代码分析。
### 安装
1. 在 VS Code 市场中搜索 "Skylos" 或运行：
```
ext install oha.skylos-vscode-extension
```
2. 确保已安装 CLI：
```
pip install skylos
```
3. （可选）在 VS Code 设置中为 AI 功能添加您的 API key → `skylos.openaiApiKey` 或 `skylos.anthropicApiKey`
### 工作原理
| 层 | 触发器 | 作用 |
|-------|---------|--------------|
| **静态分析** | 保存时 | 运行 Skylos CLI 检查死代码、敏感信息、危险模式 |
| **AI Watcher** | 空闲时 (2s) | 将更改的函数发送给 GPT-4/Claude 进行错误检测 |
### 功能
- **实时分析**：在您输入时检测错误 —— 无需保存
- **CodeLens 按钮**："Fix with AI" 和 "Dismiss" 出现在错误行的内联位置
- **流式修复**：实时查看修复进度
- **智能缓存**：仅重新分析实际更改的函数
- **多 Provider**：在 OpenAI 和 Anthropic 之间选择
#### 新功能
- **MCP Server 支持**：将 Skylos 直接连接到 Claude Desktop 或任何 MCP 客户端以与您的代码库聊天。
- **CI/CD Agent**：在您的管道中自动扫描、修复、测试和开启 PR 的自主机器人。
- **混合验证**：通过使用 LLM 推理验证静态发现来消除误报。
### 扩展设置
| 设置 | 默认值 | 描述 |
|---------|---------|-------------|
| `skylos.aiProvider` | `"openai"` | `"openai"` 或 `"anthropic"` |
| `skylos.openaiApiKey` | `""` | 您的 OpenAI API key |
| `skylos.anthropicApiKey` | `""` | 您的 Anthropic API key |
| `skylos.idleMs` | `2000` | AI 分析前的等待时间 |
| `skylos.runOnSave` | `true` | 保存时运行 Skylos CLI |
| `skylos.enableSecrets` | `true` | 扫描硬编码的敏感信息 |
| `skylos.enableDanger` | `true` | 标记危险模式 |
### 使用
| 操作 | 结果 |
|--------|--------|
| 保存 Python 文件 | Skylos CLI 扫描工作区 |
| 输入并暂停 | AI 分析更改的函数 |
| 点击 "Fix with AI" | 生成带有 diff 预览的修复 |
| `Cmd+Shift+P` -> "Skylos: Scan Workspace" | 完整项目扫描 |
### 隐私
- 静态分析 100% 在本地运行
- AI 功能仅将更改的函数代码发送给您配置的 provider
- 我们不收集任何遥测或数据
**[从 VS Code 市场安装](https://marketplace.visualstudio.com/items?itemName=oha.skylos-vscode-extension)**
## 门控
在合并前阻断不良代码。配置阈值，在本地运行，然后在 CI 中自动化。
### 初始化配置
```
skylos init
```
在您的 `pyproject.toml` 中创建 `[tool.skylos]`：
```
[tool.skylos]
# 质量阈值
complexity = 10
nesting = 3
max_args = 5
max_lines = 50
ignore = []
model = "gpt-4.1"
# 语言覆盖（可选）
[tool.skylos.languages.typescript]
complexity = 15
nesting = 4
# 关卡策略
[tool.skylos.gate]
fail_on_critical = true
max_security = 0 # Zero tolerance
max_quality = 10 # Allow up to 10 warnings
strict = false
```
### 免费层
使用退出代码在本地运行扫描：
```
skylos . --danger --gate
```
- 退出代码 `0` = 通过
- 退出代码 `1` = 失败
在任何 CI 系统中使用：
```
name: Skylos Quality Gate
on:
pull_request:
branches: [main, master]
jobs:
skylos:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: '3.11'
- run: pip install skylos
- run: skylos . --danger --gate
```
### Pro 层
开发者**无法绕过**的服务器控制 GitHub 检查。
### 快速设置
```
pip install skylos
skylos sync setup
```
### 工作原理
1. 开发者开启 PR → GitHub App 创建所需的检查
2. 扫描运行 → 结果上传到 Skylos 服务器
3. 服务器更新检查 → Pass ✅ 或 Fail ❌
4. 开发者**无法合并**，直到检查通过
### Free 与 Pro 对比
| 功能 | Free | Pro |
|---------|------|-----|
| 本地扫描 | ✅ | ✅ |
| `--gate` 退出代码 | ✅ | ✅ |
| GitHub Actions | ✅ (DIY) | ✅ (auto) |
| 开发者可以绕过？ | 是 | **否** |
| 服务器控制的检查 | ❌ | ✅ |
| Slack/Discord 警报 | ❌ | ✅ |
### GitHub App 设置
1. **Dashboard -> Settings -> Install GitHub App**
2. 选择您的仓库
3. 在 GitHub 仓库设置中：
- Settings -> Branches -> Add rule -> `main`
- 需要状态检查
- 选择 "Skylos Quality Gate"
### 添加 Token 到 GitHub
仓库 **Settings → Secrets → Actions → New secret**
- Name: `SKYLOS_TOKEN`
- Value: *（来自 Dashboard → Settings）*
## 集成与生态
Skylos 旨在存在于您的代码所在的任何地方——从您的 IDE 到您的部署管道。
### 1. 集成环境
| 环境 | 工具 | 用例 |
|-------------|------|----------|
| VS Code | Skylos Extension | 实时守护。保存时高亮显示代码腐烂和风险。 |
| Web UI | `skylos run` | 在 `localhost:5090` 启动本地仪表板以进行可视化审计。 |
| CI/CD | GitHub Actions / Pre-commit | 自动化门控，在合并前审计每个 PR。 |
| Quality Gate | `skylos --gate` | 如果超过安全或复杂度阈值则阻断部署。 |
### 2. 输出格式
控制如何使用看门狗的发现。
| 标志 | 格式 | 主要用途 |
|------|--------|-------------|
| `--tui` | TUI Dashboard | 启动交互式 TUI 仪表板。 |
| `--tree` | Logic Tree | 可视化代码层次结构和结构依赖关系。 |
| `--json` | Machine Raw | 通过管道将结果传输到 `jq`、自定义脚本或日志聚合器。 |
| `--sarif` | SARIF | GitHub Code Scanning，IDE 集成 |
| `--llm` | LLM Report | 为 Claude Code、Codex 或任何 AI agent 提供带有代码上下文的结构化发现。 |
| `-o, --output` | File Export | 将审计报告直接保存到文件而不是 `stdout`。 |
## 审计与精度
默认情况下，Skylos 查找死代码。使用标志启用额外的扫描。
### 安全 (`--danger`)
追踪从用户输入到危险 sink 的污点数据。
```
skylos . --danger
```
| 规则 | ID | 捕获内容 |
|------|-----|-----------------|
| **注入** | | |
| SQL injection | SKY-D211 | `cur.execute(f"SELECT * FROM users WHERE name='{name}'")` |
| SQL raw query | SKY-D217 | `sqlalchemy.text()`, `pandas.read_sql()`, Django `.raw()` 使用污点输入 |
| Command injection | SKY-D212 | `os.system()`, `subprocess(shell=True)` 使用污点输入 |
| SSRF | SKY-D216 | `requests.get(request.args["url"])` |
| Path traversal | SKY-D215 | `open(request.args.get("p"))` |
| XSS (mark_safe) | SKY-D226 | 不可信内容传递给 `mark_safe()` / `Markup()` |
| XSS (template) | SKY-D227 | 禁用 autoescape 的内联模板 |
| XSS (HTML build) | SKY-D228 | 从未转义的用户输入构建的 HTML |
| Open redirect | SKY-D230 | 用户控制的 URL 传递给 `redirect()` |
| **危险调用** | | |
| eval() | SKY-D201 | 通过 `eval()` 进行动态代码执行 |
| exec() | SKY-D202 | 通过 `exec()` 进行动态代码执行 |
| os.system() | SKY-D203 | OS 命令执行 |
| pickle.load | SKY-D204 | 不安全的反序列化 |
| yaml.load | SKY-D206 | `yaml.load()` 无 SafeLoader |
| Weak hash (MD5) | SKY-D207 | `hashlib.md5()` |
| Weak hash (SHA1) | SKY-D208 | `hashlib.sha1()` |
| shell=True | SKY-D209 | `subprocess` 使用 `shell=True` |
| TLS disabled | SKY-D210 | `requests` 使用 `verify=False` |
| Unsafe deserialization | SKY-D233 | `marshal.loads`, `shelve.open`, `jsonpickle.decode`, `dill` |
| **Web 安全** | | |
| CORS misconfiguration | SKY-D231 | 通配符来源、凭证泄露、过于宽松的头部 |
| JWT vulnerabilities | SKY-D232 | `algorithms=['none']`、验证、弱密钥 |
| Mass assignment | SKY-D234 | Django `Meta.fields = '__all__'` 暴露所有模型字段 |
| **供应链** | | |
| Hallucinated dependency | SKY-D222 | 导入的包在 PyPI 上不存在 (CRITICAL) |
| Undeclared dependency | SKY-D223 | 导入未在 requirements.txt / pyproject.toml 中声明 |
| **MCP 安全** | | |
| Tool description poisoning | SKY-D240 | MCP 工具元数据中的提示注入 |
| Unauthenticated transport | SKY-D241 | SSE/HTTP MCP 服务器无认证中间件 |
| Permissive resource URI | SKY-D242 | 通过 MCP 资源 URI 模板的路径遍历 |
| Network-exposed MCP | SKY-D243 | MCP 服务器绑定到 `0.0.0.0` 无认证 |
| Hardcoded secrets in MCP | SKY-D244 | MCP 工具参数默认值中的敏感信息 |
完整列表见 `DANGEROUS_CODE.md`。
### 敏感信息 (`--secrets`)
检测硬编码凭证。
```
skylos . --secrets
```
Provider：GitHub, GitLab, AWS, Stripe, Slack, Google, SendGrid, Twilio, 私钥。
### 质量 (`--quality`)
标记难以维护的函数。
```
skylos . --quality
```
| 规则 | ID | 捕获内容 |
|------|-----|-----------------|
| **复杂度** | | |
| Cyclomatic complexity | SKY-Q301 | 分支/循环过多（默认：>10） |
| Deep nesting | SKY-Q302 | 嵌套层级过多（默认：>3） |
| Async Blocking | SKY-Q401 | 检测 async 函数中扼杀服务器吞吐量的阻塞调用 |
| God class | SKY-Q501 | 类有太多的方法/属性 |
| Coupling (CBO) | SKY-Q701 | 高类间耦合（7 种依赖类型：继承、类型提示、实例化、属性访问、导入、装饰器、protocol/ABC） |
| Cohesion (LCOM) | SKY-Q702 | 低类内聚 —— 应该拆分的断开方法组（带 Union-Find 的 LCOM1/4/5 指标） |
| **架构** | | |
| Distance from Main Sequence | SKY-Q802 | 模块远离抽象性与不稳定性的理想平衡 |
| Zone warning | SKY-Q803 | 模块处于痛苦区域（僵化）或无用区域（一次性的） |
| DIP violation | SKY-Q804 | 稳定模块依赖于不稳定模块（依赖倒置原则） |
| **结构** | | |
| Too many arguments | SKY-C303 | 参数 >5 的函数 |
| Function too long | SKY-C304 | 函数 >50 行 |
| **逻辑** | | |
| Mutable default | SKY-L001 | `def foo(x=[])` - 导致状态泄露 |
| Bare except | SKY-L002 | `except:` 吞掉 SystemExit |
| Dangerous comparison | SKY-L003 | `x == None` 而不是 `x is None` |
| Anti-pattern try block | SKY-L004 | 嵌套 try，或 try 包裹太多逻辑 |
| Unused exception var | SKY-L005 | `except Error as e:` 其中 `e` 从未被引用 |
| Inconsistent return | SKY-L006 | 函数同时返回值和 `None` |
| **性能** | | |
| Memory load | SKY-P401 | `.read()` / `.readlines()` 加载整个文件 |
| Pandas no chunk | SKY-P402 | `read_csv()` 没有 `chunksize` |
| Nested loop | SKY-P403 | O(N²) 复杂度 |
| **不可达** | | |
| Unreachable Code | SKY-UC001 | `if False:` 或 always-true 之后的 `else` |
| **空** | | |
| Empty File | SKY-E002 | 空文件 |
要忽略特定规则：
```
# pyproject.toml
[tool.skylos]
ignore = ["SKY-P403"] # Allow nested loops
```
在 `pyproject.toml` 中调整阈值和禁用规则：
```
[tool.skylos]
# 调整阈值
complexity = 15 # Default: 10
nesting = 4 # Default: 3
max_args = 7 # Default: 5
max_lines = 80
```
### 默认 CLI 选项 (`addopts`)
在 `pyproject.toml` 中设置默认标志，这样您就不必每次都输入它们 —— 就像 pytest 的 `addopts`：
```
[tool.skylos]
addopts = ["--quality", "--danger", "--secrets"]
```
字符串格式也可以：
```
[tool.skylos]
addopts = "--quality --danger --confidence=80"
```
CLI 标志覆盖 `addopts`，因此您始终可以在不编辑配置的情况下缩小或扩大运行范围。
### 旧版 AI 标志
```
# LLM 驱动的审计（单文件）
skylos . --audit
# 指定模型
skylos . --audit --model claude-haiku-4-5-20251001
```
### 组合所有
```
skylos . -a # All static scans (danger + secrets + quality + sca)
skylos agent remediate . --dry-run # Preview AI-assisted fixes
```
## 智能追踪
静态分析无法看到所有内容。Python 的动态特性意味着像 `getattr()`、插件注册表和基于字符串的分发这样的模式看起来像死代码——但它们不是。
**智能追踪解决了这个问题。** 通过使用 `sys.settrace()` 运行测试，Skylos 记录每个实际被调用的函数。
### 快速开始
```
# 运行带有调用追踪的测试，然后分析
skylos . --trace
# 追踪数据保存到 .skylos_trace
skylos .
```
### 工作原理
| 分析类型 | 准确度 | 捕获内容 |
|---------------|----------|-----------------|
| Static only | 70-85% | 直接调用、导入、装饰器 |
| + Framework rules | 85-95% | Django/Flask 路由、pytest fixture |
| + `--trace` | 95-99% | 动态分发、插件、注册表 |
### 示例
```
# 静态分析会认为这是死代码，因为没有可见的直接调用
def handle_login():
return "Login handler"
# 但它实际上是在运行时动态调用的
action = request.args.get("action")
func = getattr(module, f"handle_{action}")
func() # here
```
| Without Tracing | With `--trace` |
|-----------------|----------------|
| `handle_login` 被标记为死代码 | `handle_login` 被标记为已使用 |
### 何时使用
| 情况 | 命令 |
|-----------|---------|
| 有 pytest/unittest 测试 | `skylos . --trace` |
| 没有测试 | `skylos .` (仅静态) |
| 带有缓存 trace 的 CI | `skylos .` (重用 `.skylos_trace`) |
### Tracing 捕获什么
这些模式对静态分析不可见，但会被 `--trace` 捕获：
```
# 1. 动态分发
func = getattr(module, f"handle_{action}")
func()
# 2. 插件或注册表模式
PLUGINS = []
def register(f):
PLUGINS.append(f)
return f
@register
def my_plugin(): ...
# 3. 访问者模式
class MyVisitor(ast.NodeVisitor):
def visit_FunctionDef(self, node): ... # Called via getattr
# 4. 基于字符串的访问
globals()["my_" + "func"]()
locals()[func_name]()
```
### 重要说明
- **Tracing 只添加信息。** 低测试覆盖率不会产生误报。它只是意味着某些动态模式**可能**仍会被标记。
- **提交 `.skylos_trace`** 以在 CI 中重用 trace 数据，而无需重新运行测试。
- **测试不需要通过。** Tracing 记录执行的内容，无论通过/失败状态如何。
## 过滤
控制 Skylos 分析什么和忽略什么。
### 内联抑制
使用注释消除特定发现：
```
# 忽略此行的死代码检测
def internal_hook(): # pragma: no skylos
pass
# 这也有效
def another(): # pragma: no cover
pass
def yet_another(): # noqa
pass
```
### 文件夹排除
默认情况下，Skylos 排除：`__pycache__`, `.git`, `.pytest_cache`, `.mypy_cache`, `.tox`, `htmlcov`, `.coverage`, `build`, `dist`, `*.egg-info`, `venv`, `.venv`
```
# 查看默认排除的内容
skylos --list-default-excludes
# 添加更多排除项
skylos . --exclude-folder vendor --exclude-folder generated
# 强制包含已排除的文件夹
skylos . --include-folder venv
# 扫描所有内容（无排除）
skylos . --no-default-excludes
```
### 规则抑制
在 `pyproject.toml` 中全局禁用规则：
```
[tool.skylos]
ignore = [
"SKY-P403", # Allow nested loops
"SKY-L003", # Allow == None
"SKY-S101", # Allow hardcoded secrets (not recommended)
]
```
### 摘要
| 想要... | 操作 |
|------------|---------|
| 跳过一行 | `# pragma: no skylos` |
| 跳过一个敏感信息 | `# skylos: ignore[SKY-S101]` |
| 跳过一个文件夹 | `--exclude-folder NAME` |
| 全局跳过一个规则 | pyproject.toml 中的 `ignore = ["SKY-XXX"]` |
| 包含被排除的文件夹 | `--include-folder NAME` |
| 运行所有检查 | `-a` 或 pyproject.toml 中的 `addopts` |
| 扫描所有内容 | `--no-default-excludes` |
## 白名单配置
永久抑制误报，而不会使代码混乱中充斥着内联注释。
### CLI 命令
```
# 添加模式
skylos whitelist 'handle_*'
# 添加并附带原因
skylos whitelist dark_logic --reason "Called via globals() in dispatcher"
# 查看当前白名单
skylos whitelist --show
```
### 内联忽略
```
# 单行
def dynamic_handler(): # skylos: ignore
pass
# 同样有效
def another(): # noqa: skylos
pass
# 块忽略
# skylos: ignore-start
def block_one():
pass
def block_two():
pass
# skylos: ignore-end
```
### 配置文件 (`pyproject.toml`)
```
[tool.skylos.whitelist]
# Glob 模式
names = [
"handle_*",
"visit_*",
"*Plugin",
]
# 附带原因（显示在 --show 输出中）
[tool.skylos.whitelist.documented]
"dark_logic" = "Called via globals() string manipulation"
"BasePlugin" = "Discovered via __subclasses__()"
# 临时的（过期时发出警告）
[tool.skylos.whitelist.temporary]
"legacy_handler" = { reason = "Migration - JIRA-123", expires = "2026-03-01" }
# 按路径覆盖
[tool.skylos.overrides."src/plugins/*"]
whitelist = ["*Plugin", "*Handler"]
```
### 摘要
| 想要... | 操作 |
|------------|---------|
| 白名单一个函数 | `skylos whitelist func_name` |
| 白名单一个模式 | `skylos whitelist 'handle_*'` |
| 记录原因 | `skylos whitelist x --reason "why"` |
| 临时白名单 | 添加到带 `expires` 的 `[tool.skylos.whitelist.temporary]` |
| 每个文件夹的规则 | 添加 `[tool.skylos.overrides."path/*"]` |
| 查看白名单 | `skylos whitelist --show` |
| 内联忽略 | `# skylos: ignore` 或 `# noqa: skylos` |
| 块忽略 | `# skylos: ignore-start` ... `# skylos: ignore-end` |
## CLI 选项
### 主命令标志
```
Usage: skylos [OPTIONS] PATH
Arguments:
PATH Path to the Python project to analyze
Options:
-h, --help Show this help message and exit
--json Output raw JSON instead of formatted text
--tree Output results in tree format
--tui Launch interactive TUI dashboard
--sarif Output SARIF format for GitHub/IDE integration
--llm Output LLM-optimized report with code context for AI agents
-c, --confidence LEVEL Confidence threshold 0-100 (default: 60)
--comment-out Comment out code instead of deleting
-o, --output FILE Write output to file instead of stdout
-v, --verbose Enable verbose output
--version Checks version
-i, --interactive Interactively select items to remove
--dry-run Show what would be removed without modifying files
--exclude-folder FOLDER Exclude a folder from analysis (can be used multiple times)
--include-folder FOLDER Force include a folder that would otherwise be excluded
--no-default-excludes Don't exclude default folders (__pycache__, .git, venv, etc.)
--list-default-excludes List the default excluded folders
--secrets Scan for api keys/secrets
--danger Scan for dangerous code
--quality Code complexity and maintainability
--sca Scan dependencies for known CVEs (OSV.dev)
-a, --all Enable all checks: --danger --secrets --quality --sca
--trace Run tests with coverage first
--audit LLM-powered logic review (legacy)
--model MODEL LLM model (default: gpt-4.1)
--gate Fail on threshold breach (for CI)
--force Bypass quality gate (emergency override)
```
### Agent 命令标志
```
Usage: skylos agent
[OPTIONS] PATH
Commands:
analyze Hybrid static + LLM analysis with project context
security-audit Deep LLM security audit
review Analyze only git-changed files
remediate Scan, fix, test, and create PR (end-to-end)
Options (all agent commands):
--model MODEL LLM model to use (default: gpt-4.1)
--provider PROVIDER Force provider: openai or anthropic
--base-url URL Custom endpoint for local LLMs
--format FORMAT Output: table, tree, json, sarif
-o, --output FILE Write output to file
Agent analyze options:
--min-confidence LEVEL Filter: high, medium, low
Agent remediate options:
--dry-run Show plan without applying fixes (safe preview)
--max-fixes N Max findings to fix per run (default: 10)
--auto-pr Create branch, commit, push, and open PR
--branch-prefix PREFIX Git branch prefix (default: skylos/fix)
--test-cmd CMD Custom test command (default: auto-detect)
--severity LEVEL Min severity filter: critical, high, medium, low
```
### AI 防御命令标志
```
Usage: skylos discover [OPTIONS] PATH
Map all LLM integrations in a Python codebase.
Options:
--json Output as JSON
-o, --output FILE Write output to file
--exclude FOLDER [FOLDER...] Additional folders to exclude
Usage: skylos defend [OPTIONS] PATH
Check LLM integrations for missing defenses.
Options:
--json Output as JSON
-o, --output FILE Write output to file
--min-severity LEVEL Minimum severity to include (critical/high/medium/low)
--fail-on LEVEL Exit 1 if any defense finding at or above this severity
--min-score N Exit 1 if defense score below this percentage (0-100)
--policy FILE Path to skylos-defend.yaml policy file
--owasp IDS Comma-separated OWASP LLM IDs (e.g. LLM01,LLM04)
--exclude FOLDER [FOLDER...] Additional folders to exclude
--upload Upload defense results to Skylos Cloud dashboard
```
### 命令
```
Commands:
skylos PATH Analyze a project (static analysis)
skylos discover PATH Map LLM integrations in a codebase
skylos defend PATH Check LLM integrations for missing defenses
skylos agent analyze PATH Hybrid static + LLM analysis
skylos agent security-audit PATH Deep LLM audit with file selection
skylos agent review Review git-changed files only
skylos agent remediate PATH End-to-end scan, fix, test, and PR
skylos baseline PATH Snapshot current findings for CI baselining
skylos cicd init Generate GitHub Actions workflow
skylos cicd gate Check findings against quality gate
skylos cicd annotate Emit GitHub Actions annotations
skylos cicd review Post inline PR review comments (supports --llm-input)
skylos init Initialize pyproject.toml config
skylos key Manage API keys (add/remove/list)
skylos whitelist PATTERN Add pattern to whitelist
skylos whitelist --show Display current whitelist
skylos run Start web UI at localhost:5090
Whitelist Options:
skylos whitelist PATTERN Add glob pattern (e.g., 'handle_*')
skylos whitelist NAME --reason X Add with documentation
skylos whitelist --show Display all whitelist entries
```
### CLI 输出
Skylos 显示每个发现的置信度：
```
────────────────── Unused Functions ──────────────────
# 名称 位置 置信度
1 handle_secret app.py:16 70%
2 totally_dead app.py:50 90%
```
置信度越高 = 越确定它是死代码。
### 交互模式
交互模式允许您选择要移除的特定函数和导入：
1. **选择项目**：使用箭头键和 `spacebar` 选择/取消选择
2. **确认更改**：在应用前审查选定的项目
3. **自动清理**：文件会自动更新
## 常见问题
**Q: 为什么 Skylos 不能找到 100% 的死代码？**
A: Python 的动态特性无法通过静态分析完美分析。没有工具可以达到 100% 的准确度。如果他们说可以，那是在撒谎。
**Q: 这些基准测试现实吗？**
A: 它们测试了常见场景，但无法覆盖每个边缘情况。将它们用作指南，而不是真理。
**Q: 为什么 Skylos 没有检测到我未使用的 Flask 路由？**
A: Web 框架路由的置信度较低 (20)，因为它们可能被外部 HTTP 请求调用。使用 `--confidence 20` 来查看它们。我们承认这种方法目前存在局限性，所以请谨慎使用。
**Q: 我应该使用什么置信度？**
A: 从 60（默认）开始进行安全清理。框架应用使用 30。更全面的审计使用 20。
**Q: `--trace` 做什么？**
A: 它在分析之前使用覆盖率跟踪运行 `pytest`（或 `unittest`）。实际执行的函数被标记为已使用，置信度为 100，消除了来自动态分发模式的误报。
**Q: 我需要 100% 的测试覆盖率才能让 `--trace` 有用吗？**
A: 不需要。然而，我们**强烈**建议您进行测试。任何覆盖率都有帮助。如果您有 30% 的测试覆盖率，那就是 30% 的代码被验证了。其他 70% 仍然使用静态分析。覆盖率只会移除误报，它永远不会添加它们。
**Q: 为什么 `conftest.py` 中的 fixture 显示为未使用？**
A: `conftest.py` 是共享 fixture 的标准位置。如果在那里定义了一个 fixture 但从未被任何测试引用，Skylos 将报告它为未使用。这是正常的，可以安全地审查。
**Q: 我的测试失败了。我还能使用 `--trace` 吗？**
A: 可以。覆盖率跟踪执行，而不是通过/失败。即使失败的测试也提供覆盖率数据。
**Q: `skylos . --audit` 和 `skylos agent audit` 有什么区别？**
A: `skylos agent audit` 运行完整的混合管道 —— 静态分析、judge-all LLM 死代码验证和 LLM 安全/质量分析。修复建议默认关闭（使用 `--with-fixes` 启用）。`skylos agent analyze` 是等效的，但默认包含修复建议。基础命令上的 `--audit` 标志是旧版的仅静态模式。
**Q: `--verification-mode` 做什么？**
A: 它控制 Skylos 将死代码候选者发送给 LLM 的积极程度。`judge_all` 是 `agent analyze`、`agent audit` 和 `agent verify` 的默认值；它将几乎每个 `references == 0` 的静态候选者发送给 LLM，并将确定性抑制器视为证据。`production` 更便宜，允许更明显的存活情况在 LLM 看到之前被抑制。
**Q: 我可以使用本地 LLM 代替 OpenAI/Anthropic 吗？**
A: 可以！使用 `--base-url` 指向 Ollama、LM Studio 或任何兼容 OpenAI 的端点。本地主机不需要 API key。
## 限制与故障排除
### 限制
- **动态代码**：`getattr()`、`globals()`、运行时导入很难检测
- **框架**：Django 模型、Flask、FastAPI 路由可能显示为未使用但实际上不是
- **测试数据**：场景有限，您的情况可能不同
- **误报**：在删除代码之前始终进行人工审查
- **敏感信息 PoC**：可能会为同一个 token 同时发出 provider 命中和通用高熵命中。支持的文件类型：`.py`, `.pyi`, `.pyw`, `.env`, `.yaml`, `.yml`, `.json`, `.toml`, `.ini`, `.cfg`, `.conf`, `.ts `.tsx`, `.js`, `.jsx`, `.go`
- **质量限制**：当前的 `--quality` 标志不允许您配置圈复杂度。
- **覆盖率需要执行**：`--trace` 标志只有在您有测试或可以运行应用程序时才有帮助。没有它，纯静态分析仍然可用。
- **LLM 限制**：AI 分析需要 API 访问（云端）或本地设置。结果取决于模型质量。
### 故障排除
1. **权限错误**
Error: Permission denied when removing function
在交互模式下运行前检查文件权限。
2. **缺少依赖**
Interactive mode requires 'inquirer' package
使用以下命令安装：`pip install skylos[interactive]`
3. **未找到 API Key**
# 对于云提供商
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
# 对于本地 LLM（无需密钥）
skylos agent analyze . --base-url http://localhost:11434/v1 --model codellama
4. **本地 LLM 连接被拒绝**
# 验证 Ollama 是否正在运行
curl http://localhost:11434/v1/models
# 检查 LM Studio
curl http://localhost:1234/v1/models
## 贡献
我们欢迎贡献！在提交 pull request 之前，请阅读我们的[贡献指南](CONTRIBUTING.md)。
### 快速贡献指南
1. Fork 仓库
2. 创建一个功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交您的更改 (`git commit -m 'Add amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 开启一个 Pull Request
## 路线图
- [x] 扩展我们的测试用例
- [x] 配置文件支持
- [x] Git hooks 集成
- [x] CI/CD 集成示例
- [x] 部署门控
- [ ] 进一步优化
- [ ] 添加新规则
- [ ] 扩展 `dangerous.py` 列表
- [x] 移植到 uv
- [x] 与 typescript 的小集成
- [x] 扩展的 TypeScript 死代码检测（接口、枚举、类型别名，95% 召回率）
- [ ] 扩展和改进 Skylos 在各种其他语言中的能力
- [x] AI 防御引擎：discover + defend 命令，包含 13 项检查，OWASP LLM Top 10 映射，运维评分
- [x] AI 防御云仪表板：上传、趋势图、OWASP 网格、每个集成的卡片、专用项目页面
- [x] AI 防御 CI/CD：`skylos cicd init --defend`，pre-commit hook
- [x] 扩展 LLM 的 provider（OpenAI、Anthropic、Ollama、LM Studio、vLLM）
- [x] 扩展用于检测死代码/危险代码的 LLM 部分（混合架构）
- [x] 用于运行时验证的覆盖率集成
- [x] 隐式引用检测（f-string 模式、框架装饰器）
更多功能即将推出！
## 许可证
该项目根据 Apache 2.0 许可证授权 - 详情请参阅 [LICENSE](LICENSE) 文件。
## 联系方式
- **作者**：oha
- **Email**：aaronoh2015@gmail.com
- **GitHub**：[@duriantaco](https://github.com/duriantaco)
- **Discord**：https://discord.gg/Ftn9t9tErf