You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
freeze format may emit import features with key "import_" rather than "import" #3085
What happens: model_dump_json() is called without by_alias=True on lines 457 and 576 of capa/features/freeze/init.py. Pydantic's default is to serialize using the Python field name, so the JSON key is "import_" (with trailing underscore) instead of "import".
Why it exists: The Python field is named import_ because import is a reserved keyword. The Field(alias="import") is configured correctly, and populate_by_name=True means deserialization accepts both "import" and "import_" — so roundtrip tests pass even though the output key is wrong. This masks the bug.
The same issue affects other aliased fields: FunctionNameFeature.function_name (alias "function name"), ClassFeature.class_ (alias "class"), OperandNumberFeature.operand_number (alias "operand number"), OperandOffsetFeature.operand_offset (alias "operand offset"), and several fields in init.py like base_address (alias "base address"), basic_block/basic_blocks, global_.
Recommendation: The cleanest fix is to add by_alias=True to both model_dump_json() calls (lines 457 and 576), plus all the sorting lambdas that also call model_dump_json(). This ensures the freeze file uses the intended human-readable keys ("import", "function name", "class", etc.) rather than Python-internal names.
Alternatively, you could set model_config = ConfigDict(frozen=True, populate_by_name=True, serialize_by_alias=True) on FeatureModel (Pydantic v2 feature) to make alias serialization the default for all models inheriting from it — but that's a broader change that could affect result documents and other serialization paths. The targeted by_alias=True at the two freeze dump sites is safer and more explicit.
The change would be on FeatureModel only (line 25 of features.py). The container models in init.py and result_document.py inherit from BaseModel/HashableModel/FrozenModel — not FeatureModel — so they are not directly affected. However, when a parent model serializes a nested FeatureModel field, Pydantic respects the child's serialize_by_alias config.
Feature.lt uses model_dump_json() for ordering. Key names would change, altering sort order of features. Functionally fine — only needs to be consistent, not canonical.
Result document JSON output (nested Feature fields)
scripts/bulk-process.py:215, scripts/proto-to-results.py:75 — more ResultDocument dumps
tests/test_result_document.py:252,260,267 — test assertions on JSON output
In all these, Feature models are nested inside StatementNode.child and FeatureNode.feature. The Feature portion of the JSON would change from "import_" to "import", etc. This is also the correct/desired behavior — but it means the result document JSON schema changes too, not just freeze files.
Already using by_alias=True (would become redundant but harmless)
tests/test_result_document.py:319 — meta.model_dump(by_alias=True) (this one is on a Metadata model, not FeatureModel, so unrelated)
Manual workarounds that could be removed
capa/render/vverbose.py:220-224 — special-cases ImportFeature.import_ and ClassFeature.class_ because the alias-based lookup wouldn't work without by_alias. With serialize_by_alias=True, the generic path on line 227 would handle these correctly.
Bottom line
The FeatureModel ConfigDict approach is clean and correct — it fixes both freeze files and result document JSON in one shot. The blast radius is well-contained: only the 5 aliased fields change their serialization keys, and everywhere that consumes these already expects the alias form (that's why the aliases exist). The by_alias=True calls become redundant but harmless, and the manual workarounds in vverbose.py become removable dead code.
Serialization paths: same freeze model_dump_json() calls. These inherit from HashableModel/BaseModel, not FeatureModel, so the FeatureModel ConfigDict fix alone wouldn't help — these need their own fix.
FrozenModel subclasses in capa/render/result_document.py
please do not volunteer PRs without thoroughly discussing the issue with maintainers. writing the code is not hard, especially for an LLM. the difficult part is coordinating the breaking changes with the ecosystem.
Activity
williballenthin commentedon May 20, 2026
williballenthin commentedon May 20, 2026
What happens: model_dump_json() is called without by_alias=True on lines 457 and 576 of capa/features/freeze/init.py. Pydantic's default is to serialize using the Python field name, so the JSON key is "import_" (with trailing underscore) instead of "import".
Why it exists: The Python field is named import_ because import is a reserved keyword. The Field(alias="import") is configured correctly, and populate_by_name=True means deserialization accepts both "import" and "import_" — so roundtrip tests pass even though the output key is wrong. This masks the bug.
The same issue affects other aliased fields: FunctionNameFeature.function_name (alias "function name"), ClassFeature.class_ (alias "class"), OperandNumberFeature.operand_number (alias "operand number"), OperandOffsetFeature.operand_offset (alias "operand offset"), and several fields in init.py like base_address (alias "base address"), basic_block/basic_blocks, global_.
Recommendation: The cleanest fix is to add by_alias=True to both model_dump_json() calls (lines 457 and 576), plus all the sorting lambdas that also call model_dump_json(). This ensures the freeze file uses the intended human-readable keys ("import", "function name", "class", etc.) rather than Python-internal names.
Alternatively, you could set model_config = ConfigDict(frozen=True, populate_by_name=True, serialize_by_alias=True) on FeatureModel (Pydantic v2 feature) to make alias serialization the default for all models inheriting from it — but that's a broader change that could affect result documents and other serialization paths. The targeted by_alias=True at the two freeze dump sites is safer and more explicit.
williballenthin commentedon May 20, 2026
Impact of serialize_by_alias=True on FeatureModel
The change would be on FeatureModel only (line 25 of features.py). The container models in init.py and result_document.py inherit from BaseModel/HashableModel/FrozenModel — not FeatureModel — so they are not directly affected. However, when a parent model serializes a nested FeatureModel field, Pydantic respects the child's serialize_by_alias config.
Affected fields (5 total, all in features.py)
Serialization sites impacted
In all these, Feature models are nested inside StatementNode.child and FeatureNode.feature. The Feature portion of the JSON would change from "import_" to "import", etc. This is also the correct/desired behavior — but it means the result document JSON schema changes too, not just freeze files.
Bottom line
The FeatureModel ConfigDict approach is clean and correct — it fixes both freeze files and result document JSON in one shot. The blast radius is well-contained: only the 5 aliased fields change their serialization keys, and everywhere that consumes these already expects the alias form (that's why the aliases exist). The by_alias=True calls become redundant but harmless, and the manual workarounds in vverbose.py become removable dead code.
williballenthin commentedon May 20, 2026
5 aliased fields on container models:
Serialization paths: same freeze model_dump_json() calls. These inherit from HashableModel/BaseModel, not FeatureModel, so the FeatureModel ConfigDict fix alone wouldn't help — these need their own fix.
7 aliased fields across two models:
Serialization paths: capa/render/json.py:21, capa/main.py:1013, capa/ida/plugin/form.py:1309, scripts/bulk-process.py:148,215, scripts/proto-to-results.py:75.
williballenthin commentedon May 20, 2026
The web UI is hardcoded to the current (buggy) Python field names:
williballenthin commentedon Nov 4, 2026
please do not volunteer PRs without thoroughly discussing the issue with maintainers. writing the code is not hard, especially for an LLM. the difficult part is coordinating the breaking changes with the ecosystem.