breakmancer

在任何shell中设置断点。

需要调试构建脚本，但没有方法SSH到服务器检查构建环境——或者你有，但你需要一种方法在脚本的确切点上暂停？breakmancer可以做到这一点！

功能上，这是一个仅供授权用户跳入远程服务器的反向shell。与恶意类型的反向shell不同，这个目标是保护目标的安全性。

要求

• 一台可以监听公共IP地址（或与您调试的计算机在同一网络上的内部IP地址）的开发计算机。
• 一台目标计算机，您在其中尝试调试脚本，并且您有权shell进入。此计算机必须能够通过TCP连接到开发计算机。

用法

在此示例中，开发计算机可在域名home.timmc.org上的12345端口访问。目标是GitHub Actions工作流。

1. 本地启动会话：我在我的笔记本电脑上运行breakmancer listen home.timmc.org:12345。它打印出说明并等待（“正在监听”）。
2. 在远程服务器上设置密钥：我创建一个名为breakmancer_callback的GitHub仓库密钥，其密钥来自上面的命令输出（sEYKNzulK6v8zE3gh23xkg）。
3. 设置断点：我将上面打印出的断点命令添加到我的GitHub工作流文件中。它可能看起来像这样

   name: Breakmancer Demo
   on: [push]
   jobs:
     demo:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
   
         - name: Do some stuff
           run: |
             date > something.txt
   
         - name: Invoke breakpoint
           env:
             BM_SETUP_SECRET: "${{ secrets.breakmancer_callback }}"
           run: |
             chmod +x ./breakmancer
             ./breakmancer break -c home.timmc.org:12345 -i TEXXICzjphp1mhzknJ/VfkHyOOhd6efImGQcrXxSjyI
   

   • 工作流检索安全存储的密钥并将其作为环境变量导出。
   • 与回调密钥不同，命令行可以公开显示。它只包含一个地址和公钥。
   • 我还将breakmancer二进制文件提交到我的分支。
   • 我已调整命令以调用./breakmancer（它不在PATH中）并确保二进制文件可执行。
4. 运行：我推送分支，GitHub Action运行，breakmancer连接到我的笔记本电脑，打开一个shell！

   Connection from [::ffff:52.234.38.67]:61440
   Session ready. You can enter single-line commands. Use `exit` to exit.
   >> hostname
   [out] fv-az1756-422
   [exit: 0]
   >> pwd
   [out] /home/runner/work/manual-testing/manual-testing
   [exit: 0]
   >>
   

5. 结束：完成时，我使用 exit（或 ^C 或 ^D）退出并允许工作流继续；在新的提示符下，我可以选择等待新的连接或完全结束程序。
6. 审计日志：查看GitHub工作流输出，可以看到运行过的命令记录。

   Connecting to listener at 130.44.147.140:12345
   [2024-06-25T22:33:27Z] Waiting for first command...
   [2024-06-25T22:33:30Z] Running command: hostname
   [2024-06-25T22:33:39Z] Running command: pwd
   Listener asked for normal execution to resume; exiting breakpoint.
   

提示：监听器退出后，断点侧提供的秘密和命令行将不再有效，需要替换。这可能会很麻烦。因此，在确定完成之前，你可能希望保持监听器运行。

构建、测试和发布

• 更新 Cargo.toml 中的版本
• 确保变更日志已经填写完毕
• cargoclippy --all-targets
• cargotest
• cargobuild --release
• 进行任何手动测试
• cargo发布
• gittag -avX.Y.Z -mX.Y.Z
• gitpush --tags
• 更新变更日志版本（在 Unreleased 标题下方添加新的发布标题）
• gitpush

手动测试

一些有趣的内容可以输入

• (yes "out" | head -n20)& (yes " err" | head -n20 >&2) 以显示标准输出和标准错误的交织
• echo start; sleep 10; echo stop 以实验阻塞命令
• while true; do date; sleep 0.001; done 用于快速输出流（不如 yes 快）

限制

• 由于Breakmancer不创建PTY，某些管道中可能会发生缓冲。这造成两个问题

  1. 所有输出一次性发生。在命令 for x in {1..5}; do date; sleep 1; done | head 中，我们5秒钟看不到任何输出，然后一次性输出5行。 （输出显示每个 date 调用确实间隔了1秒钟。）
  2. 如果这样的流式命令永远不会终止，输出将永远不会发送。命令 while true; do date; sleep 1; done | head 将永久挂起，没有输出。

  在这些例子中，从管道中删除 head（或将输出重定向到不同的二进制文件，如 cat）允许正常流式输出。

• 有关更多错误和想要的功能，请参阅 TODO.md。

许可

版权所有 2024 Tim McCormack

本程序是免费软件：您可以按照自由软件基金会发布的GNU Affero通用公共许可证的条款重新分发和/或修改它，许可证版本为3，或（根据您的选择）任何较新版本。

本程序分发时希望能对您有所帮助，但没有任何保证；甚至没有关于其可销售性或适用于特定目的的暗示性保证。有关详细信息，请参阅GNU Affero通用公共许可证。