GSC Scanner

🛡️ GSC — Git Security Checker

[GSC on GitHub Marketplace] [Plugin Security Scan] [License: Apache-2.0]

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:

• 67 detectors 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.

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).

Case study: XSS in a 698★ OSINT platform (stars as of 2026-10-26)

First public proof — stanfrbd/cyberbro (46,677 LOC, 281 files):

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 Auditon:  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 и тег образа — плавающие ссылки: результат может измениться без изменения вашего workflow. Для аудита/CI фиксируйте poliakarmai/gsc@<commit-sha> и образ по digest (ghcr.io/poliakarmai/gsc-scanner@sha256:<digest>).

Входные параметры:

Выходы: 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-вердикты — с ключом).

Локально: CLI или Docker

gsc scan . --ci --json          # JSON-находки в stdoutgsc scan . --fail-on-blocking   # exit 1 при CRITICAL/HIGH — гейт для pre-commit / CI

# тот же движок без установки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.

Что умеет

Где что доступно. Возможности движка не равны возможностям 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) — колонка «Где» называет модуль, а не путь в этом репозитории.

🎯 Наша фишка: BYO-LLM — движок наш, судья твой

GSC — это движок + детекторы + PoC, а не очередная обёртка над LLM.

• От GSC: 67 детекторов, 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: разметка по фиксированной сети + дискретные деактивации, без переписывания весов — скорость ежедневного апдейта без катастрофического дрейфа.

Никто не замыкает петлю обучения в проде — 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 Алексей Поляков.