Skip to content

Commit 7103786

Browse files
psifertexpsifertex
committed
add workflows documentation to developer docs
1 parent 46e7f1b commit 7103786

File tree

2 files changed

+173
-0
lines changed

2 files changed

+173
-0
lines changed

‎docs/dev/workflows.md

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
Binary Ninja Workflows Documentation
2+
===
3+
4+
---
5+
# Early Feature Preview
6+
7+
This capability is experimental with no guarantees of API stability or future compatibility. Binary Ninja Workflows is actively under development as a functional prototype. Feedback and questions are welcome!
8+
9+
10+
---
11+
# Contents
12+
---
13+
14+
- [What is Workflows](#what-is-workflows)
15+
- [Getting Started](#getting-started)
16+
- [Availability](#availability)
17+
- [Enable](#enable)
18+
- [Explore](#explore)
19+
- [Examples](#examples)
20+
- [Basic Concepts](#basic-concepts)
21+
- [Activity](#activity)
22+
- [Workflow](#workflow)
23+
- [Analysis Context](#analysis-context)
24+
- [Execution Model](#execution-model)
25+
- [Activity Description](#activity-description)
26+
- [Workflow Description](#workflow-description)
27+
- [Consistency Requirements](#consistency-requirements)
28+
- [Strategies](#strategies)
29+
- [Core Analysis Descriptions](#core-analysis-descriptions)
30+
- [Extended Analysis Descriptions](#extended-analysis-descriptions)
31+
32+
---
33+
# What Is Workflows
34+
---
35+
36+
Binary Ninja Workflows is an analysis orchestration framework which simplifies the definition and execution of a computational binary analysis pipeline. The extensible pipeline accelerates program analysis and reverse engineering of binary blobs at various levels of abstraction. Workflows supports hybridized execution models, where the ordering of activities in the pipeline can be well-known and procedural, or dynamic and reactive. Currently, the core Binary Ninja analysis is made available as a procedural model and is the aggregate of both module and function-level analyses.
37+
38+
---
39+
# Getting Started
40+
---
41+
42+
## Availability
43+
44+
Binary Ninja Workflows is currently available as an early feature preview in Commercial development builds only with a version >= `2.4.2946-dev`.
45+
46+
## Enable
47+
48+
By default, Binary Ninja Workflows is disabled. Enable the feature via *Settings* in the UI, or with the following:
49+
50+
```
51+
Settings().set_bool('workflows.enable', True)
52+
```
53+
54+
## Explore
55+
56+
The procedural core analysis model resembles a behavior tree and the activities execute as a depth-first pre-order traversal of the tree. In order to represent complex data flows, there is fine-grained control for conditional execution and subtree parallelism. It's possible to visualize the pipeline topology in the UI with `show_topology`, as shown below. There are two visual representations for the pipeline topology, a *Composite View* and a *Sequential View*.
57+
58+
```
59+
Workflow().show_topology()
60+
```
61+
62+
It's possible to create multiple workflows to satisfy the need for tailored analysis across a diverse set of binaries and goals. List available workflows as shown below.
63+
64+
```
65+
>>> list(Workflow)
66+
[<Workflow: CustomTailCallWorkflow>, <Workflow: ObjectiveCWorkflow>, <Workflow: InlinerWorkflow>, <Workflow: core.function.defaultAnalysis>, <Workflow: core.module.defaultAnalysis>]
67+
```
68+
69+
## Examples
70+
71+
---
72+
### Python
73+
74+
```
75+
pwf = Workflow().clone("PythonLogWarnWorkflow")
76+
pwf.show_topology()
77+
pwf.register_activity(Activity("PythonLogWarn", action=lambda analysis_context: binaryninja.log.log_warn("PythonLogWarn Called!")))
78+
pwf.insert("core.function.basicBlockAnalysis", ["PythonLogWarn"])
79+
pwf.register()
80+
```
81+
82+
Then open a file with options and select *PythonLogWarnWorkflow* for the *Function Workflow* setting.
83+
84+
---
85+
### C++
86+
87+
Several C++ examples are available in [binaryninja-api/examples/workflows](https://github.com/Vector35/binaryninja-api/tree/dev/examples). These examples are distributed with Binary Ninja and available via the *Function Workflow* setting. Steps for building the examples can be found [here](https://github.com/Vector35/binaryninja-api#building).
88+
89+
- Custom Tail Call Analysis
90+
- Call-Site Function Inliner
91+
- Objective C Workflow
92+
93+
---
94+
# Basic Concepts
95+
---
96+
97+
## Activity
98+
99+
An Activity is the basic building block of the Workflows framework and it is also the extensibility mechanism which allows attachment of an arbitrary callback routine. The degree of coupling between activities is discretionary. This means that an activity can be part of a tightly coupled dataflow transform, or an activity can be completely disassociated with other activities in the pipeline. Binary Ninja provides numerous core activities which together provide the program analysis results and IL transformation system. Activities are dynamically parameterized with an analysis context which enables it to produce or consume information in a coordinated fashion.
100+
101+
## Workflow
102+
103+
A Workflow is a repository of activities along with a unique strategy to execute them. Workflows are also composable, meaning workflows can include other workflows. It's possible to control various aspects of the execution strategy such as course-grained debugging as well as conditional, and parallel execution. Binary Ninja provides a default workflow which contains all of the core module and function analyses.
104+
105+
### Workflow Lifecycle
106+
107+
A Workflow starts in the unregistered state from either creating a new empty Workflow, or cloning an existing Workflow. While unregistered it's possible to add and remove activities, as well as change the execution strategy. In order to use the Workflow on a binary it must be registered. Once registered the Workflow is immutable and available for use.
108+
109+
## Analysis Context
110+
111+
The Analysis Context provides access to the current analysis hierarchy along with APIs to query and inform new analysis information.
112+
113+
---
114+
# Execution Model
115+
---
116+
117+
## State Graph
118+
119+
## Pipeline
120+
121+
## Task Queue
122+
123+
## Concurrency
124+
125+
## Activity Description
126+
127+
### Metadata
128+
129+
### Properties
130+
131+
### Constructs
132+
133+
- Simple
134+
- Selector
135+
- Iterator
136+
- Concurrent
137+
138+
## Workflow Description
139+
140+
### Metadata
141+
142+
### Properties
143+
144+
---
145+
# Consistency Requirements
146+
---
147+
148+
---
149+
# Strategies
150+
---
151+
152+
## Working with Basic Blocks
153+
154+
## Working with IL Forms
155+
156+
### Low-Level IL
157+
158+
### Medium-Level IL
159+
160+
### High-Level IL
161+
162+
### Single-Static Assignment (SSA)
163+
164+
## Rewriting IL
165+
166+
---
167+
# Core Analysis Descriptions
168+
---
169+
170+
---
171+
# Extended Analysis Descriptions
172+
---

‎mkdocs.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,7 @@ nav:
4646
- BNIL Guide&#58; LLIL: 'dev/bnil-llil.md'
4747
- BNIL Guide&#58; MLIL: 'dev/bnil-mlil.md'
4848
- Flag Guide: 'dev/flags.md'
49+
- Working with Workflows: 'dev/workflows.md'
4950
- Creating Themes: 'dev/themes.md'
5051
- Contributing Documentation: 'dev/documentation.md'
5152
- About:

0 commit comments

Comments
 (0)