{"id":51725910,"url":"https://github.com/stylusnexus/defect-scan","last_synced_at":"2026-07-17T18:35:30.478Z","repository":{"id":365019975,"uuid":"1269384011","full_name":"stylusnexus/defect-scan","owner":"stylusnexus","description":"Catch real bugs before code review — a free, local defect scanner inside Claude Code \u0026 Codex. Runs your project's real analyzers, then reasons about what they miss across 15 languages (correctness, security, supply-chain). No service, no API key; report-only by default.","archived":false,"fork":false,"pushed_at":"2026-06-26T13:34:43.000Z","size":578,"stargazers_count":1,"open_issues_count":9,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-17T18:35:21.237Z","etag":null,"topics":["ai-agents","bug-detection","claude-code","claude-code-plugin","code-review","codex","defect-detection","developer-tools","devsecops","linter","llm","sast","security","static-analysis","supply-chain-security","vulnerability-scanner"],"latest_commit_sha":null,"homepage":"https://github.com/stylusnexus/agent-plugins","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stylusnexus.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-14T16:41:13.000Z","updated_at":"2026-06-26T13:34:44.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/stylusnexus/defect-scan","commit_stats":null,"previous_names":["stylusnexus/defect-scan"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/stylusnexus/defect-scan","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stylusnexus%2Fdefect-scan","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stylusnexus%2Fdefect-scan/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stylusnexus%2Fdefect-scan/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stylusnexus%2Fdefect-scan/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stylusnexus","download_url":"https://codeload.github.com/stylusnexus/defect-scan/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stylusnexus%2Fdefect-scan/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35592242,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-17T02:00:06.162Z","response_time":116,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","bug-detection","claude-code","claude-code-plugin","code-review","codex","defect-detection","developer-tools","devsecops","linter","llm","sast","security","static-analysis","supply-chain-security","vulnerability-scanner"],"created_at":"2026-07-17T18:35:29.852Z","updated_at":"2026-07-17T18:35:30.471Z","avatar_url":"https://github.com/stylusnexus.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# defect-scan\n\n### Catch real bugs before code review — inside the agent you already use\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-16a34a?style=for-the-badge)](LICENSE)\n[![Claude Code + Codex](https://img.shields.io/badge/runs_in-Claude_Code_%2B_Codex-7c3aed?style=for-the-badge)](#codex)\n[![15 languages](https://img.shields.io/badge/languages-15-0A66C2?style=for-the-badge)](#built-in-languages)\n[![POSIX sh](https://img.shields.io/badge/engine-one_POSIX_sh_lib-111827?style=for-the-badge)](#supported-platforms)\n\n\u003cp\u003e\n  \u003ca href=\"#what-you-get-back\"\u003eOutput\u003c/a\u003e •\n  \u003ca href=\"#measured-and-regression-gated\"\u003eBenchmark\u003c/a\u003e •\n  \u003ca href=\"#built-in-languages\"\u003eLanguages\u003c/a\u003e •\n  \u003ca href=\"#install-team-via-marketplace\"\u003eInstall\u003c/a\u003e •\n  \u003ca href=\"#extending-it-zero-core-edits\"\u003eExtend\u003c/a\u003e\n\u003c/p\u003e\n\n\u003c/div\u003e\n\nMost scanners flag patterns and dump a wall of warnings. **defect-scan finds defects\nyour tools miss and tells you how sure it is** — it detects the stack, runs the *real*\nanalyzers your project already has (ruff, tsc, clippy, go vet…), then reasons about the\nbugs linters can't see and reports each finding in a **confidence tier** with a repro\npath and a one-line fix. Correctness, security, *and* supply-chain across 15 languages.\n\n**No service to deploy, no API key, no security-team budget.** It runs as a plugin\ninside Claude Code (and Codex) — the same session you're already coding in. Free, MIT,\nlocal. Report-only by default; `--fix` applies only the adversarially-verified\nhigh-confidence tier and refuses on a dirty tree so every fix stays revertable.\n\n## What you get back\n\nA scan returns a tiered, honest report — never a raw warning dump. Each finding\ncarries **two independent axes** (how sure we are it's *real*, and how *bad* it is),\nthe evidence that survived an adversarial \"prove it isn't a bug\" pass, and a fix:\n\n```\ndefect-scan — src/ (MODE=changes)\nStacks: python   Tools run: ruff, mypy, bandit, pip-audit   Tools missing: —\nTriage: deep-reasoned top 12 of 34 in-scope files (rest tool-scanned only)\nCorrelation: on (2 findings matched existing issues)\nFindings: High 3 · Medium 2 · Low 4   (NEW 4 · already-filed 1)\n\ncat#3 — Injection\n[High] (High) [NEW] api/users.py:88 · SQL built by f-string from a request arg\n  evidence:  f\"SELECT … WHERE id = {user_id}\" — user_id flows unsanitized from\n             request.args to cursor.execute; survived adversarial verification\n             (no ORM/escaping anywhere on the path)\n  fix:       parameterize — cursor.execute(sql, (user_id,))\n\ncat#2 — Silent failures\n[Medium] (Medium) [LIKELY FILED #142] worker/sync.py:51 · bare except swallows retry error\n  evidence:  except Exception: pass wraps the network retry — failures vanish silently\n  fix:       log and re-raise, or narrow the except to the expected error\n```\n\nCoverage is always reported honestly: if a tool was missing or triage couldn't deep-read\nevery file, the header **says so** — it never implies clean coverage it didn't achieve.\n\n## Measured, and regression-gated\n\ndefect-scan ships its own evidence. Every supported language has a **labeled fixture\ncorpus** with a committed precision/recall baseline, scored by a **model-free grader**\n(±2-line tolerance, strict 1:1 matching). A change may not regress these baselines —\nimprovement lands only via reviewed PRs that add fixtures *without* dropping the gate:\n\n| Corpus | precision baseline | recall baseline | enforced floor |\n|---|---|---|---|\n| Most language corpora (python, rust, go, java, ts, ruby, swift, kotlin, dart, objc, yaml, shell) | 1.00 | 1.00 | ≥ 0.80 precision |\n| supply-chain pack | 0.81 | 0.93 | ≥ 0.65 precision |\n\nThese are seen-split baselines on the maintainer-run eval harness; a green run means a\nchange *didn't get worse* — enforced, not a marketing number. On live re-measurement a\ncouple of languages (c#, php) can sit a point or two under 1.00 from a *defensible*\nsecondary finding on a bug file — **recall stays 1.00 (no missed bugs)**, and it's held\ninside the gate's noise band. Full method, splits, and how to run it:\n[`tests/eval/README.md`](./tests/eval/README.md).\n\n## Built-in languages\n15 profiles, each pairing the language's real analyzers with a reasoning checklist\nmapped to the **six baseline defect categories** + language-specific footguns (cat#1–5\ncover correctness and security fundamentals; **cat#6 — supply-chain / dependency\nintegrity** — covers npm lifecycle abuse, typosquat / dependency-confusion, lockfile\ntampering, and install-time exfil, complementing `npm audit` and `osv-scanner`):\n\n| Profile | Analyzers (auto-run if installed) |\n|---|---|\n| **python** | ruff, mypy · +bandit, pip-audit |\n| **react-typescript** | tsc, eslint (type-aware) · +npm audit, osv-scanner |\n| **ruby** | rubocop · +brakeman, bundler-audit |\n| **go** | go vet, staticcheck, golangci-lint, govulncheck |\n| **csharp** | Roslyn analyzers, dotnet list --vulnerable · +Security Code Scan, roslynator |\n| **java** | Error Prone, SpotBugs + find-sec-bugs, PMD, OWASP dependency-check |\n| **kotlin** | detekt, ktlint · +Android Lint |\n| **swift** | SwiftLint, swift-format |\n| **objc** (Objective-C / ObjC++) | clang-tidy (Clang static analyzer), oclint |\n| **php** | PHPStan, Psalm (+taint), composer audit |\n| **rust** | clippy, cargo-audit, cargo-deny |\n| **dart** (Flutter) | dart/flutter analyze |\n| **yaml** | yamllint · +actionlint/zizmor (Actions), kube-linter (k8s), ansible-lint |\n| **shell** | shellcheck |\n| **generic** | cross-cutting patterns + optional semgrep/gitleaks on any stack |\n\nMissing analyzers are reported with an install hint and skipped — the scan never\naborts. Add your own language or rules with zero core edits (see *Extending it*).\n\n## Layout (plugin)\n```\n.claude-plugin/plugin.json     # plugin manifest\nskills/scan/                   # the skill — invoked as /defect-scan:scan\n  SKILL.md  profiles/  patterns/  baseline-categories.md  report-format.md\n  lib/detect.sh                # deterministic plumbing (scope/stacks/tool/triage/issues/labels)\ncommands/help.md               # /defect-scan:help\nhooks/                         # opt-in pre-commit advisory (hooks.json + pre-commit-scan.sh)\nscripts/setup-optional-tools.sh# one-liner installer for the optional analyzers\ntests/                         # bats suite (run: bats tests/detect.bats)\n```\n\n## Install (team, via marketplace)\n```\n/plugin marketplace add stylusnexus/agent-plugins\n/plugin install defect-scan@stylus-nexus\n```\nThe repo is `stylusnexus/agent-plugins`; the marketplace **name** is `stylus-nexus`\n— so the install suffix is `@stylus-nexus`, not `@agent-plugins`. Then invoke with\n`/defect-scan:scan` (or let the model auto-invoke it). If a fresh install reports\n\"not found,\" run `/plugin marketplace update stylus-nexus` first (stale cache).\n\n## Help\n`/defect-scan:help` prints usage, flags, and what it uses.\n\n## Codex\ndefect-scan also runs under the [Codex CLI](https://github.com/openai/codex) — the\nscan logic, profiles, and patterns are shared; only the entrypoint differs. See\n[`codex/README.md`](./codex/README.md) to install the Codex prompt.\n\n## Supported platforms\nThe engine is one POSIX-sh library, so it runs on **macOS** (BSD userland), **Linux**\n(GNU userland), and **Windows via WSL or Git-Bash**. CI runs the suite on both Ubuntu\nand macOS to catch BSD-vs-GNU regressions. **Native PowerShell** users get a fallback\nshim (`windows/defect-scan.ps1`) that delegates to the bash bundled with Git for\nWindows — see [`windows/README.md`](./windows/README.md). Check your environment with\n`detect.sh preflight` (verifies git/awk/sed/grep/jq… are present).\n\n## Optional analyzers (richer coverage, all degrade-gracefully)\nThe scan runs whatever's installed and skips the rest with an install hint:\n- **`semgrep`** — multi-language taint (injection, subprocess, SQL) — highest-value add\n- **`gitleaks`** — committed secrets (run git-mode with the bundled\n  `skills/scan/gitleaks-baseline.toml`, which allowlists node_modules/build output and\n  well-known public demo keys so the scan isn't drowned in false positives)\n- **`bandit` / `pip-audit`** (Python), **`npm audit` / `osv-scanner`** (JS/TS) — security + vuln deps\n\nOne-liner to install them all (best-effort, per your package managers):\n`sh scripts/setup-optional-tools.sh`\n(or manually: `brew install semgrep gitleaks osv-scanner` · `pip install bandit pip-audit`)\n\n## Optional pre-commit advisory (off by default)\nSet `DEFECT_SCAN_HOOK=1` to get a one-line, **non-blocking** advisory on changed\nsource files when committing. It runs only the deterministic tool pass; for the\nfull reasoning report run `/defect-scan:scan`.\n\n## Extending it (zero core edits)\nAdd a language or custom defect rules by dropping files in `.defect-scan/` (team)\nor `~/.config/defect-scan/` (personal) — no core changes. Copy\n`skills/scan/profiles/TEMPLATE.md.example`, fill four frontmatter fields, done.\n**Full step-by-step guide: [`EXTENDING.md`](./EXTENDING.md).**\n\n### Three layers — and what belongs where\nBoth **profiles** (languages) and **patterns** (cross-cutting defect classes) resolve\nacross three layers, low→high precedence; higher layers shadow lower **by name**:\n\n| Layer | Profiles | Patterns | What belongs here |\n|-------|----------|----------|-------------------|\n| **Built-in (global)** | `skills/scan/profiles/` | `skills/scan/patterns/recurring.md` · `supply-chain.md` | **Generic** detections useful to *everyone* — no product/org/customer specifics. This is a public, shared plugin. |\n| **User** (`~/.config/defect-scan/`) | `profiles/*.md` | `patterns/*.md` | Your personal rules across all your repos. |\n| **Project** (`\u003crepo\u003e/.defect-scan/`) | `profiles/*.md` | `patterns/*.md` | **Product/org-specific** detections — your billing rules, your naming conventions, your internal APIs. Committed with the repo, scoped to it. |\n\nThe dividing line: **built-ins stay generic; anything specific to one product, codebase,\nor company goes in that repo's project layer.** Example — the built-in P1 \"metered-action\ncorrectness\" pattern is generic billing-integrity; a specific product's billing\nmanifestations (exact routes, field names, known incidents) belong in *its*\n`.defect-scan/patterns/`, not here. `lib/detect.sh profiles \u003crepo\u003e` and `… patterns \u003crepo\u003e`\nshow every layer's contributions with their origin (`builtin`/`user`/`project`); set\n`DEFECT_SCAN_NO_USER=1` / `DEFECT_SCAN_NO_PROJECT=1` (the `--no-user-profiles` /\n`--no-project-profiles` scan flags) to restrict to built-ins only.\n\n## Local dev\n`./install.sh` symlinks `skills/scan/` into `~/.claude/skills/defect-scan` so it\nloads while you iterate. Remove that symlink once the plugin is installed, to\navoid a double-load. Run tests: `bats tests/detect.bats`.\n\n## Contributing\nPRs welcome — see **[CONTRIBUTING.md](./CONTRIBUTING.md)** for setup, conventions,\nand step-by-step guides to **add** a language profile, **enhance** an existing one,\nor add a defect pattern. To extend defect-scan *privately* (no PR), see\n[EXTENDING.md](./EXTENDING.md). Be excellent to each other:\n[Code of Conduct](./CODE_OF_CONDUCT.md). Security issues: [SECURITY.md](./SECURITY.md)\n(private reporting — don't open a public issue).\n\nCI runs the bats suite, a POSIX-shell syntax check, and a gitleaks secret scan on\nevery PR. Scan quality is measured against a labeled corpus (`tests/eval/`) by a\nmodel-free **validator** (`detect.sh eval`) and a **loop-closing harness**\n(`detect.sh eval-run` / `eval-gaps` / `eval-categories`) — see\n**[`tests/eval/README.md`](./tests/eval/README.md)** for how to run it, the\nprecision-first scoring (±2 line tolerance, 1:1 matching), baselines, and the\ncompleteness critic. The harness is **maintainer-run** (manual, not on PR), and a\ngreen eval means the change *didn't get worse*, not that it got better at the real job.\nReleases are automated: [release-please](https://github.com/googleapis/release-please)\ngenerates [CHANGELOG.md](./CHANGELOG.md) and bumps the version from Conventional\nCommit titles at deploy.\n\n## License\n[MIT](./LICENSE) © Stylus Nexus.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstylusnexus%2Fdefect-scan","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstylusnexus%2Fdefect-scan","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstylusnexus%2Fdefect-scan/lists"}