docs: rewrite README around PQ crypto + CBOM + CNSA 2.0 (closes #247)#255
docs: rewrite README around PQ crypto + CBOM + CNSA 2.0 (closes #247)#255peaktwilight merged 4 commits intomainfrom
Conversation
…247) Restructure first screen around the 4 personas (scan, pqc, cbom, tui), add a dedicated post-quantum section with CNSA 2.0 deadline context and CBOM framing, condense install/CI/config sections, and drop to 183 lines from 305. Keep badge row, logo, existing assets, and the Semgrep/OpenGrep compatibility framing.
|
Warning Rate limit exceeded
Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 0 minutes and 49 seconds. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📝 WalkthroughWalkthroughDocumentation-only update to README.md repositioning the tool from a general fast security scanner to a specialized Rust binary focused on post-quantum cryptography auditing, with emphasis on CNSA 2.0 compliance, CycloneDX 1.6 CBOM export, and TUI-based triage capabilities. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related issues
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@README.md`:
- Line 36: Update the README sentence that currently claims foxguard "bakes
PQ-vulnerable-crypto rules into the default scan" to clarify that PQ auditing is
provided via a dedicated subcommand; specifically replace that clause with
wording like "foxguard provides a dedicated `pqc` subcommand for
PQ-vulnerable-crypto auditing" so users aren’t misled into thinking `npx
foxguard .` (the default scan) includes PQ scanning—ensure the revised sentence
references the `pqc` subcommand and keeps the rest of the description about
annotations and CycloneDX CBOM unchanged.
- Around line 26-31: The README caption overstates the demo capabilities: update
the caption text around the <code>foxguard tui .</code> snippet to accurately
reflect that the existing demo.gif only shows the scan flow (e.g., "interactive
triage — scan mode shown") and add a short TODO or issue link note indicating
that a re-recorded demo is needed to showcase diff, secrets, and PQ modes;
ensure the updated copy replaces the phrase "scan, diff, secrets, and PQ modes"
and mentions that other modes will be added once a new demo is produced.
- Line 34: The README contains a casing error: change the repository reference
string "github/codeql" to "GitHub/codeql" and any other occurrences of lowercase
"github" in the same sentence to the correct "GitHub" spelling; update the
phrase in the sentence mentioning GitHub's advanced-security/cbom-action and the
CodeQL queries so the organization name is capitalized as "GitHub" while leaving
repository names unchanged.
- Around line 79-88: The fenced code block in README.md that currently contains
the terminal output (the lines beginning with "src/tls/client.go" and the
pq-vulnerable-crypto warning) must include a language identifier for proper
highlighting; update the opening triple backticks to include a language token
such as console or text (e.g., change ``` to ```console) so the block is
recognized as terminal output.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
| <img src="assets/demo.gif" alt="foxguard scan demo" width="640" /> | ||
| </p> | ||
|
|
||
| <p align="center"> | ||
| <img src="assets/tui-findings.png" alt="foxguard TUI findings list with source/sink dataflow" width="640" /> | ||
| <br/><em>v0.7.0 adds <code>foxguard tui .</code> for interactive triage — scan, diff, and secrets modes with in-app review, baseline, and ignore actions. <a href="https://foxguard.dev/blog/foxguard-0-7-0-tui-launch">Read the launch post</a>.</em> | ||
| <br/><em><code>foxguard tui .</code> — interactive triage with scan, diff, secrets, and PQ modes. <a href="https://foxguard.dev/blog/foxguard-0-7-0-tui-launch">Launch post</a>.</em> |
There was a problem hiding this comment.
Caption overpromises compared to the demo asset.
The caption on line 31 states the TUI supports "scan, diff, secrets, and PQ modes," but according to the PR objectives, demo.gif only shows the scan-only flow and may need re-recording to demonstrate all four modes.
Do you want me to open an issue to track re-recording the demo with all four modes, or would you prefer to update the caption to reflect only what the current asset shows?
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@README.md` around lines 26 - 31, The README caption overstates the demo
capabilities: update the caption text around the <code>foxguard tui .</code>
snippet to accurately reflect that the existing demo.gif only shows the scan
flow (e.g., "interactive triage — scan mode shown") and add a short TODO or
issue link note indicating that a re-recorded demo is needed to showcase diff,
secrets, and PQ modes; ensure the updated copy replaces the phrase "scan, diff,
secrets, and PQ modes" and mentions that other modes will be added once a new
demo is produced.
Greptile SummaryThis PR rewrites the README from a generic "fast security scanner" pitch to a v0.8.0-focused document leading with the CNSA 2.0 / post-quantum problem that foxguard addresses. The rewrite compresses 305 → 183 lines, adds dedicated PQ audit and CBOM sections, and makes several honest-framing corrections (names existing CBOM tools, adds a hedge to the "first" claim, correctly attributes the CodeQL action). Verification performed:
Issues found:
Confidence Score: 4/5Safe to merge after bumping the CI action pin from @v0.7.1 to @v0.8.0; all other content is accurate and well-sourced. All factual claims in the new content were verified against the source code (rule ID, CWE, migration-level strings) and external sources (CNSA 2.0 FAQ URL). One concrete P1 remains: the CI action is pinned to a version that predates every feature this README documents, which would actively mislead new adopters. Fixing that one line makes this mergeable. README.md line 118 (action pin) and line 130 (benchmark version note) Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[npx foxguard] --> B{Subcommand?}
B -->|none| C[Core scan\n170+ rules, taint tracking\nSARIF / JSON / terminal output]
B -->|pqc| D[PQ crypto audit\nCNSA 2.0 deadline annotations\nML-KEM / ML-DSA guidance]
B -->|--format cbom| E[CycloneDX 1.6 CBOM\nEvery component linked to\nsource location + severity]
B -->|tui| F[Interactive TUI\nscan / diff / secrets / pqc modes\nBaseline, ignore, severity override]
B -->|secrets| G[Secrets scan\nAWS, GitHub, Stripe tokens\nRedacted output + baseline]
B -->|diff| H[Changed-file scan\nNew findings vs target branch\n--github-pr review comments]
C --> I[CI: SARIF upload to\nGitHub Code Scanning]
D --> I
E --> J[Compliance reporting\nCBOM feeds SBOMs / audits]
|
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| ## Benchmarks | ||
|
|
||
| Or run `foxguard init` to install a git hook directly. | ||
| Reproducible via `./benchmarks/run.sh`. Numbers below are from a local run on an Apple Silicon laptop with `foxguard 0.6.2`, `semgrep 1.156.0`, `tokei 14.0.0`. LoC is counted by tokei, scoped to the target language only (no vendored HTML/JSON). |
There was a problem hiding this comment.
The benchmark prose calls out foxguard 0.6.2 as the measured version. This README is explicitly being rewritten for v0.8.0, so a reader has no way to know whether the numbers still hold — particularly since the new PQ rule set and CBOM serialization path add work to the default scan. Even a one-word note (e.g., "numbers measured with foxguard 0.6.2; see benchmarks/README.md for the current run") would keep the claim honest until the benchmarks are re-run against v0.8.0.
Previous hook and tagline led with "post-quantum crypto audit" as if that were foxguard's identity. It's one of four modes (scan, diff, secrets, pqc). Rewrite the tagline and intro paragraph to describe what foxguard IS at steady state, promote a "the four modes" table to the top of the content, and demote the PQ deep-dive to a feature section further down. Drops all "v0.8 adds..." framing — the README is product docs, not release notes.
1 participant
Summary
Rewrites README for v0.8.0 per #247. Down from 305 → 183 lines. First screen covers all four personas (scan / pqc / cbom / tui) and leads with the CNSA 2.0 user problem instead of a generic "security scanner" pitch.
Honest-framing moves (from the pre-publication fact-check)
advanced-security/cbom-actionand experimental queries), so HN doesn't tear us down for pretending it doesn't exist"As far as we can tell"hedge — "first OSS source-code scanner that annotates each PQ finding with its CNSA 2.0 migration deadline"Sections cut or condensed
foxguard.dev/rules+docs/precision.mdStructure
Example-output accuracy
Initial agent draft had a synthetic example with
go/pq-vulnerable-crypto-ecdh+CWE-1240. Grepping the rule definitions showed the real ID isgo/pq-vulnerable-cryptoand CWE isCWE-327. Migration-level string fixed to match the actualcompliance.rsoutput ("at-risk" / "on-track" / "clean"), not the invented "82% PQ-safe". Fixed in commit 994c591.Deferred / noted
assets/demo.gifstill shows scan-only flow — worth re-recording for the PQ+CBOM+TUI sequence before cutting v0.8.0Verification
foxguard.dev/rulesandfoxguard.dev/blog/foxguard-0-7-0-tui-launchwhich I'm assuming exist — please verify on the site)Closes #247.
Summary by CodeRabbit