🛡️ GSC — Git Security Checker

English
GSC is a self-learning AppSec platform that proves exploits, verifies fixes, and heals CI.
detect → prove → fix → verify → heal → learn
$ gsc scan . --ci --json
[{"rule_id": "GS001", "severity": "CRITICAL", "title": "Hardcoded API key",
"file_path": "app.py", "line": 1, "fix_suggestion": "Move this value to an env var"}]
Most scanners report matches. GSC proves them: every finding can be turned into a
runnable proof-of-concept, validated in a sandbox, then fixed and re-verified by
re-running the exploit.
What makes it different:
- 73 detectors (69 rules + 4 engines) across SAST, SCA, secrets and IaC — plus a YAML rule DSL.
- PoC auto-generation with a safe-exploitation gate: a finding ships with a working exploit, not just a line number.
- Proof-of-Fix — a patch is only accepted after the exploit stops firing in a sandbox.
- Self-learning — detectors are re-scored nightly against a calibration network; noisy patterns are auto-deactivated at <30% TP. Federated feedback is privacy-first (
{tenant_hash, rule_id, tp, fp} + DP noise).
- Priority by exploitability, not CVSS — EPSS + CISA KEV + ExploitDB.
- BYO-LLM — the engine, detectors and PoC logic are ours; LLM revalidation runs on your key (any OpenAI-compatible endpoint, including a local Ollama). No key → fast regex-only mode.
Who it is for: platform/DevSecOps teams that need findings proven before a PR blocks;
AppSec engineers triaging noisy regex output; AI coding agents that need a scanner tool over MCP.
Use it as a GitHub Action (see below), from the CLI / Docker image, or as an
MCP server for AI coding agents — ten tools (scan_repo, scan_diff,
list_findings, get_finding, get_poc, verify_finding, verify_findings,
verify_fix, doctor, list_detectors) over stdio or HTTP.
Read-only towards your repository: no patching, no PRs, no writes to the working tree.
(verify_finding does execute a PoC — see the safety notes in the MCP section.)
Proven on real code: HALL_OF_FAME.md ·
first public case study: CASE_STUDY_CYBERBRO.md
Measured on 100 real GitHub projects
The same fixed corpus is re-scanned after detector changes — 100 real repositories
(90 clean + 10 known-vulnerable), pinned to specific commits, regex-only, no LLM key.
Same projects every run, so a delta is the fix and not a new dataset.
| 2026-08-21 (baseline) | 2026-08-28 (after FP fixes) |
|---|
| Findings | 64,831 | 41,127 |
| CRITICAL | 4,302 | 414 |
| HIGH | 37,246 | 2,187 |
| Known-vulnerable projects flagged | 8 / 10 | 10 / 10 |
| Clean projects with ≥1 false CRITICAL | 48 / 90 | 41 / 90 |
CRITICAL precision on a labeled review of 434 findings: ~4–5% at baseline → 31.1%
(TP = 135, FP = 299, 2026-08-26). That is still noisy. The remaining false-positive mass is
concentrated in GS001 (secrets), GS005 (SQLi), GS020 (XSS) and GS037 (path traversal) and is
worked down rule by rule — we publish the numbers we have, not the numbers we would like.
Method note: corpus, severity counting and per-rule aggregation are ours; the engine ships as
a closed image, so reproducing this means running gsc scan --ci --json over the same pinned
projects and aggregating the same way. No clean-room comparison against other vendors is implied.
License: this repo (Action, docs, marketing) is Apache-2.0. The engine ships as a
closed Docker image ghcr.io/poliakarmai/gsc-scanner under BSL 1.1 (free to scan your own
repos; competing SaaS requires a commercial license; converts to Apache-2.0 on 2030-08-06).
First public proof — stanfrbd/cyberbro (46,677 LOC, 281 files):
| |
|---|
| Finding | CWE-79 XSS via search highlight — static/history.js:50, p.innerHTML = p.title.replace(...) |
| Severity | MEDIUM (CVSS 5.4) — reflected XSS без аутентификации |
| Detector | GS020 (gs020_xss_injection) |
| Fix | 9 lines, 1 file — exploit re-run in sandbox confirms it no longer fires |
Full write-up → CASE_STUDY_CYBERBRO.md ·
more findings in production OSS → 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
with:
fail_on_critical: false
Откройте pull request — GSC отсканирует код, пришлёт комментарий с находками
(CRITICAL / HIGH) и поставит оценку безопасности. Ядро поставляется как
закрытый Docker-образ ghcr.io/poliakarmai/gsc-scanner — исходный код движка
не публикуется.
Воспроизводимость. @v1 и тег образа — плавающие ссылки: результат может
измениться без изменения вашего workflow. Для аудита/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-only) |
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 }}
Без ключа — быстрый regex-only скан (уязвимости находит; confirmed-вердикты — с ключом).
Локально: CLI или Docker
gsc scan . --ci --json
gsc scan . --fail-on-blocking
docker run --rm -v "$PWD:/repo:ro" ghcr.io/poliakarmai/gsc-scanner:v1 scan /repo --ci --json
scan — точка входа; pof (Proof-of-Fix), verify-fix, report, --compliance …
и остальные ≈80 подкоманд — в gsc --help.
Что умеет
| Слой | Возможности |
|---|
| SAST | 73 детектора (69 правил + 4 движка) в SAST · SCA · Secrets · IaC, YAML rule DSL, LLM-триаж с confidence scoring |
| Доказательство | PoC auto-generation — рабочий эксплойт для находки (CLI --with-poc, MCP get_poc/verify_finding) |
| Исправление | Proof-of-Fix — патч верифицируется перезапуском эксплойта в sandbox; self-healing CI (авто-PR) (CLI, требует явного флага) |
| Приоритизация | EPSS + CISA KEV + ExploitDB (не сырой CVSS), БДУ ФСТЭК |
| Recon | passive reconnaissance: subdomain / tech / DNS / HTTP |
| Supply chain | SBOM (CycloneDX / SPDX) + VEX |
| Compliance | маппинг находок на ГОСТ Р 56939-2024, PCI DSS 4.0, SOC2, ISO 27001, CWE, OWASP — отчёт для ФСТЭК / КИИ / аудита |
| Интеллект | security archaeology, predictive forecasting, NL-policy, federated self-learning |
Где что доступно. Возможности движка не равны возможностям Action/MCP:
| Возможность | Action | MCP | CLI / engine image |
|---|
| Скан (SAST/SCA/Secrets/IaC) | ✅ | ✅ | ✅ |
| PoC auto-generation | — | ✅ (get_poc, verify_finding) | ✅ (--with-poc) |
| Proof-of-Fix | — | ✅ (verify_fix) | ✅ (pof generate) |
| Self-healing CI (авто-PR) | — | — | ✅ (--create-pr, human-approval) |
В MCP нет деструктивных действий (auto-patch/PR) — осознанно, они остаются
в CLI/human-лупе. verify_finding перезапускает PoC в sandbox, то есть по
побочным эффектам это не «чисто read-only».
Что уже внутри (код, а не план)
Исходники движка в публичном репо не публикуются (закрытый образ, BSL 1.1) — колонка «Где» называет модуль, а не путь в этом репозитории.
| Механика | Где | Что делает |
|---|
| Мутационный re-attack PoF | движок: PoC-мутатор → Proof-of-Fix | после фикса PoC перезапускается в мутированных формах (url-encode, double-encode, HTML-entities, case-swap, tab/space) — ловит «залатали симптом, а не причину». Детерминированно, без LLM |
| Positive control + taint-recheck | движок: PoF-sandbox + taint-recheck тесты | PoC обязан срабатывать на уязвимом варианте и молчать на исправленном |
| OS-изоляция hostile-PoC | движок: _isolation_backend() | docker/podman (--network none, read-only, cap-drop, non-root) на хосте, bubblewrap внутри образа (--unshare-all: mount/pid/net/user/ipc/uts, --clearenv, read-only системные деревья, writable только workspace, --die-with-parent) — докер-демон и проброс сокета не нужны. Уровень изоляции (docker / podman / bwrap) возвращается в каждом результате и в ответе verify_finding (isolation); без OS-изоляции движок fail-closed и отвечает unavailable, а не «не воспроизводится» |
| Quick-режим без LLM | CLI: gsc external-scan --scan-mode quick | regex-only: находки без LLM-вердиктов, 0 токенов |
🎯 Наша фишка: BYO-LLM — движок наш, судья твой
GSC — это движок + детекторы + PoC, а не очередная обёртка над LLM.
- От GSC: 73 детектора, V3-scoring, FP-фильтр, PoC/PoF, self-learning — закрытый IP в Docker-образе.
- От вас: LLM-ключ (любой OpenAI-совместимый — DeepSeek/OpenRouter/GMI/локальный Ollama).
Почему это выгодно вам:
- Ноль расходов на чужие токены — ревалидация на вашем ключе.
- Никакой привязки к провайдеру — хоть бесплатный локальный Ollama.
- Вы платите за детекторы и логику, а не за вызовы LLM.
🧠 Второй столп: Self-Learning — детекторы обновляются сами, каждую ночь
Помимо BYO-LLM у GSC есть замкнутый контур обучения без LLM (0 токенов, детерминированный):
скан → авто-разметка findings по calibration-сети (13 проектов: 9 clean + 4 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
Движок отдаёт 10 инструментов по MCP (read-only по отношению к репозиторию — не патчит
и не делает PR; verify_finding исполняет PoC в bubblewrap-песочнице внутри образа — см. границы ниже): scan_repo,
scan_diff, list_findings, get_finding, get_poc, verify_finding, verify_findings,
verify_fix, doctor, list_detectors.
Сервер уже внутри образа — .mcp.json в корне проекта (Claude Code):
{
"mcpServers": {
"gsc": {
"command": "docker",
"args": ["run", "--rm", "-i",
"--security-opt", "seccomp=unconfined",
"--security-opt", "apparmor=unconfined",
"-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 127.0.0.1:8001:8001 -e GSC_MCP_TOKEN=your-secret \
ghcr.io/poliakarmai/gsc-scanner:v1 mcp --transport http --host 0.0.0.0 --port 8001
⚠️ --host 0.0.0.0 слушает все интерфейсы контейнера: порт привязан к 127.0.0.1 намеренно.
Нужен доступ извне — ставьте перед сервером reverse-proxy с TLS, не публикуйте -p 8001:8001
в интернет: эндпоинт исполняет PoC.
⚠️ На том конце — агент, и честно о границах:
- Деструктивных действий нет: ни auto-patch, ни PR — они в CLI/human-лупе.
verify_finding исполняет PoC в этом образе — через bubblewrap
(--unshare-all: mount/pid/net/user/ipc/uts, --clearenv, read-only системные
деревья, writable только workspace). Докер-демон не нужен, проброс docker.sock
не нужен и запрещён (это выдача PoC хостового демона, эквивалент root).
Для user-namespace контейнеру нужны --security-opt seccomp=unconfined --security-opt apparmor=unconfined; без них тул честно отвечает
status: "unavailable" (PoC не запускался — это не вердикт о находке).
В ответе есть isolation (bwrap / docker / podman) и exploit_success.
- PoC прикрепляется к находке при скане: сначала детерминированный шаблон
(curl-payload под класс уязвимости — работает и в regex-only режиме, без
LLM-ключа и без
confidence), затем LLM-PoC для находок с confidence ≥ 0.80.
Шаблоны есть под XSS/SSTI, command injection, SQLi, path traversal, SSRF, IDOR,
deserialization, XXE, open redirect; DESTRUCTIVE-шаблоны не прикрепляются никогда.
Если PoC нет вообще — verify_finding отвечает error_code: "UNAVAILABLE" с
текстом «no PoC attached», и это тоже не «не воспроизводится».
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. Каталог уже есть в
образе и принадлежит uid/gid 999, поэтому -v gsc-state:/app/.hermes/state работает
сразу. Ритуал chown нужен только для томов, созданных до v1.4.1 (там каталог от root):
docker run --rm -v gsc-state:/s --user 0 <image> chown -R 999:999 /s, либо просто
docker volume rm gsc-state и создать заново. Без этого scan_repo вернёт
persisted: false (скан работает, БД — нет), а --read-only вообще не годится.
- Без
llm_api_key/DEEPSEEK_API_KEY работают только regex-детекторы.
Paperclip — «найми GSC как сотрудника по безопасности»
Paperclip (107K★, 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.
Для демо, пилота или приобретения — свяжитесь с автором.
Участие и безопасность: CONTRIBUTING.md (PRs welcome) ·
SECURITY.md — приватный канал для уязвимостей, не публичный issue.
© 2026 Алексей Поляков.