OWASP / OWASP/pytm

Add docstrings for pytm model entities

Open
#294 6 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
1.2k
Forks
229
PR merge metrics
No merged PRs in 30d

Description

The CLI based development workflow using ./tm.py --list-elements + ./tm.py --describe <element> is not convenient for threat model creation.

An easier and more efficient workflow to work with model entities (this includes custom model entities) makes use of/depends on docstrings.

E.g. when using google docstring format the Actor class (docstring reference) + __init__ method (google format docstring reference) could be documented like

class Actor(Element):
    """An entity usually initiating actions.

    Attributes:
        port (int): Default TCP port for outgoing data flows.
        protocol (str): Default network protocol for outgoing data flows.
        data (list): List of pytm.Data objects in outgoing data flows.
        inputs (list): List of incoming Dataflows.
        outputs (list): List of outgoing Dataflows.
        isAdmin (bool): Indicates if the actor is an administrator.
    """

    port = varInt(-1, doc="Default TCP port for outgoing data flows")
    protocol = varString("", doc="Default network protocol for outgoing data flows")
    data = varData([], doc="pytm.Data object(s) in outgoing data flows")
    inputs = varElements([], doc="incoming Dataflows")
    outputs = varElements([], doc="outgoing Dataflows")
    isAdmin = varBool(False)

    def __init__(self, name, **kwargs):
        """
        Initialize an Actor object.

        Args:
            name (str): The name of the actor.
            **kwargs: Additional keyword arguments.
                port (int): Default TCP port for outgoing data flows.
                protocol (str): Default network protocol for outgoing data flows.
                data (list): List of pytm.Data objects in outgoing data flows.
                inputs (list): List of incoming Dataflows.
                outputs (list): List of outgoing Dataflows.
                isAdmin (bool): Indicates if the actor is an administrator.
        """
        super().__init__(name, **kwargs)
        TM._actors.append(self)

and would result IDE-wise in something like this:

https://github.com/user-attachments/assets/9ede76e1-3689-4906-bd39-b2af7e0333af

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in pytm/pytm.py with the Actor class and its init method, then identify the other pytm model entity classes covered by the request. Follow the linked Google-style class and function docstring references, and use ./tm.py --list-elements and ./tm.py --describe to verify that the documented entities expose useful descriptions.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.