@pensar/apex 2.5.0 → 2.6.1-canary.025b1ecf

package/src/lib/cwe/cwe-catalog.ts

@@ -0,0 +1,444 @@
+/**
+ * Canonical CWE ID-to-Name lookup table.
+ *
+ * Contains common CWEs relevant to application and network security,
+ * sourced from the MITRE CWE database (https://cwe.mitre.org/).
+ *
+ * Covers: OWASP Top 10, CWE Top 25, and all CWEs referenced in the
+ * CVSS scorer system prompt.
+ *
+ * Key: numeric CWE ID (e.g., 79 for CWE-79)
+ * Value: canonical short name from MITRE
+ */
+export const CWE_CATALOG: ReadonlyMap<number, string> = new Map([
+  // CWE-NONE / Pillars / Categories referenced in findings
+  [16, "Configuration"],
+  [19, "Data Processing Errors"],
+  [20, "Improper Input Validation"],
+  [
+    22,
+    "Improper Limitation of a Pathname to a Restricted Directory ('Path Traversal')",
+  ],
+  [23, "Relative Path Traversal"],
+  [25, "Path Traversal: '/../filedir'"],
+  [29, "Path Traversal: '\\..\\filename'"],
+  [35, "Path Traversal: '.../...//'"],
+  [36, "Absolute Path Traversal"],
+  [59, "Improper Link Resolution Before File Access ('Link Following')"],
+  [
+    74,
+    "Improper Neutralization of Special Elements in Output Used by a Downstream Component ('Injection')",
+  ],
+  [
+    75,
+    "Failure to Sanitize Special Elements into a Different Plane (Special Element Injection)",
+  ],
+  [
+    77,
+    "Improper Neutralization of Special Elements used in a Command ('Command Injection')",
+  ],
+  [
+    78,
+    "Improper Neutralization of Special Elements used in an OS Command ('OS Command Injection')",
+  ],
+  [
+    79,
+    "Improper Neutralization of Input During Web Page Generation ('Cross-site Scripting')",
+  ],
+  [
+    80,
+    "Improper Neutralization of Script-Related HTML Tags in a Web Page (Basic XSS)",
+  ],
+  [83, "Improper Neutralization of Script in Attributes in a Web Page"],
+  [84, "Improper Neutralization of Encoded URI Schemes in a Web Page"],
+  [85, "Doubled Character XSS Manipulations"],
+  [
+    86,
+    "Improper Neutralization of Invalid Characters in Identifiers in Web Pages",
+  ],
+  [87, "Improper Neutralization of Alternate XSS Syntax"],
+  [
+    88,
+    "Improper Neutralization of Argument Delimiters in a Command ('Argument Injection')",
+  ],
+  [
+    89,
+    "Improper Neutralization of Special Elements used in an SQL Command ('SQL Injection')",
+  ],
+  [
+    90,
+    "Improper Neutralization of Special Elements used in an LDAP Query ('LDAP Injection')",
+  ],
+  [91, "XML Injection (aka Blind XPath Injection)"],
+  [93, "Improper Neutralization of CRLF Sequences ('CRLF Injection')"],
+  [94, "Improper Control of Generation of Code ('Code Injection')"],
+  [
+    95,
+    "Improper Neutralization of Directives in Dynamically Evaluated Code ('Eval Injection')",
+  ],
+  [
+    96,
+    "Improper Neutralization of Directives in Statically Saved Code ('Static Code Injection')",
+  ],
+  [
+    97,
+    "Improper Neutralization of Server-Side Includes (SSI) Within a Web Page",
+  ],
+  [
+    98,
+    "Improper Control of Filename for Include/Require Statement in PHP Program",
+  ],
+  [99, "Improper Control of Resource Identifiers ('Resource Injection')"],
+  [100, "Technology-Specific Input Validation Problems"],
+  [
+    113,
+    "Improper Neutralization of CRLF Sequences in HTTP Headers ('HTTP Request/Response Splitting')",
+  ],
+  [116, "Improper Encoding or Escaping of Output"],
+  [
+    119,
+    "Improper Restriction of Operations within the Bounds of a Memory Buffer",
+  ],
+  [
+    120,
+    "Buffer Copy without Checking Size of Input ('Classic Buffer Overflow')",
+  ],
+  [121, "Stack-based Buffer Overflow"],
+  [122, "Heap-based Buffer Overflow"],
+  [125, "Out-of-bounds Read"],
+  [126, "Buffer Over-read"],
+  [127, "Buffer Under-read"],
+  [128, "Wrap-around Error"],
+  [129, "Improper Validation of Array Index"],
+  [130, "Improper Handling of Length Parameter Inconsistency"],
+  [131, "Incorrect Calculation of Buffer Size"],
+  [134, "Use of Externally-Controlled Format String"],
+  [135, "Incorrect Calculation of Multi-Byte String Length"],
+  [170, "Improper Null Termination"],
+  [176, "Improper Handling of Unicode Encoding"],
+  [178, "Improper Handling of Case Sensitivity"],
+  [183, "Permissive List of Allowed Inputs"],
+  [184, "Incomplete List of Disallowed Inputs"],
+  [185, "Incorrect Regular Expression"],
+  [190, "Integer Overflow or Wraparound"],
+  [191, "Integer Underflow (Wrap or Wraparound)"],
+  [193, "Off-by-one Error"],
+  [200, "Exposure of Sensitive Information to an Unauthorized Actor"],
+  [201, "Insertion of Sensitive Information Into Sent Data"],
+  [204, "Observable Response Discrepancy"],
+  [209, "Generation of Error Message Containing Sensitive Information"],
+  [210, "Self-generated Error Message Containing Sensitive Information"],
+  [212, "Improper Removal of Sensitive Information Before Storage or Transfer"],
+  [213, "Exposure of Sensitive Information Due to Incompatible Policies"],
+  [214, "Invocation of Process Using Visible Sensitive Information"],
+  [215, "Insertion of Sensitive Information Into Debugging Code"],
+  [219, "Storage of File with Sensitive Data Under Web Root"],
+  [220, "Storage of File With Sensitive Data Under FTP Root"],
+  [223, "Omission of Security-relevant Information"],
+  [226, "Sensitive Information in Resource Not Removed Before Reuse"],
+  [235, "Improper Handling of Extra Parameters"],
+  [250, "Execution with Unnecessary Privileges"],
+  [252, "Unchecked Return Value"],
+  [256, "Plaintext Storage of a Password"],
+  [257, "Storing Passwords in a Recoverable Format"],
+  [259, "Use of Hard-coded Password"],
+  [260, "Password in Configuration File"],
+  [261, "Weak Encoding for Password"],
+  [262, "Not Using Password Aging"],
+  [263, "Password Aging with Long Expiration"],
+  [266, "Incorrect Privilege Assignment"],
+  [269, "Improper Privilege Management"],
+  [270, "Privilege Context Switching Error"],
+  [271, "Privilege Dropping / Lowering Errors"],
+  [272, "Least Privilege Violation"],
+  [273, "Improper Check for Dropped Privileges"],
+  [274, "Improper Handling of Insufficient Privileges"],
+  [276, "Incorrect Default Permissions"],
+  [277, "Insecure Inherited Permissions"],
+  [278, "Insecure Preserved Inherited Permissions"],
+  [279, "Incorrect Execution-Assigned Permissions"],
+  [280, "Improper Handling of Insufficient Permissions or Privileges"],
+  [281, "Improper Preservation of Permissions"],
+  [282, "Improper Ownership Management"],
+  [283, "Unverified Ownership"],
+  [284, "Improper Access Control"],
+  [285, "Improper Authorization"],
+  [286, "Incorrect User Management"],
+  [287, "Improper Authentication"],
+  [288, "Authentication Bypass Using an Alternate Path or Channel"],
+  [289, "Authentication Bypass by Alternate Name"],
+  [290, "Authentication Bypass by Spoofing"],
+  [291, "Reliance on IP Address for Authentication"],
+  [293, "Using Referer Field for Authentication"],
+  [294, "Authentication Bypass by Capture-replay"],
+  [295, "Improper Certificate Validation"],
+  [296, "Improper Following of a Certificate's Chain of Trust"],
+  [297, "Improper Validation of Certificate with Host Mismatch"],
+  [298, "Improper Validation of Certificate Expiration"],
+  [300, "Channel Accessible by Non-Endpoint"],
+  [306, "Missing Authentication for Critical Function"],
+  [307, "Improper Restriction of Excessive Authentication Attempts"],
+  [308, "Use of Single-factor Authentication"],
+  [309, "Use of Password System for Primary Authentication"],
+  [311, "Missing Encryption of Sensitive Data"],
+  [312, "Cleartext Storage of Sensitive Information"],
+  [313, "Cleartext Storage in a File or on Disk"],
+  [314, "Cleartext Storage in the Registry"],
+  [315, "Cleartext Storage of Sensitive Information in a Cookie"],
+  [316, "Cleartext Storage of Sensitive Information in Memory"],
+  [317, "Cleartext Storage of Sensitive Information in GUI"],
+  [319, "Cleartext Transmission of Sensitive Information"],
+  [321, "Use of Hard-coded Cryptographic Key"],
+  [322, "Key Exchange without Entity Authentication"],
+  [323, "Reusing a Nonce, Key Pair in Encryption"],
+  [324, "Use of a Key Past its Expiration Date"],
+  [325, "Missing Cryptographic Step"],
+  [326, "Inadequate Encryption Strength"],
+  [327, "Use of a Broken or Risky Cryptographic Algorithm"],
+  [328, "Use of Weak Hash"],
+  [329, "Generation of Predictable IV with CBC Mode"],
+  [330, "Use of Insufficiently Random Values"],
+  [331, "Insufficient Entropy"],
+  [332, "Insufficient Entropy in PRNG"],
+  [335, "Incorrect Usage of Seeds in Pseudo-Random Number Generator (PRNG)"],
+  [336, "Same Seed in Pseudo-Random Number Generator (PRNG)"],
+  [337, "Predictable Seed in Pseudo-Random Number Generator (PRNG)"],
+  [338, "Use of Cryptographically Weak Pseudo-Random Number Generator (PRNG)"],
+  [339, "Small Seed Space in PRNG"],
+  [340, "Generation of Predictable Numbers or Identifiers"],
+  [345, "Insufficient Verification of Data Authenticity"],
+  [346, "Origin Validation Error"],
+  [347, "Improper Verification of Cryptographic Signature"],
+  [348, "Use of Less Trusted Source"],
+  [349, "Acceptance of Extraneous Untrusted Data With Trusted Data"],
+  [350, "Reliance on Reverse DNS Resolution for a Security-Critical Action"],
+  [352, "Cross-Site Request Forgery (CSRF)"],
+  [353, "Missing Support for Integrity Check"],
+  [354, "Improper Validation of Integrity Check Value"],
+  [359, "Exposure of Private Personal Information to an Unauthorized Actor"],
+  [
+    362,
+    "Concurrent Execution using Shared Resource with Improper Synchronization ('Race Condition')",
+  ],
+  [367, "Time-of-check Time-of-use (TOCTOU) Race Condition"],
+  [369, "Divide By Zero"],
+  [377, "Insecure Temporary File"],
+  [384, "Session Fixation"],
+  [385, "Covert Timing Channel"],
+  [400, "Uncontrolled Resource Consumption"],
+  [401, "Missing Release of Memory after Effective Lifetime"],
+  [
+    402,
+    "Transmission of Private Resources into a New Sphere ('Resource Leak')",
+  ],
+  [404, "Improper Resource Shutdown or Release"],
+  [
+    406,
+    "Insufficient Control of Network Message Volume (Network Amplification)",
+  ],
+  [407, "Inefficient Algorithmic Complexity"],
+  [409, "Improper Handling of Highly Compressed Data (Data Amplification)"],
+  [415, "Double Free"],
+  [416, "Use After Free"],
+  [417, "Communication Channel Errors"],
+  [419, "Unprotected Primary Channel"],
+  [420, "Unprotected Alternate Channel"],
+  [425, "Direct Request ('Forced Browsing')"],
+  [426, "Untrusted Search Path"],
+  [427, "Uncontrolled Search Path Element"],
+  [428, "Unquoted Search Path or Element"],
+  [434, "Unrestricted Upload of File with Dangerous Type"],
+  [436, "Interpretation Conflict"],
+  [441, "Unintended Proxy or Intermediary ('Confused Deputy')"],
+  [
+    444,
+    "Inconsistent Interpretation of HTTP Requests ('HTTP Request/Response Smuggling')",
+  ],
+  [451, "User Interface (UI) Misrepresentation of Critical Information"],
+  [454, "External Initialization of Trusted Variables or Data Stores"],
+  [459, "Incomplete Cleanup"],
+  [
+    470,
+    "Use of Externally-Controlled Input to Select Classes or Code ('Unsafe Reflection')",
+  ],
+  [471, "Modification of Assumed-Immutable Data (MAID)"],
+  [472, "External Control of Assumed-Immutable Web Parameter"],
+  [476, "NULL Pointer Dereference"],
+  [477, "Use of Obsolete Function"],
+  [494, "Download of Code Without Integrity Check"],
+  [
+    497,
+    "Exposure of Sensitive System Information to an Unauthorized Control Sphere",
+  ],
+  [498, "Cloneable Class Containing Sensitive Information"],
+  [502, "Deserialization of Untrusted Data"],
+  [506, "Embedded Malicious Code"],
+  [507, "Trojan Horse"],
+  [521, "Weak Password Requirements"],
+  [522, "Insufficiently Protected Credentials"],
+  [523, "Unprotected Transport of Credentials"],
+  [524, "Use of Cache Containing Sensitive Information"],
+  [525, "Use of Web Browser Cache Containing Sensitive Information"],
+  [532, "Insertion of Sensitive Information into Log File"],
+  [
+    538,
+    "Insertion of Sensitive Information into Externally-Accessible File or Directory",
+  ],
+  [539, "Use of Persistent Cookies Containing Sensitive Information"],
+  [540, "Inclusion of Sensitive Information in Source Code"],
+  [541, "Inclusion of Sensitive Information in an Include File"],
+  [
+    543,
+    "Use of Singleton Pattern Without Synchronization in a Multithreaded Context",
+  ],
+  [548, "Exposure of Information Through Directory Listing"],
+  [552, "Files or Directories Accessible to External Parties"],
+  [564, "SQL Injection: Hibernate"],
+  [565, "Reliance on Cookies without Validation and Integrity Checking"],
+  [566, "Authorization Bypass Through User-Controlled SQL Primary Key"],
+  [601, "URL Redirection to Untrusted Site ('Open Redirect')"],
+  [602, "Client-Side Enforcement of Server-Side Security"],
+  [611, "Improper Restriction of XML External Entity Reference"],
+  [613, "Insufficient Session Expiration"],
+  [614, "Sensitive Cookie in HTTPS Session Without 'Secure' Attribute"],
+  [615, "Inclusion of Sensitive Information in Source Code Comments"],
+  [616, "Incomplete Identification of Uploaded File Variables (PHP)"],
+  [617, "Reachable Assertion"],
+  [618, "Exposed Dangerous Method or Function"],
+  [620, "Unverified Password Change"],
+  [639, "Authorization Bypass Through User-Controlled Key"],
+  [640, "Weak Password Recovery Mechanism for Forgotten Password"],
+  [641, "Improper Restriction of Names for Files and Other Resources"],
+  [642, "External Control of Critical State Data"],
+  [643, "Improper Neutralization of Data within XPath Expressions"],
+  [644, "Improper Neutralization of HTTP Headers for Scripting Syntax"],
+  [645, "Overly Restrictive Account Lockout Mechanism"],
+  [646, "Reliance on File Name or Extension of Externally-Supplied File"],
+  [650, "Trusting HTTP Permission Methods on the Server Side"],
+  [651, "Exposure of WSDL File Containing Sensitive Information"],
+  [652, "Improper Neutralization of Data within XQuery Expressions"],
+  [653, "Improper Isolation or Compartmentalization"],
+  [662, "Improper Synchronization"],
+  [668, "Exposure of Resource to Wrong Sphere"],
+  [669, "Incorrect Resource Transfer Between Spheres"],
+  [670, "Always-Incorrect Control Flow Implementation"],
+  [672, "Operation on a Resource after Expiration or Release"],
+  [674, "Uncontrolled Recursion"],
+  [676, "Use of Potentially Dangerous Function"],
+  [681, "Incorrect Conversion between Numeric Types"],
+  [682, "Incorrect Calculation"],
+  [693, "Protection Mechanism Failure"],
+  [694, "Use of Multiple Resources with Duplicate Identifier"],
+  [697, "Incorrect Comparison"],
+  [704, "Incorrect Type Conversion or Cast"],
+  [706, "Use of Incorrectly-Resolved Name or Reference"],
+  [707, "Improper Neutralization"],
+  [732, "Incorrect Permission Assignment for Critical Resource"],
+  [
+    733,
+    "Compiler Optimization Removal or Modification of Security-critical Code",
+  ],
+  [749, "Exposed Dangerous Method or Function"],
+  [754, "Improper Check for Unusual or Exceptional Conditions"],
+  [755, "Improper Handling of Exceptional Conditions"],
+  [
+    757,
+    "Selection of Less-Secure Algorithm During Negotiation ('Algorithm Downgrade')",
+  ],
+  [759, "Use of a One-Way Hash without a Salt"],
+  [760, "Use of a One-Way Hash with a Predictable Salt"],
+  [770, "Allocation of Resources Without Limits or Throttling"],
+  [771, "Missing Reference to Active Allocated Resource"],
+  [772, "Missing Release of Resource after Effective Lifetime"],
+  [
+    776,
+    "Improper Restriction of Recursive Entity References in DTDs ('XML Entity Expansion')",
+  ],
+  [778, "Insufficient Logging"],
+  [779, "Logging of Excessive Data"],
+  [780, "Use of RSA Algorithm without OAEP"],
+  [
+    784,
+    "Reliance on Cookies without Validation and Integrity Checking in a Security Decision",
+  ],
+  [787, "Out-of-bounds Write"],
+  [788, "Access of Memory Location After End of Buffer"],
+  [798, "Use of Hard-coded Credentials"],
+  [799, "Improper Control of Interaction Frequency"],
+  [804, "Guessable CAPTCHA"],
+  [805, "Buffer Access with Incorrect Length Value"],
+  [807, "Reliance on Untrusted Inputs in a Security Decision"],
+  [824, "Access of Uninitialized Pointer"],
+  [829, "Inclusion of Functionality from Untrusted Control Sphere"],
+  [834, "Excessive Iteration"],
+  [835, "Loop with Unreachable Exit Condition ('Infinite Loop')"],
+  [838, "Inappropriate Encoding for Output"],
+  [841, "Improper Enforcement of Behavioral Workflow"],
+  [843, "Access of Resource Using Incompatible Type ('Type Confusion')"],
+  [862, "Missing Authorization"],
+  [863, "Incorrect Authorization"],
+  [908, "Use of Uninitialized Resource"],
+  [909, "Missing Initialization of Resource"],
+  [912, "Hidden Functionality"],
+  [913, "Improper Control of Dynamically-Managed Code Resources"],
+  [
+    915,
+    "Improperly Controlled Modification of Dynamically-Determined Object Attributes",
+  ],
+  [916, "Use of Password Hash With Insufficient Computational Effort"],
+  [
+    917,
+    "Improper Neutralization of Special Elements used in an Expression Language Statement",
+  ],
+  [918, "Server-Side Request Forgery (SSRF)"],
+  [920, "Improper Restriction of Power Consumption"],
+  [922, "Insecure Storage of Sensitive Information"],
+  [923, "Improper Restriction of Communication Channel to Intended Endpoints"],
+  [
+    924,
+    "Improper Enforcement of Message Integrity During Transmission in a Communication Channel",
+  ],
+  [925, "Improper Verification of Intent by Broadcast Receiver"],
+  [926, "Improper Export of Android Application Components"],
+  [927, "Use of Implicit Intent for Sensitive Communication"],
+  [939, "Improper Authorization in Handler for Custom URL Scheme"],
+  [940, "Improper Verification of Source of a Communication Channel"],
+  [941, "Incorrectly Specified Destination in a Communication Channel"],
+  [942, "Permissive Cross-domain Policy with Untrusted Domains"],
+  [943, "Improper Neutralization of Special Elements in Data Query Logic"],
+  [1004, "Sensitive Cookie Without 'HttpOnly' Flag"],
+  [1007, "Insufficient Visual Distinction of Homoglyphs"],
+  [1021, "Improper Restriction of Rendered UI Layers or Frames"],
+  [1022, "Use of Web Link to Untrusted Target with window.opener Access"],
+  [1035, "Single Sign-On Without Re-Authentication for Sensitive Operations"],
+  [1104, "Use of Unmaintained Third Party Components"],
+  [1236, "Improper Neutralization of Formula Elements in a CSV File"],
+  [1275, "Sensitive Cookie with Improper SameSite Attribute"],
+  [
+    1321,
+    "Improperly Controlled Modification of Object Prototype Attributes ('Prototype Pollution')",
+  ],
+  [1327, "Binding to an Unrestricted IP Address"],
+  [1333, "Inefficient Regular Expression Complexity"],
+  [
+    1336,
+    "Improper Neutralization of Special Elements Used in a Template Engine",
+  ],
+]);
+
+/**
+ * Look up the canonical MITRE name for a CWE ID.
+ * @param id Numeric CWE ID (e.g., 89 for CWE-89)
+ * @returns The canonical name, or undefined if not in the catalog
+ */
+function lookupCweName(id: number): string | undefined {
+  return CWE_CATALOG.get(id);
+}
+
+/**
+ * Check whether a CWE ID exists in the catalog.
+ * @param id Numeric CWE ID
+ */
+function isKnownCweId(id: number): boolean {
+  return CWE_CATALOG.has(id);
+}

