mandiant / mandiant/capa

tree-sitter: protobuf output incomplete

Open
#3,146 0 comments 0 reactions 1 assignee Claimed by @saniyafatima07 View on GitHub
bug gsoc tree-sitter
Dominant language
Python
Stars
6.2k
Forks
726
Avg merge
11d 11h
Merged PRs (30d)
7

Description

Converting script analysis results into the Protobuf format (e.g., via `scripts/proto-from-results.py` or calling `capa.render.proto.doc_to_pb2()`) fails with unhandled type assertions.

The script analysis feature introduced `ScriptLanguage` (`script language`) features and `FileOffsetRangeAddress` (`file range`) addresses into `capa.features` and `capa.features.freeze`. However, the protobuf schema and the `capa.render.proto` converter logic were not updated to handle these newly added types.

When attempting to serialize a script analysis result document to Protobuf format, `capa.render.proto` throws an `AssertionError` in `assert_never()` upon encountering the unhandled `FileOffsetRangeAddress` and `ScriptLanguageFeature` types.

To achieve full parity with existing output formats, we need to update the protobuf serialization layer:
1. **Protobuf Schema (`capa.proto`)**:
- Extend the `AddressType` enum and `Address` message to support file offset range addresses.
- Add a definition for `ScriptLanguageFeature` and include it in the `FeatureNode` message union.
2. **Regenerate Protobuf Code & Stubs**:
- Recompile `capa.proto` using `protoc` to update `capa_pb2.py` and `capa_pb2.pyi`:
```bash
protoc --python_out=. --pyi_out=. capa/render/proto/capa.proto
```
3. **Protobuf Renderer (`capa/render/proto/__init__.py`)**:
- Update `addr_to_pb2` and `addr_from_pb2` to map `FileOffsetRangeAddress` to/from Protobuf messages.
- Update `feature_to_pb2` and `feature_from_pb2` to support bidirectional conversion of `ScriptLanguageFeature`.
4. **Testing**:
- Add unit test coverage in `tests/test_proto.py` verifying roundtrip conversion for `FileOffsetRangeAddress` and `ScriptLanguageFeature`.
- Ensure script analysis results can be successfully converted via `scripts/proto-from-results.py`.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.