GSC Scanner

🛡️ GSC — Git 安全检查器

English

GSC 是一个自学习的应用安全平台，可验证漏洞利用、确认修复效果并修复 CI。

detect → prove → fix → verify → heal → learn

大多数扫描器只会报告匹配项。GSC 则会验证它们：每个发现的问题都可以转化为可运行的概念验证，在沙箱中验证，然后修复并通过重新运行漏洞利用再次确认修复效果。

它的独特之处：

• 69 种检测器，覆盖 SAST、SCA、密钥和 IaC，并提供 YAML 规则 DSL。
• 自动生成 PoC，并设有安全利用门槛：发现的问题会附带可用的漏洞利用，而不只是行号。
• 修复验证——只有在漏洞利用无法在沙箱中触发后，补丁才会被接受。
• 自学习——检测器每晚都会在校准网络中重新评分；噪声模式的 TP 低于 30% 时会自动停用。联邦反馈以隐私为先（{tenant_hash, rule_id, tp, fp} + DP 噪声）。
• 依据可利用性而非 CVSS 排定优先级——EPSS + CISA KEV + ExploitDB。
• 自带 LLM——引擎、检测器和 PoC 逻辑由我们提供；LLM 重新验证使用你自己的密钥（任何兼容 OpenAI 的端点，包括本地 Ollama）。没有密钥时，会快速切换到仅使用正则表达式的模式。

可将其用作 GitHub Action（见下文），通过 CLI / Docker 镜像使用，或作为 AI 编码 Agent 的 MCP 服务——通过 stdio 或 HTTP 提供六种工具（scan_repo、scan_diff、list_findings、get_finding、verify_finding、list_detectors）。 对你的代码仓库只读：不会打补丁、创建 PR 或写入工作树。（verify_finding 确实会执行 PoC——请参阅 MCP 部分的安全说明。）

已在真实代码中验证：HALL_OF_FAME.md · 首个公开案例研究：CASE_STUDY_CYBERBRO.md

在 100 个真实 GitHub 项目中的测量结果

检测器变更后，会使用同一固定数据集重新扫描——100 个真实代码仓库（90 个干净项目 + 10 个已知存在漏洞的项目），固定到特定提交，仅使用正则表达式，不使用 LLM 密钥。 每次运行扫描的都是相同项目，因此数据变化反映的是修复效果，而非换了数据集。

	2026-08-21（基线）	2026-08-28（修复 FP 后）
发现项	64,831	41,127
严重	4,302	414
高危	37,246	2,187
被标记的已知漏洞项目	8 / 10	10 / 10
至少有 1 项误报严重问题的干净项目	48 / 90	41 / 90

在对 434 项发现进行标注审查后，严重问题的精确率为：基线约 4–5% → 31.1% （TP = 135，FP = 299，2026-08-26）。误报仍然很多。剩余误报主要集中在 GS001（密钥）、GS005（SQLi）、GS020（XSS）和 GS037（路径遍历），我们正逐条规则减少误报——我们公布实际数据，不会只公布理想数据。

*方法说明：*数据集、严重性统计和逐规则汇总均由我们完成；引擎以封闭镜像形式发布，因此要复现这些结果，需在同一批固定项目上运行 gsc scan --ci --json，并采用相同方式汇总。这并不意味着我们与其他供应商进行了独立环境下的对比。

**许可证：**本仓库（Action、文档、营销内容）采用 Apache-2.0 许可证。引擎以封闭 Docker 镜像 ghcr.io/poliakarmai/gsc-scanner 形式发布，采用 BSL 1.1 许可证（可免费扫描自己的代码仓库；竞争性 SaaS 需要商业许可证；2030-08-06 转为 Apache-2.0）。

案例研究：一个获得 122★ 的 OSINT 平台中的 XSS（截至 2026-08-08 的星标数）

首次公开验证 — stanfrbd/cyberbro（46,677 LOC，281 个文件）：

发现	CWE-79 搜索高亮导致的 XSS — static/history.js:148，p.innerHTML = p.title.replace(...)
严重性	HIGH（CVSS 7.5）
检测器	GS020（gs020_xss_injection）
修复	9 行，1 个文件 — 在沙箱中重新运行利用代码，确认漏洞已无法触发

