You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
2. Copy `config.template.py` into a file called `config.py`, and replace the upload path and source code directory path in `config.py` with the appropriate relative paths on your machine.
3. Replace the upload path and source code directory path in `config.py` with the appropriate relative paths on your machine.
41
+
42
+
### IACA
43
+
44
+
There is optional IACA integration. To use it, you must first download IACA from [Intel's website](https://software.intel.com/en-us/articles/intel-architecture-code-analyzer-download) and update variables in your config.py accordingly.
45
+
46
+
### Gunicorn
47
+
48
+
[Gunicorn](http://gunicorn.org/) is a fast and robust server, and requires little setup. It's also far more reliable; there are known issues with using Werkzeug (the default Flask server) that cause that server to crash if you send too many requests in a short amount of time.
49
+
50
+
Run `pip install gunicorn` to install it.
51
+
52
+
### PyPy
53
+
54
+
[PyPy](http://pypy.org/) is an alternative implementation of python that provides a considerable speedup. To use it, there is a little more setup involved.
55
+
56
+
1. Setup the requirements for pypy using either of the following:
57
+
* Use pip_pypy
58
+
*`pip_pypy install -r requirements.pypy.txt` (regular pip doesn't install to a directory that pypy can find)
2. Ensure that you have either `c++filt` or `gc++filt` on your machine/in your `$PATH` (The demangler library we use does not work with pypy. If you know of a python demangler library that can run on pypy, let us know!)
63
+
64
+
Running
65
+
-------
8
66
9
-
There is optional IACA integration; to use it, you must first download IACA from [Intel's website](https://software.intel.com/en-us/articles/intel-architecture-code-analyzer-download) and update variables in your config.py accordingly.
67
+
The simplest way to run the application is the following way:
68
+
69
+
```python
70
+
python app/app.py
71
+
```
72
+
73
+
This approach does not require you to download or install anything more than the dependencies listed in requirements.txt, but it is also the slowest and least reliable.
74
+
75
+
If Gunicorn is installed, you can start the application by running the following:
10
76
11
-
To run:
12
77
```python
13
78
python run.py
14
79
python run.py -f <file(s)>
15
80
```
16
81
82
+
<<<<<<< f48072ddc62aa0b7be3fdebe42d3a5d8284c0928
17
83
`run.py` uses gunicorn for speed and robustness.
18
84
19
85
---
@@ -23,4 +89,191 @@ python run.py -f <file(s)>
23
89
24
90
1.`pip_pypy install -r requirements.pypy.txt` (regular pip doesn't install to a directory that pypy can find)
25
91
2. Ensure that you have either `c++filt` or `gc++filt` on your machine/in your `$PATH` (The demangler library we use does not work with pypy. If you know of a python demangler library that can run on pypy, let us know!)
92
+
=======
93
+
If Pypy is installed, then you can run the application by running pypy instead of python:
94
+
95
+
```python
96
+
pypy app/app.py
97
+
```
98
+
99
+
You can also combine Gunicorn and Pypy to form the best experience:
100
+
101
+
```python
102
+
pypy run.py
103
+
```
104
+
105
+
### Options
106
+
107
+
* -f <file(s)>, --files <file(s)>
108
+
* File(s) that you want to appear on the homepage to disassemble.
109
+
110
+
About
111
+
-----
112
+
113
+
Disasm is a web application written in Flask. It allows you to disassemble ELF files that have been assembled as Intel x86 assembly. The assembly and analysis can be displayed in a browser so that you can click around and interact with it.
114
+
115
+
Features
116
+
--------
117
+
118
+
Features marked with an asterisk (*) require that the .dwarf_info and .dwarf_aranges sections be defined in order to use it.
119
+
120
+
### Disassembly
121
+
122
+
The main feature of the application, an Intel x86 ELF executable can be disassembled into x86 assembly and displayed in the browser.
123
+
124
+
### Source code stack trace *
125
+
126
+
After selecting a line of assembly, the source code that corresponds to it can be displayed, as well as the full stack trace of function calls that refer to it.
127
+
128
+
Note: This feature requires that the source directory of the code that compiled into this executable be defined in config.py.
129
+
130
+
![source code stack trace](screenshots/stack-trace.png"Example of source code stack trace")
131
+
132
+
### IACA integration
133
+
134
+
A sequence of instructions can be analyzed by Intel IACA.
135
+
136
+
Note: In order to use this feature, you must first download IACA from [Intel's website](https://software.intel.com/en-us/articles/intel-architecture-code-analyzer-download) and update variables in your config.py accordingly.
137
+
138
+
![intel iaca integration](screenshots/iaca.gif"Using IACA to determine the throughput of a set of instructions")
139
+
140
+
### Register contents *
141
+
142
+
Whenever possible, the contents of a register will be displayed, including the object's member that is being pointed to if a valid offset is given.
143
+
144
+
![register tracking](screenshots/register-tracking.png"Determine the contents of a register")
145
+
146
+
### Register tracking *
147
+
148
+
Observe which instructions read and/or write to a particular register. To activate this feature, right click the desired register and select the appropriate option.
149
+
150
+
![registers written to and read from](screenshots/relevant-registers.png"Display all of the instructions that write to or read from this register")
151
+
152
+
### Flags read/written
153
+
154
+
Instructions that write to a flag(s) will display a white flag next to the mnemonic. Instructions that read from a flag(s) will display a black flag next to the mnemonic. Hovering over the flag will display which flags are read to/written from in this operation.
155
+
156
+
![flags written to and read from](screenshots/relevant-flags.png"Display all of the flags that are written to or read from")
157
+
158
+
### Jump table resolution
159
+
160
+
Jump tables are parsed. Clicking on the first instruction in a jump table sequence will display a the table the mapping between value in rdi (the condition) and the address to jump to. Clicking on one of these addresses will allow you to jump to this instruction as well.
161
+
162
+
![jump table parsing](screenshots/jump-table.png"Display the information relevant to the detected jump table")
163
+
164
+
### Rip-relative address resolution and interpretation
165
+
166
+
A rip-relative adddress (e.g, "rip + 0x129d866") can be resolved into a single address by right clicking on that part of the instruction. The value at this address can also be read from the file as an 8/16/32/64-bit signed decimal/unsigned decimal/hexadecimal/binary number, single/double precision floating point number, or null-terminated C String (up to 128 bytes).
167
+
168
+
![rip relative resolution and interpretation](screenshots/rip-relative.gif"Resolving the RIP-relative address and interpreting the data at that address")
169
+
170
+
### Type analysis *
171
+
172
+
You can search for a type that is defined in this file in order to obtain obtain in-depth information about this type, including its size, subtype, and member variables. When displaying member variables, you can also see their types, their offsets, and their name.
173
+
174
+
![type analysis](screenshots/type-analysis.gif"Obtaining information about a given type")
175
+
176
+
### Jumping
177
+
178
+
Clicking on the address of a jump or call instruction will allow you to jump to the address.
By right clicking on an immediate value, you can convert it to/from decimal (signed and unsigned), hexadecimal, and binary. If the number is less than 128 in unsigned decimal, then it can also be converted to ASCII.
Hovering over an instruction mnemonic will display a short explaination of what it does. Clicking on an instruction mnemonic will display an in-depth explaination.
191
+
192
+
![short description](screenshots/short-description.png"Short description of what the instruction does")
193
+
194
+
![full description](screenshots/full-description.png"Full documentation for the instruction")
195
+
196
+
### File upload
197
+
198
+
When a file is uploaded, it will be stored on the server for quicker lookup later. These files can also be deleted.
199
+
200
+
![file upload](screenshots/file-upload.png"Display the list of files previously uploaded")
201
+
202
+
### NOP byte size
203
+
204
+
There are various different NOP instructions, each of which is encoded as a different operation, and each with a different size. Instead of displaying the operation (which is essentially meaningless), the size of the NOP will be displayed.
205
+
206
+
![NOP byte size](screenshots/nop-byte-size.png"Display the size of the NOP instruction")
207
+
208
+
### Keyboard shortcuts
209
+
210
+
#### Function search
211
+
212
+
* Up/down
213
+
* Navigate through the list of functions
214
+
* Enter
215
+
* Disassemble the currently selected function
216
+
* ?
217
+
* Display the help menu
218
+
219
+
#### Disassembly
220
+
221
+
* Up/down
222
+
* Navigate through the instructions
223
+
* Right Arrow
224
+
* On jmp/call
225
+
* Go to target address
226
+
* On ret
227
+
* Return to the calling function (only available if this function was reached by entering going through a call instruction)
228
+
* Left Arrow
229
+
* Undo previous jump/call (if applicable)
230
+
* Enter
231
+
* Open the analysis window relevant to this instruction
0 commit comments