Merge pull request #22 from decksoftware/feat/precision-monorepo-gate-and-honest-docs

feat: detector precision, monorepo discovery, CI gate + honest docs restructure

Author: decksoftware

.github/workflows/ci.yml

@@ -57,3 +57,29 @@ jobs:
 
       - name: Verify package contents
         run: npm pack --dry-run
+
+  self-scan:
+    name: Self-scan (dogfood, --fail-on high)
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v5
+        with:
+          node-version: 24
+          cache: npm
+          cache-dependency-path: csreview/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+        working-directory: csreview
+
+      - name: Install Semgrep
+        run: python -m pip install --upgrade semgrep
+
+      - name: Run CSReview against its own repository
+        run: node csreview/src/cli.js . --agent-name ci --no-update-check --fail-on high

.gitignore

@@ -21,6 +21,14 @@ security-findings.md
 *_security-findings.md
 **/*_security-report.html
 **/*_security-findings.md
+*_security.sarif
+**/*_security.sarif
+*_local-dast-report*.html
+*_local-dast-findings*.md
+**/*_local-dast-report*.html
+**/*_local-dast-findings*.md
+*_db-dump-guide.html
+**/*_db-dump-guide.html
 
 CSREVIEW-ANALISES.md
 CSREVIEW-ANALISES*.md

README.md

