diff --git a/blog/2019-05-28-first-blog-post.md b/blog/2019-05-28-first-blog-post.md deleted file mode 100644 index d3032ef..0000000 --- a/blog/2019-05-28-first-blog-post.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -slug: first-blog-post -title: First Blog Post -authors: [slorber, yangshun] -tags: [hola, docusaurus] ---- - -Lorem ipsum dolor sit amet... - - - -...consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet diff --git a/blog/2019-05-29-long-blog-post.md b/blog/2019-05-29-long-blog-post.md deleted file mode 100644 index eb4435d..0000000 --- a/blog/2019-05-29-long-blog-post.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -slug: long-blog-post -title: Long Blog Post -authors: yangshun -tags: [hello, docusaurus] ---- - -This is the summary of a very long blog post, - -Use a `` comment to limit blog post size in the list view. - - - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet diff --git a/blog/2021-08-01-mdx-blog-post.mdx b/blog/2021-08-01-mdx-blog-post.mdx deleted file mode 100644 index 0c4b4a4..0000000 --- a/blog/2021-08-01-mdx-blog-post.mdx +++ /dev/null @@ -1,24 +0,0 @@ ---- -slug: mdx-blog-post -title: MDX Blog Post -authors: [slorber] -tags: [docusaurus] ---- - -Blog posts support [Docusaurus Markdown features](https://docusaurus.io/docs/markdown-features), such as [MDX](https://mdxjs.com/). - -:::tip - -Use the power of React to create interactive blog posts. - -::: - -{/* truncate */} - -For example, use JSX to create an interactive button: - -```js - -``` - - diff --git a/blog/2021-08-26-welcome/docusaurus-plushie-banner.jpeg b/blog/2021-08-26-welcome/docusaurus-plushie-banner.jpeg deleted file mode 100644 index 11bda09..0000000 Binary files a/blog/2021-08-26-welcome/docusaurus-plushie-banner.jpeg and /dev/null differ diff --git a/blog/2021-08-26-welcome/index.md b/blog/2021-08-26-welcome/index.md deleted file mode 100644 index 349ea07..0000000 --- a/blog/2021-08-26-welcome/index.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -slug: welcome -title: Welcome -authors: [slorber, yangshun] -tags: [facebook, hello, docusaurus] ---- - -[Docusaurus blogging features](https://docusaurus.io/docs/blog) are powered by the [blog plugin](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-blog). - -Here are a few tips you might find useful. - - - -Simply add Markdown files (or folders) to the `blog` directory. - -Regular blog authors can be added to `authors.yml`. - -The blog post date can be extracted from filenames, such as: - -- `2019-05-30-welcome.md` -- `2019-05-30-welcome/index.md` - -A blog post folder can be convenient to co-locate blog post images: - -![Docusaurus Plushie](./docusaurus-plushie-banner.jpeg) - -The blog supports tags as well! - -**And if you don't want a blog**: just delete this directory, and use `blog: false` in your Docusaurus config. diff --git a/blog/2022-11-13-binsync-lives.md b/blog/2022-11-13-binsync-lives.md new file mode 100644 index 0000000..53785c3 --- /dev/null +++ b/blog/2022-11-13-binsync-lives.md @@ -0,0 +1,8 @@ +--- +slug: binsync-lives +title: "BinSync Lives!" +authors: mahaloz +tags: [hello] +--- + +Today, the BinSync docs and front page are made public! Let's hope we get some awesome features and fixes before 2023. diff --git a/blog/authors.yml b/blog/authors.yml index 8bfa5c7..5065cd0 100644 --- a/blog/authors.yml +++ b/blog/authors.yml @@ -1,23 +1,9 @@ -yangshun: - name: Yangshun Tay - title: Front End Engineer @ Facebook - url: https://github.com/yangshun - image_url: https://github.com/yangshun.png +mahaloz: + name: Zion Basque (mahaloz) + title: Lead Developer + url: https://github.com/mahaloz + image_url: https://github.com/mahaloz.png page: true socials: - x: yangshunz - github: yangshun - -slorber: - name: Sébastien Lorber - title: Docusaurus maintainer - url: https://sebastienlorber.com - image_url: https://github.com/slorber.png - page: - # customize the url of the author page at /blog/authors/ - permalink: '/all-sebastien-lorber-articles' - socials: - x: sebastienlorber - linkedin: sebastienlorber - github: slorber - newsletter: https://thisweekinreact.com + x: mahal0z + github: mahaloz diff --git a/blog/tags.yml b/blog/tags.yml index bfaa778..a986775 100644 --- a/blog/tags.yml +++ b/blog/tags.yml @@ -1,19 +1,4 @@ -facebook: - label: Facebook - permalink: /facebook - description: Facebook tag description - hello: label: Hello permalink: /hello description: Hello tag description - -docusaurus: - label: Docusaurus - permalink: /docusaurus - description: Docusaurus tag description - -hola: - label: Hola - permalink: /hola - description: Hola tag description diff --git a/docs/decompilers/_category_.json b/docs/decompilers/_category_.json new file mode 100644 index 0000000..8984a4e --- /dev/null +++ b/docs/decompilers/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Decompilers", + "position": 4, + "link": { + "type": "generated-index", + "description": "Extra info on supported decompilers in BinSync." + } +} diff --git a/docs/decompilers/angr.md b/docs/decompilers/angr.md new file mode 100644 index 0000000..d327465 --- /dev/null +++ b/docs/decompilers/angr.md @@ -0,0 +1,16 @@ +--- +sidebar_position: 5 +--- + +# angr + +## Support Progress + + +| Operations     | Function Headers     | Stack Vars     | Global Vars     | Structs     | Enums     | Comments     | +|----------- |-------------------- |----------------------- | -------------------- |-------------------- |-------------------- |-------------------- | +| Symbols | :heavy_check_mark: | :heavy_check_mark: | :x: | :x: | :x: | :heavy_check_mark: | +| Types | :heavy_check_mark: | :heavy_check_mark: | :x: | :x: | :x: | :heavy_check_mark: | +| Pull | :heavy_check_mark: | :heavy_check_mark: | :x: | :x: | :x: | :heavy_check_mark: | +| Push | :heavy_check_mark: | :heavy_check_mark: | :x: | :x: | :x: | :heavy_check_mark: | +| Auto Push | :heavy_check_mark: | :heavy_check_mark: | :x: | :x: | :x: | :heavy_check_mark: | diff --git a/docs/decompilers/binja.md b/docs/decompilers/binja.md new file mode 100644 index 0000000..ade8974 --- /dev/null +++ b/docs/decompilers/binja.md @@ -0,0 +1,23 @@ +--- +sidebar_position: 4 +--- + +# Binary Ninja + +## Extra Install Steps +Since Binja may be running a custom Python interpreter, please manually set or verify that your Python +for Binja is set to the same python as `python3` in your terminal. To do that: +1. Open Binja +2. Click `Settings->Python` +3. Select the correct Python interpreter for `Python Interpreter` +4. Restart Binja + +## Support Progress + +| Operations     | Function Headers     | Stack Vars     | Global Vars     | Structs     | Enums     | Comments     | +|------------------------------------|------------------------------------------|------------------------------------|-------------------------------------|---------------------------------|-------------------------------|----------------------------------| +| Symbols | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | +| Types | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | +| Pull | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | +| Push | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | +| Auto Push | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | diff --git a/docs/decompilers/dec-introduction.md b/docs/decompilers/dec-introduction.md new file mode 100644 index 0000000..26898b5 --- /dev/null +++ b/docs/decompilers/dec-introduction.md @@ -0,0 +1,25 @@ +--- +sidebar_position: 1 +--- + +# Introduction + +BinSync supports all the decompilers shown in this section, but not every decompiler is supported to the same level. +In each decompiler section, you will find a table with support progress. The support operations are as follows: + +- **Symbols**: the literal name of the artifact is supported for either pulling or pushing. This would be names for things +like stack vars and function headers + +- **Types**: artifact types, including user created types, are supported for either pulling or pushing. This would be the +C-type associated to the artifact. In stack vars this could be something like `int[32]`. In function headers it's the return type. + +- **Pull**: though a user does not request BinSync to pull, this operation refers to the ability to bring changes into your +decompiler given a BS repo. As an example, pull support allows you to take changes from a BinSync project set by another user, +but you may not be able to push changes. + +- **Push**: though a user does not request BinSync to push, this operation refers to the ability to take changes from your decompiler +and save them to a BS project. As an example, push support allows you to change the name of a function in your decompiler, which would then +save that change into your BinSync project. This push level requires users to request the push. + +- **Auto Push**: this operation is an upgraded option of the _push_ operation. This support means your decompiler can detect when you make +changes to an artifact locally and automatically can stage and push these changes without the user asking to push. \ No newline at end of file diff --git a/docs/decompilers/ghidra.md b/docs/decompilers/ghidra.md new file mode 100644 index 0000000..92f737c --- /dev/null +++ b/docs/decompilers/ghidra.md @@ -0,0 +1,24 @@ +--- +sidebar_position: 3 +--- + +# Ghidra + +## Extra Info +BinSync is written in Python 3, however, Ghidra only has a Python 2 backend. +To deal with this, we use a vendored version of [ghidra_bridge](https://github.com/justfoxing/ghidra_bridge). +We copy a BinSync stub, along with Ghidra Bridge code, into the `ghidra_scripts` folder, which is Python 2. +Inside Ghidra, when you start BinSync, we use the Python 2 side to start the Python 3 GUI in another thread. +We use Ghidra Bridge to make change requests to the Ghidra UI. + +## Support Progress + +| Operations     | Function Headers     | Stack Vars     | Global Vars     | Structs     | Enums     | Comments     | +|------------------------------------|------------------------------------------|------------------------------------|-------------------------------------|---------------------------------|-------------------------------|----------------------------------| +| Symbols | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: | :heavy_check_mark: | +| Types | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: | :heavy_check_mark: | +| Pull | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: | :x: | :heavy_check_mark: | +| Push | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: | :x: | +| Auto Push | :x: | :x: | :x: | :x: | :x: | :x: | + + diff --git a/docs/decompilers/ida.md b/docs/decompilers/ida.md new file mode 100644 index 0000000..e7c95c3 --- /dev/null +++ b/docs/decompilers/ida.md @@ -0,0 +1,17 @@ +--- +sidebar_position: 2 +--- + +# IDA Pro + + +## Support Progress + + +| Operations     | Function Headers     | Stack Vars     | Global Vars     | Structs     | Enums     | Comments     | +|----------- |-------------------- |----------------------- | -------------------- |-------------------- |-------------------- |-------------------- | +| Symbols | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | +| Types | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | +| Pull | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | +| Push | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | +| Auto Push | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | diff --git a/docs/hacking/_category_.json b/docs/hacking/_category_.json new file mode 100644 index 0000000..bb9891b --- /dev/null +++ b/docs/hacking/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Hacking", + "position": 5, + "link": { + "type": "generated-index", + "description": "Learn how to modify and fix BinSync." + } +} diff --git a/docs/hacking/add-decompiler.md b/docs/hacking/add-decompiler.md new file mode 100644 index 0000000..a3e6423 --- /dev/null +++ b/docs/hacking/add-decompiler.md @@ -0,0 +1,7 @@ +--- +sidebar_position: 2 +--- + +# Adding a Decompiler + +Work in progress... diff --git a/docs/hacking/binsync-overview.md b/docs/hacking/binsync-overview.md new file mode 100644 index 0000000..a631dd1 --- /dev/null +++ b/docs/hacking/binsync-overview.md @@ -0,0 +1,81 @@ +--- +sidebar_position: 1 +--- +# Architecture Overview + + +In this section, we go over some of the larger infrastructures of BinSync. If you have not yet read the Usage Guide for BinSync, then you should go read it now to have a high-level understanding of how to even use BinSync and what it offers. + +## Architecture Overview +You can consider that BinSync is split into three pieces: +1. [BinSync Core](https://github.com/angr/binsync/tree/master/binsync), which deals with Git operations, storing user changes, and filesystem operations +2. [BinSync Common](https://github.com/angr/binsync/tree/master/binsync/common), which deals with UI and Core Interfaces reused in most Plugins +3. [BinSync Plugins](https://github.com/angr/binsync/tree/master/plugins), this is where decompiler-specific artifact getting/setting is done. Note: UI is done in BinSync Common + +To make things easy to understand, let's talk about how changes are detected and reflected in the remote BinSync repo. +Each plugin comes with a [Controller](https://github.com/angr/binsync/blob/37aee8b6c891973944d983c7cd138d6e6ff742af/binsync/common/controller.py#L121) class that is a child of the Controller class in BinSync Common. + +The Controller in each plugin is usually running three threads: +1. Updater Thread (daemon): git pull/push every S seconds; updates UI data shown; does jobs +2. UI Thread: contains the Control Panel UI and sends signals back to the updater for a new job +3. Decompiler Main Thread: thread where the actual decompiler UI is running, never want to stall this + +The Decompiler Thread has the special change of detecting when a change to some Artifact happens. It finds _what_ exactly changed (the diff), and then sends a push job to the Updater Thread. As an activity diagram it looks like this: + +![BinSync_Activity_Dia](https://user-images.githubusercontent.com/21327264/172236348-fc321e92-acd7-4694-9313-3c913f2eb24c.png) + +In this activity diagram, it shows off how we pass around signals between threads to get Commands (which are jobs) done. We call them commands because then can either be a push (which is detected in Decompiler Thread) or a sync (which is detected in UI Thread). By doing these jobs in order on the same thread, we guarantee we are not committing, pushing, or pulling at the exact same time. This also promises the UI is up to date with data in the repo. + +## Hacking BinSync Core +The two most important files in the Core are: +1. [client.py](https://github.com/angr/binsync/blob/master/binsync/client.py) +2. [state.py](https://github.com/angr/binsync/blob/master/binsync/state.py) + +In the client, we deal with all the Git and I/O Filesystem operations. We also make sure we are on the right branch per-user when committing and that we are sanely dumping files correctly. + +In state.py, we deal with all the classes found in `data`, which represent each type of Artifact that BinSync can sync (like a Struct or Stack Variable class). Here you will find how we update the high-level data in BinSync. We convert artifacts into a BinSync string like format, then convert those into Tomls. The Toml is then passed to the client which dumps it on the Filesystem. You will also find smaller things here like the ability to mark when a change was made by a user or not. This is documented in the [update_last_change](https://github.com/angr/binsync/blob/37aee8b6c891973944d983c7cd138d6e6ff742af/binsync/state.py#L43) function. + +## Hacking BinSync Common +There is two division in the Common: the UI and the Controller. + +### Common Controller +In the [common controller](https://github.com/angr/binsync/blob/master/binsync/common/controller.py) we implement functions that are commonly used by plugins to perform push and sync operations. As an example, syncing in a stack variable is the same across all decompilers, so its implemented here. Note however that `fill` is different from sync and _must_ be implemented on the plugin level. We also implement the `Updater Thread` mentioned in the beginning in this file. + +### Common UI +The common UI has many parts to it, but for the most part it's all just standard PyQT. To accommodate many decompilers we have to user multiple versions of PyQT (PyQT5, PySide2, PySide6). To do this, at the root of the Common UI folder we implement something called `ui_version` which should always be set before any UI from BinSync is imported. Here is an example: +```py +from . import ui_version +if ui_version == "PySide2": + from PySide2.QtWidgets import QVBoxLayout, QGroupBox, QWidget, QLabel, QTabWidget, QTableWidget, QStatusBar + from PySide2.QtCore import Signal +elif ui_version == "PySide6": + from PySide6.QtWidgets import QVBoxLayout, QGroupBox, QWidget, QLabel, QTabWidget, QTableWidget, QStatusBar + from PySide6.QtCore import Signal +else: + from PyQt5.QtWidgets import QVBoxLayout, QGroupBox, QWidget, QLabel, QTabWidget, QTableWidget, QStatusBar + from PyQt5.QtCore import pyqtSignal as Signal +``` + +Here you can see the `ui_version` is used to find which version to import from. In some cases, we need to change the import names as shown in PyQt5. When you add a new UI dependency import, make sure you update this for each import. + +The `control_panel.py` is where the main Control Panel BinSync shows is implemented. We embed all the tables in the `tables` folder. We also get updates through the `ui_callback` property which is passed across threads. + + +## Hacking BinSync Plugins +We try to reuse code as much as we can from BinSync Common, but at a fundamental level each plugin needs to implement: +1. Setting Artifacts in their UI +2. Getting Artifacts from their DB system +3. Hooking changes as they happen and notifying the Controller + +In the next few sections, we will try to describe the important semantics of each decompiler we support so far. + +## Hacking BinSync IDA +IDA has a very solid way of tracking changes as they happen making it really easy to know when diffs. All of these change detectors are implemented in the [hooks.py](https://github.com/angr/binsync/blob/master/plugins/ida_binsync/ida_binsync/hooks.py) file. We can detect changes on every Artifact type BinSync supports. These are then converted into a job for BinSync and sent to the Worker Thread. + +All the updates to decompiler UI and DB are done in the `fill_*` functions in [controller.py](https://github.com/angr/binsync/blob/master/plugins/ida_binsync/ida_binsync/controller.py) like all the plugins. + +Something important to note is that IDA does not allow you to use their API from another thread, which requires us to start an API call in a wrapper and pass that wrapper to the main IDA thread. To implement this, we put all thread-dependent API for IDA in the [compat.py](https://github.com/angr/binsync/blob/master/plugins/ida_binsync/ida_binsync/compat.py) file (short for compatibility). You will see things like `get_func_addr` and the like in this file. We also get all data and set all data through these functions. + + + + diff --git a/docs/img/manual1.png b/docs/img/manual1.png new file mode 100644 index 0000000..5d64d5c Binary files /dev/null and b/docs/img/manual1.png differ diff --git a/docs/img/manual2.png b/docs/img/manual2.png new file mode 100644 index 0000000..272ee43 Binary files /dev/null and b/docs/img/manual2.png differ diff --git a/docs/img/manual3.png b/docs/img/manual3.png new file mode 100644 index 0000000..6d2f00e Binary files /dev/null and b/docs/img/manual3.png differ diff --git a/docs/img/manual4.png b/docs/img/manual4.png new file mode 100644 index 0000000..d1f9d4b Binary files /dev/null and b/docs/img/manual4.png differ diff --git a/docs/intro.md b/docs/intro.md index 28c52ea..f691764 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -2,46 +2,77 @@ sidebar_position: 1 --- -# BinSync +# Welcome to BinSync -Let's discover **Docusaurus in less than 5 minutes**. -## Getting Started +BinSync is a decompiler collaboration tool built on the Git versioning system to enable fined-grained reverse +engineering collaboration regardless of decompiler. BinSync is built by [mahaloz](https://github.com/mahaloz), +the [angr](https://angr.io) team, and the [SEFCOM](https://sefcom.asu.edu) research lab. It's also due +in large part to its use by the [Shellphish](https://shellphish.net) hacking team. -Get started by **creating a new site**. +All good decompilers share common objects called Reverse Engineering Artifacts (REAs). These REAs are the +center of BinSync's syncing ability. Here are the supported REAs: +- Function headers (symbol, args, type) +- Stack Variables (symbol, type) +- Structs +- Comments -Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new)**. +Note: all types support user-created types like structs. In short, with BinSync you can track, manage, and sync +changes you make in your decompiler with any decompiler supported by BinSync. -### What you'll need +For synchronous help, or a more vocal discussion, join our discord: -- [Node.js](https://nodejs.org/en/download/) version 18.0 or above: - - When installing Node.js, you are recommended to check all checkboxes related to dependencies. +[![Discord](https://img.shields.io/discord/900841083532087347?label=Discord&style=plastic)](https://discord.gg/wZSCeXnEvR) -## Generate a new site +## Supported Platforms +- IDA Pro: **>= 7.3** +- Binary Ninja: **>= 2.4** +- angr-management: **>= 9.0** +- Ghidra: **>= 10.1** -Generate a new Docusaurus site using the **classic template**. +All versions require **Python >= 3.6** and **Git** installed on your system. Ghidra support is still very much in early stage, so only expect the minimal features. -The classic template will automatically be added to your project after you run the command: +## Decompiler Support Progress +Although we support the decompilers in the earlier section, not every decompiler is supported at the same level of syncing. +To understand the difference between artifact support, pull, push, and auto push, read our [decompiler use introduction](https://binsync.net/docs/dec-introduction/). -```bash -npm init docusaurus@latest my-website classic -``` +### IDA Pro -You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor. +| Operations     | Function Headers     | Stack Vars     | Global Vars     | Structs     | Enums     | Comments     | +|----------- |-------------------- |----------------------- | -------------------- |-------------------- |-------------------- |-------------------- | +| Symbols | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | +| Types | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | +| Pull | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | +| Push | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | +| Auto Push | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | -The command also installs all necessary dependencies you need to run Docusaurus. +### Binary Ninja -## Start your site +| Operations     | Function Headers     | Stack Vars     | Global Vars     | Structs     | Enums     | Comments     | +|------------------------------------|------------------------------------------|------------------------------------|-------------------------------------|---------------------------------|-------------------------------|----------------------------------| +| Symbols | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | +| Types | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | +| Pull | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | +| Push | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | +| Auto Push | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | -Run the development server: -```bash -cd my-website -npm run start -``` +### Ghidra -The `cd` command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there. +| Operations     | Function Headers     | Stack Vars     | Global Vars     | Structs     | Enums     | Comments     | +|------------------------------------|------------------------------------------|------------------------------------|-------------------------------------|---------------------------------|-------------------------------|----------------------------------| +| Symbols | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | +| Types | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | +| Pull | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | +| Push | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: | :heavy_check_mark: | +| Auto Push | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: | -The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/. +### angr-management -Open `docs/intro.md` (this page) and edit some lines: the site **reloads automatically** and displays your changes. +| Operations     | Function Headers     | Stack Vars     | Global Vars     | Structs     | Enums     | Comments     | +|----------- |-------------------- |----------------------- | -------------------- |-------------------- |-------------------- |-------------------- | +| Symbols | :heavy_check_mark: | :heavy_check_mark: | :x: | :x: | :x: | :heavy_check_mark: | +| Types | :heavy_check_mark: | :heavy_check_mark: | :x: | :x: | :x: | :heavy_check_mark: | +| Pull | :heavy_check_mark: | :heavy_check_mark: | :x: | :x: | :x: | :heavy_check_mark: | +| Push | :heavy_check_mark: | :heavy_check_mark: | :x: | :x: | :x: | :heavy_check_mark: | +| Auto Push | :heavy_check_mark: | :heavy_check_mark: | :x: | :x: | :x: | :heavy_check_mark: | diff --git a/docs/quickstart/_category_.json b/docs/quickstart/_category_.json new file mode 100644 index 0000000..d25cc72 --- /dev/null +++ b/docs/quickstart/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Quickstart", + "position": 2, + "link": { + "type": "generated-index", + "description": "10 minutes to get BinSync up and running on your decompiler!" + } +} diff --git a/docs/quickstart/creating-project.md b/docs/quickstart/creating-project.md new file mode 100644 index 0000000..7f085ea --- /dev/null +++ b/docs/quickstart/creating-project.md @@ -0,0 +1,26 @@ +--- +sidebar_position: 3 +--- + +# Creating a Project + +Like in the [Joining a Project](/quickstart/joining-project) section, you can create your own repo for a BinSync project. +BinSync will work with any Git URL, but for this tutorial, we will only show you how to do it on GitHub. + +1. Make a GitHub repo; it does not matter if you init it or add a README + + +2. Copy the SSH url from the next page; It would look something like: `git@github.com:mahaloz/my_binsync_project.git` + +3. Open a binary in your decompiler of choice; we will use `fauxware` again from the `example.bsproj` in intall. + +4. Open the BinSync configuration window like in the install tutorial, but select `New`. + +5. Fill in the remote URL, the location (and name) you want it to be cloned to, and the username you will use to first connect. + + +You should now be connected to your new remote repo. The remote on GitHub will also show 2 new branches now: +- your first user +- the `binsync/__root__` repo + +Now all your friends can connect their clients to your repo like in the example above :). diff --git a/docs/quickstart/img/binsync_idaplugin.png b/docs/quickstart/img/binsync_idaplugin.png new file mode 100644 index 0000000..39e6096 Binary files /dev/null and b/docs/quickstart/img/binsync_idaplugin.png differ diff --git a/docs/quickstart/img/demo1.png b/docs/quickstart/img/demo1.png new file mode 100644 index 0000000..7531422 Binary files /dev/null and b/docs/quickstart/img/demo1.png differ diff --git a/docs/quickstart/img/demo2.png b/docs/quickstart/img/demo2.png new file mode 100644 index 0000000..6089ccd Binary files /dev/null and b/docs/quickstart/img/demo2.png differ diff --git a/docs/quickstart/img/demo3.png b/docs/quickstart/img/demo3.png new file mode 100644 index 0000000..d8bf199 Binary files /dev/null and b/docs/quickstart/img/demo3.png differ diff --git a/docs/quickstart/img/demo4.png b/docs/quickstart/img/demo4.png new file mode 100644 index 0000000..9ce171c Binary files /dev/null and b/docs/quickstart/img/demo4.png differ diff --git a/docs/quickstart/img/demo5.png b/docs/quickstart/img/demo5.png new file mode 100644 index 0000000..1b3d4c8 Binary files /dev/null and b/docs/quickstart/img/demo5.png differ diff --git a/docs/quickstart/install.md b/docs/quickstart/install.md new file mode 100644 index 0000000..047fcef --- /dev/null +++ b/docs/quickstart/install.md @@ -0,0 +1,60 @@ +--- +sidebar_position: 1 +--- + +# Installation + +Installing BinSync can be as simple as using pip in combination with our Python-based installer: +```bash +pip3 install binsync && binsync --install +``` + +**If you are using BS with Ghidra**, you must install using `pip3 install binsync[ghidra]` for the extra dependencies. +If you are using Binary Ninja, and you don't plan on developing BinSync, it's recommended to install it through the +Binary Ninja plugin manager, which allows you to skip these install steps. + +Installation is a two-step process because we need to first install the BinSync core library into your Python install, +then we need to copy the plugin code to your respective decompiler. Using the above command is the simplest solution +since it will open an assistant prompt that asks for decompiler paths. It looks something like: +``` +$ binsync --install + + _____ _ _____ +| __ |_|___| __|_ _ ___ ___ +| __ -| | |__ | | | | _| +|_____|_|_|_|_____|_ |_|_|___| + |___| +Now installing BinSync... +Please input decompiler/debugger install paths as prompted. Enter nothing to either use +the default install path if one exist, or to skip. + +IDA Plugins Path: +... +``` + +If you are not able to find the `binsync` command, you might be able to access it with `python3 -m binsync`. +**NOTE: you must pip install binsync to the python interpreter used in your decompiler**. If even that fails, +please jump to the [Manual Install](#manual-install) section. + + +## Manual Install (skip if above worked) +If you were able to use the built-in Python script, skip this. + +If you are unable to install using the earlier method, you are probably on Windows. In that case, installing +BinSync is a two-step process: +1. Install the core with the Python version associated with your decompiler: `pip3 install binsync` +2. Install the plugin stub into your decompilers `plugin` folder. + +For step 2, you copy (or link) the `binsync_plugin.py` file found in the root of pip project into your decompiler. + +## Unlocking your SSH Key +If you plan on using BinSync to pull and push to a BinSync repo, you need a SSH key that is associated with that repo. If you plan +on only reading from the repo, you don't need one. Since BinSync relies on Git for its headless-server and database, you must unlock +your SSH key when BinSync is in use. + +## Install Validation and Usage +After you are done installing BinSync with the steps above, it is reccommended that you validate the install works by syncing data from our example binsync project. +You can find a tutorial to validate this install, with some basic usage, in the [Joining a BinSync project](./joining-project) section. + +After validating your installation, it's **highly** recommended that you read the [Usage Guide](/docs/fundamentals), since BinSync can be rather complicated to +use on your very first look at it. diff --git a/docs/quickstart/joining-project.md b/docs/quickstart/joining-project.md new file mode 100644 index 0000000..5983a9b --- /dev/null +++ b/docs/quickstart/joining-project.md @@ -0,0 +1,100 @@ +--- +sidebar_position: 2 +--- + +# Joining a Project + +Although every decompiler has a slightly different implementation for BinSync, the instructions below should work almost the same for all decompilers. +This is because we use a unified GUI made to work in a variety of QT versions. + +In this tutorial, you will validate your BinSync install can: +1. Use Git to connect to a BinSync project +2. Read data from the remote BinSync project +3. Set the read data into your decompiler. + +For this tutorial, we will use the example binsync repo that is a part of the BinSync project. + +### Sync Validation +1. Clone down the example BinSync project +```bash +git clone https://github.com/binsync/example.bsproj.git +``` + +2. Copy the `fauxware` binary out of the `data` branch for testing +``` +(cd example.bsproj && git checkout data && cp fauxware ../) +``` + +3. Open the fauxware binary in your decompiler, verify it has loaded in the decompiler terminal +``` +[BinSync] X.X.X loaded +``` +Or check your plugin menu. For example, if you are using IDA, you should see this option: + + + +If neither show, it means the plugin is not in the plugins folder. + +4. Open the BinSync Config Pane and click the `Open` button + 1. You can hit `Ctrl+Shift+B` or `Ctrl+Alt+Shift+B` to open it, OR + 2. You can click your decompiler menu: `Edit -> Plugins -> Binsync: Configure...`. On Binja it's under `Plugins`. On Ghidra under `Tools` + +5. Enter a username and set the project path to the location of `example.bsproj` + + +If you are running these instructions on a computer without internet, you may want to open the project settings group and select `Disable auto-push to remote`. + +6. Verify your terminal says (with your username): +```bash +[BinSync]: Client has connected to sync repo with user: . +``` + +If you are on angr-management or Ghidra this may be hidden. Instead, you should see a panel open with your username in green or yellow (indicating a valid setup to the project). + +7. You should now see an Info Panel. Click on `Activity`, you can see other user's activities. You should also notice + your username on the bottom right of the panel to be green (online). + + +Congrats, your BinSync seems to connect to a repo, and recognize you as a user. +Let's test pulling to verify you can actually do stuff with your install. + +8. In your decompiler, click anywhere in the function `main` once. After a second or two you should notice on the + Info Panel that the words on the bottom left say `main@0x40071d`. This is your context. + +9. Now click on the `Context` tab, and right click on the user `mahaloz`. Click the `Sync` popup. + + +10. If everything works out, your decompilation should've changed for `main`. Now the function should be named + `mahaloz_main`, and it should look something like: + +```c +// *** +// This is a large comment in the header of +// the function! Thanks for using BinSync +// +// - <3 mahaloz +// *** +char __cdecl mahaloz_main(int my_arg1, const char **my_arg2, int **my_arg3) +{ + int v4; // [rsp+1Ch] [rbp-24h] BYREF + mahaloz_struct special_var; // [rsp+20h] [rbp-20h] BYREF + char buf[16]; // [rsp+30h] [rbp-10h] BYREF + + buf[8] = 0; + LOBYTE(special_var.s3) = 0; + puts("Username: "); + read(0, buf, 8uLL); // the username is likley read here + read(0, &v4, 1uLL); + puts("Password: "); + read(0, &special_var, 8uLL); + read(0, &v4, 1uLL); + v4 = authenticate(buf, &special_var); + if ( !v4 ) + rejected(buf); + return sub_4006ED(buf); +} +``` + +Take note of the variable names & types, and the comments. This will look different per decompiler, but the symbols and types should line up for the most part. + +For more general use, tips, and advice, see our [Use Guide](../ui-guide). diff --git a/docs/tutorial-basics/_category_.json b/docs/tutorial-basics/_category_.json deleted file mode 100644 index 2e6db55..0000000 --- a/docs/tutorial-basics/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Tutorial - Basics", - "position": 2, - "link": { - "type": "generated-index", - "description": "5 minutes to learn the most important Docusaurus concepts." - } -} diff --git a/docs/tutorial-basics/congratulations.md b/docs/tutorial-basics/congratulations.md deleted file mode 100644 index 04771a0..0000000 --- a/docs/tutorial-basics/congratulations.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -sidebar_position: 6 ---- - -# Congratulations! - -You have just learned the **basics of Docusaurus** and made some changes to the **initial template**. - -Docusaurus has **much more to offer**! - -Have **5 more minutes**? Take a look at **[versioning](../tutorial-extras/manage-docs-versions.md)** and **[i18n](../tutorial-extras/translate-your-site.md)**. - -Anything **unclear** or **buggy** in this tutorial? [Please report it!](https://github.com/facebook/docusaurus/discussions/4610) - -## What's next? - -- Read the [official documentation](https://docusaurus.io/) -- Modify your site configuration with [`docusaurus.config.js`](https://docusaurus.io/docs/api/docusaurus-config) -- Add navbar and footer items with [`themeConfig`](https://docusaurus.io/docs/api/themes/configuration) -- Add a custom [Design and Layout](https://docusaurus.io/docs/styling-layout) -- Add a [search bar](https://docusaurus.io/docs/search) -- Find inspirations in the [Docusaurus showcase](https://docusaurus.io/showcase) -- Get involved in the [Docusaurus Community](https://docusaurus.io/community/support) diff --git a/docs/tutorial-basics/create-a-blog-post.md b/docs/tutorial-basics/create-a-blog-post.md deleted file mode 100644 index 550ae17..0000000 --- a/docs/tutorial-basics/create-a-blog-post.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -sidebar_position: 3 ---- - -# Create a Blog Post - -Docusaurus creates a **page for each blog post**, but also a **blog index page**, a **tag system**, an **RSS** feed... - -## Create your first Post - -Create a file at `blog/2021-02-28-greetings.md`: - -```md title="blog/2021-02-28-greetings.md" ---- -slug: greetings -title: Greetings! -authors: - - name: Joel Marcey - title: Co-creator of Docusaurus 1 - url: https://github.com/JoelMarcey - image_url: https://github.com/JoelMarcey.png - - name: Sébastien Lorber - title: Docusaurus maintainer - url: https://sebastienlorber.com - image_url: https://github.com/slorber.png -tags: [greetings] ---- - -Congratulations, you have made your first post! - -Feel free to play around and edit this post as much as you like. -``` - -A new blog post is now available at [http://localhost:3000/blog/greetings](http://localhost:3000/blog/greetings). diff --git a/docs/tutorial-basics/create-a-document.md b/docs/tutorial-basics/create-a-document.md deleted file mode 100644 index c22fe29..0000000 --- a/docs/tutorial-basics/create-a-document.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -sidebar_position: 2 ---- - -# Create a Document - -Documents are **groups of pages** connected through: - -- a **sidebar** -- **previous/next navigation** -- **versioning** - -## Create your first Doc - -Create a Markdown file at `docs/hello.md`: - -```md title="docs/hello.md" -# Hello - -This is my **first Docusaurus document**! -``` - -A new document is now available at [http://localhost:3000/docs/hello](http://localhost:3000/docs/hello). - -## Configure the Sidebar - -Docusaurus automatically **creates a sidebar** from the `docs` folder. - -Add metadata to customize the sidebar label and position: - -```md title="docs/hello.md" {1-4} ---- -sidebar_label: 'Hi!' -sidebar_position: 3 ---- - -# Hello - -This is my **first Docusaurus document**! -``` - -It is also possible to create your sidebar explicitly in `sidebars.js`: - -```js title="sidebars.js" -export default { - tutorialSidebar: [ - 'intro', - // highlight-next-line - 'hello', - { - type: 'category', - label: 'Tutorial', - items: ['tutorial-basics/create-a-document'], - }, - ], -}; -``` diff --git a/docs/tutorial-basics/create-a-page.md b/docs/tutorial-basics/create-a-page.md deleted file mode 100644 index 20e2ac3..0000000 --- a/docs/tutorial-basics/create-a-page.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -sidebar_position: 1 ---- - -# Create a Page - -Add **Markdown or React** files to `src/pages` to create a **standalone page**: - -- `src/pages/index.js` → `localhost:3000/` -- `src/pages/foo.md` → `localhost:3000/foo` -- `src/pages/foo/bar.js` → `localhost:3000/foo/bar` - -## Create your first React Page - -Create a file at `src/pages/my-react-page.js`: - -```jsx title="src/pages/my-react-page.js" -import React from 'react'; -import Layout from '@theme/Layout'; - -export default function MyReactPage() { - return ( - -

My React page

-

This is a React page

- - ); -} -``` - -A new page is now available at [http://localhost:3000/my-react-page](http://localhost:3000/my-react-page). - -## Create your first Markdown Page - -Create a file at `src/pages/my-markdown-page.md`: - -```mdx title="src/pages/my-markdown-page.md" -# My Markdown page - -This is a Markdown page -``` - -A new page is now available at [http://localhost:3000/my-markdown-page](http://localhost:3000/my-markdown-page). diff --git a/docs/tutorial-basics/deploy-your-site.md b/docs/tutorial-basics/deploy-your-site.md deleted file mode 100644 index 1c50ee0..0000000 --- a/docs/tutorial-basics/deploy-your-site.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -sidebar_position: 5 ---- - -# Deploy your site - -Docusaurus is a **static-site-generator** (also called **[Jamstack](https://jamstack.org/)**). - -It builds your site as simple **static HTML, JavaScript and CSS files**. - -## Build your site - -Build your site **for production**: - -```bash -npm run build -``` - -The static files are generated in the `build` folder. - -## Deploy your site - -Test your production build locally: - -```bash -npm run serve -``` - -The `build` folder is now served at [http://localhost:3000/](http://localhost:3000/). - -You can now deploy the `build` folder **almost anywhere** easily, **for free** or very small cost (read the **[Deployment Guide](https://docusaurus.io/docs/deployment)**). diff --git a/docs/tutorial-basics/markdown-features.mdx b/docs/tutorial-basics/markdown-features.mdx deleted file mode 100644 index 35e0082..0000000 --- a/docs/tutorial-basics/markdown-features.mdx +++ /dev/null @@ -1,152 +0,0 @@ ---- -sidebar_position: 4 ---- - -# Markdown Features - -Docusaurus supports **[Markdown](https://daringfireball.net/projects/markdown/syntax)** and a few **additional features**. - -## Front Matter - -Markdown documents have metadata at the top called [Front Matter](https://jekyllrb.com/docs/front-matter/): - -```text title="my-doc.md" -// highlight-start ---- -id: my-doc-id -title: My document title -description: My document description -slug: /my-custom-url ---- -// highlight-end - -## Markdown heading - -Markdown text with [links](./hello.md) -``` - -## Links - -Regular Markdown links are supported, using url paths or relative file paths. - -```md -Let's see how to [Create a page](/create-a-page). -``` - -```md -Let's see how to [Create a page](./create-a-page.md). -``` - -**Result:** Let's see how to [Create a page](./create-a-page.md). - -## Images - -Regular Markdown images are supported. - -You can use absolute paths to reference images in the static directory (`static/img/docusaurus.png`): - -```md -![Docusaurus logo](/img/docusaurus.png) -``` - -![Docusaurus logo](/img/docusaurus.png) - -You can reference images relative to the current file as well. This is particularly useful to colocate images close to the Markdown files using them: - -```md -![Docusaurus logo](./img/docusaurus.png) -``` - -## Code Blocks - -Markdown code blocks are supported with Syntax highlighting. - -````md -```jsx title="src/components/HelloDocusaurus.js" -function HelloDocusaurus() { - return

