diff --git a/dsgai_scanner_tool/CHANGES_v0.3.md b/dsgai_scanner_tool/CHANGES_v0.3.md index f58057d..ac85734 100644 --- a/dsgai_scanner_tool/CHANGES_v0.3.md +++ b/dsgai_scanner_tool/CHANGES_v0.3.md @@ -75,9 +75,18 @@ dates are ISO-8601. The previous line is recorded in [`CHANGES_v0.2.md`](CHANGES Fixed the push-gate bug — gating is now driven by the `DSGAI_FAIL_ON` repo variable (empty = report-only), not force-gated on every push. (PR-08) +- **README truth pass**: reflects the deterministic-CLI + LLM-orchestration architecture, + two engine modes, SARIF/Code Scanning, timestamped reports, file-ID strict mode, and + a **Cost & runtime** section ($0 CLI-only mode, fork-PR behavior, `--diff` marked + v0.4). Adds a Contributing quick-start ("found a wrong result? that's a contribution"). + Skill version badge → v0.3. (PR-09) + ### Changed -- Honest-language pass across the skill: every "safe to share/commit/store" replaced - with "designed to minimize disclosure" + a residual-risk note. (PR-07) +- Honest-language pass across the skill **and README**: every "safe to share/commit/store" + replaced with "designed to minimize disclosure" + a residual-risk note — the Phase-2 + overclaim gate now passes repo-wide. (PR-07, PR-09) +- Sample-report image caption now states it is interim and will be regenerated from the + public fixture app once the deterministic report template lands (PR-14). (PR-09) - `DSGAI-samplereport.png` compressed from ~5.0 MB to ~0.35 MB (14×) as an interim fix; full regeneration from the fixture app lands in PR-09. (PR-02) diff --git a/dsgai_scanner_tool/README.md b/dsgai_scanner_tool/README.md index 5df76c0..c774ff7 100644 --- a/dsgai_scanner_tool/README.md +++ b/dsgai_scanner_tool/README.md @@ -2,10 +2,10 @@ [![OWASP](https://img.shields.io/badge/OWASP-GenAI%20Data%20Security-blue)](https://genai.owasp.org/initiative/data-security/) [![Framework](https://img.shields.io/badge/Framework-DSGAI%202026%20v1.0-purple)](https://genai.owasp.org/resource/owasp-genai-data-security-risks-mitigations-2026/) -[![Skill Version](https://img.shields.io/badge/Skill-v0.2-green)](./CHANGES_v0.2.md) +[![Skill Version](https://img.shields.io/badge/Skill-v0.3-green)](./CHANGES_v0.3.md) [![License](https://img.shields.io/badge/License-CC%20BY--SA%204.0-lightgrey)](https://creativecommons.org/licenses/by-sa/4.0/) -A Claude Code slash command that automatically scans GenAI and agentic codebases against the **OWASP GenAI Data Security Risks and Mitigations 2026 (v1.0)** — covering all 21 DSGAI risk controls across the full GenAI data lifecycle. The report is **strict-by-default redacted** so it's safe to share with auditors, attach to tickets, or store in a public repo. +Scans GenAI and agentic codebases against the **OWASP GenAI Data Security Risks and Mitigations 2026 (v1.0)** — all 21 DSGAI risk controls across the GenAI data lifecycle. A **deterministic CLI** (`cli/dsgai_scan.py`) owns pattern matching so results are reproducible; the **Claude Code skill** orchestrates and writes the report. The report is **strict-by-default redacted** (file IDs + line numbers only, value-bearing matches never shown) — designed to minimize disclosure. It is not automatically public-safe: the existence and location of failing controls is itself information, so handle it like any security assessment. Part of the [OWASP GenAI Data Security Initiative](https://genai.owasp.org/initiative/data-security/). @@ -53,13 +53,19 @@ curl -fsSL https://raw.githubusercontent.com/GenAI-Security-Project/GenAI-Data-S cd ~/my-genai-app claude -# 3. Run the scan +# 3. Run the scan (the skill prefers the deterministic CLI if bundled) /dsgai_scanner_tool -# 4. Open the report (auto-saved at repo root) -open DSGAI-report.html # macOS -xdg-open DSGAI-report.html # Linux -start DSGAI-report.html # Windows +# 4. Open the timestamped report from dsgai-reports/ +open dsgai-reports/DSGAI-report-*.html # macOS +xdg-open dsgai-reports/DSGAI-report-*.html # Linux +start dsgai-reports\DSGAI-report-.html # Windows +``` + +**Deterministic, LLM-free option ($0):** run the CLI directly for reproducible findings + SARIF, no API cost: + +```bash +python dsgai_scanner_tool/cli/dsgai_scan.py scan . --sarif DSGAI-scan.sarif ``` That's it. Full installation, flags, and CI integration are documented below. @@ -73,7 +79,7 @@ When you run `/dsgai_scanner_tool` inside a repository, the skill: 1. **Detects** whether the repo contains GenAI/agentic patterns (LangChain, LlamaIndex, OpenAI SDK, vector stores, MCP servers, etc.) — bails out gracefully if none are found. 2. **Enriches live CVEs** by querying OSV, NVD, GitHub Advisory Database, and AVID against the exact package versions pinned in the repo (Python, JS/TS, Java, **Go**). 3. **Scans source code** for all 21 DSGAI risk indicators across all 21 controls — credentials, SQL injection via LLM output, vector store auth, telemetry logging, RAG access controls, MCP transport security, resilience, multimodal handling, synthetic data, labeling pipelines, IDE plugin scoping, and more. -4. **Generates `DSGAI-report.html`** — a self-contained, print-ready HTML report with findings, file locations, line numbers, remediation steps, MITRE ATLAS technique mapping, and a live CVE advisory panel — **with strict-by-default obfuscation so the report is safe to share**. +4. **Generates a timestamped `dsgai-reports/DSGAI-report-.html`** — a self-contained, print-ready HTML report with findings, file locations, line numbers, remediation steps, MITRE ATLAS technique mapping, and a CVE advisory panel — **strict-by-default obfuscation designed to minimize disclosure** (share under security-assessment handling; see *Residual risk*). **Performance:** All 21 control scans and all CVE source queries run as parallel tool calls — the skill fires multiple grep scans and API requests simultaneously rather than sequentially. Typical scan time: 2–5 minutes (in Claude Code; other AI tools may run sequentially and take longer). @@ -308,7 +314,7 @@ All 17 remaining controls (DSGAI01, 03–12, 16–21) are **STRUCTURAL** — mat

Sample DSGAI compliance report showing dashboard, findings cards, and CVE advisory panel
- Sample DSGAI-report.html — Section 1 (Compliance) and Section 2 (CVE Advisory). Click for full size. + Sample DSGAI report — Section 1 (Compliance) and Section 2 (CVE Advisory). This interim image will be regenerated from the public fixture app once the deterministic report template lands (v0.3.x), guaranteeing zero real-repo disclosure and a reproducible screenshot.

The generated `DSGAI-report.html` contains: @@ -342,12 +348,12 @@ The file contains only **structural scan metadata**: detected framework versions The same redaction rules that apply to the HTML report apply here: - VALUE-BEARING findings store only `{control, path_rendered, line, pattern_id, status}` — never `match_text`, `raw_grep_output`, or `value` -- In STRICT mode, the `path_internal` field is omitted entirely — the checkpoint is itself safe to share +- In STRICT mode, the `path_internal` field is omitted entirely — keeping full paths out of the checkpoint, which minimizes disclosure without making the checkpoint public-safe - In INTERNAL mode, both `path_rendered` and `path_internal` are present for team convenience ### Lifecycle -Safe to commit (in STRICT mode it contains no secrets and no full paths) or add to `.gitignore` as a build artifact. Automatically overwritten on each full scan. +In STRICT mode it contains no secrets and no full paths, but it still records which controls fail and where — treat it as a security artifact (commit only if your repo's threat model allows, or `.gitignore` it). Regenerated on each full scan. --- @@ -399,8 +405,20 @@ Controls with BUY-side aspects (DSGAI01, 08, 09, 20) generate a consolidated "Ve --- +## Cost & runtime + +- **CLI-only mode: $0.** `python cli/dsgai_scan.py scan .` uses no LLM — just ripgrep. Reproducible findings + SARIF in seconds. This is what the hardened GitHub Action runs on every PR (including fork PRs, since it needs no secrets). +- **Skill mode (LLM orchestration):** a full scan of the public fixture app renders in roughly **1–3 minutes** in Claude Code; token cost depends on repo size and the report prose. The deterministic engine does the matching; the model only classifies, writes remediation prose, and renders the report — so cost scales with findings, not lines of code. +- **Fork PRs:** the Action's scan job runs on forks and uploads the SARIF as an artifact (Code Scanning upload is skipped — fork tokens can't write security events); the LLM narration job is skipped on forks by design. +- Incremental `--diff` scans (seconds, near-zero cost) are planned for **v0.4**. + ## Contributing +> **Found a wrong result? That's a contribution.** Run the scan on your repo and file a +> [false-positive](../.github/ISSUE_TEMPLATE/scanner-false-positive.yml) or +> [false-negative](../.github/ISSUE_TEMPLATE/scanner-false-negative.yml) issue — every +> accepted report becomes a permanent, credited test case. No code required. + This is an OWASP project. Contributions welcome — open an issue or PR against [GenAI-Security-Project/GenAI-Data-Security-Initiative](https://github.com/GenAI-Security-Project/GenAI-Data-Security-Initiative). When proposing new scan patterns: