Added the list-element command

raphaelahrens commented 3 years ago

model.py --list-elements shows a list of all elements which can be used in a threat model with pytm.

Why? I often find my self looking up the exact names of the elements and there doc string.

Currently the output looks like this.

Elements:
Actor          -- An entity usually initiating actions
Asset          -- An asset with outgoing or incoming dataflows
Boundary       -- Trust boundary groups elements and data with the same trust level.
Dataflow       -- A data flow from a source to a sink
Datastore      -- An entity storing data
ExternalEntity --
Lambda         -- A lambda function running in a Function-as-a-Service (FaaS) environment
Process        -- An entity processing data
Server         -- An entity processing data
SetOfProcesses --

Atributes:
Action         -- Action taken when validating a threat model.
Classification -- An enumeration.
Data           -- Represents a single piece of data that traverses the system
Lifetime       -- An enumeration.
TLSVersion     -- An enumeration.

izar commented 3 years ago

This is great, thank you! I wonder if there isn't a bit too much filtering there - for example, where is Data?

raphaelahrens commented 3 years ago

Hi, true, Data and the Enums TLSVersion, Classifiction and Lifetime could be added.

Currently I use the reflection api to get all sub classes of Element, since I thought it would make things easier for future changes. But Data needs to be manuallay added and i guess the same is true for TLSVersion, Classifiction and Lifetime, since Enum is also used for internal components. For example when I just add Enum as well.

Elements

Actor          -- An entity usually initiating actions
Asset          -- An asset with outgoing or incoming dataflows
Boundary       -- Trust boundary groups elements and data with the same trust level.
Dataflow       -- A data flow from a source to a sink
Datastore      -- An entity storing data
ExternalEntity --
Lambda         -- A lambda function running in a Function-as-a-Service (FaaS) environment
Process        -- An entity processing data
Server         -- An entity processing data
SetOfProcesses --

Atributes

Action           -- Action taken when validating a threat model.
AddressFamily    -- An enumeration.
AddressInfo      -- An enumeration.
AlertDescription -- An enumeration.
Classification   -- An enumeration.
Flag             --
    Support for flags

HTTPStatus       -- HTTP status codes and reason phrases

    Status codes from the following RFCs are all observed:

        * RFC 7231: Hypertext Transfer Protocol (HTTP/1.1), obsoletes 2616
        * RFC 6585: Additional HTTP Status Codes
        * RFC 3229: Delta encoding in HTTP
        * RFC 4918: HTTP Extensions for WebDAV, obsoletes 2518
        * RFC 5842: Binding Extensions to WebDAV
        * RFC 7238: Permanent Redirect
        * RFC 2295: Transparent Content Negotiation in HTTP
        * RFC 2774: An HTTP Extension Framework
        * RFC 7725: An HTTP Status Code to Report Legal Obstacles
        * RFC 7540: Hypertext Transfer Protocol Version 2 (HTTP/2)

Handlers         -- An enumeration.
IntEnum          -- Enum where members are also (and must be) ints
IntFlag          --
    Support for integer-based Flags

Lifetime         -- An enumeration.
MsgFlag          -- An enumeration.
Options          -- An enumeration.
OrderedEnum      -- An enumeration.
Purpose          -- SSLContext purpose flags with X509v3 Extended Key Usage objects

RegexFlag        -- An enumeration.
SSLErrorNumber   -- An enumeration.
SafeUUID         -- An enumeration.
Sigmasks         -- An enumeration.
Signals          -- An enumeration.
SocketKind       -- An enumeration.
TLSVersion       -- An enumeration.
TLSVersion       -- An enumeration.
VerifyFlags      -- An enumeration.
VerifyMode       -- An enumeration.
_ParameterKind   -- An enumeration.
_SSLMethod       -- An enumeration.
_TLSAlertType    -- Alert types for TLSContentType.ALERT messages

    See RFC 8466, section B.2

_TLSContentType  -- Content types (record layer)

    See RFC 8446, section B.1

_TLSMessageType  -- Message types (handshake protocol)

    See RFC 8446, section B.3

Do you have a list of classes that should be in there?

raphaelahrens commented 3 years ago

Fixed a check with the args checking and added the Attributes list.

raphaelahrens commented 2 years ago

