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
Improve instructions in `README.md` on installing and setting up the
module. Add detailed instructions, fix commands where required,
reference the `dataset` and `commons` modules.
Signed-off-by: Razvan Deaconescu <[email protected]>
`attack_surface_approximation` is the CRS module that deals with the approximation of the attack surface in a vulnerable program.
24
24
25
25
Some input mechanisms are omitted: elements of the user interface, signals, devices and interrupts. At the moment, the supported mechanisms are the following:
26
-
- Files;
27
-
- Arguments;
28
-
- Standard input;
29
-
- Networking; and
30
-
- Environment variables.
31
26
32
-
In addition, a custom fuzzer is implemented to discover arguments that trigger different code coverage. It takes arguments from a dictionary which can be handcrafted or generated with an exposed command, with an implemented heuristic.
27
+
- files
28
+
- command-line arguments
29
+
- standard input
30
+
- networking
31
+
- environment variables
32
+
33
+
In addition, a custom fuzzer is implemented to discover arguments that trigger different code coverage.
34
+
It takes arguments from a dictionary which can be handcrafted or generated with an exposed command, with an implemented heuristic.
33
35
34
36
Examples of arguments dictionaries can be found in `examples/dictionaries`:
35
-
-`man.txt`, generated with the `man_parsing` heurstic and having 6605 entries; and
36
-
-`generation.txt`, generated with the `generation` heuristic and having 62 entries.
37
+
38
+
-`man.txt`: generated with the `man_parsing` heuristic and having 6605 entries
39
+
-`generation.txt`: generated with the `generation` heuristic and having 62 entries
37
40
38
41
### Limitations
39
42
40
43
- ELF format
41
44
- x86 architecture
42
-
-Non-static binaries
43
-
-Symbols present (namely, no stripping is involved)
44
-
-No obfuscation technique involved
45
+
-dynamic binaries (static binaries are not supported)
46
+
-symbols present (namely, no stripping is involved)
47
+
-no obfuscation technique involved
45
48
46
49
## How It Works
47
50
48
-
The module works by automating Ghidra for static binary analysis. It extracts information and apply heuristics to determine if a given input stream is present.
51
+
The module works by automating [Ghidra](https://ghidra-sre.org/) for static binary analysis.
52
+
It extracts information and applies heuristics to determine if a given input stream is present.
49
53
50
54
Examples of such heuristics are:
51
-
- For standard input, calls to `getc()` and `gets()`
52
-
- For networking, calls to `recv()` and `recvfrom()`
53
-
- For arguments, occurrences of `argc` and `argv` in the `main()`'s decompilation.
54
55
55
-
The argument fuzzer uses Docker and QBDI to detect basic block coverage.
56
+
- for standard input: calls to `getc()` and `gets()`
57
+
- for networking: calls to `recv()` and `recvfrom()`
58
+
- for command-line arguments: occurrences of `argc` and `argv` in `main()`
59
+
60
+
The argument fuzzer uses [Docker](https://www.docker.com/) for running and [QBDI](https://qbdi.quarkslab.com/) to detect basic-block coverage.
56
61
57
62
## Setup
58
63
59
-
1. Ensure you have Docker installed.
60
-
2. Install the required Python 3 packages via `poetry install --no-dev`.
61
-
3. Ensure the Docker API is accessible by:
62
-
- Running the module as `root`; or
63
-
- Changing the Docker socket permissions (unsecure approach) via `chmod 777 /var/run/docker.sock`.
64
+
1. Make sure you have set up the repositories and Python environment according to the [top-level instructions](https://github.com/open-crs#requirements).
65
+
That is:
66
+
67
+
- Docker is installed and is properly running.
68
+
Check using:
69
+
70
+
```console
71
+
docker version
72
+
docker ps -a
73
+
docker run --rm hello-world
74
+
```
75
+
76
+
These commands should run without errors.
77
+
78
+
- The current module repository and all other module repositories (particularly the [`dataset` repository](https://github.com/open-crs/dataset) and the [`commons` repository](https://github.com/open-crs/commons)) are cloned in the same directory.
79
+
80
+
- You are running all commands inside a Python virtual environment.
81
+
There should be `(.venv)` prefix to your prompt.
82
+
83
+
- You have installed Poetry in the virtual environment.
84
+
If you run:
85
+
86
+
```console
87
+
which poetry
88
+
```
89
+
90
+
you should get a path ending with `.venv/bin/poetry`.
This is an problem that may occur in certain situations, preventing Poetry from getting packages.
99
+
100
+
1. Install the required packages with Poetry (based on `pyprojects.toml`):
101
+
102
+
```console
103
+
poetry install --only main
104
+
```
105
+
106
+
1. Create the `ghidra` and `qbdi_args_fuzzing` Docker images by using the [instructions in the `commons` repository](https://github.com/open-crs/commons?tab=readme-ov-file#setup).
107
+
108
+
1. Optionally, generate executables by using the [instructions in the `dataset` repository](https://github.com/open-crs/dataset).
64
109
65
110
## Usage
66
111
112
+
You can use the `attack_surface_approximation` module either standalone, as a CLI tool, or integrated into Python applications, as a Python module.
113
+
67
114
### As a CLI Tool
68
115
69
-
#### Arguments Dictionary Generation
116
+
As a CLI tool, you can either use the `cli.py` module:
117
+
118
+
```console
119
+
python attack_surface_approximation/cli.py
120
+
```
121
+
122
+
or the Poetry interface:
70
123
124
+
```console
125
+
poetry run attack_surface_approximation
71
126
```
72
-
➜ poetry run attack_surface_approximation generate --heuristic man --output args.txt --top 10
0 commit comments