SPHIOR CODE logo

SPHIOR CODE

0

sphior-code plugin for Cursor

4 skills

fix-security-findings

Find and fix security problems in the current codebase with SPHIOR CODE — hard-coded secrets, insecure patterns mapped to CWE, and taint flows (untrusted input reaching a shell, SQL, eval, HTML, file-path or URL sink). Use when the user says things like "scan this project", "check this for vulnerabilities", "fix the security issues", "is there a SQL injection here", "any hard-coded keys?", or asks for a security review of a file or directory.

# Fix security findings with SPHIOR CODE SPHIOR CODE finds the problems deterministically; **you** write the fix. The scanner never generates code and never uploads source. It returns the location and the remediation, and you read the real code from the workspace you already have. ## Step 1 — Get the findings Use the first option that is available. **A. The `sphior-code` MCP server**, if it is connected (the Cursor plugin installs it; in Claude Code the user adds it with `claude mcp add sphior-code -- npx -y sphior-code-mcp`). Call `get_fix_context`. - No arguments → scans the directory this session is working in. - `path` → scan one directory instead. On a large repository, start narrow. - `severity` → `critical` / `high` / `medium` / `low`. **B. The command line** (Node.js 18+). Write the fix context to a temporary directory, outside the repository, and read it: ```bash OUT=$(mktemp -d) npx -y @sphior/scan@0.1.9 run <dir> --fix-context "$OUT/fix.json" ``` If the project's CI pins a version (`@sphior/scan@x.y.z`), use the same one so your result matches CI. The file is a JSON array with one entry per place to fix, most severe first. Exit code `2` means nothing was scanned (missing directory or a bad option) — never report that as a clean result. **C. Neither can run here** (no terminal, no network). Ask the user to run the command in B on their machine and attach the file, or the output of `--json`. Work from that file. All three need no account and send no source code anywhere. ## Step 2 — Read what came back Each entry is one **place to fix**, not one rule hit: | Field | Use it for | |---|---| | `location` | `path`, `start_line`, `end_line`. **Read the real code yourself** — it is not in the payload. | | `rule_id` | The rule. Ids starting with `taint.` are data-flow findings: untrusted input reaches this line from somewhere else in the file. | | `why`, `summary` | Why it matters. Fix the cause, not the symptom. | | `remediation_steps` | The concrete steps. Follow them, with the exceptions in Step 3. | | `also` | **Other findings on the same line** (`rule_id`, `title`, `severity`, `cwe`). One edit must satisfy all of them; their steps are already merged into `remediation_steps`. | | `masked_preview` | A masked secret (`sk_…tY`). Never print, log, or commit the real value. | | `severity`, `confidence` | Work from `critical` down. `confirmed` means the construct itself is the problem. | | `agent_instructions` | Guardrails for you: do not dismiss the finding, never expose a secret, a human reviews the change. | | `cwe`, `owasp`, `references` | Background when you need it. | ## Step 3 — The loop 1. Get the findings (Step 1). 2. For each entry, open `location.path` at `location.start_line` and read the surrounding code. For a `taint.` finding, find where the input comes from before editing. 3. Apply `remediation_steps`. If `also` is non-empty, your single edit must clear every finding listed there — not only the first. - **Never rewrite git history** (`git filter-repo`, BFG, force-push), even if a step mentions it. Tell the user instead; it is their decision. - If a step cannot be done here (for example a regression test that needs packages that are not installed), say so in your report rather than skipping it silently. 4. **Scan again to confirm the findings are gone.** 5. Run the project's own tests, and check that they actually load the files you changed. If no test exercises the changed code, say **"the change is untested"** — do not report "tests pass" as if it covered the fix. Steps 4 and 5 are both required. Passing one without the other means nothing. ## Fixing well, not just quietly - **Hard-coded secret** — remove it from source and read it from the environment or a secret manager. Then tell the user, in plain words, that **the exposed value must be rotated**: it is in git history and should be treated as already compromised. You cannot rotate it for them. - **Command injection** — use `execFile` / `spawn` / `subprocess.run([...])` with an argument array. Never build a shell string from input. Put `--` before user-controlled arguments. - **SQL / NoSQL injection** — parameterised queries with bound values, in the placeholder style of the database client the project uses. Never concatenate. - **`eval` / dynamic code** — replace with data parsing or an explicit, non-executing lookup. Do not "sanitise" the input and keep `eval`. - **XSS** — use the framework's escaping or a text API (`textContent`), not `innerHTML` or raw `res.send` of input. - **Path traversal** — resolve the path, then check it stays under an allowed base directory; or map an identifier to a known file instead of taking a path. - **SSRF** — allow-list the destination host and scheme; do not fetch arbitrary URLs from input. - **Unsafe deserialization** — use a data-only format (JSON) or a safe loader (`yaml.safe_load`). Never `pickle` untrusted bytes. - **Weak crypto / disabled TLS verification** — use a current algorithm (SHA-256+, AES-GCM) and keep certificate verification on. Keep behaviour the same unless the fix requires a change; if it does, say what changed. ## Rules - Never make a finding disappear without fixing it: no ignore comment, no `.sphiorignore` entry, no narrowing of a rule, no deleted test. If a finding is genuinely not a problem, stop and use the **triage-security-findings** skill, which records the reason for a human. - Never print or commit a raw secret, including in a commit message or a log line. - Detection is deterministic — the same code and scanner version always produce the same findings. If a finding looks wrong, say so to the user with your reasoning; do not silently skip it. - **A human reviews before merge.** Say what you changed, what is untested, and what still needs their action (rotating a credential, for example). ## What the scan covers - **14 languages**, parsed with real grammars: JavaScript, TypeScript (+ JSX/TSX), Python, Go, PHP, Ruby, Java, C#, Rust, Kotlin, C, C++, Scala, Swift. - **Secrets** in every text file, including `.env*` and `*.example` — but only the current files, not git history. - **Insecure patterns mapped to CWE** in all 14 languages. - **Taint analysis** in 13 languages, followed across functions **within one file**. Flows that cross files, or pass through closures and callbacks, are not followed. - **Not covered:** dependency vulnerabilities (the local scan reads source, not lockfiles) and anything at runtime. Do not tell the user a clean scan means the application is secure.

