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
Copy file name to clipboardExpand all lines: README.md
+66-38Lines changed: 66 additions & 38 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,30 +1,50 @@
1
1
# Overview
2
-
The C-Shell is a command line interpreter embedded as part of the `frida-inject` tool, it takes inspiration from the VxWorks C-Shell and is intended to allow the user to interactively inspect a running process by issuing commands. By setting `frida-inject` to use raw mode, the tool acts as a dumb byte pump sending and receiving raw key-strokes between the TTY and the C-shell. It is implmented purely in about 4k lines of Typescript (which is embedded as a resource) and converts the user's input into calls into the [FRIDA JS API bindings](https://frida.re/docs/javascript-api/).
3
-
4
-
# Getting Started
5
-
The C-Shell can be started by using the `-s` flag provided to the `frida-inject` tool as follows:
When launched the user will see the welcome banner as shown below:
10
-
11
-
```
12
-
_.---._ _ _ _
13
-
.'"".'/|\'.""'. | | | | |
14
-
: .' / | \ '. : ____ ___| |__ ___| | |
15
-
'.' / | \ '.' / _ / __| '_ \ / _ \ | |
16
-
`. / | \ .' | (__\__ \ | | | |__/ | |
17
-
`-.__|__.-' \____|___/_| |_|\___|_|_|
18
-
CSHELL running in FRIDA 16.2.2-dev.6 using QJS
19
-
Attached to:
20
-
PID: 2047276
21
-
Name: vim.basic
22
-
->
23
-
```
24
-
**Important** Be sure to include the `--interactive` command line option, otherwise the terminal will appear non-responsive.
25
-
26
-
# Wrapper
27
-
Alternatively, included in the release is a wrapper shell script `frida-cshell`:
2
+
The C-Shell is a command line interpreter which can be used in conjunction with the `frida-inject` tool, it takes inspiration from the VxWorks C-Shell and is intended to allow the user to interactively inspect a running process by issuing commands. By setting `frida-inject` to use `raw` and `interactive` modes, the script can read and write raw bytes to the TTY allowing direct interation with the user. It is implmented purely in about 12k lines of Typescript (which is embedded as a resource into a shell script which launches `frida-inject`) and converts the user's input into calls into the [FRIDA JS API bindings](https://frida.re/docs/javascript-api/).
3
+
4
+
It is intended to allow much more dynamic interaction with a process, without requiring the user to write and modify JS each time they wish to inspect something new. It works much more like a debugger, but without the complex syntax of GDB and without stopping threads (which can interefere with watchdog timers). It is extensible too, allowing the user to define macros, run commands from a file, as well as add new commands in an adhoc fashion via `JS` (so if you want to add a command to dump some application specific data format then you can).
5
+
6
+
Some of the key features are:
7
+
* Add breakpoints on function entry and exit, instructions, memory access (without stopping the target application)
8
+
* Log coverage data (using stalker) for a function to show the executed blocks or calls for a function or thread.
9
+
* Collect coverage data into a dynamoRIO format file for inspection with `lighthouse` (IDA) or `lightkeeper` (Ghidra) for a function or thread or application.
10
+
* Patch a function with another implementation (including one written in JS)
11
+
* Modify memory, or dump it to screen or to a file
12
+
* Show diassassembly listings or register contents
13
+
* Dump a file or show the open file descriptors for the process
14
+
* Perform basic math operations with a relatively simple syntax
15
+
* Query symbol and virtual memory information
16
+
* Create a coredump of the running process without killing it
17
+
* Call any function in the application with any arguments you like
18
+
* Display the value of `errno`
19
+
* Log all commands and output to file
20
+
* Filter command output using regular expressions
21
+
* Command history
22
+
* Create and manage variables (to give a friendly name to strings, addresses or numbers)
23
+
* Load modules and display module information
24
+
* Show the threads running in the application and their backtraces
25
+
* Determine which threads are busiest and compare to a baseline
26
+
27
+
# Install
28
+
## Using NPM as root
29
+
The easiest way to install `frida-cshell` is to use the command:
30
+
```bash
31
+
sudo npm install -g frida-cshell
32
+
```
33
+
34
+
## Using NPM as a normal user
35
+
If you can't or don't want to install `frida-cshell` as root, then you can install and run it as follows:
36
+
```bash
37
+
npm install frida-cshell
38
+
```
39
+
```bash
40
+
npm exec frida-cshell
41
+
```
42
+
43
+
## Adhoc
44
+
Alternatively you can download the [latest](https://github.com/WorksButNotTested/frida-cshell/releases/latest) directly from release from GitHub and download and run the `frida-cshell-x.y.z` bash script
45
+
46
+
# Options
47
+
The `frida-cshell` script presents the following options:
28
48
```
29
49
# ./frida-cshell -h
30
50
Usage
@@ -41,22 +61,30 @@ Application Options:
41
61
```
42
62
It assumes that `frida-inject` can be found on the path, otherwise an alternative can be provided using the `FRIDA_INJECT` environment variable. As an example, it can be used as follows:
Alternatively you can use `frida-inject` directly to load the `frida-inject-x.y.z.js` script (available from the [releases](https://github.com/WorksButNotTested/frida-cshell/releases/latest) page).
52
66
53
-
CSHELL v1.0.6, running in FRIDA 0.0.0 using QJS
54
-
Attached to:
55
-
PID: 253520
56
-
Name: target
67
+
**Important** Be sure to include the `--interactive` command line option, in addition to your other usual options, otherwise the terminal will appear non-responsive.
68
+
69
+
# Startup
70
+
71
+
When launched the user will see the welcome banner as shown below:
57
72
73
+
```
74
+
_.---._ _ _ _
75
+
.'"".'/|\'.""'. | | | | |
76
+
: .' / | \ '. : ____ ___| |__ ___| | |
77
+
'.' / | \ '.' / _ / __| '_ \ / _ \ | |
78
+
`. / | \ .' | (__\__ \ | | | |__/ | |
79
+
`-.__|__.-' \____|___/_| |_|\___|_|_|
80
+
CSHELL running in FRIDA 16.2.2-dev.6 using QJS
81
+
Attached to:
82
+
PID: 2047276
83
+
Name: vim.basic
58
84
->
59
85
```
86
+
**Important** Be sure to include the `--interactive` command line option, otherwise the terminal will appear non-responsive.
87
+
60
88
# Init Scripts
61
89
Commands which should be run on start-up can be provided in a file name `.cshellrc` in the current directory. An example can be found [here](assets/initrd/.cshellrc)
0 commit comments