AGENT SKILL

vulnerability-csv-reporting

Generate CSV security audit reports from scanner JSON with correct inclusion filtering, CVSS extraction as a separate attribute, and post-write verification against the source.

License 许可
Apache-2.0
最近更新
2026-11-14
Stars
★ 0
Forks
1

01 前言 Front Matter

name
vulnerability-csv-reporting
description
Generate CSV security audit reports from scanner JSON with correct inclusion filtering, CVSS extraction as a separate attribute, and post-write verification against the source.

03 SKILL.md 正文

Vulnerability CSV Report Generation

This skill provides guidance on generating structured CSV reports from vulnerability scan data—a common format for security audits and compliance reporting.

Plan and verify the report shape

  1. Decide what defines the inclusion set (e.g., “all HIGH/CRITICAL findings”); prefer a scanner-provided field for inclusion unless the task explicitly requires CVSS-threshold filtering.
  2. Decide whether your report’s Severity column is scanner-provided or derived from CVSS; do not mix sources without an explicit reconciliation rule.
  3. Choose a single CVSS source priority (e.g., NVD → GHSA → vendor) and keep the chosen source/version/score together as a unit.
  4. Define the schema first (headers and types), then implement mapping.
  5. After writing, verify that the CSV rows match the intended inclusion set from the source JSON (counts + identifier diff).

CSV generation with DictWriter

Use csv.DictWriter with an explicit header order.

import csv

def write_csv(path, rows, headers):
    with open(path, "w", newline="", encoding="utf-8") as f:
        w = csv.DictWriter(f, fieldnames=headers)
        w.writeheader()
        w.writerows(rows)

Inclusion filtering: use scanner severity, not CVSS-derived severity

When asked for “all HIGH and CRITICAL vulnerabilities” from a scanner report, filter by the scanner’s severity label (e.g., vuln["Severity"]) and treat CVSS as an independent attribute for reporting.

def include_finding(vuln, allowed=("HIGH", "CRITICAL")):
    sev = (vuln.get("Severity") or "").upper()
    return sev in set(allowed)

Decision rule: Only filter by CVSS threshold (or CVSS-derived severity) when the task explicitly defines inclusion by CVSS score; otherwise, do not let CVSS availability/parsing change which rows are included.

Read references/trivy-severity-vs-cvss.md when you are producing a HIGH/CRITICAL (or similar) subset from Trivy JSON and also extracting CVSS. Skip when you are not filtering (you are reporting all findings).

Coupling Severity with the selected CVSS score

When you emit both Severity and CVSS_Score, treat them as a coupled pair.

  • Option A: compute Severity from the chosen numeric CVSS (standard v3 ranges).
  • Option B: emit scanner-provided Severity and treat CVSS as informational; in this mode, do not recompute severity from CVSS.
def cvss_v3_severity(score):
    if score is None:
        return "UNKNOWN"
    if score >= 9.0:
        return "CRITICAL"
    if score >= 7.0:
        return "HIGH"
    if score >= 4.0:
        return "MEDIUM"
    if score > 0.0:
        return "LOW"
    return "NONE"

Read references/severity-cvss-consistency.md when the output includes both a severity label and a numeric CVSS score. Skip when the report contains only one of them (severity-only or score-only).

Field mapping from JSON to CSV

Map nested scanner output into a flat record per vulnerability.

import json

def iter_findings(report_path):
    data = json.load(open(report_path, "r", encoding="utf-8"))
    for result in data.get("Results", []):
        for vuln in result.get("Vulnerabilities", []) or []:
            yield vuln


def to_row(vuln, score_info=None):
    return {
        "Package": vuln.get("PkgName") or "Unknown",
        "Version": vuln.get("InstalledVersion") or "N/A",
        "VulnerabilityID": vuln.get("VulnerabilityID") or "N/A",
        "Severity": vuln.get("Severity") or "UNKNOWN",
        "CVSS_Score": (score_info or {}).get("score") or "N/A",
    }

Common Pitfalls

  • Filtering by a CVSS-derived severity (or CVSS availability) when the task asks for scanner-severity subsets (you can silently omit findings).
  • Mixing a scanner’s Severity label with a CVSS score extracted from a different advisory source without recording provenance.
  • Writing CSV without verifying counts/IDs against the source JSON (well-formed output can still be incomplete).

04 同仓库更多 Skills