@ulisesgascon/openjs-cna-tools 0.0.0-stage → 1.0.0-alpha.3

package/lib/prompt.js

@@ -0,0 +1,170 @@
+// Build an LLM audit prompt for a v5.2 CVE Record's natural-language
+// fields. The CLI side just prints the result; the user pastes it into
+// the LLM of their choice (no network call from this tool).
+//
+// What we ask the LLM to do:
+//   * audit the title against the OpenJS naming convention
+//   * audit the description for clarity, tone, and editorial rules
+//     (no PoCs, no em/en-dashes, no cross-references to other private
+//     advisories, references belong in cna.references[] not in prose)
+//   * return Markdown with a rating + a per-issue list including a
+//     suggested rewrite where applicable.
+//
+// The prompt embeds:
+//   * the title
+//   * the plain-text description (descriptions[0].value)
+//   * the raw Markdown if supportingMedia[0].type === text/markdown
+//   * a short facts block (affected, CVSS, CWE) so the LLM grounds its
+//     suggestions in what the vulnerability actually is.
+
+function getCna (record) {
+  return record?.containers?.cna ?? {}
+}
+
+function getDescription (cna) {
+  return cna?.descriptions?.find(d => d?.lang === 'en') ?? cna?.descriptions?.[0] ?? null
+}
+
+function getMarkdown (description) {
+  if (!description?.supportingMedia) return null
+  const media = description.supportingMedia.find(m => m?.type === 'text/markdown')
+  return media?.value ?? null
+}
+
+function summarizeAffected (cna) {
+  return (cna?.affected ?? []).map((a) => {
+    const product = `${a.vendor ?? '?'}:${a.product ?? '?'}`
+    const ranges = (a.versions ?? []).map((v) => {
+      if (v.lessThan) return `${v.version} → < ${v.lessThan}`
+      if (v.lessThanOrEqual) return `${v.version} → ≤ ${v.lessThanOrEqual}`
+      return v.version
+    })
+    return ranges.length === 0 ? product : `${product} (${ranges.join(', ')})`
+  })
+}
+
+// Metric blocks the record format accepts, in display preference order.
+const CVSS_BLOCKS = [
+  { key: 'cvssV3_1', label: 'CVSS 3.1' },
+  { key: 'cvssV4_0', label: 'CVSS 4.0' },
+  { key: 'cvssV3_0', label: 'CVSS 3.0' }
+]
+
+function summarizeCvss (cna) {
+  for (const m of cna?.metrics ?? []) {
+    for (const { key, label } of CVSS_BLOCKS) {
+      if (m?.[key]?.vectorString) {
+        const { vectorString, baseScore, baseSeverity } = m[key]
+        return { label, body: `${baseScore ?? '?'} ${baseSeverity ?? ''} (${vectorString})`.replace(/\s+/g, ' ').trim() }
+      }
+    }
+  }
+  return null
+}
+
+function summarizeCwes (cna) {
+  const out = new Set()
+  for (const pt of cna?.problemTypes ?? []) {
+    for (const d of pt?.descriptions ?? []) {
+      if (d?.cweId) out.add(d.cweId)
+    }
+  }
+  return [...out]
+}
+
+// Generate the full LLM prompt as a string. Caller is responsible for
+// printing it; this stays pure so it's trivial to test.
+export function buildAuditPrompt (record) {
+  const cna = getCna(record)
+  const description = getDescription(cna)
+  const title = cna?.title ?? '(no title)'
+  const value = description?.value ?? '(no description)'
+  const markdown = getMarkdown(description)
+  const affected = summarizeAffected(cna)
+  const cvss = summarizeCvss(cna)
+  const cwes = summarizeCwes(cna)
+  const cveId = record?.cveMetadata?.cveId
+
+  const lines = []
+  lines.push(
+    'You are reviewing the natural-language fields of a CVE record before it ships to MITRE.',
+    'The fields are read by application developers and security tooling worldwide.',
+    'Be concise, factual, and editorial. Flag what should change and why.',
+    '',
+    '## Editorial guidelines',
+    '',
+    '**Title** (`cna.title`):',
+    '- Format: `<package> vulnerable to <Vulnerability Type>` or `<package> vulnerable to <Type> via <Vector>`.',
+    '- 6 to 15 words. Package name lowercase as it appears on npm.',
+    '- Spell out vulnerability classes (e.g. "Denial of Service", not "DoS"; "Cross-Site Scripting", not "XSS").',
+    '',
+    '**Description** (`cna.descriptions[0].value`):',
+    '- Plain English. No raw PoCs, exploit code, or step-by-step attack walkthroughs. Those belong in the advisory body, not the CVE record.',
+    '- No em-dashes (—) or en-dashes (–). Use periods or commas instead.',
+    '- No references to other private advisories (consumers cannot see them).',
+    '- URLs do **not** belong in the description prose. They live in `cna.references[]`. Flag any that leaked in.',
+    '- Match the tone of prior published advisories: short, neutral, factual. No alarmist language ("catastrophic", "blocks the entire event loop"). State facts.',
+    '- Sections (Impact / Patches / Workarounds) should be labelled clearly and read as standalone paragraphs.',
+    '',
+    '**General**:',
+    '- Confusing or ambiguous wording is a defect. Flag it.',
+    '- Inconsistencies between the title, description, and the facts block (affected, CWE, CVSS) are also defects.',
+    '- Do not invent facts. If a guideline cannot be evaluated from the text alone, say so.',
+    '',
+    '## Record context',
+    ''
+  )
+  if (cveId) lines.push(`- **CVE**: ${cveId}`)
+  if (affected.length > 0) lines.push(`- **Affected**: ${affected.join('; ')}`)
+  if (cvss) lines.push(`- **${cvss.label}**: ${cvss.body}`)
+  if (cwes.length > 0) lines.push(`- **CWE**: ${cwes.join(', ')}`)
+  lines.push(
+    '',
+    '## Title to audit',
+    '',
+    '```',
+    title,
+    '```',
+    '',
+    '## Description (plain-text value)',
+    '',
+    '```',
+    value,
+    '```'
+  )
+  if (markdown) {
+    lines.push(
+      '',
+      '## Description (original Markdown, from supportingMedia)',
+      '',
+      '```markdown',
+      markdown,
+      '```'
+    )
+  }
+  lines.push(
+    '',
+    '## Respond in this exact Markdown shape',
+    '',
+    '```markdown',
+    '**Rating**: ready | needs-work | blocked',
+    '',
+    '### Issues',
+    '',
+    '- **[field]** *(severity: blocker | warning | suggestion)*: what is wrong, in one sentence.',
+    '  - **Suggested rewrite**: a concrete replacement, OR "n/a" if the issue is about deletion / structure rather than wording.',
+    '',
+    '(Omit the Issues section entirely if Rating is "ready".)',
+    '',
+    '### Rewritten title (only if the title needs work)',
+    '',
+    'Single-line suggested replacement.',
+    '',
+    '### Rewritten description (only if the description needs material edits)',
+    '',
+    'A full replacement, in the same plain-text style as the original.',
+    '```',
+    ''
+  )
+  return lines.join('\n')
+}

