reverse-engineer-rpi

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/reverse-engineer-rpi

Reverse-engineer a product into a mechanically verifiable feature inventory + registry + spec set, with optional security-audit artifacts and validation gates.

将产品逆向工程为可机械验证的功能清单+注册表+规格集，可附带安全审计工件和验证关卡。

Hard Guardrails (MANDATORY)

硬性约束（强制执行）

Only operate on code/binaries you own or have explicit written authorization to analyze.
Do not provide steps to bypass protections/ToS or to extract proprietary source code/system prompts from third-party products.
Do not output reconstructed proprietary source or embedded prompts from binaries (index only; redact in reports).
Redact secrets/tokens/keys if encountered; run the secret-scan gate over outputs.
Always separate: docs say vs code proves vs hosted/control-plane.

仅可对您拥有或获得明确书面授权的代码/二进制文件进行分析。
不得提供绕过保护措施/服务条款或从第三方产品中提取专有源代码/系统提示的步骤。
不得输出从二进制文件重构的专有源代码或嵌入提示（仅建立索引；在报告中进行脱敏）。
若遇到密钥/令牌/密钥需进行脱敏；对输出内容运行密钥扫描关卡。
始终区分：文档声称 vs 代码实际实现 vs 托管/控制平面。

One-Command Example

单命令示例

bash

python3 skills/reverse-engineer-rpi/scripts/reverse_engineer_rpi.py ao \
  --authorized \
  --mode=binary \
  --binary-path="$(command -v ao)" \
  --output-dir=".agents/research/ao/"

If you do not have explicit written authorization to analyze that binary, do not run the above. Use the included demo fixture instead (see Self-Test below).

Repo-only example (no binary required):

bash

python3 skills/reverse-engineer-rpi/scripts/reverse_engineer_rpi.py cc-sdd \
  --mode=repo \
  --upstream-repo="https://github.com/gotalab/cc-sdd.git" \
  --output-dir=".agents/research/cc-sdd/"

bash

python3 skills/reverse-engineer-rpi/scripts/reverse_engineer_rpi.py ao \
  --authorized \
  --mode=binary \
  --binary-path="$(command -v ao)" \
  --output-dir=".agents/research/ao/"

如果您没有分析该二进制文件的明确书面授权，请勿运行上述命令。请改用附带的演示测试用例（见下文的自我测试）。

仅仓库示例（无需二进制文件）：

bash

python3 skills/reverse-engineer-rpi/scripts/reverse_engineer_rpi.py cc-sdd \
  --mode=repo \
  --upstream-repo="https://github.com/gotalab/cc-sdd.git" \
  --output-dir=".agents/research/cc-sdd/"

Invocation Contract

调用约定

Required:

```
product_name
```

Optional:

```
--docs-sitemap-url
```
(recommended when available; supports
```
https://...
```
and
```
file:///...
```
)
```
--docs-features-prefix
```
(default:
```
docs/features/
```
)
```
--upstream-repo
```
(optional)
```
--local-clone-dir
```
(default:
```
.tmp/<product_name>
```
)

--output-dir

(default:

.agents/research/<product_name>/

)

```
--mode
```
(default:
```
binary
```
; allowed:
```
repo|binary|both
```
)
```
--binary-path
```
(required if
```
--mode
```
includes
```
binary
```
)
```
--no-materialize-archives
```
(authorized-only; binary mode extracts embedded ZIPs by default; this disables extraction and keeps index-only)

Security audit flags (optional):

```
--security-audit
```
(enables security artifacts + gates)
```
--sbom
```
(generate SBOM + dependency risk report where possible; may no-op with a note)
```
--fuzz
```
(only if a safe harness exists; timeboxed)

Mandatory guardrail flag:

```
--authorized
```
(required for binary mode; refuses to run binary analysis without it)

必填项：

```
product_name
```

可选项：

--docs-sitemap-url

（如有可用则推荐；支持

https://...

和

file:///...

）

```
--docs-features-prefix
```
（默认值：
```
docs/features/
```
）
```
--upstream-repo
```
（可选）
```
--local-clone-dir
```
（默认值：
```
.tmp/<product_name>
```
）

