docs: align README examples with current Pydantic API (#336)

izar · snyk-bot · web-flow · commit 5e664f4e3d58 · 2026-07-06T09:09:25.000-04:00
## Summary

- **`controls.isHardened`**: `web.isHardened = True` and `db.isHardened
= False` changed to `web.controls.isHardened = True` /
`db.controls.isHardened = False`. `isHardened` lives on `Controls`, not
on `Element`. Because `Element` has `extra="allow"`, the old form
**failed silently** — it stored the value as an extra field and left
`controls.isHardened` at its default.
- **`controls.hasAccessControl`**: `my_lambda.hasAccessControl = True` →
`my_lambda.controls.hasAccessControl = True`. Same silent-failure
mechanism.
- **`db.type = DatastoreType.SQL`**: `db.isSql = True` → `db.type =
DatastoreType.SQL`. The actual field is `isSQL` (uppercase), not
`isSql`; `isSql` was silently stored as an extra field. The shipped
`tm.py` uses `DatastoreType.SQL`.
- **`sourceFiles`**: `web.sourceCode` and `db.sourceCode` →
`web.sourceFiles = [...]` / `db.sourceFiles = [...]`. `sourceFiles` is a
`List[str]` on `Element`; `sourceCode` was silently ignored.
- **`DatastoreType` import**: Added to the sample import list (required
by `db.type = DatastoreType.SQL`).
- **`--describe` block**: Replaced stale hand-written output (showing
pre-Pydantic fields that no longer exist) with verbatim output of
`./tm.py --describe Server`, which shows the full inherited attribute
set including `controls`, `sourceFiles`, `minTLSVersion`, etc.
- **Usage block**: Updated synopsis (added `--colormap` to synopsis
line; changed `optional arguments:` to `options:` — Python 3.10+
argparse wording).
- **Threat condition example**: `f.sink.isSQL` → `f.sink.type ==
DatastoreType.SQL`. `isSQL` is a valid bool field (still exists,
defaults `True`) but is non-discriminating for all Datastores by
default; `type == DatastoreType.SQL` matches the idiom in the shipped
`tm.py`.

## Verified failure mode of old sample

`extra="allow"` on Pydantic models means every stale attribute set
(`web.isHardened`, `db.isSql`, `web.sourceCode`, etc.) was silently
stored in `model_extra` rather than raising a `ValidationError`. No
error was raised; the intended fields were simply never set.

## Validation

```
# Corrected sample
python /tmp/sample.py --dfd &gt; /dev/null          # OK
python /tmp/sample.py --report docs/basic_template.md &gt; /dev/null   # OK

# Test suite
uv run pytest tests/ -x -q   # 243 passed

# Diff touches only README.md
git diff --stat HEAD~1  # README.md | 93 +++...
```

## Hypotheses that turned out wrong

- The hypothesis stated the README uses `from pytm.pytm import`; it
already used `from pytm import` correctly. Only the missing
`DatastoreType` in the import list needed fixing.
- `docs/threats.md` hits from the `grep` sweep
(`target.controls.isHardened`, `target.controls.hasAccessControl`) are
already in correct form — no changes needed there.

## Out-of-scope finding

`./tm.py --describe Element` errors with "No such class to describe:
Element" because `Element` is not added to `_CLASS_REGISTRY` in
`pytm/pytm.py` (only its subclasses are added via `_iter_subclasses`).
Tracked separately.

---------

Co-authored-by: snyk-bot &lt;snyk-bot@snyk.io&gt;
diff --git a/README.md b/README.md
@@ -75,12 +75,12 @@ lower overhead and more convenient alternative to the OCI container approach.
 All available arguments:
 
 ```text
-usage: tm.py [-h] [--debug] [--dfd] [--report REPORT]
-             [--exclude EXCLUDE] [--seq] [--list] [--describe DESCRIBE]
+usage: tm.py [-h] [--debug] [--dfd] [--report REPORT] [--exclude EXCLUDE]
+             [--seq] [--list] [--colormap] [--describe DESCRIBE]
              [--list-elements] [--json JSON] [--levels LEVELS [LEVELS ...]]
              [--stale_days STALE_DAYS]
 
-optional arguments:
+options:
   -h, --help            show this help message and exit
   --debug               print debug messages
   --dfd                 output DFD
@@ -109,21 +109,62 @@ Currently available elements are: TM, Element, Server, ExternalEntity, Datastore
 The available properties of an element can be listed by using `--describe` followed by the name of an element:
 
 ```text
-
-(pytm) ➜  pytm git:(master) ✗ ./tm.py --describe Element
-Element class attributes:
-  OS
-  definesConnectionTimeout        default: False
-  description
-  handlesResources                default: False
-  implementsAuthenticationScheme  default: False
-  implementsNonce                 default: False
-  inBoundary
-  inScope                         Is the element in scope of the threat model, default: True
-  isAdmin                         default: False
-  isHardened                      default: False
-  name                            required
-  onAWS                           default: False
+$ ./tm.py --describe Server
+Server class attributes:
+  OS                        Operating system
+                            default: ''
+  assumptions               Assumptions about the element. These optionally allow to exclude threats with the given SIDs
+                            default factory: list
+  controls                  Security controls for this element
+                            default factory: Controls
+  data                      pytm.Data object(s) in incoming data flows
+                            default factory: DataSet
+  description               Description of the element
+                            default: ''
+  findings                  Threats that apply to this element
+                            default factory: list
+  handlesResources          Does this asset handle resources?
+                            default: False
+  inBoundary                Trust boundary this element exists in
+                            default: None
+  inScope                   Is the element in scope of the threat model
+                            default: True
+  inputs                    incoming Dataflows
+                            default factory: list
+  is_drawn                  default: False
+  levels                    List of levels (0, 1, 2, ...) to be drawn in the model
+                            default factory: <lambda>
+  maxClassification         Maximum data classification this element can handle
+                            default: <Classification.UNKNOWN: 0>
+  minTLSVersion             Minimum TLS version required
+                            default: <TLSVersion.NONE: 0>
+  name                      Name of the element
+                            required
+  onAWS                     Is this asset on AWS?
+                            default: False
+  outputs                   outgoing Dataflows
+                            default factory: list
+  overrides                 Overrides to findings, allowing to set a custom response, CVSS score or override other attributes
+                            default factory: list
+  port                      Default TCP port for incoming data flows
+                            default: -1
+  protocol                  Default network protocol for incoming data flows
+                            default: ''
+  severity                  Severity level of threats affecting this element
+                            default: 0
+  sourceFiles               Location of the source code that describes this element relative to the directory of the model script
+                            default factory: list
+  usesCache                 Does this server use cache?
+                            default: False
+  usesEnvironmentVariables  Does this asset use environment variables?
+                            default: False
+  usesSessionTokens         Does this server use session tokens?
+                            default: False
+  usesVPN                   Does this server use VPN?
+                            default: False
+  usesXMLParser             Does this server use XML parser?
+                            default: False
+  uuid                      default factory: <lambda>
 
 ```
 
@@ -146,7 +187,8 @@ that periodically cleans the Database.
 
 #!/usr/bin/env python3
 
-from pytm import TM, Server, Datastore, Dataflow, Boundary, Actor, Lambda, LLM, Data, Classification
+from pytm import TM, Server, Datastore, Dataflow, Boundary, Actor, Lambda, LLM, Data, Classification, DatastoreType
+
 
 tm = TM("my test tm")
 tm.description = "another test tm"
@@ -160,16 +202,16 @@ user.inBoundary = User_Web
 
 web = Server("Web Server")
 web.OS = "CloudOS"
-web.isHardened = True
-web.sourceCode = "server/web.cc"
+web.controls.isHardened = True
+web.sourceFiles = ["server/web.cc"]
 
 db = Datastore("SQL Database (*)")
 db.OS = "CentOS"
-db.isHardened = False
+db.controls.isHardened = False
 db.inBoundary = Web_DB
-db.isSql = True
+db.type = DatastoreType.SQL
 db.inScope = False
-db.sourceCode = "model/schema.sql"
+db.sourceFiles = ["model/schema.sql"]
 
 comments = Data(
     name="Comments", 
@@ -196,7 +238,7 @@ results = Data(
 )
 
 my_lambda = Lambda("cleanDBevery6hours")
-my_lambda.hasAccessControl = True
+my_lambda.controls.hasAccessControl = True
 my_lambda.inBoundary = Web_DB
 
 llm_api = LLM("AI Writing Assistant")
@@ -393,7 +435,7 @@ If `target` is a Dataflow, remember you can access `target.source` and/or `targe
 Conditions on assets can analyze all incoming and outgoing Dataflows by inspecting
 the `target.input` and `target.output` attributes. For example, to match a threat only against
 servers with incoming traffic, use `any(target.inputs)`. A more advanced example,
-matching elements connecting to SQL datastores, would be `any(f.sink.oneOf(Datastore) and f.sink.isSQL for f in target.outputs)`.
+matching elements connecting to SQL datastores, would be `any(f.sink.oneOf(Datastore) and f.sink.type == DatastoreType.SQL for f in target.outputs)`.
 
 ## Importing from JSON
 