package/lib/record.js

@@ -0,0 +1,123 @@
+// Helpers for the parts of a v5.2 CVE Record that are about the record
+// format rather than about where the data came from: the CVSS metric block
+// and the record envelope. Converters (GHSA here, release trackers in
+// downstream projects) build the container fields they know about and use
+// these so the format-level details are written once.
+
+import { USER_AGENT } from './client.js'
+import { calculateBaseScore, severityFromScore } from './cvss.js'
+import { OPENJS_CNA_ORG_ID } from './review/schema.js'
+
+// MITRE schema version we emit on every Record. Matches what every CVE
+// published by the OpenJS CNA carries today.
+export const DATA_VERSION = '5.2'
+
+// Metric block key per CVSS version prefix. v2 is not emitted by anything
+// the foundation publishes, so it is left out on purpose.
+const METRIC_KEYS = new Map([
+  ['3.0', 'cvssV3_0'],
+  ['3.1', 'cvssV3_1'],
+  ['4.0', 'cvssV4_0']
+])
+
+/**
+ * Build one `metrics[]` entry from a CVSS vector string.
+ *
+ * The block key (`cvssV3_0`, `cvssV3_1`, `cvssV4_0`) follows the vector's
+ * `CVSS:<version>/` prefix, which is what MITRE validates each block
+ * against. `baseScore` is taken from `options.baseScore` when given and
+ * computed from the vector otherwise (v3.x only; v4.0 has no bundled
+ * calculator). `baseSeverity` is always derived from the final score.
+ *
+ * A vector with an unknown prefix or one the calculator rejects is passed
+ * through under the closest key with no score, so the reviewer can report
+ * it instead of this helper guessing.
+ */
+export function buildCvssMetric (vectorString, { baseScore } = {}) {
+  const vector = String(vectorString ?? '').trim()
+  const version = vector.match(/^CVSS:(\d\.\d)\//)?.[1]
+  const key = METRIC_KEYS.get(version) ?? 'cvssV3_1'
+
+  let score = typeof baseScore === 'number' ? baseScore : undefined
+  if (score === undefined && (version === '3.0' || version === '3.1')) {
+    try {
+      score = calculateBaseScore(vector).baseScore
+    } catch {}
+  }
+
+  return {
+    format: 'CVSS',
+    [key]: {
+      version: version ?? '3.1',
+      vectorString: vector,
+      ...(score !== undefined ? { baseScore: score, baseSeverity: severityFromScore(score) } : {})
+    }
+  }
+}
+
+/**
+ * Build one `problemTypes[]` entry from one or more CWE references.
+ *
+ * Accepts a single `{ cweId, name? }` or an array of them. `cweId` may be
+ * given as `400`, `CWE-400` or `cwe-400` and is normalised to the
+ * `CWE-<number>` form MITRE's pattern requires; anything else throws so
+ * the mistake surfaces at build time. `description` is required by MITRE,
+ * so it is the CWE name when known and the id otherwise.
+ */
+export function buildProblemType (cwes) {
+  const list = Array.isArray(cwes) ? cwes : [cwes]
+  if (list.length === 0) {
+    throw new TypeError('buildProblemType: at least one CWE reference is required')
+  }
+  return {
+    descriptions: list.map(({ cweId, name } = {}) => {
+      const id = String(cweId ?? '').trim().match(/^(?:CWE-)?([1-9]\d*)$/i)?.[1]
+      if (!id) {
+        throw new TypeError(`buildProblemType: '${cweId}' is not a CWE id (expected CWE-<number>)`)
+      }
+      const text = String(name ?? '').trim()
+      return {
+        lang: 'en',
+        type: 'CWE',
+        cweId: `CWE-${id}`,
+        description: text || `CWE-${id}`
+      }
+    })
+  }
+}
+
+/**
+ * Wrap a CNA container in the v5.2 Record envelope.
+ *
+ * Sets `providerMetadata.orgId` and `x_generator.engine` on the container
+ * when the caller has not, so no consumer needs to know the OpenJS CNA org
+ * id or the generator string. `cveMetadata` is emitted only when `cveId` is
+ * given; without it the publisher's CLI argument is the sole source of
+ * truth for the id.
+ */
+export function buildRecordEnvelope ({
+  cna,
+  cveId,
+  assignerOrgId = OPENJS_CNA_ORG_ID,
+  engineId = USER_AGENT,
+  dataVersion = DATA_VERSION
+} = {}) {
+  if (!cna || typeof cna !== 'object') {
+    throw new TypeError('buildRecordEnvelope: `cna` must be the CNA container object')
+  }
+  const container = {
+    providerMetadata: { orgId: assignerOrgId },
+    ...cna,
+    // x_ prefixes are MITRE's extension namespace. x_generator is the
+    // canonical place to surface "this container was produced by …".
+    x_generator: cna.x_generator ?? { engine: engineId }
+  }
+  return {
+    dataType: 'CVE_RECORD',
+    dataVersion,
+    ...(cveId
+      ? { cveMetadata: { cveId, assignerOrgId, state: 'PUBLISHED' } }
+      : {}),
+    containers: { cna: container }
+  }
+}

package/lib/review/index.js

@@ -0,0 +1,78 @@
+// reviewRecord(record, { strict }) -> review report
+//
+// Sync, offline. Validates a full v5.2 CVE Record:
+//   { dataType, dataVersion, cveMetadata, containers: { cna: {...} } }
+//
+// MITRE's official schema check (via ajv) runs against the whole Record;
+// the editorial rules in ./rules.js then walk the inner cna container.
+
+import { RULES } from './rules.js'
+import { validateAgainstMitreSchema } from './schema.js'
+
+// `strict` defaults to true because publishing to MITRE is irreversible:
+// every warning the reviewer surfaces blocks until the operator opts out
+// explicitly via `--no-strict` (CLI) or `{ strict: false }` (library).
+export function reviewRecord (record, { strict = true } = {}) {
+  const issues = []
+
+  // MITRE schema first. Every schema violation is a blocker because
+  // publish will fail downstream — there is no soft version of "doesn't
+  // match the schema MITRE uses". One issue per ajv error so operators
+  // see exactly what's wrong.
+  for (const err of validateAgainstMitreSchema(record)) {
+    issues.push({
+      rule: 'mitre-schema',
+      // Schema violations always fail at MITRE's end too.
+      tier: 'mitre-common',
+      severity: 'blocker',
+      path: err.path,
+      message: err.message
+    })
+  }
+
+  // Editorial rules look at just the cna container — drill in once here.
+  const cna = record?.containers?.cna ?? {}
+
+  for (const rule of RULES) {
+    let result
+    try {
+      result = rule.check(cna)
+    } catch (e) {
+      // A buggy rule shouldn't fail the review. Surface as a warning so the
+      // operator knows to file an issue.
+      issues.push({
+        rule: `${rule.id}:internal-error`,
+        // Carry the source rule's tier through so the --tier filter still
+        // works in the unlikely event the rule itself blew up.
+        tier: rule.tier,
+        severity: 'warning',
+        path: 'reviewer',
+        message: `Rule '${rule.id}' threw: ${e.message}`
+      })
+      continue
+    }
+    if (result) {
+      issues.push({
+        rule: rule.id,
+        tier: rule.tier,
+        severity: strict && rule.severity === 'warning' ? 'blocker' : rule.severity,
+        path: result.path,
+        message: result.message
+      })
+    }
+  }
+
+  const blockers = issues.filter(i => i.severity === 'blocker').length
+  const warnings = issues.filter(i => i.severity === 'warning').length
+  const suggestions = issues.filter(i => i.severity === 'suggestion').length
+
+  let rating
+  if (blockers > 0) rating = 'blocked'
+  else if (warnings > 0) rating = 'needs-work'
+  else rating = 'ready'
+
+  return {
+    summary: { rating, blockers, warnings, suggestions, total: issues.length },
+    issues
+  }
+}