sphior-code plugin for Cursor
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.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.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.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.