cwe-tree 1.0.0__tar.gz

cwe_tree-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Yichao Xu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cwe_tree-1.0.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+include LICENSE
+recursive-include data *.csv

cwe_tree-1.0.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.2
+Name: cwe_tree
+Version: 1.0.0
+Summary: A Python package for querying CWE trees
+Home-page: https://github.com/YichaoXu/cwe-tree
+Author: Yichao Xu
+Author-email: yxu166@jhu.edu
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: requires-python
+Dynamic: summary
+
+# CWE Tree Python Package
+
+## Overview
+
+This package provides a structured representation of the [Common Weakness Enumeration (CWE)](https://cwe.mitre.org/) hierarchy using a tree-based data model. It allows users to query CWE nodes, understand parent-child relationships, and extract metadata for each CWE entry.
+
+## Features
+- Load CWE nodes and relationships from CSV files (`nodes.csv` and `rels.csv`).
+- Represent CWE entries as `CweNode` objects.
+- Store and manage the entire CWE structure as a `CweTree`.
+- Query CWE metadata, parent-child relationships, and tree layers.
+
+## Installation
+
+Clone this repository and install dependencies if required:
+
+```sh
+pip install -e . 
+```
+
+or using pip repo
+
+```sh
+pip install cwe_tree 
+```
+
+## Usage
+
+### Import the package
+```python
+from cwe_tree import query, CweTree, CweNode
+```
+
+### Querying CWE nodes
+
+```python
+# Retrieve a CWE node by ID
+cwe_node = query.get_node("CWE-732")
+if cwe_node:
+    print(cwe_node.get_metadata())
+```
+
+### Fetching parent-child relationships
+
+```python
+# Get parent CWEs
+parents = query.get_parents("CWE-732")
+print("Parent CWE IDs:", parents)
+
+# Get child CWEs
+children = query.get_children("CWE-732")
+print("Child CWE IDs:", children)
+```
+
+### Retrieving metadata
+
+```python
+metadata = query.get_metadata("CWE-732")
+print("CWE Metadata:", metadata)
+```
+
+### Getting root nodes
+```python
+roots = query.get_roots()
+print("Root CWE nodes:", [node.cwe_id for node in roots])
+```
+
+## API Reference
+
+### `CweNode`
+Represents a single CWE entry.
+
+#### Properties:
+- `cwe_id`: The unique CWE identifier.
+- `name`: The CWE name/description.
+- `abstract`: The abstraction type (e.g., Class, Base, Variant).
+- `layer`: A dictionary representing the depth in various CWE trees.
+- `parents`: A set of parent CWE IDs.
+- `children`: A set of child CWE IDs.
+
+#### Methods:
+- `get_metadata() -> dict`: Returns CWE node metadata.
+
+### `CweTree`
+Manages the CWE hierarchy and provides querying capabilities.
+
+#### Methods:
+- `get_node(cwe_id: str) -> CweNode`: Retrieves a CWE node by ID.
+- `get_parents(cwe_id: str) -> set`: Returns parent CWE IDs.
+- `get_children(cwe_id: str) -> set`: Returns child CWE IDs.
+- `get_layer(cwe_id: str) -> dict`: Returns the CWE's layer mapping.
+- `get_metadata(cwe_id: str) -> dict`: Returns CWE metadata.
+- `get_roots() -> list`: Returns a list of root CWE nodes.
+
+## Data Format
+
+The package loads CWE data from CSV files:
+- `nodes.csv`: Contains CWE nodes with columns: `id`, `name`, `abstract`, `layer`
+- `rels.csv`: Contains relationships with columns: `source`, `target`
+
+## License
+This package is released under the MIT License.
+
+## Contributing
+Contributions are welcome! Please submit a pull request or open an issue for discussions.
+

cwe_tree-1.0.0/README.md

@@ -0,0 +1,106 @@
+# CWE Tree Python Package
+
+## Overview
+
+This package provides a structured representation of the [Common Weakness Enumeration (CWE)](https://cwe.mitre.org/) hierarchy using a tree-based data model. It allows users to query CWE nodes, understand parent-child relationships, and extract metadata for each CWE entry.
+
+## Features
+- Load CWE nodes and relationships from CSV files (`nodes.csv` and `rels.csv`).
+- Represent CWE entries as `CweNode` objects.
+- Store and manage the entire CWE structure as a `CweTree`.
+- Query CWE metadata, parent-child relationships, and tree layers.
+
+## Installation
+
+Clone this repository and install dependencies if required:
+
+```sh
+pip install -e . 
+```
+
+or using pip repo
+
+```sh
+pip install cwe_tree 
+```
+
+## Usage
+
+### Import the package
+```python
+from cwe_tree import query, CweTree, CweNode
+```
+
+### Querying CWE nodes
+
+```python
+# Retrieve a CWE node by ID
+cwe_node = query.get_node("CWE-732")
+if cwe_node:
+    print(cwe_node.get_metadata())
+```
+
+### Fetching parent-child relationships
+
+```python
+# Get parent CWEs
+parents = query.get_parents("CWE-732")
+print("Parent CWE IDs:", parents)
+
+# Get child CWEs
+children = query.get_children("CWE-732")
+print("Child CWE IDs:", children)
+```
+
+### Retrieving metadata
+
+```python
+metadata = query.get_metadata("CWE-732")
+print("CWE Metadata:", metadata)
+```
+
+### Getting root nodes
+```python
+roots = query.get_roots()
+print("Root CWE nodes:", [node.cwe_id for node in roots])
+```
+
+## API Reference
+
+### `CweNode`
+Represents a single CWE entry.
+
+#### Properties:
+- `cwe_id`: The unique CWE identifier.
+- `name`: The CWE name/description.
+- `abstract`: The abstraction type (e.g., Class, Base, Variant).
+- `layer`: A dictionary representing the depth in various CWE trees.
+- `parents`: A set of parent CWE IDs.
+- `children`: A set of child CWE IDs.
+
+#### Methods:
+- `get_metadata() -> dict`: Returns CWE node metadata.
+
+### `CweTree`
+Manages the CWE hierarchy and provides querying capabilities.
+
+#### Methods:
+- `get_node(cwe_id: str) -> CweNode`: Retrieves a CWE node by ID.
+- `get_parents(cwe_id: str) -> set`: Returns parent CWE IDs.
+- `get_children(cwe_id: str) -> set`: Returns child CWE IDs.
+- `get_layer(cwe_id: str) -> dict`: Returns the CWE's layer mapping.
+- `get_metadata(cwe_id: str) -> dict`: Returns CWE metadata.
+- `get_roots() -> list`: Returns a list of root CWE nodes.
+
+## Data Format
+
+The package loads CWE data from CSV files:
+- `nodes.csv`: Contains CWE nodes with columns: `id`, `name`, `abstract`, `layer`
+- `rels.csv`: Contains relationships with columns: `source`, `target`
+
+## License
+This package is released under the MIT License.
+
+## Contributing
+Contributions are welcome! Please submit a pull request or open an issue for discussions.
+

cwe_tree-1.0.0/cwe_tree/__init__.py

@@ -0,0 +1,48 @@
+import csv, os
+from .cwe_node import CweNode  # Import the CweNode class (represents a CWE node)
+from .cwe_tree import CweTree  # Import the CweTree class (represents the entire CWE tree)
+
+# Get the absolute path of the current file and locate the `data/` directory containing CSV files
+base_path = os.path.dirname(os.path.abspath(__file__))  # Get the module's directory path
+nodes_csv = os.path.join(base_path, "data", "nodes.csv")  # Path to the nodes CSV file
+rels_csv = os.path.join(base_path, "data", "rels.csv")  # Path to the relationships CSV file
+
+def _load_data(cwe_tree: CweTree) -> CweTree:
+    """
+    Loads data from `nodes.csv` and `rels.csv` in the `data/` directory and populates the CweTree instance.
+
+    Args:
+        cwe_tree (CweTree): An instance of CweTree to be populated with data.
+
+    Returns:
+        CweTree: A fully populated CweTree instance containing all CWE nodes and relationships.
+    """
+    base_path = os.path.dirname(os.path.abspath(__file__))  # Get module's directory path
+    nodes_csv = os.path.join(base_path, "data", "nodes.csv")  # Path to the nodes CSV file
+    rels_csv = os.path.join(base_path, "data", "rels.csv")  # Path to the relationships CSV file
+
+    # Read `nodes.csv` and add nodes to the CweTree
+    with open(nodes_csv, "r", encoding="utf-8") as f:
+        reader = csv.DictReader(f)  # Read CSV as a dictionary
+        for row in reader:
+            cwe_id = row["id"]  # Retrieve CWE ID
+            name = row["name"]  # Retrieve CWE name
+            abstract = row["abstract"]  # Retrieve CWE abstraction type
+            layer = row["layer"]  # Retrieve layer information
+            cwe_tree._add_node(cwe_id, name, abstract, layer)  # Add node to CweTree
+
+    # Read `rels.csv` and add relationships (edges)
+    with open(rels_csv, "r", encoding="utf-8") as f:
+        reader = csv.DictReader(f)  # Read CSV as a dictionary
+        for row in reader:
+            parent_id = row["source"]  # Retrieve source (parent) CWE ID
+            child_id = row["target"]  # Retrieve target (child) CWE ID
+            cwe_tree._add_edge(parent_id, child_id)  # Add edge (parent-child relationship) in CweTree
+
+    return cwe_tree  # Return the populated CweTree instance
+
+# Create a `CweTree` instance and load data immediately when the module is imported
+query: CweTree = _load_data(CweTree())
+
+# Define `__all__` to specify the public API of the module
+__all__ = ["query", "CweTree", "CweNode"]  # Allows users to import `query`, `CweTree`, and `CweNode`

cwe_tree-1.0.0/cwe_tree/cwe_node.py

@@ -0,0 +1,116 @@
+class CweNode:
+    """
+    Represents a single CWE (Common Weakness Enumeration) node in the CWE hierarchy.
+
+    A CWE node contains:
+    - A unique CWE ID.
+    - A name describing the weakness.
+    - An abstract type (e.g., Class, Base, Variant).
+    - A layer mapping indicating its depth in different root trees.
+    - Parent-child relationships to track CWE dependencies.
+    """
+
+    def __init__(self, cwe_id: str, name: str, abstract: str):
+        """
+        Initializes a CWE node with its unique ID, name, and type.
+
+        Args:
+            cwe_id (str): The unique CWE identifier (e.g., "CWE-732").
+            name (str): The name/description of the CWE.
+            abstract (str): The abstraction type (e.g., "Class", "Base", "Variant").
+        """
+        self._cwe_id = cwe_id  # CWE ID (e.g., "CWE-732")
+        self._name = name  # CWE Name (e.g., "Incorrect Permission Assignment for Critical Resource")
+        self._abstract = abstract  # CWE Type (e.g., "Class", "Base", "Variant")
+        self._layer = {}  # Dictionary to store layer levels in different trees { "CWE-284": 2 }
+        self._parents = set()  # Set of parent nodes (other CWEs this node is derived from)
+        self._children = set()  # Set of child nodes (other CWEs that depend on this node)
+
+    @property
+    def cwe_id(self) -> str:
+        """Returns the CWE ID (read-only)."""
+        return self._cwe_id
+
+    @property
+    def name(self) -> str:
+        """Returns the CWE name (read-only)."""
+        return self._name
+
+    @property
+    def abstract(self) -> str:
+        """Returns the CWE abstraction type (read-only)."""
+        return self._abstract
+
+    @property
+    def layer(self) -> dict:
+        """
+        Returns a copy of the layer mapping.
+
+        The layer mapping stores the depth level of this node in different root CWE trees.
+        Example:
+            { "CWE-284": 2 } means this node is at level 2 in the CWE-284 hierarchy.
+        """
+        return self._layer.copy()  # Return a copy to prevent modification
+
+    @property
+    def parents(self) -> set:
+        """
+        Returns a copy of the set of parent CWE nodes.
+
+        Parents are CWEs from which this node is derived.
+        """
+        return self._parents.copy()  # Return a copy to prevent modification
+
+    @property
+    def children(self) -> set:
+        """
+        Returns a copy of the set of child CWE nodes.
+
+        Children are CWEs that depend on this node.
+        """
+        return self._children.copy()  # Return a copy to prevent modification
+
+    def _add_layer(self, root_id: str, level: int):
+        """
+        Adds or updates the layer mapping for this node.
+
+        Args:
+            root_id (str): The root CWE ID representing the tree.
+            level (int): The depth level of this node in the specified CWE tree.
+        """
+        self._layer[root_id] = level
+
+    def _add_parent(self, parent_id: str):
+        """
+        Adds a parent CWE ID to this node.
+
+        Args:
+            parent_id (str): The CWE ID of the parent node.
+        """
+        self._parents.add(parent_id)
+
+    def _add_child(self, child_id: str):
+        """
+        Adds a child CWE ID to this node.
+
+        Args:
+            child_id (str): The CWE ID of the child node.
+        """
+        self._children.add(child_id)
+
+    def get_metadata(self) -> dict:
+        """
+        Returns metadata of this CWE node, including its ID, name, abstraction type, layer mapping,
+        and relationships (parents and children).
+
+        Returns:
+            dict: A dictionary containing CWE node information.
+        """
+        return {
+            "id": self.cwe_id,
+            "name": self.name,
+            "abstract": self.abstract,
+            "layer": self.layer,  # Layer mapping in different root trees
+            "parents": list(self.parents),  # Convert set to list for serialization
+            "children": list(self.children),  # Convert set to list for serialization
+        }

cwe_tree-1.0.0/cwe_tree/cwe_tree.py

@@ -0,0 +1,147 @@
+import json
+from .cwe_node import CweNode
+
+class CweTree:
+    """
+    Represents a CWE Tree, which contains CWE nodes and their relationships.
+
+    This class manages:
+    - Creating and storing CWE nodes.
+    - Establishing parent-child relationships between CWE nodes.
+    - Providing utility functions for retrieving metadata and relationships.
+    """
+
+    def __init__(self):
+        """ Initializes an empty CWE Tree. """
+        self._nodes = {}  # Dictionary to store CWE nodes { "CWE-732": CweNode, ... }
+
+    def _normalize_cwe(self, cwe_id: str) -> str:
+        """
+        Normalizes a CWE ID to ensure consistency.
+
+        If the CWE ID does not start with "CWE-", it adds the prefix.
+        This allows users to query using either "732" or "CWE-732".
+
+        Args:
+            cwe_id (str): The CWE ID to normalize.
+
+        Returns:
+            str: Normalized CWE ID (e.g., "CWE-732").
+        """
+        return f"CWE-{cwe_id}" if not cwe_id.startswith("CWE-") else cwe_id
+
+    def _add_node(self, cwe_id: str, name: str, abstract: str, layer: str):
+        """
+        Adds a CWE node to the tree.
+
+        Args:
+            cwe_id (str): The unique CWE identifier.
+            name (str): The name/description of the CWE.
+            abstract (str): The abstraction type (e.g., "Class", "Base", "Variant").
+            layer (str): A JSON string or dictionary representing the node's layer levels.
+        """
+        cwe_id = self._normalize_cwe(cwe_id)
+
+        # Create node if it doesn't already exist
+        if cwe_id not in self._nodes:
+            self._nodes[cwe_id] = CweNode(cwe_id, name, abstract)
+
+        # Parse and store layer data (JSON format)
+        try:
+            layer_data = json.loads(layer) if isinstance(layer, str) else layer
+            if isinstance(layer_data, dict):
+                for root, level in layer_data.items():
+                    self._nodes[cwe_id]._add_layer(root, level)
+        except json.JSONDecodeError:
+            pass  # Ignore invalid layer data
+
+    def _add_edge(self, parent_id: str, child_id: str):
+        """
+        Establishes a parent-child relationship between two CWE nodes.
+
+        Args:
+            parent_id (str): The CWE ID of the parent node.
+            child_id (str): The CWE ID of the child node.
+        """
+        parent_id, child_id = self._normalize_cwe(parent_id), self._normalize_cwe(child_id)
+
+        # Ensure both nodes exist before creating a relationship
+        if parent_id in self._nodes and child_id in self._nodes:
+            self._nodes[parent_id]._add_child(child_id)
+            self._nodes[child_id]._add_parent(parent_id)
+
+    def get_node(self, cwe_id: str) -> CweNode:
+        """
+        Retrieves a CWE node by its ID.
+
+        Args:
+            cwe_id (str): The CWE ID to retrieve.
+
+        Returns:
+            CweNode: The requested CWE node, or None if it does not exist.
+        """
+        cwe_id = self._normalize_cwe(cwe_id)
+        return self._nodes.get(cwe_id)
+
+    def get_parents(self, cwe_id: str) -> set:
+        """
+        Retrieves the parents of a given CWE node.
+
+        Args:
+            cwe_id (str): The CWE ID whose parents should be retrieved.
+
+        Returns:
+            set: A set of parent CWE IDs.
+        """
+        node = self.get_node(cwe_id)
+        return node.parents if node else set()
+
+    def get_children(self, cwe_id: str) -> set:
+        """
+        Retrieves the children of a given CWE node.
+
+        Args:
+            cwe_id (str): The CWE ID whose children should be retrieved.
+
+        Returns:
+            set: A set of child CWE IDs.
+        """
+        node = self.get_node(cwe_id)
+        return node.children if node else set()
+
+    def get_layer(self, cwe_id: str) -> dict:
+        """
+        Retrieves the layer information for a given CWE node.
+
+        Args:
+            cwe_id (str): The CWE ID whose layer should be retrieved.
+
+        Returns:
+            dict: A dictionary representing the layer mapping (e.g., { "CWE-284": 2 }).
+        """
+        node = self.get_node(cwe_id)
+        return node.layer if node else {}
+
+    def get_metadata(self, cwe_id: str) -> dict:
+        """
+        Retrieves metadata for a given CWE node.
+
+        Args:
+            cwe_id (str): The CWE ID whose metadata should be retrieved.
+
+        Returns:
+            dict: A dictionary containing metadata about the CWE node.
+        """
+        node = self.get_node(cwe_id)
+        return node.get_metadata() if node else None
+
+    def get_roots(self) -> list:
+        """
+        Retrieves all root nodes in the CWE tree.
+
+        Root nodes are nodes that have no parents.
+
+        Returns:
+            list: A list of CweNode instances that have no parents.
+        """
+        return [node for node in self._nodes.values() if not node.parents]