How to get the file path and file name from file metadata

[emesare]

I am writing a script, I want to know the file path (if available) and the file name. I understand that the file path is something that could be sensitive, and the BNDB may have removed it. What I want is to know, the two apis that I should be calling. Currently it seems we have four apis:

>>> bv.file.display_name
'/Users/emesare/Downloads/iterators.exe'
>>> bv.file.filename
'/Users/emesare/Downloads/iterators.exe'
>>> bv.file.original_filename
'/Users/emesare/Downloads/iterators.exe'
>>> bv.file.virtual_path
'/Users/emesare/Downloads/iterators.exe'

Its interesting to me that none of these apis are named to "get me the file path", a more straightforward approach would be to have a file_path and a file_name, I'm sure the "answer" will be that these are historical, but I'm more interested in what we are doing to simplify an API that really should not be that difficult to grok. All in all, these APIs seem extremely overloaded, and we should try and identify all usages of them in the product to determine what exactly each callers expectations are and refactor accordingly.

[psifertex]

I believe they're all intentionally (and meaningfully) different. At least, for three of them I know differences off the top of my head, not sure about the fourth. Agree that we should clearly document the differences though if we don't already!

So first, without checking the docs, here's my understanding:

• First one, not sure, this is the only one I don't know
• Second one is the one I know best, it's the current filename of the thing you have open on disk. In the case of a BNDB, it is the file of the BNDB itself.
• The third is for when a file is a BNDB, what was the ORIGINAL path/file that went into the BNDB
• The last is for container support. Helps to be able to differentiate the "inside" vs "outside" name.

Ok, now I'm gonna check the docs and see how they fare at clarifying the differences. Wish me luck:

https://dev-api.binary.ninja/binaryninja.filemetadata-module.html#binaryninja.filemetadata.FileMetadata.display_name
So that is also related to containers and makes sense. It's the "virtual" file path. I think this makes sense though up for hearing specific criticism. Biggest complaint I have is it doesn't link to filename, just references it. I think it does clarify.

https://dev-api.binary.ninja/binaryninja.filemetadata-module.html#binaryninja.filemetadata.FileMetadata.original_filename
Ohh, original_filename needs work. It only references projects (another case I hadn't considered) but that also makes sense! It should just reference the BNDB case too I think, work for me here.

https://dev-api.binary.ninja/binaryninja.filemetadata-module.html#binaryninja.filemetadata.FileMetadata.virtual_path
I think it makes sense, especially with the extract context in the note in .filename. My biggest complaint here is it doesn't cross-link to the other APIs. I'll fix that.

https://dev-api.binary.ninja/binaryninja.filemetadata-module.html#binaryninja.filemetadata.FileMetadata.filename
The OG. This could use a lot of cleanup now that we have all of the others. I think the note from .display_name belongs here and also it should cross-link the others, maybe in a table? I wonder if there's even a reasonable way to sort them all next to each other. Would that be helpful?

We have a lot of "container things". We have databases. We have projects. There's a lot of necessary differentiation that I'm not sure removing any of the APIs is the right call. Mostly feels like some API documentation improvements?

[emesare]

I think my original idea of collecting all usages of these apis would go a long way to figure out what we actually need. I am confident that there are many places in the core that do not have the correct assumptions about what these do.

• If I could also get the API to call to get the file name and the file path (if available) that would be very helpful! For example, the file name we show in the UI tab, where is that derived?
• Do we want virtual path to work with projects? Or is it specific to the transform system, the docs seem to suggest only the transform system should touch that.
• Why does display_name not resolve project file name?

>>> bv.file.display_name
'/Users/emesare/Library/Application Support/Binary Ninja/remote/273ba74ab91715811fb32b986c2cec0816719e3d8707531d98746c2d0abf9e22/23ce5eaa-f532-4a93-80f2-a7d7f0aed040.bnpr/data/d8/3f4069-a3f4-4df7-ab80-1867a85fdf62'
>>> bv.file.filename
'/Users/emesare/Library/Application Support/Binary Ninja/remote/273ba74ab91715811fb32b986c2cec0816719e3d8707531d98746c2d0abf9e22/23ce5eaa-f532-4a93-80f2-a7d7f0aed040.bnpr/data/d8/3f4069-a3f4-4df7-ab80-1867a85fdf62'
>>> bv.file.original_filename
'/Users/emesare/Library/Application Support/Binary Ninja/remote/273ba74ab91715811fb32b986c2cec0816719e3d8707531d98746c2d0abf9e22/23ce5eaa-f532-4a93-80f2-a7d7f0aed040.bnpr/data/bd/5c6582-f6b2-49da-9aec-9d31beb48f16'
>>> bv.file.virtual_path
'/Users/emesare/Library/Application Support/Binary Ninja/remote/273ba74ab91715811fb32b986c2cec0816719e3d8707531d98746c2d0abf9e22/23ce5eaa-f532-4a93-80f2-a7d7f0aed040.bnpr/data/d8/3f4069-a3f4-4df7-ab80-1867a85fdf62'

There is also a question of where this stuff lives, the project stuff resolves the file name within the UI instead of adding another new field in the file metadata or altering an existing one.

[psifertex]

A holistic analysis of the places we use them to re-evaluate them is a solid idea. Especially after so many have been added from the original.

Yeah, Projects aren't really well integrated here either. Those live off in their own API iirc? The UI hacks around this with its own UI-only APIs which is also kinda not great since those should probably be in the core.

[emesare]

It seems strange we return anything at all when virtual path is not set:

>>> bv.file.virtual_path
'/Users/emesare/Downloads/iterators.exe'

i now need to check if its equal to bv.file.filename (i think???) to determine if i have a virtual path or not.

So far it seems that the appropriate solution for determining the file path and the file name is to do:

>>> bv.file.display_name.split('/')[-1]
'SAPfewui.dll.bndb'
>>> bv.file.filename
'/Users/emesare/Downloads/SAPfewui.dll.bndb'

Why is the display name the full path to the binary?

>>> bv.file.display_name
'/Users/emesare/Library/Application Support/Binary Ninja/remote/273ba74ab91715811fb32b986c2cec0816719e3d8707531d98746c2d0abf9e22/24ec9292-6de0-41de-b07f-8df098ce4128.bnpr/data/f3/papi_img4_lzfse.krnl.1.extracted'

[bpotchik]

These APIs are intentionally distinct. They just happen to return identical values for the common case (no bndb, no project, no container.

Quick reference:

• filename - physical path on disk (the bndb path if saved as a database)
• original_filename - the source binary path (differs from filename when working with a bndb...I think)
• virtual_path - provenance chain from the container/transform system (defaults to filename for non-container files)
• display_name - synthesized name for UI display (currently covers containers; project-aware display names are not yet in core. The code I found for project name translation all resides in the UI at the moment.)

Roughly, each of these convey: Storage, Source, Provenance, Presentation, respectively. The docs look like they could make this more clear, but the API surface itself is intentional.

[emesare]

Okay, so to answer the first question this is how I am suppose to get the file name and the file path?

So far it seems that the appropriate solution for determining the file path and the file name is to do:

>>> bv.file.display_name.split('/')[-1]
'SAPfewui.dll.bndb'
>>> bv.file.filename
'/Users/emesare/Downloads/SAPfewui.dll.bndb'

[bpotchik]

For the filesystem name, you just need filename

>>> Path(bv.file.filename).name
'papi'
>>> bv.file.filename
'/Users/brian/Downloads/container_tests/papi'