pre-release-security-check

Run a SPHIOR CODE security gate before a release, merge or deploy and give a clear ready / not-ready verdict — no exposed secrets and no open critical or high findings. Use when the user says "is this ready to ship", "check before release", "pre-merge security check", "can I deploy this", "final security pass", or is about to tag a version or open a release pull request.

# Pre-release security check A short, repeatable gate. You run one deterministic scan, apply fixed criteria, and report a verdict with the evidence behind it. The same code and scanner version always give the same verdict. ## Step 1 — Run the scan From the repository root (Node.js 18+), or the directory being released. If the project's CI pins a scanner version, use the same one. Write outside the repository: ```bash OUT=$(mktemp -d) npx -y @sphior/scan@0.1.9 run . --json "$OUT/open.json" --suppressed "$OUT/accepted.json" ``` Keep the summary line from standard error: it records files scanned, files excluded, accepted findings, and the engine and ruleset versions. Those go into the report. **Stop and report "not checked"** if: - the exit code is `2` (missing directory or a bad option — nothing was scanned), or - the summary says no files were scanned. Neither is a pass. ## Step 2 — Apply the criteria | Check | Pass when | |---|---| | Exposed secrets | **Zero open** findings with `kind: "sast_secret"` in `open.json`, at any severity | | Serious findings | **Zero open** findings with severity `critical` or `high` in `open.json` | | Accepted findings | Every entry in `accepted.json` has `suppression.justification` | | Excluded paths | Report the "files excluded" count. List `.sphiorignore` lines without a rule id and flag any that are not generated or vendored code | | Medium and below | Reported, not blocking — unless the user set a stricter bar | If the project already has a CI threshold (`--fail-on` in its workflow), say whether this result would pass it. If it has a scan step without `--fail-on`, point out that its CI never fails on findings. ## Step 3 — Report the verdict Start with one line: **Ready** or **Not ready**. Then: - Counts by severity, files scanned and excluded, engine and ruleset versions. - **Blocking items**, each as `file:line — title (rule id, CWE)`. - Accepted findings: how many, and any without a reason. - Excluded paths that look like hand-written code. - Non-blocking medium and low findings, summarised. - **Needs action even if Ready:** any secret removed from source in this branch is still in git history. List it under "rotate this credential" — a clean scan of the current files does not make it safe. Keep it factual. Do not soften a "not ready". ## Step 4 — If it is not ready Offer to fix the blocking items with **fix-security-findings**, then run this check again. For a finding the user believes is not a problem, use **triage-security-findings** so the decision is recorded with a reason. Never change `.sphiorignore`, add ignore comments, or raise a threshold to turn "not ready" into "ready". ## What this check does not cover Say this in the report, briefly: - **Dependencies are not checked.** The scan reads source files, not lockfiles. Run the package manager's audit (`npm audit`, `pip-audit`, `govulncheck`, …) or a dependency scanner as well. - Git history is not scanned; data flow is followed within a file, not across files. - It is a source-code check, not a penetration test, and it is not a compliance verdict.

