ghostpwn

用于授权测试的自动化渗透测试编排引擎。 ghostpwn 运行 YAML 定义的工作流，这些工作流通过依赖 DAG 将安全工具阶段（侦察、扫描、报告）串联起来。它会解析阶段依赖关系，并行运行独立的阶段，在阶段之间传递结构化数据，并将所有内容整合为一份报告。可以把它想象成“用于渗透测试工作流的 CI”：你只需定义各个阶段及其连接方式，ghostpwn 就会负责调度和运行它们，并为你提供可审计的结果。 它能够编排可插拔的工具适配器，包括通过通用命令适配器接入的您自己的工具（例如 ghostrecon 和 ghostmap），并且内置了多种适配器和一个确定性模拟（mock）适配器，因此无需安装任何外部工具即可完全运行和测试。 ## 仅限授权使用 ghostpwn 专为授权的安全评估而设计。请仅针对您拥有或获得明确书面测试许可的系统运行它。操作者需对保持在商定范围和法律规定内负全部责任。内置的示例工作流默认指向占位目标；离线示例完全不涉及网络。 ## 安装 需要 Python 3.11+。 ``` git clone https://github.com/joemunene-by/ghostpwn cd ghostpwn python -m venv .venv && source .venv/bin/activate pip install -e ".[dev]" ``` 这将安装 `ghostpwn` 控制台脚本。 ## 快速开始 运行完全离线的模拟工作流并查看综合报告： ``` ghostpwn run examples/mock_recon.yaml ``` 控制台报告示例： ``` ╭─────────────────────────────────────────────╮ │ ghostpwn run: mock-recon-demo target=example.com │ ╰─────────────────────────────────────────────╯ Stage results ┏━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━┓ ┃ stage ┃ adapter ┃ status ┃ duration ┃ findings ┃ detail ┃ ┡━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━┩ │ discover │ mock │ success │ 0.00s │ 1 │ │ │ enumerate │ mock │ success │ 0.00s │ 1 │ │ │ fingerprint │ mock │ success │ 0.00s │ 1 │ │ │ report │ mock │ success │ 0.00s │ 0 │ │ └─────────────┴─────────┴─────────┴──────────┴──────────┴────────┘ Findings rollup ┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┓ ┃ severity ┃ title ┃ description ┃ ┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━┩ │ medium │ outdated TLS configuration ... │ Server ... TLS 1.0│ │ low │ open SSH service on 10.0.0.5 │ Port 22 accepts ..│ │ info │ host 10.0.0.5 responds ... │ ICMP echo reply │ └──────────┴────────────────────────────────┴───────────────────┘ ╭──────────────────────────────────────────────────────────────╮ │ PASS stages: 4 ok, 0 failed, 0 error, 0 skipped | findings:│ │ 0 critical, 0 high, 1 medium, 1 low, 1 info │ ╰──────────────────────────────────────────────────────────────╯ ``` 检查已解析的 DAG 和并行执行层： ``` ghostpwn graph examples/mock_recon.yaml ``` 列出已注册的适配器： ``` ghostpwn adapters ``` ## CLI | 命令 | 描述 | | --- | --- | | `ghostpwn run ` | 验证并执行工作流，生成报告。 | | `ghostpwn validate ` | 解析并进行语义验证，但不运行。 | | `ghostpwn graph ` | 打印拓扑顺序和并行层。 | | `ghostpwn adapters` | 列出所有已注册的适配器。 | | `ghostpwn version` | 打印版本号。 | `run` 的参数标志：`--target`、`--var key=value`（可重复使用）、`--output DIR`、`--format {console,json}`、`--concurrency N`、`--dry-run`、`--verbose`。 ## 工作流 schema 工作流是一个 YAML 映射，包含一个 `name`、一个可选的 `target`、可选的共享 `vars` 以及一个 `stages` 列表。每个阶段都有一个 `id`、一个 `adapter`、可选的 `params` 以及可选的 `needs`（它所依赖的 id）。 ``` name: web-assessment # required, unique workflow name target: example.com # optional default target, overridable with --target vars: # optional shared variables scheme: https stages: - id: dns # required, unique within the workflow adapter: dns_recon # required, must be a registered adapter description: "Resolve records." params: # adapter-specific, templated (see below) domain: "${{ target }}" records: ["A", "AAAA", "MX"] - id: probe adapter: http_probe needs: [dns] # runs only after `dns` completes params: url: "${{ vars.scheme }}://${{ target }}" - id: nmap adapter: command needs: [dns] # independent of `probe`, runs in parallel with it continue_on_error: true # a failure here does not skip dependents timeout: 120 # per-stage timeout in seconds params: cmd: nmap args: ["-Pn", "-F", "${{ target }}"] allow_nonzero: true ``` 各阶段选项：`continue_on_error`（默认为 false）、`timeout`（秒，可选）、`description`（可选）。 ## DAG、并行执行与数据传递 ghostpwn 根据 `needs` 边构建有向无环图 (DAG)。它会： - 对阶段进行拓扑排序，并以明确的错误提示拒绝循环； - 将阶段分组到不同层，同一层中的所有阶段都可以并发运行； - 按照 `--concurrency` 并行执行阶段，并严格遵循 `needs` 的顺序； - 强制执行各阶段的超时限制。 阶段之间会向前传递数据。后续阶段可以使用受限的 `${{ ... }}` 语法来引用早期阶段的结构化输出、工作流变量或目标： - `${{ target }}` 用于解析工作流目标。 - `${{ vars.key }}` 用于解析工作流变量。 - `${{ stages..outputs. }}` 用于解析前序阶段的输出。 - 支持列表索引：`${{ stages.discover.outputs.hosts.0 }}`。 这种替换是纯粹的字典遍历过程。其中不涉及 `eval` 或 `exec`，也没有任意的表达式求值，因此模板永远无法执行代码。未知的引用会直接引发错误，而不是默默地解析为空字符串。当整个参数值是一个单一表达式时，解析后的值会保留其原始类型（列表仍然是列表）；而内嵌的表达式则会作为字符串进行插值处理。 ## 失败策略 - 失败或出错的阶段会将其间接依赖项标记为 `skipped`。 - 标记为 `continue_on_error: true` 的阶段允许其依赖项继续运行。 - 独立的阶段不受其他无关失败的影响。 - 只有当没有任何阶段失败或出错时，一次运行的总体状态才会是 PASS。 ## 适配器 | 适配器 | 用途 | | --- | --- | | `mock` | 确定性且无副作用。用于支持演示和测试。 | | `command` | 安全运行任何外部 CLI（采用 argv 向量，无 shell，包含超时设置和 JSON 解析）。 | | `http_probe` | 探测 HTTP endpoint 并评估安全标头（使用 httpx）。 | | `dns_recon` | 解析域名的 DNS 记录（使用 dnspython）。 | ### 接入真实工具 (ghostrecon, ghostmap, nmap) `command` 适配器是在零代码改动下运行真实工具的切入点。 它在 `shell=False` 的情况下执行显式参数向量，因此不存在命令注入的风险；同时它会捕获 stdout 和 stderr，强制执行超时限制，并能够将 JSON 输出解析为结构化的阶段输出，供后续阶段作为模板使用。 ``` - id: recon adapter: command params: cmd: ghostrecon args: ["scan", "${{ target }}", "--profile", "passive", "--format", "json"] parse_json: true timeout: 120 - id: map adapter: command needs: [recon] params: cmd: ghostmap args: ["--target", "${{ target }}", "--json"] parse_json: true ``` 完整链路请参见 `examples/ghost_tools.yaml`。 ### 添加适配器 继承 `Adapter` 类，设置唯一的 `name`，实现 `run` 方法，然后注册它。 ``` from ghostpwn.adapters import register from ghostpwn.adapters.base import Adapter, StageContext from ghostpwn.models import StageResult, StageStatus, Finding, Severity class MyAdapter(Adapter): name = "my_tool" def validate_params(self, params: dict) -> None: if "target_path" not in params: from ghostpwn.errors import AdapterError raise AdapterError("my_tool requires 'target_path'") def run(self, context: StageContext) -> StageResult: # `run` may be sync (run in a worker thread) or `async def` (awaited). return StageResult( stage_id=context.stage_id, adapter=self.name, status=StageStatus.SUCCESS, outputs={"checked": context.param("target_path")}, findings=[Finding(title="example", severity=Severity.INFO)], ) register(MyAdapter()) ``` 适配器会接收一个 `StageContext`，其中包含已解析的 `params`、`target`、工作流 `vars` 和 `prior_outputs`；并返回一个 `StageResult`，其中携带了状态、结构化的 `outputs`、`findings` 和 `artifacts`。 ## 输出 `--output DIR` 会将 `report.json` 以及各阶段的 JSON 持久化保存到 `DIR/stages/` 目录下。 `--format json` 会将综合报告以 JSON 格式打印到 stdout。 ## 路线图 - 通过 entry points 发现适配器插件。 - 为每个阶段提供重试和退避策略。 - 基于严重程度阈值的门控（当超过特定严重级别时判定运行失败）。 - 为 ghostsuite 中的其他工具提供原生适配器。 - 支持 SARIF 和 HTML 报告导出器。 ## 许可证 MIT，详见 [LICENSE](LICENSE)。 _{属于 ghostsuite 的一部分：十一款开源安全工具，同一个 ghost。}

标签：Python, 任务调度, 密码管理, 插件系统, 无后门, 自动化编排, 运行时操纵, 逆向工具