Skip to content

Commit 0b8aa37

Browse files
gsingh93gsingh93
committed
Update README
1 parent 327a709 commit 0b8aa37

File tree

1 file changed

+144
-80
lines changed

1 file changed

+144
-80
lines changed

‎README.md

Lines changed: 144 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,10 @@
11
# Linux Exploit Development Environment
22

3-
## Building
3+
## Quickstart
44

5-
Tested on Ubuntu 22.04.
5+
The only supported host OS is Ubuntu 22.04, things may or may not work on any other system.
66

7+
First install the dependencies and clone the project:
78
```bash
89
sudo apt update
910
sudo apt install -y bc bison build-essential flex git libelf-dev libssl-dev ncurses-dev qemu qemu-system-x86 qemu-system-arm llvm clang clang-tools lld lz4 binutils-aarch64-linux-gnu gcc-aarch64-linux-gnu pahole
@@ -13,121 +14,184 @@ cd linux-exploit-dev-env
1314

1415
This will clone the Linux kernel and Android Common Kernel (ACK) submodules. You can checkout any version of the kernel you want, i.e.
1516
```bash
16-
cd linux
17-
git checkout v5.10.107 # Checkout a specific version
18-
git checkout linux-5.10.y # Checkout the latest version of an LTS kernel
17+
VERSION=5.10.107 make linux_checkout # Checkout a specific version
18+
VERSION=5.10.y make linux_checkout # Checkout the latest version of an LTS kernel
1919
```
2020

21-
To see all targets and configuration options:
21+
Create the default rootfs images:
22+
```bash
23+
make rootfs-init
24+
```
2225

26+
Build and run the Linux kernel:
27+
```bash
28+
make
29+
make run
2330
```
24-
$ make help
25-
Environment Variables:
26-
ARCH - Specify one of the supported architectures: x86_64, arm64 (default: x86_64)
27-
ACK - Set to 1 if building ACK instead of the Linux kernel. Does not need to be set for `ack` and `run-ack` targets (default: 0)
28-
VERBOSE - Set to 1 to enable verbose output (default: 0)
29-
EXT4_SIZE - TODO
30-
INITRAMFS_DIR - TODO
31-
ROOTFS - TODO
32-
ROOTFS_FORMAT - TODO
33-
INITRD - TODO
34-
RDINIT - TODO
3531

36-
Build/Config Targets:
37-
linux (default) - builds the Linux kernel
38-
linux_defconfig - builds the Linux kernel
39-
linux_modules - builds the Linux kernel modules
40-
ack - builds the Android Common Kernel
41-
tools-vm - builds linux/tools/vm
42-
43-
Build/Config Environment Variables:
44-
LINUX_DEFCONFIG - TODO
45-
LINUX_SRC - TODO
46-
LINUX_OUT - TODO
47-
LINUX_CONFIG_FRAGMENT - TODO
32+
To exit QEMU, use `ctrl+a x` (`ctrl-c` will not work).
4833

49-
Clean Targets:
50-
clean - cleans output from all build targets
51-
<target>_clean - cleans output for <target>
34+
To attach with GDB, set the `GDB` environment variable before running:
35+
```bash
36+
GDB=1 make run
37+
```
5238

53-
Run/Debug Targets:
54-
run - run QEMU with the built kernel, bootloader, and rootfs image
55-
run-ack - same as `run` but runs ACK instead
56-
57-
Run/Debug Environment Variables:
58-
GDB - Set to 1 to start a gdbserver and wait for GDB when running QEMU (default: 0)
59-
CPU - Specify the number of CPUs to use when running QEMU (default: 4)
60-
MEM - Specify the memory size in MB to use when running QEMU (default: 1024)
61-
QEMU_EXTRA_ARGS - Specify additional arguments to pass to QEMU (default: "")
62-
QEMU_EXTRA_KERNEL_CMDLINE - Specify additional arguments to pass to the kernel (default: "")
63-
KERNEL_IMAGE - TODO
39+
And then in another terminal, attach with:
40+
```bash
41+
scripts/gdb.sh
42+
```
6443

65-
rootfs Targets:
66-
rootfs-init - TODO
67-
rootfs - TODO
68-
ext4 - TODO
69-
cpio - TODO
70-
rootfs-mount - TODO
71-
rootfs-unmount - TODO
44+
The default architecture is x86_64, but arm64 is also supported:
45+
```bash
46+
ARCH=arm64 make rootfs-init
47+
ARCH=arm64 make run
48+
```
7249

73-
Miscellaneous Targets:
74-
linux_download - TODO
75-
linux_checkout - TODO
50+
## All Targets and Options
7651

77-
Miscellaneous Environment Variables:
78-
VERSION - TODO
52+
```
53+
$ make help
54+
General Environment Variables:
55+
ARCH - Specify one of the supported architectures: x86_64, arm64 (default: x86_64)
56+
ACK - Set to 1 if building ACK instead of the Linux kernel. Does not need to be set for `ack` and `run-ack` targets (default: 0)
57+
VERBOSE - Set to 1 to enable verbose output (default: 0)
58+
59+
Build/Config:
60+
Targets:
61+
linux (default) - Builds the Linux kernel
62+
linux_defconfig - Builds the Linux kernel
63+
linux_modules - Builds the Linux kernel modules
64+
ack - Builds the Android Common Kernel
65+
tools-vm - Builds linux/tools/vm
66+
67+
Environment Variables:
68+
LINUX_DEFCONFIG - The defconfig to use when building the kernel (default: defconfig, ACK default: gki_defconfig)
69+
LINUX_SRC - The path to the kernel source directory (default: linux, ACK default: ack/common)
70+
LINUX_OUT - The path where the kernel build output should be stored (default: out/linux/$ARCH, ACK default: out/ack/common/$ARCH)
71+
LINUX_CONFIG_FRAGMENT - A kernel config fragment to merge with the defconfig (default: config/config.fragment, ACK default: config/config.fragment)
72+
73+
Clean:
74+
Targets:
75+
clean - Cleans output from default build targets
76+
<target>_clean - Cleans output for <target>
77+
78+
Run/Debug:
79+
Targets:
80+
run - Run QEMU with the built kernel, bootloader, and rootfs image
81+
run-ack - Same as `run` but runs ACK instead
82+
83+
Environment Variables:
84+
GDB - Set to 1 to start a gdbserver and wait for GDB when running QEMU (default: 0)
85+
CPU - Specify the number of CPUs to use when running QEMU (default: 4)
86+
MEM - Specify the memory size in MB to use when running QEMU (default: 1024)
87+
QEMU_EXTRA_ARGS - Specify additional arguments to pass to QEMU (default: "")
88+
QEMU_EXTRA_KERNEL_CMDLINE - Specify additional arguments to pass to the kernel (default: "")
89+
KERNEL_IMAGE - The path to the kernel image to run (x86_64 default: $LINUX_OUT/arch/$ARCH/boot/bzImage, arm64 default: $LINUX_OUT/arch/$ARCH/boot/Image)
90+
ROOTFS - The path to the rootfs image file (default: rootfs/rootfs-$ARCH.img)
91+
ROOTFS_FORMAT - The format of the rootfs image file (default: qcow2)
92+
INITRD - The path to a gziped initramfs CPIO file to use instead of a rootfs image (default: "")
93+
RDINIT - The value of the `rdinit` kernel command line paramter (default: "", default if INITRD is set: /sbin/init)
94+
95+
rootfs:
96+
Targets:
97+
rootfs-init - Extracts the Alpine Linux rootfs to rootfs/alpine-$ARCH, makes arch-specific changes, and builds a rootfs image at rootfs/alpine-$ARCH.img
98+
rootfs - An alias for the `ext4` target
99+
ext4 - Builds a QCOW2 rootfs image at rootfs/alpine-$ARCH.img with an ext4 filesystem
100+
cpio - Builds a gziped initramfs CPIO file from the $INITRAMFS_DIR directory
101+
rootfs-mount - Mount rootfs image at /tmp/rootfs
102+
rootfs-unmount - Unmount rootfs image
103+
104+
Environment Variables:
105+
EXT4_SIZE - The disk size of the rootfs image to build
106+
INITRAMFS_DIR - The directory to create the initramfs from (default: rootfs/alpine-$ARCH)
107+
ROOTFS_DIR - The directory to create the ext4/rootfs image from (default: rootfs/alpine-$ARCH)
108+
ROOTFS - The path to the rootfs image file (default: rootfs/rootfs-$ARCH.img)
109+
ROOTFS_FORMAT - The format of the rootfs image file (default: qcow2)
110+
111+
Miscellaneous:
112+
Targets:
113+
linux_download - Downloads an archive of the Linux kernel source for the version specified in $VERSION
114+
linux_checkout - Checks out the version specified by $VERSION of the linux kernel in $LINUX_SRC
115+
116+
Environment Variables:
117+
VERSION - The version to download or checkout. For checkout only, if the third number in the version string is a 'y', the latest version of the kernel with that major and minor version is used. Examples: 5.10, 5.10.107, v5.10, 5.10.y, linux-5.10.y
79118
```
80119

81-
To build the Linux kernel:
120+
## Building
121+
122+
You can customize the path to the linux source and output directories with the `LINUX_SRC` and `LINUX_OUT` environment variables:
82123
```bash
83-
make # or: make linux
124+
LINUX_SRC=/path/to/src LINUX_OUT=/path/to/out make linux
84125
```
85126

86-
To build an `arm64` kernel instead of the default of `x86_64`:
127+
Note that the default output directory is `out/$KERNEL_DIR/$ARCH`, which means that switching between architecture or kernel types (i.e. ACK or Linux) will not overwrite builds of another architecture or kernel type.
128+
129+
### Android Common Kernel (ACK)
130+
131+
Instead of the Linux kernel, you can set the `ACK` variable to build the Android Common Kernel:
132+
```bash
133+
ACK=1 make linux
134+
ACK=1 make run
135+
```
136+
137+
### defconfig
138+
139+
To generate the default kernel config with the default `defconfig`, run:
87140
```bash
88-
ARCH=arm64 make
141+
make linux_defconfig
89142
```
90143

91-
To build ACK instead of Linux:
144+
The `ARCH` and `ACK` variables can also be used here:
92145
```bash
93-
ACK=1 make linux # or: make ack
94-
ACK=1 ARCH=arm64 linux # or: ARCH=arm64 make ack
146+
ACK=1 ARCH=arm64 make linux_defconfig
95147
```
96148

97-
All built artifacts are placed in `out/`. ACK and Linux builds are placed in separate folders, and each architecture is placed in their own folders, so you can switch between these kernels without the other build variants.
149+
If `ACK` is set `gki_defconfig` is used instead of `defconfig`. By default, `config/config.fragment` is merged into the generated config to create the final kernel config. This can be customized by setting `LINUX_CONFIG_FRAGMENT`.
150+
151+
## rootfs
152+
153+
The default rootfs is based on [Alpine Linux's](https://alpinelinux.org/downloads/) mini root filesystem. `make rootfs-init` will automatically extract the file system to `rootfs/alpine-$ARCH` and create the filesystem image at `rootfs/rootfs-$ARCH.img`. You can modify the file system by modifying the files in `rootfs/alpine-$ARCH` and then running `make rootfs` to regenerate the image. If you have another directory where you keep your rootfs, or you'd like to customize where the output image is stored, you can use the `ROOTFS_DIR` and `ROOTFS` variables:
154+
```bash
155+
ROOTFS_DIR=/path/to/rootfs/dir ROOTFS=/path/to/output/rootfs.img ROOTFS_FORMAT=qcow2 make rootfs
156+
```
98157

99-
The default build targets can be cleaned with `make clean`, and any specific target can be cleaned with `make <target>_clean`, i.e.:
158+
If you'd like to use an initramfs instead of a disk image, you can use `make cpio`, which will create `rootfs/alpine-$ARCH.cpio.gz` by default. To build an initramfs from a different directory, use the `INITRAMFS_DIR` variable:
100159
```bash
101-
make linux_clean
160+
INITRAMFS_DIR=/path/to/initramfs/dir make cpio
102161
```
103162

163+
Remember to set the correct `ARCH` variable for these commands if you are working with an architecture other than x86_64.
164+
104165
## Running
105166

106-
First setup the default Alpine rootfs:
167+
When running a kernel, you can specify an alternative rootfs or initramfs (but not both) with the `ROOTFS` and `INITRD` variables:
107168
```bash
108-
make rootfs-init # x86_64 rootfs
109-
ARCH=arm64 make rootfs-init # arm64 rootfs
169+
ROOTFS=/path/to/rootfs-qcow2.img make run
170+
ROOTFS=/path/to/rootfs-raw.img ROOTFS_FORMAT=raw make run
171+
INITRD=/path/to/initramfs.cpio.gz make run
110172
```
111173

112-
To run the built `x86_64` Linux image with QEMU:
174+
The number of CPUs and the amount of memory can be configured with the `CPU` and `MEM` variables. You can pass additional arguments to QEMU or the kernel command line with `QEMU_EXTRA_ARGS` and `QEMU_EXTRA_KERNEL_CMDLINE`, respectively:
113175
```bash
114-
make run
176+
CPU=4 MEM=2048M QEMU_EXTRA_KERNEL_CMDLINE="nokaslr" QEMU_EXTRA_ARGS="-S -s" make run
115177
```
116178

117-
The other variants can be run by setting the same environment variables that were needed to build them:
179+
As shown earlier, `GDB=1` can be used instead of `QEMU_EXTRA_ARGS="-S -s"`.
180+
181+
## Miscellaneous Commands
182+
183+
`make linux_download` (which downloads a source archive) and `make linux_checkout` can be used to more easily switch between kernel versions. The kernel version to download or checkout must be specified with the `VERSION` environment variable:
118184
```bash
119-
ACK=1 make run
120-
ARCH=arm64 make run
121-
ACK=1 ARCH=arm64 make run
185+
VERSION=5.10.107 make linux_download
186+
VERSION=5.10.107 make linux_checkout
122187
```
123188

124-
To start a GDB server and wait for GDB to attach, set the `GDB` environment variable:
189+
The version string can be specified as `5.10.107` as `v5.10.107` (the name of the version tag in the Linux git repo). For `linux_checkout`, you can additionally set the last number to `y` to checkout the latest version of that kernel:
125190
```bash
126-
GDB=1 make run
191+
VERSION=5.10.y make linux_checkout
127192
```
193+
Using `linux-5.10.y` will also work here, which is the name of the corresponding branch in the Linux git repo.
128194

129-
To exit QEMU, use `ctrl+a x` (`ctrl-c` will not work).
130-
131-
## Configuration
195+
The `LINUX_SRC` variable can be used to customize the source directory for `linux_checkout`
132196

133-
TODO
197+
These `make` targets are just wrappers around the `./scripts/download_linux.sh` and `./scripts/checkout_linux.sh` scripts, so if you prefer those can be used instead.

0 commit comments

Comments
 (0)