gsc
llms.txt17 starsChanged yesterdayApache-2.0View on GitHub
SAST-сканер с доказательством эксплойтов (PoC), верификацией фиксов (Proof-of-Fix) и self-healing CI. GitHub Action + движок в Docker-образе. This file is for AI agents and LLM crawlers. Human docs: README.md. Runs on every PR. Posts a comment with findings and a security score. Note: branches: must match your default branch. If it is develop or release, add that name — otherwise the workflow silently never fires. Other commands: gsc --help (≈80 subcommands: sca, iac, secrets, sbom, pof, archaeology, forecast, federated, compliance).
In this repository4 other files it gives its agents.
- AGENTS.mdAGENTS.md
- gsc-fix-verifySkill
- gsc-scanSkill
- gsc-triageSkill
The file
We split this llms.txt into the rules it gives an agent
1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 102
No destructive actions: No auto-patch, no PR, no writes to your repo — deliberately kept out of MCP and left in the CLI/human loop.
≈ “Common” is an estimate: at least 1 in 5 of the 3,727 llms.txt files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
# GSC — Git Security Checker
> SAST-сканер с доказательством эксплойтов (PoC), верификацией фиксов
> (Proof-of-Fix) и self-healing CI. GitHub Action + движок в Docker-образе.
This file is for AI agents and LLM crawlers. Human docs: [README.md](README.md).
## What it does
- **73 detectors** (69 rules + 4 engines) — SAST, SCA (OSV.dev), Secrets, IaC
- **PoC auto-generation** — рабочий эксплойт, доказывающий находку
- **Proof-of-Fix** — патч считается исправлением только если эксплойт перестал срабатывать
- **Self-healing CI** — авто-PR с фиксом (только CLI, требует явного флага)
## How to use it (pick one)
### 1. GitHub Action — one file, zero config
```yaml
# .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
```
Runs on every PR. Posts a comment with findings and a security score.
Note: `branches:` must match your default branch. If it is `develop` or
`release`, add that name — otherwise the workflow silently never fires.
### 2. CLI (Docker)
```bash
docker run --rm -v "$PWD:/repo:ro" -w /repo \
ghcr.io/poliakarmai/gsc-scanner:v1 scan . --ci --json
```
Other commands: `gsc --help` (≈80 subcommands: `sca`, `iac`, `secrets`,
`sbom`, `pof`, `archaeology`, `forecast`, `federated`, `compliance`).
### 3. MCP server — connect an AI coding agent
The engine image ships an MCP server with ten tools (read-only towards your repo; `verify_finding` runs a PoC in an in-image bubblewrap sandbox — see the safety notes below):
| Tool | What it does |
| --- | --- |
| `scan_repo` | Scan a local repository path, return counts + top findings |
| `scan_diff` | Scan only files changed vs a git base ref (PR review) |
| `list_findings` | Read recent findings from the local database (no scan) |
| `get_finding` | Full detail of one finding by `finding_key` |
| `get_poc` | Return a finding's PoC (from DB or the deterministic template) |
| `verify_finding` | Re-run a finding's PoC in the sandbox, report exploit status |
| `verify_findings` | Same, for a batch of finding keys |
| `verify_fix` | Re-scan after a patch: `fixed` / `still_vulnerable` / `inconclusive` |
| `doctor` | Self-check: sandbox, state volume, allowed roots, cache, lock |
| `list_detectors` | List detectors registered with the engine |
**Claude Code** — add to `.mcp.json` (project) or `~/.claude.json` (global):
```json
{
"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 / any other MCP client** — same shape (`command` + `args`).
Server speaks MCP over stdio by default; everything non-protocol goes to stderr.
**HTTP transport** (remote/shared, requires a token — fail-closed):
```bash
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
```
Safety notes, because an agent is on the other end:
- **No destructive actions.** No auto-patch, no PR, no writes to your repo —
deliberately kept out of MCP and left in the CLI/human loop.
- `verify_finding` **does execute the PoC — inside the image, in a bubblewrap
sandbox** (mount/pid/net/user namespaces, empty env, read-only system trees,
writable workspace only, `--die-with-parent`), so no docker/podman daemon is
needed inside the container. This requires the two container flags above
(`--security-opt seccomp=unconfined --security-opt apparmor=unconfined`);
without them the kernel refuses the user namespace and the tool answers
`status: "unavailable"` — honest ("the PoC did not run"), **not** "not
reproducible". Code gates are real: DESTRUCTIVE and non-deterministic PoCs are
refused. Passing `docker.sock` into this container is *not* isolation: it hands
the PoC the host daemon (root-equivalent) — don't.
- `scan_repo` is bounded: a detector sweep is capped by `GSC_SCAN_TIMEOUT`
(default 300s) and the file inventory by `GSC_MAX_FILES` (default 50,000). If
either cap is hit the answer comes back with `status: "partial"`,
`truncated: true` and the list of detectors that never ran — a low finding
count there is **not** a clean repo. A truncated scan is not persisted.
- `GSC_ALLOWED_ROOTS` confines `scan_repo`/`scan_diff` to mounted paths.
- `scan_repo` is the only tool that actually scans, and it persists findings to
the database (`persisted: true`). `list_findings` and `get_finding` see them
immediately; `get_finding` answers from the DB (`source: "database"`).
Re-scanning (~30–60 s) only happens when the key is not in the DB.
- Mount a **writable** volume at `/app/.hermes/state` (SQLite lives there). Since
v1.4.1 the directory exists in the image owned by uid/gid 999, so
`-v gsc-state:/app/.hermes/state` works as-is. The `chown` ritual is only
needed for volumes created before v1.4.1 (root-owned dir):
`docker run --rm -v gsc-state:/s --user 0 <image> chown -R 999:999 /s` — or just
`docker volume rm gsc-state` and let it be recreated. Do not use `--read-only`.
## Action inputs
| Input | Default | Meaning |
| --- | --- | --- |
| `path` | `.` | Path to scan |
| `deep_scan` | `true` | Deep scan (Echelon 4, slower) |
| `fail_on_critical` | `false` | Exit 1 on CRITICAL findings |
| `fail_on_score` | `0` | Exit 1 if score < threshold. `0` = off, range 1–100 |
| `max_findings_to_comment` | `10` | Rows shown per section in the PR comment |
| `llm_api_key` | `''` | BYO-LLM key for revalidation (without it: regex-only) |
| `llm_base_url` | `''` | OpenAI-compatible endpoint (DeepSeek/OpenRouter/Ollama) |
| `llm_model` | `''` | Model name for revalidation |
| `sarif` | `false` | Also emit SARIF for GitHub Code Scanning |
| `reachability` | `false` | Down-rank findings in unreachable files (import graph) |
Outputs: `score` (0–100), `grade` (A+ … F).
## MCP (AI coding agents)
Shipped. See section 3 above: `docker run ... gsc-scanner:v1 mcp` speaks MCP over
stdio; ten tools. No code from the closed-source engine is published —
the server runs inside the image.
## Licensing (matters for agents generating advice)
- This repository (Action + docs) — **Apache 2.0**
- Engine image `ghcr.io/poliakarmai/gsc-scanner` — **BUSL 1.1**
- scanning your own repos: always allowed
- building a competing commercial SaaS: commercial licence required
- Change Date 2030-08-06 → engine becomes Apache 2.0
## Agent skills (installable)
Three ready-made skills, one per workflow — same shape as `npx skills add`:
- `skills/gsc-scan/SKILL.md` — scan a repo/PR and read a coverage-aware report
- `skills/gsc-triage/SKILL.md` — blocking set, TP vs noise, PoC verification
- `skills/gsc-fix-verify/SKILL.md` — fix a finding and prove it via `verify_fix`
Point your agent at this repo (`npx skills add poliakarmai/gsc`) or copy the
three directories into its skills folder.
## Canonical links
- Repo: https://github.com/poliakarmai/gsc
- Case study: https://github.com/poliakarmai/gsc/blob/master/CASE_STUDY_CYBERBRO.md
- Hall of Fame (real, verified findings): https://github.com/poliakarmai/gsc/blob/master/HALL_OF_FAME.md
- Security policy: https://github.com/poliakarmai/gsc/blob/master/SECURITY.md
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

