agentleFS
poliakarmaipoliakarmai/gsc/skills/gsc-scan/SKILL.md

gsc-scan

Skill17 starsChanged yesterdayApache-2.0View on GitHub

Use when scanning a repo or PR with GSC and reading the coverage-aware report.

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 1 is distinctive, and 3 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.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read scan_status first: ok or partial.

    line 54
  2. Distinctive:

    Read the coverage block before trusting any verdict:

    line 55
  3. Very specific:

    Do not report "clean" on an empty finding list while detectors_not_run is non-empty — that is an incomplete scan, not a pass.

    line 68
  4. Very specific:

    No PoC attached ≠ false positive: several classes (e.g.

    line 74

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill 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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

GSC Scan

When to use

You are asked to scan a repository, a local path, or a pull request diff for vulnerabilities, secrets, dependency issues, or IaC misconfigurations with GSC, and to interpret the resulting report. GSC is a SAST engine with PoC verification; the engine runs from the Docker image ghcr.io/poliakarmai/gsc-scanner:v1 (BUSL 1.1), the Action poliakarmai/gsc@v1 is Apache 2.0.

Commands

GitHub Action — one file, zero config (.github/workflows/gsc.yml):

name: GSC Audit
on:
  pull_request:
    branches: [main, master]      # must match your default branch, else it never fires
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
          # fail_on_score: 80      # fail the PR when the score drops below this
          # sarif: true            # also emit SARIF for GitHub Code Scanning

CLI in Docker:

docker run --rm -v "$PWD:/repo:ro" -w /repo \
  ghcr.io/poliakarmai/gsc-scanner:v1 scan . --ci --json

Useful Action inputs: path (default .), deep_scan (default true), fail_on_critical, fail_on_score (0 = off, 1–100), max_findings_to_comment (default 10), sarif, reachability, and BYO-LLM llm_api_key / llm_base_url / llm_model (without a key the engine runs regex-only).

How to read the result

  1. Read scan_status first: ok or partial.
  2. Read the coverage block before trusting any verdict:
    • files_scanned / files_total / files_truncated — how much of the tree was seen;
    • detectors_total / detectors_ran / detectors_not_run — which detectors executed.
  3. scan_status: partial (a cap hit, not a crash) means a low finding count is not a clean repo. Say which detectors did not run.
  4. Per finding, check whether a PoC is attached. Two layers: a deterministic template (works without an LLM key, no confidence gate) and an LLM PoC for findings with confidence >= 0.80.
  5. verify_finding answers status: "unavailable" when the sandbox cannot start or no PoC is attached. That is not a verdict about the finding.

Pitfalls

  • Do not report "clean" on an empty finding list while detectors_not_run is non-empty — that is an incomplete scan, not a pass.
  • pr-gate / diff mode only sees changed files; it can never give a whole-repo verdict. Use a full scan for that.
  • scan_repo is bounded by GSC_SCAN_TIMEOUT (default 300 s) and GSC_MAX_FILES (default 50 000). A truncated scan is not persisted.
  • No PoC attached ≠ false positive: several classes (e.g. hardcoded secrets) have no deterministic template, and UNAVAILABLE is the honest answer.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.