Hi, I just wanted to know if this PR may lead to something or if it should be closed.

izar commented 2 years ago

So so sorry! I got overridden by Real Life(TM). I think it is a very useful feature, just wondering how can it better filtered as currently it seems to be reflecting way more than pytm elements and their attributes. Any ideas?

raphaelahrens commented 2 years ago

No problem. I already boiled it done to these two statements.

print_components(all_subclasses(Element))

and

print_components(
        all_subclasses(OrderedEnum) | {Data, Action, Lifetime}

)

Which gives this output

Elements:
Actor          -- An entity usually initiating actions
Asset          -- An asset with outgoing or incoming dataflows
Boundary       -- Trust boundary groups elements and data with the same trust level.
Dataflow       -- A data flow from a source to a sink
Datastore      -- An entity storing data
ExternalEntity --
Lambda         -- A lambda function running in a Function-as-a-Service (FaaS) environment
Process        -- An entity processing data
Server         -- An entity processing data
SetOfProcesses --

Atributes:
Action         -- Action taken when validating a threat model.
Classification -- An enumeration.
Data           -- Represents a single piece of data that traverses the system
Lifetime       -- An enumeration.
TLSVersion     -- An enumeration.

This is possible since the classesElement and OrderedEnum come from pytm. Only {Data, Action, Lifetime} have to be added manually since they have no indicator that they are Attributes which can be used.

To discover all components automatically they would need some indicator by which they could be selected. Either through

adding a dummy parent class (this would add useless code)
moving the components into separate modules (adds extra imports and they have to be reexported in ___init__.py)
have a special marker attribute (sounds horrible), except the attribute is something useful like a short description.

I guess it is fine as it is now, or is there something still in the list which should not be displayed? The only downside to the current solution is if other classes like Data will be added with no indicator.

To make the output more useful it would be good to have doc strings for TLSVersion, Lifetime, Classification, Server, Process, SetOfProcesses,and ExternalEntity. This would also help with my confusion on the differences between Actor and ExternalEntity (I guess Actor is a human?), and Server and Process.

izar commented 2 years ago

It is interesting you mention the possibility of making this easier by going into separate modules. I have been talking with @nineinchnick and even have a branch with work half-done separating classes into separate modules; unfortunately I took some wrong turns into design choices right at the beginning that make that work harder. Still, I consider it an important part of the roadmap (actually, I need to add it to the file). Any suggestions you may have on that are most welcome! Thanks for this useful feature.

raphaelahrens commented 2 years ago

If the attributes would be in a module pytm/attributes.py then it would be very easy to select them since one would only need to look at one module to select the classes from it.

I looked at the branch modular which you mentioned and I don't know it this would have helped. a) all classes have their own modules and so it is not clear if actor.Actor is an element or an attribute. b) splitting every single class in its own module doesn't help readability and is not typical python code. I would prefer if similar classes are in a single module.

May I ask what the main motivation was for the modular branch? And what where the "wrong turns into design choices"? Is there already an Issue for this topic where a discussion can be held?

izar commented 2 years ago

I don't think we have a discussion going on. The design choices were more in the vein of "ok, let me see if i can get this working" than being really pythonic and clear - for example, Jan has repeatedly explained to me that context managers would be of great help in simplifying things.

What would you suggest would be a better reorg and redesign?

thanks!

On Mon, Aug 30, 2021 at 5:44 AM Raphael Ahrens @.***> wrote:

If the attributes would be in a module pytm/attributes.py then it would be very easy to select them since one would only need to look at one module to select the classes from it.

I looked at the branch modular which you mentioned and I don't know it this would have helped. a) all classes have there own modules and so it is not clear if actor.Actor is an element or an attribute. b) splitting every single class in its own module doesn't help readability and is not typical python code. I would prefer if similar classes are in a single module.

May I ask what the main motivation was for the modular branch? And what where the "wrong turns into design choices"? Is there already an Issue for this topic where a discussion can be held?

— You are receiving this because you modified the open/close state. Reply to this email directly, view it on GitHub https://github.com/izar/pytm/pull/167#issuecomment-908200582, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAC2BAP53YJF7QJB3AGMJTLT7NHHNANCNFSM5BT6FDCQ . Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub.

izar / pytm

Added the list-element command #167