setup-security-ci

Add SPHIOR CODE security scanning to a project's CI — fail the build on serious findings and publish SARIF to GitHub code scanning. Use when the user asks to "add security scanning to CI", "scan every pull request", "block merges with secrets or vulnerabilities", "set up SAST in GitHub Actions / GitLab CI", or wants findings in the GitHub Security tab.

# Set up SPHIOR CODE in CI The goal is a CI step that runs the same deterministic scan on every push and pull request, fails when something serious appears, and leaves a report people can read. You write the CI configuration; the scanner itself needs no account, no key and no network access beyond installing the package. ## Step 1 — Learn the project - Find the CI system: `.github/workflows/` (GitHub Actions), `.gitlab-ci.yml`, `.circleci/config.yml`, `azure-pipelines.yml`, `Jenkinsfile`, `bitbucket-pipelines.yml`. If there is none, ask the user which one they use. Default to GitHub Actions only if the repository is on GitHub. - Find the default branch: `git symbolic-ref --short refs/remotes/origin/HEAD` (strip `origin/`). With no remote, use the current branch and confirm it with the user. - On GitHub, check visibility if you can (`gh repo view --json visibility`). Uploading SARIF to code scanning works on public repositories; on private ones it needs GitHub Advanced Security. If you cannot tell, ask. ## Step 2 — Measure the current state before choosing a threshold Run the scan locally first, from the repository root (Node.js 18+), writing outside the repository: ```bash OUT=$(mktemp -d) npx -y @sphior/scan@0.1.9 run . --json "$OUT/baseline.json" ``` Read the summary line (counts by severity, files scanned, engine and ruleset versions). Then choose the threshold — with the user when they are available; otherwise follow this table and say which row you used: | Current state | `--fail-on` | |---|---| | No critical or high findings | `high` | | A few critical or high findings | Fix them first (**fix-security-findings**), then `high` | | Many existing findings | `critical` now, tighten to `high` once the backlog is fixed | Never add `.sphiorignore` entries or ignore comments just to make the first CI run pass. Real findings get fixed; findings that are genuinely not a problem go through **triage-security-findings**, which records a reason. ## Step 3 — Pin the version Look up the current version and pin it, so a ruleset update never changes CI results without a commit: ```bash npm view @sphior/scan version # add --offline to read it from the local cache ``` Use **0.1.8 or later**: from 0.1.8 a mistyped option or `--fail-on` value stops with exit `2` instead of being ignored. Write it as `npx -y @sphior/scan@<version>`, and tell the user that updating the scanner is then a deliberate one-line change. ## Step 4 — Write the CI step Copy the option exactly as `--fail-on high`. ### GitHub Actions Create `.github/workflows/sphior-code.yml` (or add the job to an existing workflow): ```yaml name: SPHIOR CODE on: push: branches: [main] # the real default branch pull_request: jobs: scan: runs-on: ubuntu-latest permissions: contents: read security-events: write # only for the upload step steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 20 - name: Scan run: npx -y @sphior/scan@<version> run . --sarif sphior.sarif --fail-on high - name: Upload to code scanning if: always() uses: github/codeql-action/upload-sarif@v3 with: sarif_file: sphior.sarif ``` - **Public repository, or Advanced Security enabled:** keep the upload step. Findings appear in the Security tab and as annotations on pull requests, and alerts are tracked across commits. - **Private repository without Advanced Security:** the upload fails with 403. Replace it with an artifact so the report is still downloadable, and drop `security-events: write`: ```yaml - name: Keep the report if: always() uses: actions/upload-artifact@v4 with: name: sphior-sarif path: sphior.sarif ``` ### GitLab CI ```yaml sphior-code: image: node:20 script: - npx -y @sphior/scan@<version> run . --json sphior.json --sarif sphior.sarif --fail-on high artifacts: when: always paths: [sphior.json, sphior.sarif] ``` ### Any other CI Run the same command on a Node.js 18+ image and archive the SARIF or JSON. The exit code is the contract: | Code | Meaning | |---|---| | `0` | Nothing at or above `--fail-on` | | `1` | At least one finding at or above `--fail-on` — fail the build | | `2` | Nothing was scanned: missing directory, or (0.1.8+) an unknown option or invalid value — fail the build | A directory with no scannable files exits `0` with a warning, so make sure the step runs from the repository root. ## Step 5 — Verify before handing over 1. **Prove the gate can fail.** A clean repository exits `0` whether the gate works or not. Run the exact CI command against a copy that still contains a known finding — for example a commit from before the fixes (`git archive <commit> | tar -x -C "$(mktemp -d)"`), or a temporary directory holding one file with `eval(userInput)` — and confirm exit `1`. 2. Run the exact command on the current tree and confirm the exit code you expect. Write the SARIF to a temporary directory when you do this locally; a `sphior.sarif` left in the repository is read by the next local scan and is easy to commit by mistake. 3. Validate the YAML (syntax, indentation, the real default branch name). 4. If the repository has generated or vendored code that should not be scanned, propose `.sphiorignore` path entries **without a rule id** (that means "do not read these files"), and show them to the user. Build output, `node_modules`, `vendor` and similar are already skipped. 5. Tell the user what will now happen on a pull request, which threshold you chose and why, and that accepted findings are kept out of SARIF on purpose (GitHub would otherwise show them as open alerts) — `--suppressed accepted.json` keeps that record if they want it archived. ## Rules - Do not put secrets, tokens or API keys into the workflow. The scanner needs none. - Do not weaken an existing security job to make room for this one. - Do not claim the CI step makes the application secure or compliant. It checks source code for known patterns, secrets and data flows within a file; it does not check dependencies or the running application.