--output-dir

（默认值：

.agents/research/<product_name>/

）

```
--mode
```
（默认值：
```
binary
```
；允许值：
```
repo|binary|both
```
）
```
--binary-path
```
（若
```
--mode
```
包含
```
binary
```
则为必填项）
```
--no-materialize-archives
```
（仅授权用户可用；二进制模式默认提取嵌入的ZIP文件；此参数将禁用提取，仅保留索引）

安全审计标志（可选）：

```
--security-audit
```
（启用安全工件+关卡）
```
--sbom
```
（尽可能生成SBOM+依赖风险报告；可能无操作并给出说明）
```
--fuzz
```
（仅当存在安全测试harness时使用；限时运行）

强制约束标志：

```
--authorized
```
（二进制模式必填；无此标志将拒绝运行二进制分析）

Script-Driven Workflow

脚本驱动的工作流

Run:

bash

python3 skills/reverse-engineer-rpi/scripts/reverse_engineer_rpi.py <product_name> --authorized [flags...]

This generates the required outputs under

output_dir/

and (when applicable)

.agents/council/

and

.agents/learnings/

运行：

bash

python3 skills/reverse-engineer-rpi/scripts/reverse_engineer_rpi.py <product_name> --authorized [flags...]

这会在

output_dir/

下生成所需输出，适用时还会在

.agents/council/

和

.agents/learnings/

下生成。

Outputs (MUST be generated)

输出内容（必须生成）

Core outputs under

output_dir/

```
feature-inventory.md
```
```
feature-registry.yaml
```
```
validate-feature-registry.py
```
```
feature-catalog.md
```
```
spec-architecture.md
```
```
spec-code-map.md
```
```
spec-cli-surface.md
```
(only if a CLI exists; otherwise a note is written to
```
spec-code-map.md
```
)
```
spec-clone-vs-use.md
```
```
spec-clone-mvp.md
```
(original MVP spec; do not copy from target)

Binary-mode extras:

```
binary-analysis.md
```
(best-effort summary)
```
binary-embedded-archives.md
```
(index only; no dumps)

--security-audit

, also create

output_dir/security/

```
threat-model.md
```
```
attack-surface.md
```
```
dataflow.md
```
```
crypto-review.md
```
```
authn-authz.md
```
```
findings.md
```
```
reproducibility.md
```
```
validate-security-audit.sh
```

output_dir/

下的核心输出：

```
feature-inventory.md
```
```
feature-registry.yaml
```
```
validate-feature-registry.py
```
```
feature-catalog.md
```
```
spec-architecture.md
```
```
spec-code-map.md
```
```
spec-cli-surface.md
```
（仅当存在CLI时生成；否则会在
```
spec-code-map.md
```
中添加说明）
```
spec-clone-vs-use.md
```
```
spec-clone-mvp.md
```
（原始MVP规格；请勿复制目标产品内容）

二进制模式额外输出：

```
binary-analysis.md
```
（尽最大努力生成的摘要）
```
binary-embedded-archives.md
```
（仅索引；不转储内容）

若启用

--security-audit

，还会创建

output_dir/security/

```
threat-model.md
```
```
attack-surface.md
```
```
dataflow.md
```
```
crypto-review.md
```
```
authn-authz.md
```
```
findings.md
```
```
reproducibility.md
```
```
validate-security-audit.sh
```

Self-Test (Acceptance Criteria)

自我测试（验收标准）

End-to-end fixture (safe, owned demo binary with embedded ZIP):

bash

bash skills/reverse-engineer-rpi/scripts/self_test.sh

This must show:

feature inventory generated
registry generated
registry validator exits 0
in security mode:
```
validate-security-audit.sh
```
exits 0 and secret scan passes

端到端测试用例（安全、自有演示二进制文件，含嵌入ZIP）：

bash

bash skills/reverse-engineer-rpi/scripts/self_test.sh

测试必须显示：

已生成功能清单
已生成注册表
注册表验证器退出码为0
安全模式下：
```
validate-security-audit.sh
```
退出码为0且密钥扫描通过