scripts/build_cwe_references.py
GitHub#!/usr/bin/env python3
"""Build searchable CWE review references from a CWE catalog XML and schema XSD."""
from __future__ import annotations
import argparse
import json
import re
import xml.etree.ElementTree as ET
from collections import Counter, defaultdict
from pathlib import Path
from typing import Any, Iterable
CWE_NS = "http://cwe.mitre.org/cwe-7"
XSD_NS = "http://www.w3.org/2001/XMLSchema"
NS = {"cwe": CWE_NS, "xs": XSD_NS}
REVIEW_VIEW_NOTES = {
"699": "Primary software-development browsing view. Use it to scope common review surfaces by development concept.",
"1000": "Research graph. Use it to move between broad parents and precise child weaknesses while tracing root cause.",
"1003": "Simplified vulnerability-mapping graph. Use it when a finding needs a practical mapping candidate before refining it.",
"1435": "2025 CWE Top 25 view from this catalog release. Use it as prioritization context, never as proof of severity.",
"1344": "OWASP Top Ten 2021 view. Use it when a review or report must align findings with the OWASP 2021 grouping.",
"1450": "OWASP Top Ten 2025 RC1 view. Use it only when the RC1 taxonomy is specifically relevant.",
"1448": "AI/ML product view. Use it when model inputs, training, inference, or agentic behavior are in scope.",
"658": "Implicit C-language view.",
"659": "Implicit C++-language view.",
"660": "Implicit Java-language view.",
"661": "Implicit PHP-language view.",
"701": "Implicit design-introduction view.",
"702": "Implicit implementation-introduction view.",
"919": "Implicit mobile-application view.",
}
CORE_COMPLEX_TYPES = [
"WeaknessType",
"MappingNotesType",
"RelatedWeaknessesType",
"RelationshipsType",
"ModesOfIntroductionType",
"ApplicablePlatformsType",
"FunctionalAreasType",
"CommonConsequencesType",
"DetectionMethodsType",
"PotentialMitigationsType",
"ObservedExampleType",
]
def normalize_space(value: str | None) -> str:
return re.sub(r"\s+", " ", value or "").strip()
def text_of(node: ET.Element | None) -> str:
if node is None:
return ""
return normalize_space(" ".join(node.itertext()))
def doc_of(node: ET.Element | None) -> str:
if node is None:
return ""
docs = [text_of(item) for item in node.findall("xs:annotation/xs:documentation", NS)]
return normalize_space(" ".join(item for item in docs if item))
def short_text(value: str, limit: int = 180) -> str:
value = normalize_space(value)
if len(value) <= limit:
return value
return value[: limit - 3].rstrip() + "..."
def md_escape(value: str) -> str:
return value.replace("|", "\\|").replace("\n", " ")
def snake_key(value: str) -> str:
value = re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", value)
return value.replace("-", "_").lower()
def normalized_attrs(node: ET.Element) -> dict[str, str]:
return {snake_key(key): value for key, value in node.attrib.items()}
def first_text(node: ET.Element, path: str) -> str:
return text_of(node.find(path, NS))
def all_text(node: ET.Element, path: str) -> list[str]:
return [text_of(item) for item in node.findall(path, NS) if text_of(item)]
def parse_external_references(root: ET.Element) -> dict[str, dict[str, Any]]:
references: dict[str, dict[str, Any]] = {}
for ref in root.findall("cwe:External_References/cwe:External_Reference", NS):
ref_id = ref.attrib["Reference_ID"]
references[ref_id] = {
"reference_id": ref_id,
"authors": all_text(ref, "cwe:Author"),
"title": first_text(ref, "cwe:Title"),
"edition": first_text(ref, "cwe:Edition"),
"publication": first_text(ref, "cwe:Publication"),
"publication_year": first_text(ref, "cwe:Publication_Year"),
"publisher": first_text(ref, "cwe:Publisher"),
"url": first_text(ref, "cwe:URL"),
"url_date": first_text(ref, "cwe:URL_Date"),
}
return references
def parse_mapping_notes(node: ET.Element) -> dict[str, Any]:
mapping = node.find("cwe:Mapping_Notes", NS)
if mapping is None:
return {}
return {
"usage": first_text(mapping, "cwe:Usage"),
"rationale": first_text(mapping, "cwe:Rationale"),
"comments": first_text(mapping, "cwe:Comments"),
"reasons": [
item.attrib.get("Type", "")
for item in mapping.findall("cwe:Reasons/cwe:Reason", NS)
if item.attrib.get("Type")
],
"suggestions": [
{
"cwe_id": item.attrib.get("CWE_ID", ""),
"comment": item.attrib.get("Comment", ""),
}
for item in mapping.findall("cwe:Suggestions/cwe:Suggestion", NS)
],
}
def parse_platforms(node: ET.Element) -> list[dict[str, str]]:
platforms: list[dict[str, str]] = []
parent = node.find("cwe:Applicable_Platforms", NS)
if parent is None:
return platforms
for child in list(parent):
item = {"kind": child.tag.rsplit("}", 1)[-1]}
item.update(normalized_attrs(child))
platforms.append(item)
return platforms
def parse_relationships(node: ET.Element) -> list[dict[str, str]]:
return [
normalized_attrs(item)
for item in node.findall("cwe:Related_Weaknesses/cwe:Related_Weakness", NS)
]
def parse_consequences(node: ET.Element) -> list[dict[str, Any]]:
consequences: list[dict[str, Any]] = []
for item in node.findall("cwe:Common_Consequences/cwe:Consequence", NS):
consequences.append(
{
"consequence_id": item.attrib.get("Consequence_ID", ""),
"scopes": all_text(item, "cwe:Scope"),
"impacts": all_text(item, "cwe:Impact"),
"likelihood": first_text(item, "cwe:Likelihood"),
"note": first_text(item, "cwe:Note"),
}
)
return consequences
def parse_detection_methods(node: ET.Element) -> list[dict[str, str]]:
methods: list[dict[str, str]] = []
for item in node.findall("cwe:Detection_Methods/cwe:Detection_Method", NS):
methods.append(
{
"detection_method_id": item.attrib.get("Detection_Method_ID", ""),
"method": first_text(item, "cwe:Method"),
"description": first_text(item, "cwe:Description"),
"effectiveness": first_text(item, "cwe:Effectiveness"),
"effectiveness_notes": first_text(item, "cwe:Effectiveness_Notes"),
}
)
return methods
def parse_mitigations(node: ET.Element) -> list[dict[str, Any]]:
mitigations: list[dict[str, Any]] = []
for item in node.findall("cwe:Potential_Mitigations/cwe:Mitigation", NS):
mitigations.append(
{
"mitigation_id": item.attrib.get("Mitigation_ID", ""),
"phases": all_text(item, "cwe:Phase"),
"strategy": first_text(item, "cwe:Strategy"),
"description": first_text(item, "cwe:Description"),
"effectiveness": first_text(item, "cwe:Effectiveness"),
"effectiveness_notes": first_text(item, "cwe:Effectiveness_Notes"),
}
)
return mitigations
def parse_taxonomy_mappings(node: ET.Element) -> list[dict[str, str]]:
mappings: list[dict[str, str]] = []
for item in node.findall("cwe:Taxonomy_Mappings/cwe:Taxonomy_Mapping", NS):
mappings.append(
{
"taxonomy_name": item.attrib.get("Taxonomy_Name", ""),
"entry_id": first_text(item, "cwe:Entry_ID"),
"entry_name": first_text(item, "cwe:Entry_Name"),
"mapping_fit": first_text(item, "cwe:Mapping_Fit"),
}
)
return mappings
def parse_weakness(
node: ET.Element,
external_references: dict[str, dict[str, Any]],
) -> dict[str, Any]:
record: dict[str, Any] = {
"id": node.attrib["ID"],
"name": node.attrib["Name"],
"abstraction": node.attrib.get("Abstraction", ""),
"structure": node.attrib.get("Structure", ""),
"status": node.attrib.get("Status", ""),
"diagram": node.attrib.get("Diagram", ""),
"description": first_text(node, "cwe:Description"),
"extended_description": first_text(node, "cwe:Extended_Description"),
"relationships": parse_relationships(node),
"weakness_ordinalities": [
{
"ordinality": first_text(item, "cwe:Ordinality"),
"description": first_text(item, "cwe:Description"),
}
for item in node.findall("cwe:Weakness_Ordinalities/cwe:Weakness_Ordinality", NS)
],
"platforms": parse_platforms(node),
"background_details": all_text(node, "cwe:Background_Details/cwe:Background_Detail"),
"alternate_terms": [
{
"term": first_text(item, "cwe:Term"),
"description": first_text(item, "cwe:Description"),
}
for item in node.findall("cwe:Alternate_Terms/cwe:Alternate_Term", NS)
],
"modes_of_introduction": [
{
"phase": first_text(item, "cwe:Phase"),
"note": first_text(item, "cwe:Note"),
}
for item in node.findall("cwe:Modes_Of_Introduction/cwe:Introduction", NS)
],
"exploitation_factors": all_text(node, "cwe:Exploitation_Factors/cwe:Exploitation_Factor"),
"likelihood_of_exploit": first_text(node, "cwe:Likelihood_Of_Exploit"),
"consequences": parse_consequences(node),
"detection_methods": parse_detection_methods(node),
"mitigations": parse_mitigations(node),
"functional_areas": all_text(node, "cwe:Functional_Areas/cwe:Functional_Area"),
"affected_resources": all_text(node, "cwe:Affected_Resources/cwe:Affected_Resource"),
"taxonomy_mappings": parse_taxonomy_mappings(node),
"related_attack_patterns": [
item.attrib.get("CAPEC_ID", "")
for item in node.findall("cwe:Related_Attack_Patterns/cwe:Related_Attack_Pattern", NS)
if item.attrib.get("CAPEC_ID")
],
"observed_examples": [
{
"reference": first_text(item, "cwe:Reference"),
"description": first_text(item, "cwe:Description"),
"link": first_text(item, "cwe:Link"),
}
for item in node.findall("cwe:Observed_Examples/cwe:Observed_Example", NS)
],
"mapping": parse_mapping_notes(node),
"notes": [
{
"type": item.attrib.get("Type", ""),
"text": text_of(item),
}
for item in node.findall("cwe:Notes/cwe:Note", NS)
],
}
ref_ids = list(
dict.fromkeys(
item.attrib.get("External_Reference_ID", "")
for item in node.findall("cwe:References/cwe:Reference", NS)
if item.attrib.get("External_Reference_ID")
)
)
record["references"] = [
external_references[ref_id] for ref_id in ref_ids if ref_id in external_references
]
return record
def parse_categories(root: ET.Element) -> dict[str, dict[str, Any]]:
categories: dict[str, dict[str, Any]] = {}
for node in root.findall("cwe:Categories/cwe:Category", NS):
categories[node.attrib["ID"]] = {
"id": node.attrib["ID"],
"name": node.attrib["Name"],
"status": node.attrib.get("Status", ""),
"summary": first_text(node, "cwe:Summary"),
"relationships": [
{
"kind": item.tag.rsplit("}", 1)[-1],
**normalized_attrs(item),
}
for item in node.findall("cwe:Relationships/*", NS)
],
"mapping": parse_mapping_notes(node),
}
return categories
def parse_views(root: ET.Element) -> dict[str, dict[str, Any]]:
views: dict[str, dict[str, Any]] = {}
for node in root.findall("cwe:Views/cwe:View", NS):
views[node.attrib["ID"]] = {
"id": node.attrib["ID"],
"name": node.attrib["Name"],
"type": node.attrib.get("Type", ""),
"status": node.attrib.get("Status", ""),
"objective": first_text(node, "cwe:Objective"),
"filter": first_text(node, "cwe:Filter"),
"members": [
{
"kind": item.tag.rsplit("}", 1)[-1],
**normalized_attrs(item),
}
for item in node.findall("cwe:Members/*", NS)
],
"mapping": parse_mapping_notes(node),
}
return views
def implicit_view_members(view_id: str, records: dict[str, dict[str, Any]]) -> set[str]:
members: set[str] = set()
for record in records.values():
if view_id == "1040" and any(
item["ordinality"] == "Indirect" for item in record["weakness_ordinalities"]
):
members.add(record["id"])
elif view_id == "1081" and any(item["type"] == "Maintenance" for item in record["notes"]):
members.add(record["id"])
elif view_id == "1424" and any(
item["taxonomy_name"] == "ISA/IEC 62443" for item in record["taxonomy_mappings"]
):
members.add(record["id"])
elif view_id == "2000":
members.add(record["id"])
elif view_id == "604" and record["status"] == "Deprecated":
members.add(record["id"])
elif view_id in {"658", "659", "660", "661"}:
language = {"658": "C", "659": "C++", "660": "Java", "661": "PHP"}[view_id]
if any(item.get("kind") == "Language" and item.get("name") == language for item in record["platforms"]):
members.add(record["id"])
elif view_id == "677" and record["abstraction"] == "Base" and record["status"] != "Deprecated":
members.add(record["id"])
elif view_id == "678" and record["structure"] == "Composite" and record["status"] != "Deprecated":
members.add(record["id"])
elif view_id in {"679", "999"}:
continue
elif view_id == "701" and record["abstraction"] in {"Base", "Class"} and any(
item["phase"] == "Architecture and Design" for item in record["modes_of_introduction"]
):
members.add(record["id"])
elif view_id == "702" and any(
item["phase"] == "Implementation" for item in record["modes_of_introduction"]
):
members.add(record["id"])
elif view_id == "709" and record["structure"] == "Chain":
members.add(record["id"])
elif view_id == "919" and any(
item.get("kind") == "Technology" and item.get("class") == "Mobile"
for item in record["platforms"]
):
members.add(record["id"])
return members
def attach_relationship_names(records: dict[str, dict[str, Any]]) -> None:
for record in records.values():
for relationship in record["relationships"]:
target = records.get(relationship.get("cwe_id", ""))
if target:
relationship["target_name"] = target["name"]
def attach_view_memberships(
records: dict[str, dict[str, Any]],
categories: dict[str, dict[str, Any]],
views: dict[str, dict[str, Any]],
) -> None:
view_members: dict[str, set[str]] = defaultdict(set)
for view_id, view in views.items():
if view["type"] == "Implicit":
view_members[view_id].update(implicit_view_members(view_id, records))
for member in view["members"]:
cwe_id = member.get("cwe_id", "")
if cwe_id in records:
view_members[view_id].add(cwe_id)
for category in categories.values():
for relationship in category["relationships"]:
view_id = relationship.get("view_id", "")
cwe_id = relationship.get("cwe_id", "")
if relationship.get("kind") == "Has_Member" and cwe_id in records:
view_members[view_id].add(cwe_id)
for record in records.values():
for relationship in record["relationships"]:
view_id = relationship.get("view_id", "")
view_members[view_id].add(record["id"])
cwe_id = relationship.get("cwe_id", "")
if cwe_id in records:
view_members[view_id].add(cwe_id)
for view_id, view in views.items():
view["weakness_member_ids"] = sorted(view_members[view_id], key=int)
for record in records.values():
record["view_ids"] = sorted(
[view_id for view_id, members in view_members.items() if record["id"] in members],
key=int,
)
def parse_schema(schema_root: ET.Element) -> dict[str, Any]:
appinfo = schema_root.find("xs:annotation/xs:appinfo", NS)
metadata = {
"version": schema_root.attrib.get("version", ""),
"schema": first_text(appinfo, "schema") if appinfo is not None else "",
"date": first_text(appinfo, "date") if appinfo is not None else "",
"documentation": doc_of(schema_root),
}
simple_types: dict[str, dict[str, Any]] = {}
for node in schema_root.findall("xs:simpleType", NS):
values = []
for enum in node.findall(".//xs:enumeration", NS):
values.append(
{
"value": enum.attrib.get("value", ""),
"documentation": doc_of(enum),
}
)
if values:
simple_types[node.attrib.get("name", "")] = {
"documentation": doc_of(node),
"values": values,
}
complex_types: dict[str, dict[str, Any]] = {}
for name in CORE_COMPLEX_TYPES:
node = schema_root.find(f"xs:complexType[@name='{name}']", NS)
if node is None:
continue
elements = []
for child in node.findall("xs:sequence/xs:element", NS):
elements.append(
{
"name": child.attrib.get("name", ""),
"type": child.attrib.get("type", ""),
"min_occurs": child.attrib.get("minOccurs", "1"),
"max_occurs": child.attrib.get("maxOccurs", "1"),
}
)
attributes = []
for attribute in node.findall("xs:attribute", NS):
attributes.append(
{
"name": attribute.attrib.get("name", ""),
"type": attribute.attrib.get("type", ""),
"use": attribute.attrib.get("use", "optional"),
}
)
complex_types[name] = {
"documentation": doc_of(node),
"elements": elements,
"attributes": attributes,
}
return {
"metadata": metadata,
"simple_types": simple_types,
"complex_types": complex_types,
}
def entity_label(
cwe_id: str,
records: dict[str, dict[str, Any]],
categories: dict[str, dict[str, Any]],
views: dict[str, dict[str, Any]],
) -> str:
if cwe_id in records:
return f"CWE-{cwe_id} {records[cwe_id]['name']} [Weakness]"
if cwe_id in categories:
return f"CWE-{cwe_id} {categories[cwe_id]['name']} [Category]"
if cwe_id in views:
return f"CWE-{cwe_id} {views[cwe_id]['name']} [View]"
return f"CWE-{cwe_id}"
def write_jsonl(path: Path, records: dict[str, dict[str, Any]]) -> None:
with path.open("w", encoding="utf-8") as handle:
for record in sorted(records.values(), key=lambda item: int(item["id"])):
handle.write(json.dumps(record, sort_keys=True, ensure_ascii=True) + "\n")
def write_metadata_json(
path: Path,
root: ET.Element,
schema: dict[str, Any],
categories: dict[str, dict[str, Any]],
views: dict[str, dict[str, Any]],
) -> None:
payload = {
"catalog": {
"name": root.attrib.get("Name", ""),
"version": root.attrib.get("Version", ""),
"date": root.attrib.get("Date", ""),
"namespace": CWE_NS,
"schema_location": root.attrib.get(
"{http://www.w3.org/2001/XMLSchema-instance}schemaLocation", ""
),
},
"schema": schema["metadata"],
"categories": categories,
"views": views,
}
path.write_text(json.dumps(payload, indent=2, sort_keys=True, ensure_ascii=True) + "\n", encoding="utf-8")
def write_catalog_summary(
path: Path,
root: ET.Element,
schema: dict[str, Any],
records: dict[str, dict[str, Any]],
categories: dict[str, dict[str, Any]],
views: dict[str, dict[str, Any]],
) -> None:
abstraction_counts = Counter(record["abstraction"] for record in records.values())
status_counts = Counter(record["status"] for record in records.values())
usage_counts = Counter(record["mapping"].get("usage", "") for record in records.values())
structure_counts = Counter(record["structure"] for record in records.values())
mapping_usage_summary = ", ".join(
f"{key or 'Unknown'}: {value}" for key, value in sorted(usage_counts.items())
)
lines = [
"# CWE Catalog Summary",
"",
"Generated by `scripts/build_cwe_references.py` from the local CWE catalog and XSD supplied to the skill.",
"",
"## Source",
"",
f"- Catalog: {root.attrib.get('Name', '')} {root.attrib.get('Version', '')} dated {root.attrib.get('Date', '')}",
f"- Catalog namespace: `{CWE_NS}`",
f"- Schema: {schema['metadata'].get('schema', '')} {schema['metadata'].get('version', '')} dated {schema['metadata'].get('date', '')}",
f"- Counts: {len(records)} weaknesses, {len(categories)} categories, {len(views)} views",
"",
"## How To Use This Corpus",
"",
"- Start with code evidence and a trust-boundary failure, then use the corpus to refine the root-cause weakness.",
"- Prefer weaknesses with mapping usage `Allowed` or `Allowed-with-Review`; treat `Discouraged` and `Prohibited` entries as navigation aids unless the mapping notes justify an exception.",
"- Prefer the most precise supported weakness over a broad Pillar, Class, Category, or View. Categories and Views organize the corpus and are not root-cause mappings.",
"- Use view membership as coverage or prioritization context, not as a severity rating.",
"- Use `scripts/cwe_lookup.py` for detail retrieval. Use `references/cwe-weakness-index.md` for fast grep-based browsing.",
"",
"## Catalog Shape",
"",
"| Dimension | Values |",
"| --- | --- |",
f"| Abstraction | {', '.join(f'{key}: {value}' for key, value in sorted(abstraction_counts.items()))} |",
f"| Structure | {', '.join(f'{key}: {value}' for key, value in sorted(structure_counts.items()))} |",
f"| Status | {', '.join(f'{key}: {value}' for key, value in sorted(status_counts.items()))} |",
f"| Mapping usage | {mapping_usage_summary} |",
"",
"## Review-Oriented Views",
"",
"| View | Type | Status | Weakness Members | Use |",
"| --- | --- | --- | ---: | --- |",
]
for view_id in REVIEW_VIEW_NOTES:
view = views.get(view_id)
if not view:
continue
lines.append(
f"| CWE-{view_id} {md_escape(view['name'])} | {view['type']} | {view['status']} | "
f"{len(view.get('weakness_member_ids', []))} | {md_escape(REVIEW_VIEW_NOTES[view_id])} |"
)
lines.extend(
[
"",
"## Generated Files",
"",
"- `cwe-weakness-index.md`: compact, line-oriented index of every weakness for grep and quick scanning.",
"- `cwe-review-views.md`: review-oriented view descriptions, filters, and member lists.",
"- `cwe-schema-guide.md`: XSD-derived field semantics and enumeration vocabulary.",
"- `cwe-records.jsonl`: machine-readable record per weakness with mapping notes, relationships, detection methods, mitigations, and examples.",
"- `cwe-catalog-metadata.json`: machine-readable catalog, schema, category, and view metadata.",
"",
]
)
path.write_text("\n".join(lines), encoding="utf-8")
def write_weakness_index(path: Path, records: dict[str, dict[str, Any]]) -> None:
lines = [
"# CWE Weakness Index",
"",
"Generated from the local CWE catalog. Search this file first, then use `scripts/cwe_lookup.py --id <id>` for complete detail.",
"",
"| CWE | Name | Abstraction | Status | Mapping | Phases | Functional Areas | Parent IDs | View IDs |",
"| --- | --- | --- | --- | --- | --- | --- | --- | --- |",
]
for record in sorted(records.values(), key=lambda item: int(item["id"])):
parents = [
f"CWE-{item['cwe_id']}"
for item in record["relationships"]
if item.get("nature") == "ChildOf" and item.get("cwe_id")
]
phases = sorted({item["phase"] for item in record["modes_of_introduction"] if item["phase"]})
lines.append(
"| "
+ " | ".join(
[
f"CWE-{record['id']}",
md_escape(record["name"]),
record["abstraction"],
record["status"],
record["mapping"].get("usage", ""),
md_escape(", ".join(phases)),
md_escape(", ".join(record["functional_areas"])),
md_escape(", ".join(parents)),
md_escape(", ".join(f"CWE-{item}" for item in record["view_ids"])),
]
)
+ " |"
)
path.write_text("\n".join(lines) + "\n", encoding="utf-8")
def write_review_views(
path: Path,
records: dict[str, dict[str, Any]],
categories: dict[str, dict[str, Any]],
views: dict[str, dict[str, Any]],
) -> None:
lines = [
"# CWE Review Views",
"",
"Use these views to scope coverage and navigate the catalog. A view is not itself a finding or a root-cause mapping.",
"",
"## Contents",
"",
]
for view_id in REVIEW_VIEW_NOTES:
if view_id in views:
lines.append(f"- [CWE-{view_id} {views[view_id]['name']}](#cwe-{view_id})")
for view_id, note in REVIEW_VIEW_NOTES.items():
view = views.get(view_id)
if not view:
continue
lines.extend(
[
"",
f"## CWE-{view_id}",
"",
f"**{view['name']}**",
"",
f"- Type: {view['type']}",
f"- Status: {view['status']}",
f"- Weakness members: {len(view.get('weakness_member_ids', []))}",
f"- Review use: {note}",
"",
short_text(view["objective"], 600),
]
)
if view["filter"]:
lines.extend(["", f"Filter: `{view['filter']}`"])
if view["members"]:
label = "Ordered direct members:" if view_id == "1435" else "Direct members:"
lines.extend(["", label, ""])
for index, member in enumerate(view["members"], start=1):
prefix = f"{index}." if view_id == "1435" else "-"
lines.append(
f"{prefix} {entity_label(member.get('cwe_id', ''), records, categories, views)}"
)
weakness_member_ids = view.get("weakness_member_ids", [])
show_all = view_id in {"1003", "1448"}
if show_all:
lines.extend(["", "Weakness members:", ""])
for cwe_id in weakness_member_ids:
record = records[cwe_id]
lines.append(
f"- CWE-{cwe_id} {record['name']} "
f"({record['abstraction']}; mapping {record['mapping'].get('usage', '')})"
)
elif weakness_member_ids:
sample = weakness_member_ids[:20]
lines.extend(
[
"",
f"Sample weakness members ({len(sample)} of {len(weakness_member_ids)}):",
"",
]
)
for cwe_id in sample:
record = records[cwe_id]
lines.append(f"- CWE-{cwe_id} {record['name']}")
path.write_text("\n".join(lines) + "\n", encoding="utf-8")
def write_schema_guide(path: Path, schema: dict[str, Any]) -> None:
lines = [
"# CWE Schema Guide",
"",
"Generated from the local CWE XSD. Use this file when interpreting field meaning, relationship semantics, or allowed vocabulary.",
"",
"## Contents",
"",
"- [Schema Metadata](#schema-metadata)",
"- [Core Complex Types](#core-complex-types)",
"- [Enumerations](#enumerations)",
"",
"## Schema Metadata",
"",
f"- Name: {schema['metadata'].get('schema', '')}",
f"- Version: {schema['metadata'].get('version', '')}",
f"- Date: {schema['metadata'].get('date', '')}",
"",
"## Core Complex Types",
"",
]
for name in CORE_COMPLEX_TYPES:
item = schema["complex_types"].get(name)
if not item:
continue
lines.extend([f"### {name}", "", short_text(item["documentation"], 900), ""])
if item["elements"]:
lines.extend(
[
"| Element | Type | Cardinality |",
"| --- | --- | --- |",
]
)
for element in item["elements"]:
lines.append(
f"| {element['name']} | {element['type'] or 'inline type'} | "
f"{element['min_occurs']}..{element['max_occurs']} |"
)
lines.append("")
if item["attributes"]:
lines.extend(
[
"| Attribute | Type | Use |",
"| --- | --- | --- |",
]
)
for attribute in item["attributes"]:
lines.append(
f"| {attribute['name']} | {attribute['type'] or 'inline type'} | {attribute['use']} |"
)
lines.append("")
lines.extend(["## Enumerations", ""])
for name, item in sorted(schema["simple_types"].items()):
lines.extend([f"### {name}", "", short_text(item["documentation"], 500), ""])
lines.extend(["| Value | Notes |", "| --- | --- |"])
for value in item["values"]:
lines.append(
f"| {md_escape(value['value'])} | {md_escape(short_text(value['documentation'], 240))} |"
)
lines.append("")
path.write_text("\n".join(lines), encoding="utf-8")
def build(catalog_path: Path, schema_path: Path, output_dir: Path) -> None:
catalog_root = ET.parse(catalog_path).getroot()
schema_root = ET.parse(schema_path).getroot()
external_references = parse_external_references(catalog_root)
records = {
node.attrib["ID"]: parse_weakness(node, external_references)
for node in catalog_root.findall("cwe:Weaknesses/cwe:Weakness", NS)
}
categories = parse_categories(catalog_root)
views = parse_views(catalog_root)
schema = parse_schema(schema_root)
attach_relationship_names(records)
attach_view_memberships(records, categories, views)
output_dir.mkdir(parents=True, exist_ok=True)
write_jsonl(output_dir / "cwe-records.jsonl", records)
write_metadata_json(output_dir / "cwe-catalog-metadata.json", catalog_root, schema, categories, views)
write_catalog_summary(output_dir / "cwe-catalog-summary.md", catalog_root, schema, records, categories, views)
write_weakness_index(output_dir / "cwe-weakness-index.md", records)
write_review_views(output_dir / "cwe-review-views.md", records, categories, views)
write_schema_guide(output_dir / "cwe-schema-guide.md", schema)
def main() -> None:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--catalog", required=True, type=Path, help="Path to CWE catalog XML.")
parser.add_argument("--schema", required=True, type=Path, help="Path to CWE schema XSD.")
parser.add_argument(
"--output-dir",
type=Path,
default=Path(__file__).resolve().parent.parent / "references",
help="Directory for generated references.",
)
args = parser.parse_args()
build(args.catalog, args.schema, args.output_dir)
print(f"Generated CWE references in {args.output_dir}")
if __name__ == "__main__":
main()