codeguard-cve

codeguard cve

Capability Boundaries

✅ Strengths

1. Automatically detect the ecosystem and orchestrate the corresponding scanning tool
2. Language recognized but no native ecosystem mapping → automatically fall back to universal(trivy fs --scanners vuln); when a native ecosystem exists, do not run the fallback in parallel
3. --severity means "that level and above", with the same semantics across all scanners (maven converts by the CVSS band lower bound, HIGH⇒7)
4. Exit codes: 0 pass / 1 unverifiable / 2 vulnerabilities found / 3 parameter error (reject before any scan if --ecosystem is not declared)
5. Threshold gating (--severity MEDIUM/HIGH/CRITICAL）
6. --fix automatic fix (npm audit fix); for other ecosystems output remediation guidance
7. Three-state exit codes: 0=pass / 1=unverifiable (tool missing) / 2=vulnerabilities found

⚠️ Prerequisites

1. Maven: mvn + network (first run downloads the NVD database; applying for an NVD_API_KEY is recommended)
2. Node：npm + package-lock.json
3. Python：pip-audit（pip install pip-audit）
4. Rust：cargo-audit（cargo install cargo-audit）
5. Generic fallback: trivy (brew install trivy) — triggered only when a language with no native scanner is detected (Go/PHP/Ruby, etc.)

❌ Out of Scope

1. OS package CVEs in images → trivy image (can be integrated later)
2. Dockerfile misconfig → codeguard-dockerfile
3. Exemption policy formulation → codeguard-security-code

Command

Determine the engine first; the two command surfaces differ. Rust codeguard component's cve uses positional arguments to select the ecosystem, and has no --severity / --fix / --json; for the quality path it always returns incomplete (exit code 3) and cannot be used to issue a "no vulnerabilities" conclusion.

Legacy Python engine:

bin/codeguard cve                          # 全生态扫描
bin/codeguard cve --ecosystem node         # 只扫 node
bin/codeguard cve --fix                    # 扫描 + 自动修复 + 复扫
bin/codeguard cve --severity MEDIUM        # 门禁阈值调到中危（发版前）
bin/codeguard cve --json path/             # 结构化输出

Rust component (partial native observation, conclusion remains incomplete):

codeguard cve typescript [path] --node-tool ABS_PATH --npm-entry ABS_PATH --npm-version VERSION
codeguard cve rust [path] --cargo-audit-tool ABS_PATH --db ABS_PATH
codeguard cve python [path] --pip-audit-tool ABS_PATH --pip-audit-version VERSION

For the engine determination and comparison of the two command surfaces, see the codeguard skill's references/operations/engine-contract.md。

Three-state semantics (gating must comply)

Exit code	Meaning	Gating action
0	All passed	Allow commit
1	Unverifiable (tool missing/timeout)	Not considered passed— install the tool first
2	Vulnerabilities found	Must be fixed (upgrade/replace/register mitigation); reporting without handling is prohibited
3	Check incomplete	Not considered passed— can only be stated as incomplete or partial observation

Workflow

1. Scan:bin/codeguard cve
2. If findings exist → read the report to locate affected packages and introduction paths (mvn dependency:tree / npm ls）
3. Remediation: prefer upgrading versions; if upgrade is not possible, provide mitigations (WAF/reduce exposure surface) and register a decommission date
4. Rescan until zero HIGH/CRITICAL
5. Run once more before committing to confirm

Out of scope (when not to use)

• The issue is container base images or OS packages, and Codeguard does not yet have evidence from such a scanner.
• The issue is source code secret leakage, authentication, or data security; it should be handed off to the corresponding security skill.
• There is no lockfile/dependency metadata but proof that no vulnerabilities exist is required.

Data and Security

Dependency names, versions, and lockfiles may be sent by scanning tools to external vulnerability data sources. Before execution, the network boundary must be explained, and source code, credentials, or private package contents must not be uploaded. Reports must not echo tokens/NVD keys; this skill will not automatically create suppressions or upgrade dependencies.

Evidence-Based Workflow

Step 1: Determine Ecosystem and Scope

Locate the lockfile, build files, workspace boundaries, and production/dev/test dependency classifications.

Step 2: Detect the Scanner

Record the scanner version, vulnerability database time, and gate thresholds. When the data source is unavailable, the status is UNVERIFIED。

Step 3: Perform a Read-Only Scan

Prefer bin/codeguard cve --json <path> to save structured evidence; do not include --fixduring the first scan. Under the Rust engine, switch to the --format json call of cve <生态> , and truthfully mark that result as incomplete.

Step 4: Confirm Exploitability and Introduction Path

Verify the CVE/GHSA, affected versions, fixed versions, direct/transitive dependencies, and whether the project uses the affected functionality.

Step 5: Choose Remediation

Prefer the smallest compatible upgrade, then replace the component or close the exposure surface. A suppression must have a false-positive basis, an owner, and an expiration date.

Step 6: Regression Testing

After dependency changes, perform lockfile diff review, compilation, unit tests, integration tests, and key compatibility checks.

Step 7: Rescan Using the Original Thresholds

Findings must not be "fixed" by raising thresholds. The report must list fixed, mitigated, suppressed, and unresolved items.

Rules

1. Inability to access the vulnerability data source does not equal zero vulnerabilities.
2. Do not blindly run npm audit fix --force or upgrade everything to the latest version.
3. Do not just copy the scanner title; you must confirm the dependency path and the available fixed version.
4. Mitigation does not equal remediation; residual risk and a tracking date must be stated.
5. The report must record the scan date and database freshness.
6. It must state which engine issued this scan; incomplete results from the Rust component must not be described as zero vulnerabilities.

Output Template

Codeguard CVE 结果
- 范围/生态：<workspace and lockfiles>
- 扫描器：<name/version/db timestamp>
- 阈值：<severity policy>
- 状态：PASS / FAIL / UNVERIFIED
- 发现：<CVE, dependency path, affected/fixed range>
- 处置：<upgrade/replace/mitigate/suppress with evidence>
- 回归：<build/test evidence>
- 复扫：<command and exit>

Gotchas

1. Missing lockfile: scanning based on declared versions may differ from the actual resolved versions.
2. NVD/registry rate limiting: a failed download on the first run is UNVERIFIED, not PASS.
3. dev dependencies can also reach production: build-chain supply chain risk cannot be ignored merely on the grounds of "not runtime."
4. A fixed version may break the API: this must be judged based on semver, the changelog, and regression evidence.
5. The same vulnerability introduced through multiple paths: upgrading only one direct dependency may still leave a transitive path.
6. Suppressions expire: suppressed items need an expiration date and re-verification conditions.

Load Resources on Demand

• When choosing the scanner and thresholds, read references/rules/scanner-matrix.md。
• When designing remediation/suppression evidence, read references/operations/remediation-playbook.md。
• Only read examples/ examples that match the current ecosystem or failure mode.