@@ -1,6 +1,6 @@
 {
   "name": "csreview",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Development-time local workspace security alignment for AI coding agents",
   "main": "src/index.js",
   "bin": {
@@ -29,6 +29,7 @@
   "license": "MIT",
   "files": [
     "src/",
+    "reference/",
     "SKILL.md",
     "README.md",
     "LICENSE"

csreview/SKILL.md

@@ -0,0 +1,103 @@
+# CSReview Reference - Compliance & Framework Correlation
+
+**Honesty contract**: the engine maps findings to the frameworks below by CWE
+correlation only (see `COMPLIANCE_MAP` in `src/detector.js`). It does NOT
+compute per-article PASS/FAIL verdicts, ASVS coverage percentages, or SLSA
+levels, and the agent MUST NOT fabricate such numbers in summaries. Per-article
+or per-requirement assessments may appear in a report only when a human or the
+agent explicitly evaluated that requirement against the workspace and says so.
+Compliance output is **indicative correlation, not an audited compliance
+verification**.
+
+## SLSA Supply Chain Review (SLSA Build L3, v1.2)
+
+Checklist for the agent's supply-chain review. Reference requirements with
+track + level + version (e.g. "SLSA Build L3 (v1.2)").
+
+**Source integrity**: signed commits, branch protection, required reviews,
+CODEOWNERS, repository permission audit, 2FA enforcement.
+
+**Build integrity**: automated CI/CD, reproducible/hermetic builds, hosted build
+service, signed build attestations/provenance, artifact signing
+(Sigstore/cosign/GPG), base image verification.
+
+**Dependency security**: lock files present and committed, exact version
+pinning, integrity hashes, SBOM generation and maintenance, automated
+vulnerability scanning, typosquatting review, license audit.
+
+**Deployment security**: dev/staging/production separation, secrets in a
+vault/manager (not code or committed env files), restricted and audited
+deployment access, rollback capability, audited IaC templates.
+
+## OWASP ASVS 5.0.0 Review Areas
+
+Systematic verification areas from the OWASP Application Security Verification
+Standard 5.0.0 (stable since 2025-05-30). Reference requirements with the
+version, e.g. `v5.0.0-1.2.5`. The engine's `COMPLIANCE_MAP` correlates CWEs to
+ASVS chapters; chapter-by-chapter verification is agent/human work.
+
+- **V1 Architecture**: threat model, security architecture, trust boundaries
+- **V2 Authentication**: password policy, MFA, credential storage
+  (bcrypt/scrypt/Argon2 — never MD5/SHA1), lockout, recovery
+- **V3 Session Management**: random session IDs, lifecycle/timeout, cookie
+  flags (HttpOnly/Secure/SameSite), session binding
+- **V4 Access Control**: default deny, function-level and data-level checks,
+  JWT verification, OAuth scopes
+- **V5 Validation & Encoding**: input validation at every entry point,
+  context-aware output encoding, deserialization safety, mass assignment
+- **V6 Stored Cryptography**: key management, modern algorithms (AES-256,
+  RSA-2048+; never DES/RC4), CSPRNG, key rotation
+- **V7 Errors & Logging**: no sensitive info in errors, security event logging,
+  log integrity, PII redaction, log injection prevention
+- **V8 Data Protection**: classification, encryption at rest and in transit
+  (TLS 1.2+), PII minimization, retention/deletion
+- **V9 Communication**: TLS configuration, certificate validation/pinning, HSTS
+- **V10 Malicious Code**: no backdoors/time bombs, anti-tampering
+- **V11 Business Logic**: flow validation, abuse prevention, rate limiting
+- **V12 Files & Resources**: upload restrictions, execution prevention, path
+  traversal protection
+- **V13 API & Web Services**: API authn/authz, rate limiting, GraphQL
+  introspection off in production, WebSocket security
+- **V14 Configuration**: secure build/deploy, security headers, debug off in
+  production
+
+## Regulatory Correlation Checklists
+
+These lists support the agent when the user asks for a privacy/compliance
+review. Many items are process/documentation controls that cannot be verified
+from source code alone — say so explicitly instead of guessing.
+
+### LGPD (Brazil)
+
+Data inventory and classification; documented legal basis; granular consent and
+withdrawal; data subject rights endpoints (access, correction, deletion,
+portability); DPO contact; cross-border transfer safeguards; 72h ANPD breach
+notification plan; privacy by design/default; processor agreements.
+
+### GDPR (EU)
+
+LGPD items plus: DPIA for high-risk processing; records of processing (ROPA);
+right to be forgotten (automated deletion); machine-readable data portability;
+timestamped, versioned consent records; EU representative for non-EU companies;
+SCCs for international transfers.
+
+### SOC 2 Type II
+
+Security (access controls), availability (SLA monitoring, DR), processing
+integrity (validation, error handling), confidentiality (classification,
+encryption), privacy (collection/use/retention/disposal), continuous monitoring
+and audit logging, change management.
+
+### HIPAA (US)
+
+PHI mapping in the codebase; role-based access with minimum-necessary; audit
+logging of PHI access; AES-256 at rest and TLS 1.2+ in transit; BAAs with third
+parties handling PHI; HIPAA-specific breach procedures; de-identification
+methods; integrity controls. (BAA and similar contractual controls are process
+items — not verifiable from code.)
+
+### CCPA/CPRA (California)
+
+Right to know/delete/opt-out/correct/limit; "Do Not Sell" mechanism when
+applicable; opt-in for sensitive personal information; service provider
+agreements; data minimization; documented retention schedules.

csreview/package-lock.json

@@ -0,0 +1,58 @@
+# CSReview Reference - Phase 9 Optional Local DAST
+
+Full protocol for the optional, post-remediation, local-only dynamic
+complement. The core rules and the required user-facing confirmation prompt
+live in SKILL.md; this file holds the operational detail.
+
+## What the built-in probe actually does
+
+`csreview <dir> --local-dast-url <url> --confirm-local-dast` performs a
+conservative, non-mutating HTTP check against the confirmed loopback target:
+reachability, browser security headers (Content-Security-Policy,
+X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Permissions-Policy),
+and CORS behavior against a hostile origin. It is **not** a penetration test,
+it never follows redirects, and it aborts immediately if a response points to
+an external host.
+
+## Engine guards (enforced in code, not just documented)
+
+- Target hostname must be `localhost`, `127.0.0.1`, or `[::1]`; anything else
+  is rejected before any request.
+- `--confirm-local-dast` is required; without it the run stops with the
+  confirmation instructions.
+- Redirects are not followed (`redirect: manual`); an external `Location`
+  aborts the phase.
+- Reports are written only inside `csreview-reports/`.
+- An advisory pre-flight scans `.env`, `.env.local`, and `.env.development` for
+  external hosts and surfaces them as `DAST-SUSPECTED` so you can verify the
+  local app does not proxy probe traffic outward. It is advisory because real
+  development env files almost always reference external services.
+
+## Status labels (honest semantics)
+
+- `DAST-SUSPECTED` — anomalous local response that requires human review.
+- `DAST-CLEAN` — the checked condition passed for the local target.
+- `DAST-CONFIRMED` — **reserved label, never produced by the built-in probe.**
+  It may only appear when a dedicated local DAST tool (run separately by the
+  agent, e.g. OWASP ZAP or Nikto against the same confirmed loopback target,
+  after the same pre-flight and confirmation) dynamically reproduced an issue
+  with clear evidence. If no such tool ran, no finding may carry this label.
+
+## Outputs
+
+- `csreview-reports/<agent>_local-dast-report.html`
+- `csreview-reports/<agent>_local-dast-findings.md`
+- With a run ID: timestamped history copies
+  (`<agent>_local-dast-report-<runId>.html` / `...-findings-<runId>.md`) so
+  re-running after remediation never overwrites prior evidence.
+- `<agent>_db-dump-guide.html` — a read-only, per-backend guide for preparing
+  an isolated local database copy BEFORE any database-level testing (schema-only
+  dumps, synthetic users, zero real PII; never dump production).
+
+## Hard limits
+
+Never probe external IPs, domains, staging, or production. Never use
+destructive payloads or DELETE. Do not send mutating POST/PUT/PATCH unless the
+user provided an explicit local test endpoint allowlist and confirmed the data
+mutation risk. If the test uses a database copy, it must be deliberately
+created, stored securely, and sanitized or minimized where needed.

csreview/package.json

@@ -0,0 +1,74 @@
+# CSReview Reference - What the Engine Reports Actually Contain
+
+The engine writes every report deterministically. The agent never handcrafts
+report files and never invents metrics that the engine does not compute. In
+particular there is **no** "ASVS coverage %", "SLSA level", or per-article
+compliance PASS/FAIL anywhere in the generated reports — see
+`reference/compliance-frameworks.md` for what compliance correlation means.
+
+## HTML report (`<agent>_security-report.html`)
+
+For human review, generated in a self-contained file: executive summary with
+the 0-100 score (severity-capped: any CRITICAL caps it at 49, any HIGH at 74),
+severity and category charts, findings-by-origin breakdown (which tool reported
+what, corroborated findings first), tool execution status (which engine tools
+ran, versions, raw counts), filterable finding cards (severity, category, file
+search), per-finding metadata (CWE link, OWASP category, confidence, compliance
+correlation, vibe-risk flag, redacted evidence snippet, theoretical
+exploitation hypothesis, remediation guidance, references), and an "Export as
+JSON" button. Secrets are redacted before rendering; all dynamic content is
+HTML-escaped.
+
+## Markdown report (`<agent>_security-findings.md`)
+
+For coding agents (always English). Actual sections emitted by the engine:
+
+1. **Executive Summary** — score, totals by severity, mode, tool status
+2. **Findings Index** — table of every finding with file:line
+3. **Detailed Findings** — full canonical finding objects
+4. **Category Analysis** — counts and highlights per category
+5. **Compliance Impact** — CWE-correlated framework references (indicative)
+6. **Fix Priority Order** — Immediate (CRITICAL) → Short-term (HIGH) →
+   Medium-term (MEDIUM) → Low Priority (LOW/INFO)
+7. **Remediation Guidance** — per-finding guidance, never an exact patch to
+   apply blindly
+8. **Scan Metadata** — timestamps, file counts, tool versions, suppression and
+   baseline counts
+
+## SARIF report (`<agent>_security.sarif`)
+
+SARIF 2.1.0 for CI and GitHub code scanning. It never embeds raw vulnerable
+code, so secrets are not leaked into uploaded artifacts. Pair it with
+`--fail-on <severity>` to gate merges.
+
+## Canonical finding schema
+
+Exchanged by the detector, tool normalizers, subagent partials, and all report
+generators:
+
+```json
+{
+  "id": "SQL_INJECTION_src-auth-ts_45",
+  "severity": "CRITICAL|HIGH|MEDIUM|LOW|INFO",
+  "category": "Injection",
+  "name": "...",
+  "description": "...",
+  "file": "src/auth.ts",
+  "line": 45,
+  "vulnerableCode": "redacted/snippet",
+  "cwe": "CWE-89",
+  "owasp": "A03:2021-Injection",
+  "fix": "...",
+  "confidence": "CONFIRMED|TOOL-ONLY|HIGH|MEDIUM|LOW",
+  "exploitation": "theoretical hypothesis, never a validated exploit",
+  "references": ["https://..."],
+  "source": "csreview-detector|semgrep|npm-audit|pnpm-audit|bun-audit|osv-scanner|gitleaks|trivy|gosec|bandit|subagent:<domain>",
+  "vibeRisk": false,
+  "compliance": "OWASP ASVS V5.3, GDPR Art.32 (CWE correlation)"
+}
+```
+
+Confidence semantics: `CONFIRMED` = corroborated by more than one independent
+source (e.g. detector + Semgrep at the same file:line:CWE); `TOOL-ONLY` = one
+external tool; `HIGH|MEDIUM|LOW` = heuristic detector confidence. Findings in
+test/fixture/example paths are downgraded to LOW instead of hidden.

csreview/reference/compliance-frameworks.md

@@ -0,0 +1,52 @@
+# CSReview Reference - Code Review Modes
+
+Detail for the five review modes summarized in SKILL.md. These are agent
+methodologies layered on top of the engine run; they do not change what the
+engine writes.
+
+## Mode 1 - Standard Code Review (`@csreview review [files]`)
+
+Quality: readability, naming, complexity, dead code, duplication, SOLID/DRY,
+separation of concerns. Architecture: pattern fit, coupling, dependency
+direction. Performance: algorithmic complexity, leaks, N+1 queries, caching,
+bundle impact. Testing: coverage gaps, missing edge cases, isolation, mock
+overuse. Documentation: missing docstrings on public APIs, stale comments,
+undocumented breaking changes.
+
+## Mode 2 - Adversarial Review (`@csreview adversarial [files]`)
+
+Red-team mindset: actively try to break the change. Boundary exploitation,
+race conditions, resource exhaustion, error-handling bypass, state corruption,
+validation gaps at every layer. Failure modes: external service down, malformed
+input, extreme load, concurrent modification, full disk/memory. Edge cases:
+empty/null, maximum sizes, Unicode, timezones, float precision, integer
+overflow. Ask: "How can I make this fail?", "What is the worst input?", "What
+assumption can be wrong?", "Can I bypass this check?"
+
+## Mode 3 - Security-Focused Review (`@csreview security-review [files]`)
+
+Apply the security and database checklists (see
+`reference/security-checklists.md`) to the specific changed files, assess the
+security impact of each change, and flag architectural changes that require
+threat-model updates. Vibe-risk heuristics from the engine apply here.
+
+## Mode 4 - Requesting a Review (`@csreview request-review [scope]`)
+
+Protocol: identify scope (files/functions/modules) → choose depth → select
+modes (quality/adversarial/security) → build a checklist for the change type →
+execute → prioritize by severity and actionability. Change types: new feature
+(full + adversarial), bug fix (correctness + regression), refactor (behavior
+preservation), configuration (security impact), dependency update
+(vulnerability + license), migration (integrity + rollback).
+
+## Mode 5 - Receiving Review Findings
+
+(`@csreview review csreview-reports/codex_security-findings.md`)
+
+Parse the Markdown report → categorize by severity → for each finding:
+acknowledge, research the fix (official docs first), propose, apply (coding
+agent's responsibility, never CSReview's), verify nothing new broke. Fix
+verification checklist: addresses the specific vulnerability; preserves
+behavior; follows framework practice; introduces no new issues; tested;
+documented when behavior changes. After all fixes, re-run the engine —
+optionally with `--baseline` so only NEW findings fail CI.