Add Binary Similarity Documentation - #8382
Conversation
psifertex
left a comment
psifertex
left a comment
There was a problem hiding this comment.
Most of these should be quick changes. Only bigger issue is putting together an image with numbered overlays like other UI elements so that it's more clear which things you're talking about in which sections, it's easy to get lost in the text descriptions. @ashvika-creator can probably help with that if you'd like, she's got the screenshot setup at hand if you want to let her know the numbers/orders.
| Additional providers may be supplied by plugins. You can use more than one provider in the same session and compare | ||
| their results together. | ||
|
|
||
|  |
There was a problem hiding this comment.
I wonder if just showing the sidebar itself and not the linear view above would be better, I'm not sure there's context above that matters? Easy enough to crop without re-taking the screenshot.
|
|
||
| 1. **Choose Binaries** selects a reference binary and a target binary. Each can be an open Binary Ninja view or a file | ||
| selected with **Browse files...**. Quick Setup creates the edge `reference -> target`. | ||
| 2. **Select Matching Components** lists providers and optional resolvers in a table. Select at least one provider. |
There was a problem hiding this comment.
Could use a screenshot here too. Doesn't have to hold up acceptance though.
| - **Similarity** describes how closely the functions match. | ||
| - **Confidence** describes how strongly the provider supports that match. | ||
|
|
||
| The **Metric Similarity Resolver** combines available provider results, ignores results below its configured thresholds, |
There was a problem hiding this comment.
What is the metric similarity resolver? A menu? A button? A tab? Like I get that it's. "resolver" as mentioned above, but I feel like some context is missing here as to where I find it / use it.
|
|
||
| Restricting a session to the functions you care about can substantially reduce processing time for large binaries. | ||
|
|
||
|  |
There was a problem hiding this comment.
|
|
||
| ### Configuring Matching | ||
|
|
||
| Select **Session Configuration** on the session rail to open the configuration dialog. Providers and resolvers are |
There was a problem hiding this comment.
"session rail"? This definitely could use a screenshot to clarify (or, if following the suggestion above to number the visual elements, just refer back to the top image with a number)
|
|
||
| ## Multiple Sessions | ||
|
|
||
| Use the **New Similarity Session** command to create another independent session. When more than one session exists, a |
There was a problem hiding this comment.
command-palette command? Is there no other UI or menu for it? Stylistically I believe we escape commands as code instead of with emphasis.
|
|
||
| ## Troubleshooting | ||
|
|
||
| Common troubleshooting scenarios, if you run into something you think we should add here let us know on our [Slack][Slack]. |
There was a problem hiding this comment.
easier to link to https://dev-docs.binary.ninja/guide/index.html?h=contact#support even though it's one layer of indirection so we have less things to update if we want to change things around (plus it points out the other support mechanisms)
| when you want to find functions that remain structurally related after recompilation or source changes. Using both | ||
| providers can give a resolver exact evidence where available and broader candidates everywhere else. | ||
|
|
||
| ## Glossary |
There was a problem hiding this comment.
I'm not sure about the glossary. If it's just to keyword stuff to make it easier to find the docs that might make sense, but I don't know if the definitions below are as useful as just using the phrases in the appropriate context where they are described above. Related: I was thinking about removing them from the other places we use them. Typically, a global glossary that links back to individual pages might make sense but I'm not sure about separate ones spread throughout.
No action item here, I'm just brainstorming out loud, we can discuss it more broadly later.
|
|
||
| [WARP]: warp.md | ||
| [Python API]: https://api.binary.ninja/binaryninja.similarity-module.html | ||
| [Binary Ninja API repository]: https://github.com/Vector35/binaryninja-api/blob/dev/python/examples/bindiff.py |
There was a problem hiding this comment.
is this from something that used to be linked and isn't anymore? I don't see a reference above currently. Also, which commit is the file itself in?
| @@ -0,0 +1,342 @@ | |||
| # Binary Similarity | |||
There was a problem hiding this comment.
General feedback on the docs:
- should have a view that explains the functions of the sidebar buttons (something like https://dev-docs.binary.ninja/guide/index.html#edit-function-properties-dialog that is, the image itself)
- are the images compressed with ect? some good (big) screenshots so if not probably some file savings
|
Weird -- my first review comment got eaten somehow? Specifically suggested a better overview image with numbered elements (alluded to in the first comment above). It also mentioned using ect on all the PNGs as from the size I think they might not have been compressed yet? |
fuzyll
left a comment
fuzyll
left a comment
There was a problem hiding this comment.
At least half of these images will need replaced once you tell me what icons you need and we get them properly placed into the product.
This doesn't necessarily need to block having any documentation in the product, but we also shouldn't lose this as a release task.
3 participants
This change introduces another page in the user guide aimed at explaining and going over the features of the binary similarity system. Might still need to change / update the photos depending on how the rest goes.