完整分析 → CASE_STUDY_CYBERBRO.md · 生产环境开源软件中的更多发现 → HALL_OF_FAME.md

---

GSC — 自我学习的全周期 AppSec 平台。

detect → prove → fix → verify → heal → learn

🚀 快速开始 — GitHub Action

只需 30 秒即可检查你的仓库。添加文件 .github/workflows/gsc.yml：

name: GSC Audit
on:
  pull_request:
    branches: [main, master]

jobs:
  audit:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - uses: poliakarmai/gsc@v1   # для воспроизводимости — pin на commit SHA
        with:
          fail_on_critical: false   # true = блокировать merge при CRITICAL

创建 pull request — GSC 将扫描代码，发送包含发现项的评论 （CRITICAL / HIGH），并给出安全评分。核心以 闭源 Docker 镜像 ghcr.io/poliakarmai/gsc-scanner 的形式提供 — 引擎源代码 不会公开。

可复现性。 @v1 和镜像标签都是浮动引用：即使不更改你的工作流，结果也可能 发生变化。进行审计/CI 时，请固定到 poliakarmai/gsc@<commit-sha>，并使用镜像 digest （ghcr.io/poliakarmai/gsc-scanner@sha256:<digest>）。

输入参数：

输入	默认值	作用
path	.	要扫描的内容（仓库根目录）
deep_scan	true	深度扫描（Echelon 4，速度较慢）
fail_on_critical	false	true — 遇到 CRITICAL 时失败
fail_on_score	0	score 低于阈值时失败。0 = 关闭，范围 1–100
max_findings_to_comment	10	每个部分在评论中显示的行数
llm_api_key	''	用于重新验证的 BYO-LLM 密钥（不提供则仅使用 regex）
llm_base_url	''	自定义的 OpenAI 兼容端点（DeepSeek/OpenRouter/Ollama）
llm_model	''	用于重新验证的模型名称
sarif	false	额外生成 SARIF，供 GitHub Code Scanning 使用
reachability	false	降低不可达文件中的发现项等级（import-graph）

输出： score（0–100）和 grade（A+ … F）。

PR 评论按位置（file:line）统计发现项，而不是按检测器触发次数统计：一个被四条规则捕获的密钥，会计为一行并列出规则，而不是四行。表格中的 Total 始终等于各类别之和。

LLM 重新验证 — 使用你自己的密钥（BYO-LLM）：

- uses: poliakarmai/gsc@v1
  with:
    llm_api_key: ${{ secrets.DEEPSEEK_API_KEY }}   # DeepSeek / OpenRouter / GMI / Ollama

不提供密钥 — 快速的 regex-only 扫描（能发现漏洞；confirmed 判定需要密钥）。

功能介绍

层级	功能
SAST	69 个检测器（SAST · SCA · Secrets · IaC）、YAML 规则 DSL、带置信度评分的 LLM 分诊
验证	PoC 自动生成——为发现项生成可运行的漏洞利用程序 （引擎功能；CLI/引擎，不属于 MCP）
修复	Proof-of-Fix——通过在沙盒中重新运行漏洞利用程序来验证补丁；自愈 CI（自动 PR）（CLI，需要显式标志）
优先级排序	EPSS + CISA KEV + ExploitDB（不是原始 CVSS）、БДУ ФСТЭК
Recon	被动侦察：子域名 / 技术栈 / DNS / HTTP
供应链	SBOM（CycloneDX / SPDX）+ VEX
合规性	将发现项映射到 ГОСТ Р 56939-2024、PCI DSS 4.0、SOC2、ISO 27001、CWE、OWASP——生成供 ФСТЭК / КИИ / 审计使用的报告
智能	安全考古分析、预测性预报、自然语言策略、联邦式自学习

各项功能的可用位置。 引擎功能不等同于 Action/MCP 的功能：

功能	Action	MCP	CLI / 引擎镜像
扫描（SAST/SCA/Secrets/IaC）	✅	✅	✅
PoC 自动生成	—	—	✅ (--with-poc)
Proof-of-Fix	—	—	✅ (pof generate)
自愈 CI（自动 PR）	—	—	✅ (--create-pr，需人工审批）

MCP 不提供破坏性操作（自动打补丁/创建 PR）——这是有意为之，这些操作仍留在 CLI/人工流程中。verify_finding 会在沙盒中重新运行 PoC，因此就 副作用而言，它并非“纯只读”。

已实现的功能（代码，而非计划）

机制	位置	功能
基于变异的 PoF 再攻击	gsc_cli/gsc_poc_mutator.py → gsc_proofoffix.py	修复后，以变异形式重新运行 PoC（URL 编码、双重编码、HTML 实体、大小写交换、制表符/空格）——捕获“只修补了症状，未解决根因”的情况。确定性执行，不使用 LLM
正向控制 + 污点复查	gsc_pof_sandbox.py、tests/test_taint_recheck.py	PoC 必须在易受攻击的版本上触发，在已修复的版本上不触发
恶意 PoC 的容器隔离	gsc_pof_sandbox.py::_isolation_backend()	docker/podman（--network none、只读、cap-drop、非 root）+ rlimit 回退；每个结果都会返回隔离级别。公开镜像中没有 docker/podman → 引擎采用 fail-closed 策略：完全不执行 PoC，判定为 unavailable（这不等于“无法复现”）；实际运行 PoC 时，需在装有 docker/podman 的主机上使用 CLI。挂载 docker.sock 并非隔离，而是将主机守护进程交给 PoC
无 LLM 的快速模式	gsc external-scan --scan-mode quick	仅使用正则表达式：返回发现项，不提供 LLM 判定，消耗 0 个令牌

🎯 我们的特色：BYO-LLM——引擎由我们提供，裁判由你选择

GSC 是引擎 + 检测器 + PoC，而不是又一个 LLM 封装层。

• **GSC 提供：**69 个检测器、V3 评分、误报过滤器、PoC/PoF、自学习——闭源 IP 封装在 Docker 镜像中。
• **你提供：**LLM 密钥（任何兼容 OpenAI 的服务——DeepSeek/OpenRouter/GMI/本地 Ollama）。

这对你有利，因为：

• 无需为他人的令牌付费——使用你自己的密钥进行重新验证。
• 不绑定任何服务提供商——甚至可以使用免费的本地 Ollama。
• 你为检测器和逻辑付费，而不是为 LLM 调用付费。

🧠 Второй столп: Self-Learning — детекторы обновляются сами, каждую ночь

Помимо BYO-LLM у GSC есть замкнутый контур обучения без LLM (0 токенов, детерминированный):

скан → авто-разметка findings по calibration-сети (16 проектов: 9 clean + 7 vuln)
     → авто-деактивация шумных паттернов (<30% TP)
     → пополнение эталонов из security-фидов
     → federated feedback (приватно: только {tenant_hash, rule_id, tp, fp} + DP-шум)

Детекторы учатся на реальных находках клиентов через federated-контур — то, чего мейнстрим сознательно избегает (риск дрейфа). GSC обходит это консервативным self-learning: разметка по фиксированной сети + дискретные деактивации, без переписывания весов — скорость ежедневного апдейта без катастрофического дрейфа.

Вендор	Как обновляет правила	Self-learning
Semgrep	вручную (semgrep-rules)	❌
GitHub CodeQL	вручную (Security Lab)	❌
Snyk Code	офлайн-ML, «never customer data»	❌
SonarQube	вручную (SonarSource)	❌
GSC	ежедневно · 0-LLM · federated	✅

Никто не замыкает петлю обучения в проде — GSC закрывает этот зазор. Подробно, с пруф-базой (доки вендоров + research-статьи) → SELF_LEARNING.md.

Честная рамка. GSC не заменяет Semgrep/CodeQL: у них шире покрытие языков и зрелее правила. GSC закрывает то, чего они не делают — доказывает находку PoC, верифицирует фикс перезапуском эксплойта, учится на TP/FP. Рабочая схема — вместе: зрелый сканер на массовый охват + GSC на закрытие конкретных находок.

🔌 Интеграции

MCP — подключи GSC к Claude Code / Cursor / Codex

Движок отдаёт 6 инструментов по MCP (read-only по отношению к репозиторию — не патчит и не делает PR; verify_finding исполняет PoC там, где есть docker/podman — см. границы ниже): scan_repo, scan_diff, list_findings, get_finding, verify_finding, list_detectors. Сервер уже внутри образа — .mcp.json в корне проекта (Claude Code):

{
  "mcpServers": {
    "gsc": {
      "command": "docker",
      "args": ["run", "--rm", "-i",
               "-v", "${PWD}:/repo:ro",
               "-v", "gsc-state:/app/.hermes/state",
               "ghcr.io/poliakarmai/gsc-scanner:v1", "mcp"],
      "env": { "GSC_ALLOWED_ROOTS": "/repo" }
    }
  }
}

Cursor и любой другой MCP-клиент — та же форма (command + args). По умолчанию транспорт stdio; всё не-протокольное идёт в stderr.

HTTP (общий сервер, токен обязателен — fail-closed):

docker run --rm -p 8001:8001 -e GSC_MCP_TOKEN=your-secret \
  ghcr.io/poliakarmai/gsc-scanner:v1 mcp --transport http --host 0.0.0.0 --port 8001

⚠️ На том конце — агент, и честно о границах:

• Деструктивных действий нет: ни auto-patch, ни PR — они в CLI/human-лупе.
• verify_finding не исполняет PoC в этом образе. Гейты в коде реальные (DESTRUCTIVE-PoC и недетерминированный PoC отклоняются), а без OS-изоляции движок fail-closed: docker/podman внутри нет → PoC не запускается вовсе, тул отвечает status: "unavailable" + hint. Это не «не воспроизводится»: о самой находке такой ответ не говорит ничего. Реальный прогон — CLI на хосте с docker/podman. Проброс docker.sock — не изоляция, а выдача PoC хостового демона (эквивалент root): не делать.
• scan_repo ограничен бюджетом: GSC_SCAN_TIMEOUT (default 300 с) на свип детекторов, GSC_MAX_FILES (default 50 000) на инвентарь. Упёрлись в лимит — в ответе status: "partial", truncated: true и список детекторов, которые не запускались. Мало находок там не значит «чисто»; такой скан в БД не сохраняется.
• GSC_ALLOWED_ROOTS ограничивает scan_repo/scan_diff смонтированными путями.
• scan_repo сохраняет находки в БД (persisted: true в ответе), поэтому list_findings и get_finding их видят сразу. get_finding отвечает из БД (source: "database"), без пересканирования; ~30–60 с — только если ключа в БД нет и он пересобирает скан.
• Нужен writable volume на /app/.hermes/state — там SQLite. Docker создаёт volume от root, а процесс идёт под uid 999, поэтому сначала отдайте права: docker run --rm -v gsc-state:/s --user 0 <image> chown -R 999:999 /s. Без этого scan_repo вернёт persisted: false (скан работает, БД — нет), а --read-only вообще не годится.
• Без llm_api_key/DEEPSEEK_API_KEY работают только regex-детекторы.

Paperclip — «найми GSC как сотрудника по безопасности»

Paperclip (79K★, open-source оркестратор AI-агентов) подключает GSC через MCP Tool Gateway — любой нанятый агент (Claude Code / Codex / Hermes) получает GSC-инструменты и роль «Security Engineer».

📦 Интеграция идёт через MCP-сервер образа (см. раздел MCP выше). Гайд и skill gsc-security-review поставляются с коммерческим доступом (репозиторий gsc-core, docs/integrations/paperclip/) — в публичном репо их нет.

• Транспорт: local_stdio (subprocess) или mcp_remote (HTTP)

Подключение за минуты: зарегистрируй ToolStdioCommandTemplate, создай gateway — и GSC сканирует репозитории твоей Paperclip-компании.

Лицензия и доступ

Этот репозиторий (GitHub Action, документация, маркетинг) — Apache License 2.0. Свободно используйте Action в своих репозиториях.

Движок GSC (детекторы, PoC/PoF, калибровочная сеть, LLM-слой) поставляется отдельно как закрытый Docker-образ ghcr.io/poliakarmai/gsc-scanner под Business Source License 1.1 (BSL 1.1):

• Свободное использование — включая сканирование собственных репозиториев в production — разрешено всегда.
• Коммерческий SaaS/SAST-сервис для третьих лиц, конкурирующий с GSC, — требует коммерческой лицензии (после NDA).
• Change Date 2030-08-06 → движок автоматически переходит на Apache 2.0.

Для демо, пилота или приобретения — свяжитесь с автором.

© 2026 Алексей Поляков.