package/src/lib/cwe/types.test.ts

@@ -0,0 +1,142 @@
+import { describe, expect, it } from "vitest";
+import type { CweEntry, ValidatedCweEntry } from "./types";
+import {
+  CweEntrySchema,
+  hasCanonicalName,
+  ValidatedCweEntrySchema,
+} from "./types";
+
+describe("CweEntrySchema", () => {
+  it("accepts valid CWE entry", () => {
+    const result = CweEntrySchema.safeParse({
+      id: "CWE-89",
+      reasoning: "SQL injection via unsanitized user input",
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("accepts CWE with large number", () => {
+    const result = CweEntrySchema.safeParse({
+      id: "CWE-1336",
+      reasoning: "Server-side template injection",
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects lowercase cwe prefix", () => {
+    const result = CweEntrySchema.safeParse({
+      id: "cwe-89",
+      reasoning: "SQL injection",
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects missing hyphen", () => {
+    const result = CweEntrySchema.safeParse({
+      id: "CWE89",
+      reasoning: "SQL injection",
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects space instead of hyphen", () => {
+    const result = CweEntrySchema.safeParse({
+      id: "CWE 89",
+      reasoning: "SQL injection",
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects bare number without prefix", () => {
+    const result = CweEntrySchema.safeParse({
+      id: "89",
+      reasoning: "SQL injection",
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects descriptive name instead of ID", () => {
+    const result = CweEntrySchema.safeParse({
+      id: "SQL Injection",
+      reasoning: "SQL injection",
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects CWE- without number", () => {
+    const result = CweEntrySchema.safeParse({
+      id: "CWE-",
+      reasoning: "Missing number",
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects CWE- with non-numeric suffix", () => {
+    const result = CweEntrySchema.safeParse({
+      id: "CWE-abc",
+      reasoning: "Invalid",
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects missing reasoning", () => {
+    const result = CweEntrySchema.safeParse({
+      id: "CWE-89",
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects missing id", () => {
+    const result = CweEntrySchema.safeParse({
+      reasoning: "SQL injection",
+    });
+    expect(result.success).toBe(false);
+  });
+});
+
+describe("ValidatedCweEntrySchema", () => {
+  it("accepts a validated entry with name", () => {
+    const result = ValidatedCweEntrySchema.safeParse({
+      id: "CWE-89",
+      name: "Improper Neutralization of Special Elements used in an SQL Command ('SQL Injection')",
+      reasoning: "SQL injection via unsanitized user input",
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects entry without name", () => {
+    const result = ValidatedCweEntrySchema.safeParse({
+      id: "CWE-89",
+      reasoning: "SQL injection",
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects entry with non-string name", () => {
+    const result = ValidatedCweEntrySchema.safeParse({
+      id: "CWE-89",
+      name: 123,
+      reasoning: "SQL injection",
+    });
+    expect(result.success).toBe(false);
+  });
+});
+
+describe("hasCanonicalName", () => {
+  it("returns true for ValidatedCweEntry", () => {
+    const entry: ValidatedCweEntry = {
+      id: "CWE-89",
+      name: "SQL Injection",
+      reasoning: "test",
+    };
+    expect(hasCanonicalName(entry)).toBe(true);
+  });
+
+  it("returns false for plain CweEntry", () => {
+    const entry: CweEntry = {
+      id: "CWE-89",
+      reasoning: "test",
+    };
+    expect(hasCanonicalName(entry)).toBe(false);
+  });
+});

package/src/lib/cwe/types.ts

@@ -0,0 +1,37 @@
+import { z } from "zod";
+
+/**
+ * Schema for a single CWE classification entry.
+ *
+ * Each entry pairs a CWE identifier (e.g., "CWE-89") with a reasoning
+ * string explaining why that CWE applies to the observed vulnerability.
+ */
+export const CweEntrySchema = z.object({
+  id: z.string().regex(/^CWE-\d+$/, "Must be CWE-<number> format"),
+  reasoning: z
+    .string()
+    .describe("Why this CWE applies to the observed vulnerability"),
+});
+
+export type CweEntry = z.infer<typeof CweEntrySchema>;
+
+/**
+ * A CWE entry that has been validated against the CWE database
+ * and enriched with the canonical MITRE name.
+ */
+export const ValidatedCweEntrySchema = CweEntrySchema.extend({
+  name: z.string().describe("Canonical CWE name from the MITRE database"),
+});
+
+export type ValidatedCweEntry = z.infer<typeof ValidatedCweEntrySchema>;
+
+/**
+ * Type guard: does this CWE entry have a canonical name?
+ * Use in renderers to safely access the `name` field on entries
+ * that may be either CweEntry or ValidatedCweEntry.
+ */
+export function hasCanonicalName(
+  cwe: CweEntry | ValidatedCweEntry,
+): cwe is ValidatedCweEntry {
+  return "name" in cwe && typeof (cwe as ValidatedCweEntry).name === "string";
+}