triage-security-findings

Review SPHIOR CODE findings one by one and decide which are real, which are test fixtures or examples, and which are false positives — fixing the real ones and recording each accepted one with a written reason in .sphiorignore or an inline comment. Use when the user says "there are too many findings", "these are false positives", "this is test data", "clean up the scan results", "suppress this", or before turning on a CI gate on an existing codebase.

# Triage SPHIOR CODE findings Triage means deciding, finding by finding, what each one is — and leaving a record a reviewer or auditor can read later. It is **not** a way to make the number go down. A finding is only accepted when you can write down, in one sentence, why it is not a risk in this code. ## Step 1 — Get the full list, including what is already accepted Use the command line for triage (Node.js 18+). Write outside the repository: ```bash OUT=$(mktemp -d) npx -y @sphior/scan@0.1.9 run . --json "$OUT/findings.json" --suppressed "$OUT/accepted.json" ``` Use the same scanner version as the project's CI if it pins one. Keep the summary line from standard error; it shows how many files were scanned and how many were excluded. - `findings.json` — open findings. Each has `rule_id`, `severity`, `confidence`, `location` and a stable `fingerprint`. - `accepted.json` — findings already accepted, each with `suppression.justification` (absent when nobody wrote a reason) and `suppression.source` (where it was recorded). Read it so you do not duplicate entries. The MCP tool `get_fix_context` is built for fixing: it has no accepted list, and its `agent_instructions` tell a fixer not to re-classify findings. That instruction is for the fix skill; in triage, classifying is the job. ## Step 2 — Read each finding in its real context Open the file at the reported line and read enough code to understand the data flow. Put the finding into exactly one bucket: | Bucket | What it looks like | What to do | |---|---|---| | **Real** | Reachable code with untrusted input, a working credential, a weak algorithm used for security | **Fix it** — hand it to **fix-security-findings**. Never accept. | | **Test data / example** | A fixture, test vector, documentation example or deliberately vulnerable sample | Accept, scoped to that path **and** that rule, with a reason | | **False positive** | The flagged construct is safe here, and you can say why (input is a compile-time constant, value is a public identifier, the hash is not used for security) | Accept at the single line, scoped to the rule, with a reason | | **Not our code** | Generated, vendored or third-party code that is not edited by hand | Exclude the path (no rule id) — see the caution below | How to weigh it: - `confidence: confirmed` means the construct itself is the problem. These are rarely false positives — the bar for accepting one is high. - `confidence: needs_review` (for example the generic high-entropy secret rule) is where most false positives are. - **A secret that looks real is never "test data"**, even inside a test folder. Live prefixes such as `sk_live_`, `AKIA`, `ghp_`, `xoxb-`, or a PEM private key with a body, are treated as exposed: tell the user it must be rotated, then move it out of source. - **Generated code with a real vulnerability is both "Real" and "Not our code".** Excluding the path hides it from every later scan. Before excluding, list its findings in your report and tell the user the fix belongs in the generator or its input, not in the generated file. ## Step 3 — Record the decision in the narrowest form **One line in ordinary code** → an inline comment with the rule id and a reason. Works with any line comment (`//`, `#`, `--`, `;`): ```python digest = hashlib.md5(data).hexdigest() # sphior-ignore pattern.py.weak_hash: cache key, not a security use ``` ```js // sphior-ignore-next-line secret.generic.high_entropy_assignment: public analytics key, shipped to browsers by design const PUBLIC_ANALYTICS_TOKEN = "3f9a6c0e1b2d4e5f8a7b6c5d4e3f2a1b"; ``` **Test data, fixtures and examples** (even a single line) → `.sphiorignore` at the scan root, so the test file stays untouched. One entry per line: `<glob> [rule_id] [# reason]` ```gitignore # accepted: scanned, then recorded with a reason test/fixtures/keys.js secret.generic.high_entropy_assignment # fake token used by unit tests docs/examples/** pattern.js.eval # intentionally insecure documentation samples # excluded: not read at all (no rule id) src/generated/** # generated from openapi.yaml; findings reported to the owner on <date> ``` Rules for writing entries: - **Always give a rule id** when accepting. A path without a rule id means "do not read this file at all" — use that only for generated or vendored code. - **Always give a reason.** The CLI reports accepted findings without one; an auditor cannot read an empty reason. - **Narrowest scope wins.** One rule over a family (`secret.*` only when several secret rules fire on the same fixture), one file over a directory, one directory over the repository. Never pair `**` with a broad rule. - Do not touch existing entries written by someone else unless the user asks. ## Step 4 — Prove nothing else changed Run the Step 1 command again and compare by **`fingerprint`** (it stays the same when lines move): - Every finding you accepted is now in `accepted.json`, with your reason. - Findings under paths you excluded are gone from both lists — expected. The "files excluded" count in the summary line should have risen by the number of files you excluded. - **No other finding disappeared.** If one did, your glob or rule pattern is too broad — narrow it. - Real findings you handed to **fix-security-findings** are still open until that skill has run; check them again after it has. ## Step 5 — Report for human review Give the user a short table: | File:line | Rule | Decision | Reason | |---|---|---|---| followed by the counts (fixed / accepted / excluded / still open), the findings inside excluded paths, and anything that needs their action, such as rotating a credential. Say clearly that the accepted entries are your judgement and should be reviewed before merge.