CSReview - Code Security Review Skill

CSReview is an orchestration, corroboration, and evidence layer for security review of the local workspace — built for AI coding agents and the humans who supervise them. It is local, development-time security alignment (SAST/SCA + actionable reports + agent methodology): not an automated penetration test, not a substitute for independent security validation, and read-only on your source code.

What it actually does

One command runs the whole pipeline deterministically:

1. Discovers the workspace (source, configs, .env, lockfiles, IaC, BaaS rules — recursively, monorepo-aware) and detects the stack.
2. Orchestrates real security tools — OpenGrep 1.26.0 with a bundled offline rulepack (required baseline), one root package audit selected from the detected npm/pnpm/bun lockfile, OSV-Scanner, and (opt-in) Gitleaks, Trivy, gosec, Bandit — and parses their JSON output.
3. Adds its own heuristic detector for secrets (redacted in evidence), config/IaC/BaaS misconfigurations, and common vulnerability shapes — a complementary net, not a taint-tracking SAST.
4. Corroborates: findings are deduplicated across sources by file:line:CWE; matching evidence from the built-in detector and at least one additional normalized source is promoted to CONFIRMED, and every finding carries an explicit confidence label (CONFIRMED / TOOL-ONLY / heuristic HIGH|MEDIUM|LOW).
5. Reports for both audiences: an HTML report for humans, a Markdown report for coding agents to plan remediation from, and SARIF 2.1.0 for CI — plus --fail-on <severity> so a pipeline can block merges, and --baseline so CI fails only on NEW findings.

What it does not do — said up front: it does not modify your code, it does not probe deployed systems, it does not compute compliance verdicts (compliance fields are CWE correlation — indicative, never an audited compliance verification), and a clean report is evidence of absence-of-detection, not proof of security.

Security tooling CSReview relies on (and can install for you)

CSReview's fidelity — results faithful to the objective, with far fewer false positives — comes from running real, best-in-class security tools and corroborating them with its own heuristics (a finding confirmed by both a tool and the detector is marked CONFIRMED).

| Tool | Purpose | Official source | |------|---------|-----------------| | OpenGrep 1.26.0 | Offline multi-language SAST (required baseline) | https://github.com/opengrep/opengrep | | OSV-Scanner | Dependency vulnerabilities (SCA) | https://github.com/google/osv-scanner | | Gitleaks | Hardcoded secret detection | https://github.com/gitleaks/gitleaks | | Trivy | IaC / container / filesystem misconfig + vulns | https://github.com/aquasecurity/trivy | | Bandit | Python security (AST) — run if already installed | https://github.com/PyCQA/bandit | | gosec | Go security (AST) | https://github.com/securego/gosec |

With --provision-tools, CSReview can auto-download the approved OpenGrep 1.26.0, Gitleaks, Trivy, and gosec artifacts from official releases. Bandit is PyPI-distributed, so CSReview runs it only when it is already installed (pip install bandit). OSV-Scanner is detected on PATH and must be installed separately.

For approved opt-in downloads, --provision-tools tells CSReview to:

• download each tool only from its official release page (the sources above), pinned to the official host;
• verify its SHA-256 checksum before running anything (a mismatch — or any non-official host — is rejected and never executed);
• install OpenGrep into CSReview's private user cache outside the audited project; stack-native complements use an isolated, gitignored .csreview/bin/ — never globally, never with sudo, never as a project dependency, and never modifying your source code;
• fail open: if an optional tool cannot be installed (offline or unsupported platform), the remaining available scanners and heuristics still run, and skipped tools are disclosed.

Prefer to manage them yourself? Optional tools can use installations detected on PATH; OpenGrep is accepted only when it matches the approved 1.26.0 version and SHA-256 digest. Either way, the report tells you which tools ran, which were partial, and which were skipped.

Quickstart

# 1. Get the engine (distributed via GitHub)
git clone https://github.com/decksoftware/csreview.git
cd csreview/csreview && npm install -g .

# 2. Check your scanner toolchain
csreview --doctor .

# 3. Scan a project (read-only; reports land in <project>/csreview-reports/)
csreview /path/to/project --agent-name claude

# 4. Gate your CI
csreview . --agent-name ci --fail-on high      # exit 1 if HIGH/CRITICAL remain

Current configuration

The package manifest currently defines CSReview 0.1.4, ESM, with Node.js 20 or newer. A normal scan writes static reports to <target>/csreview-reports/ using the codex prefix unless another agent name is configured.

CLI options

| Option | Current behavior | | --- | --- | | --output, -o <dir> | Changes the static-report output directory. Default: <target>/csreview-reports/. | | --agent-name <name> | Prefixes report filenames. Default: CSREVIEW_AGENT_NAME, then codex. | | --fail-on <severity> | Exits with code 1 after writing reports when critical, high, medium, or low findings at or above the threshold remain. | | --baseline <file> | Suppresses matching known-finding fingerprints from reports and the CI gate. | | --update-baseline | Writes or refreshes the selected baseline; without --baseline, writes <target>/.csreview-baseline.json. | | --strict-partials | Fails when <output>/.partials/ exists but its subagent results cannot be reconciled. | | --provision-tools | Provisions the approved OpenGrep 1.26.0 artifact in the private user cache and runs relevant Gitleaks, Trivy, gosec, and Bandit checks. Every supported download is official-source and SHA-256 verified; Bandit is used only if installed. | | --tool-timeout <seconds> | Sets the per-tool timeout for OpenGrep, package audit, and OSV-Scanner. Default: 120 seconds. | | --opengrep-config <path> | Adds an existing local OpenGrep rule file or directory after the bundled offline rulepack. URLs, auto, and registry references are rejected before execution. | | --dump-guide | Adds <agent>_db-dump-guide.html; this is also generated automatically with local DAST. | | --local-dast-url <url> | Runs the optional loopback-only header/CORS probe after the static scan. Accepts only localhost, 127.0.0.1, or [::1]. | | --confirm-local-dast | Mandatory explicit confirmation for --local-dast-url. | | --no-update-check | Skips the read-only, fail-open CSReview update advisory. | | --doctor [target] | Checks the approved OpenGrep artifact, the lockfile-selected package-audit tool, OSV-Scanner, and tool freshness without scanning source. | | --no-tool-check | With --doctor, skips the online freshness comparison while retaining local availability checks. | | --version, -v / --help, -h | Prints the installed version or CLI help. |

Unknown flags are hard errors: a mistyped option aborts instead of silently changing what is audited.

Files and environment

| Configuration | Current behavior | | --- | --- | | .csreview-ignore | Optional gitignore-style rules at the target root. They suppress matching findings in reports without changing source files; ! rules can re-include a built-in exclusion. | | .csreview-baseline.json | Default deterministic baseline written only when --update-baseline is requested without another path. | | <output>/.partials/<subagent>.json | Optional subagent input contract (<output> defaults to csreview-reports). The engine remains the single writer of final reports. | | %LOCALAPPDATA%\CSReview\tools (Windows) / $XDG_CACHE_HOME/csreview/tools or ~/.cache/csreview/tools (Unix) | Private cache for the approved OpenGrep artifact, outside the audited target. Entries are keyed by version and SHA-256 and include a validated manifest. | | .csreview/bin/ | Isolated, gitignored target-local cache for optional stack-native tools only. OpenGrep is never loaded from this directory. | | CSREVIEW_AGENT_NAME | Default report prefix when --agent-name is omitted. |

Static output is <agent>_security-report.html, <agent>_security-findings.md, and <agent>_security.sarif. Local DAST always writes its current and timestamped history reports inside <target>/csreview-reports/, even when the static scan uses a custom --output directory.

Honest limits

• The built-in regex detector is line-oriented: it catches secrets, misconfigurations, and common shapes, but it has no taint tracking or cross-file analysis — OpenGrep (and optionally CodeQL) provides the required SAST baseline, and runs are marked lower-confidence without it.
• Language-specific engine rules exist for JavaScript/TypeScript, Python, C#, Go, C/C++, and Delphi; other stacks lean on OpenGrep + OSV-Scanner + agent checklists.
• Compliance output (LGPD/GDPR/SOC 2/HIPAA/CCPA-CPRA, OWASP ASVS, SLSA) is indicative correlation by CWE to support a human review — the engine computes no coverage percentages and no per-article verdicts, and the agent instructions forbid fabricating them.
• The optional Phase 9 "local DAST" is a conservative loopback-only HTTP probe (headers, CORS, reachability) with hard engine guards — it is not a penetration test.

Canonical Agent Instructions

The most important artifact in this repository is csreview/SKILL.md: the exact instruction file loaded by coding agents, kept deliberately lean. Detailed checklists and protocols live in csreview/reference/ and are loaded on demand. SKILL.md is mirrored below so GitHub visitors can evaluate the real CSReview behavior from the landing page without cloning.

<details> <summary>Expand the full SKILL.md read by coding agents</summary> <!-- BEGIN CSREVIEW_SKILL_MD -->

---
name: "csreview"
description: "Development-time local workspace security alignment for codebases. Generates HTML report for humans and MD report for agents. Invoke when user requests security review, code audit, vulnerability scan, or pentest-style static analysis."
---

# CSReview - Code Security Review

## What CSReview Is

CSReview performs development-time security alignment for the local workspace a developer is actively building. It applies a penetration tester's adversarial mindset to the project's local source, configuration, dependencies, and infrastructure files (static SAST + SCA). It does NOT perform live penetration testing against running, deployed, or production systems.

It is two things working together, and the agent must keep them straight:

1. **A deterministic engine** (the `csreview` CLI). It discovers the workspace, runs and parses the external security tools, applies its own heuristic detector, deduplicates evidence across sources (promoting corroborated findings to `CONFIRMED`), scores the result, and writes ALL report files. The engine is the single writer of reports.
2. **An agent methodology** (this document + `reference/`). The agent runs the engine, then adds what tools cannot: contextual review of flagged code, framework research, remediation planning, and honest communication of confidence and limits.

CSReview's value is orchestration, corroboration, and evidence — OpenGrep is its required