Hello, Docusaurus!

; -} -``` -```` - -```jsx title="src/components/HelloDocusaurus.js" -function HelloDocusaurus() { - return

Hello, Docusaurus!

; -} -``` - -## Admonitions - -Docusaurus has a special syntax to create admonitions and callouts: - -```md -:::tip My tip - -Use this awesome feature option - -::: - -:::danger Take care - -This action is dangerous - -::: -``` - -:::tip My tip - -Use this awesome feature option - -::: - -:::danger Take care - -This action is dangerous - -::: - -## MDX and React Components - -[MDX](https://mdxjs.com/) can make your documentation more **interactive** and allows using any **React components inside Markdown**: - -```jsx -export const Highlight = ({children, color}) => ( - { - alert(`You clicked the color ${color} with label ${children}`) - }}> - {children} - -); - -This is Docusaurus green ! - -This is Facebook blue ! -``` - -export const Highlight = ({children, color}) => ( - { - alert(`You clicked the color ${color} with label ${children}`); - }}> - {children} - -); - -This is Docusaurus green ! - -This is Facebook blue ! diff --git a/docs/tutorial-extras/_category_.json b/docs/tutorial-extras/_category_.json deleted file mode 100644 index a8ffcc1..0000000 --- a/docs/tutorial-extras/_category_.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "label": "Tutorial - Extras", - "position": 3, - "link": { - "type": "generated-index" - } -} diff --git a/docs/tutorial-extras/img/docsVersionDropdown.png b/docs/tutorial-extras/img/docsVersionDropdown.png deleted file mode 100644 index 97e4164..0000000 Binary files a/docs/tutorial-extras/img/docsVersionDropdown.png and /dev/null differ diff --git a/docs/tutorial-extras/img/localeDropdown.png b/docs/tutorial-extras/img/localeDropdown.png deleted file mode 100644 index e257edc..0000000 Binary files a/docs/tutorial-extras/img/localeDropdown.png and /dev/null differ diff --git a/docs/tutorial-extras/manage-docs-versions.md b/docs/tutorial-extras/manage-docs-versions.md deleted file mode 100644 index ccda0b9..0000000 --- a/docs/tutorial-extras/manage-docs-versions.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -sidebar_position: 1 ---- - -# Manage Docs Versions - -Docusaurus can manage multiple versions of your docs. - -## Create a docs version - -Release a version 1.0 of your project: - -```bash -npm run docusaurus docs:version 1.0 -``` - -The `docs` folder is copied into `versioned_docs/version-1.0` and `versions.json` is created. - -Your docs now have 2 versions: - -- `1.0` at `http://localhost:3000/docs/` for the version 1.0 docs -- `current` at `http://localhost:3000/docs/next/` for the **upcoming, unreleased docs** - -## Add a Version Dropdown - -To navigate seamlessly across versions, add a version dropdown. - -Modify the `docusaurus.config.js` file: - -```js title="docusaurus.config.js" -export default { - themeConfig: { - navbar: { - items: [ - // highlight-start - { - type: 'docsVersionDropdown', - }, - // highlight-end - ], - }, - }, -}; -``` - -The docs version dropdown appears in your navbar: - -![Docs Version Dropdown](./img/docsVersionDropdown.png) - -## Update an existing version - -It is possible to edit versioned docs in their respective folder: - -- `versioned_docs/version-1.0/hello.md` updates `http://localhost:3000/docs/hello` -- `docs/hello.md` updates `http://localhost:3000/docs/next/hello` diff --git a/docs/tutorial-extras/translate-your-site.md b/docs/tutorial-extras/translate-your-site.md deleted file mode 100644 index b5a644a..0000000 --- a/docs/tutorial-extras/translate-your-site.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -sidebar_position: 2 ---- - -# Translate your site - -Let's translate `docs/intro.md` to French. - -## Configure i18n - -Modify `docusaurus.config.js` to add support for the `fr` locale: - -```js title="docusaurus.config.js" -export default { - i18n: { - defaultLocale: 'en', - locales: ['en', 'fr'], - }, -}; -``` - -## Translate a doc - -Copy the `docs/intro.md` file to the `i18n/fr` folder: - -```bash -mkdir -p i18n/fr/docusaurus-plugin-content-docs/current/ - -cp docs/intro.md i18n/fr/docusaurus-plugin-content-docs/current/intro.md -``` - -Translate `i18n/fr/docusaurus-plugin-content-docs/current/intro.md` in French. - -## Start your localized site - -Start your site on the French locale: - -```bash -npm run start -- --locale fr -``` - -Your localized site is accessible at [http://localhost:3000/fr/](http://localhost:3000/fr/) and the `Getting Started` page is translated. - -:::caution - -In development, you can only use one locale at a time. - -::: - -## Add a Locale Dropdown - -To navigate seamlessly across languages, add a locale dropdown. - -Modify the `docusaurus.config.js` file: - -```js title="docusaurus.config.js" -export default { - themeConfig: { - navbar: { - items: [ - // highlight-start - { - type: 'localeDropdown', - }, - // highlight-end - ], - }, - }, -}; -``` - -The locale dropdown now appears in your navbar: - -![Locale Dropdown](./img/localeDropdown.png) - -## Build your localized site - -Build your site for a specific locale: - -```bash -npm run build -- --locale fr -``` - -Or build your site to include all the locales at once: - -```bash -npm run build -``` diff --git a/docs/ui-guide.md b/docs/ui-guide.md new file mode 100644 index 0000000..1b62dee --- /dev/null +++ b/docs/ui-guide.md @@ -0,0 +1,99 @@ +--- +sidebar_position: 3 +--- + +# UI Guide + +It's a good idea to start here before going to any other use-page so you understand all the features BinSync has to offer and how to access them. + +## The Core Basics +BinSync works on Git, which means that everything is version-controlled, and nothing is automatically changed in your local client. If you followed the [Install Validation](/docs/install-validation) page, then you should already understand that you request specific users content. + +### Syncing: No Pulling, No Pushing +You may be thinking that when you click `Sync`, it's like you are pulling, but that is not really the case. Under the hood we have a thread going that is doing real `pulling` and `pushing` on the Git level to update your Git's knowledge of users. This makes more sense if you look at how users are stored in the BinSync database. + +Taking a look at the example repo, [mahaloz/binsync_example_repo](https://github.com/mahaloz/binsync_example_repo/), you will notice every user is actually a branch based on the initial `binsync/__root__` which has no changes: + +```bash +$ git branch + + binsync/__root__ + binsync/fish + binsync/frqmod + binsync/mahaloz + binsync/redgate + binsync/test_user + main +``` + +When you connect on your own user, we push and pull in another thread at any given time since you are your own branch. Syncing is a higher level action that actually just copies over data from a branch already present on your computer. + +### No Pushing +BinSync is smart enough to not ask you to push specific functions. BinSync will auto push changes you make to your local artifacts into your branch and up to the Git repo. This also means that only changes that happen while BinSync is on will make it into the repo. Let me repeat that: **only BinSync observed changes are saved**. In the future we will support force pushing for joining a project late with an already reversed binary. + +## Understanding the GUI +The `Info Panel` is the singular place where you will get information about the BinSync database and the actions you can perform on your local database. + +On the bottom of the `Info Panel`, there is text on the right and left. +![](./img/manual1.png) + +The text on the left is your current Context, which we will explain in the [Context](#context) Tab section. + +The text on the right is the user you are connected as and the connection status, depicted with three colors: +- Green: Connected to BinSync repo and Online +- Yellow: Connected to BinSync repo, not online (local only) +- Red: Not connected to a BinSync repo + +Yellow can occur when you create a local repo and don't connect a remote url to that repo. + +There are four tabs which separate the type of info you can get from BinSync: `Context`, `Functions`, `Globals`, `Activity`. Each tab has a table which you can right-click to do actions. + +### Context +The Context tab is likely to be the tab you use the most. The Context tab is always associated with a context, which is the current function you are looking at. In the above image, I was looking at `mahaloz_main`. The context changes any time you click on a function. + +The table shows users who have made a change to the function you are currently looking at. Right-clicking on a user gives you the ability to `Sync` from them. Note: users who only `Sync` that same function from others will not be shown on the table. + +### Functions +The Functions tab is likely the tab you will look at first when you open a new BinSync project that others have worked on. The table shows you _all_ the functions in the Binary that have been modified by at least one person. You can look at this to see what the group has started reversing. + +![](./img/manual2.png) + +Right-clicking on row give you the ability to do two thins: +1. Sync from the currently displayed user (the last person to change it) for that specific function +2. Sync from some other user that has changed that same function at some time before the currently displayed user. + +### Globals +The Globals tab shows things that can't be associated to a function. This includes Structs, Global Variables, Enums. + +![](./img/manual3.png) + +Similarly to the Functions tab, you can sync either from the displayed person or some other person that has made a change in the past. + +### Activity +The Activity tab shows you people who are assumed to be actively reversing the Binary right now. This will show you a table of any user that has made a change in the last 2 hours to something in their binary. + +![](./img/manual4.png) + +Like all other tabs, you can sync either from the displayed person and artifact or from some other person. + +--- + +Now that you know how things work, you can checkout our example workflows. + +## Known Issues +### My BinSync is not auto-pushing things, wtf? +This happens when you don't have an ssh key associated with the repo you are trying to edit, or that key is not password unlocked. Make sure the key you are using is not locked or BinSync wont be able to use it. + +If you don't + +### Git Error +If you ever get a Git Error, you may get a stack trace ending in: +```python +# [truncated] + self.tree = Tree(self.repo, hex_to_bin(readline().split()[1]), Tree.tree_id << 12, '') +binascii.Error: Non-hexadecimal digit found +``` + +This means BinSync crashed while trying to commit something. Many things could have gone wrong here. Often the easiest way to fix this is just restarting your decompiler (so you can reload BinSync). + +If possible, copy the **full** stack trace with the error that likely came right before this error (which caused it), and file an [Issue](https://github.com/angr/binsync/issues).