JSON results documentation

[brendonky18]

Going from version 3 to version 4, the release notes say that the JSON results format was changed, and that these changed were documented. Does anyone have a link to the documentation explaining what changed between v3 and v4?

[mr-tz]

Hey, I don't see more detailed documentation on this either, but the major change between v3 and v4 is the change from number-only based addresses, e.g. "base_address": 4194304, to more expressive/flexible addresses, e.g.:

"base_address":
{
    "type": "absolute",
    "value": 4194304
},

For the update we also switched to using a pydantic model. If you're processing the results that should simplify a few things. An example to load the stored results:

with open(capa_results.json, "rb") as f:
    doc = json.loads(f.read().decode("utf-8"))
res = rd.ResultDocument.parse_obj(results)

You can then access the result document fields like res.meta vs. the res["meta"] access before.

Does that help? I'm happy to provide more details for additional questions.

[brendonky18]

Yeah that's super helpful, thanks!

Do you know if there are any other valid formats for the base_address field besides absolute that I would have to account for?

[mr-tz]

base_address will be absolute or the NO_ADDRESS address type. All supported address types can be found here for example

capa/capa/features/freeze/__init__.py

Line 38 in e1735f0

class AddressType(str, Enum):

.

[brendonky18]

Looking at what you sent, it seems like the address can also be a relative address. How would I find the base address that's calculated from to get the absolute address again?

[mr-tz]

here is where the supported return types are listed:

capa/capa/features/extractors/base_extractor.py

Line 93 in fb99ef5

def get_base_address(self) -> Union[AbsoluteVirtualAddress, capa.features.address._NoAddress]: