Metadata-Version: 2.1
Name: clawnexus-cli-sdk
Version: 1.3.0
Summary: ClawNexus (洞察·灵枢) Dual Commercial CLI SDK v1.3: TLS 1.3 SPKI Pinning + HMAC-SHA256 v2 + PCDN FlowSketch Scan (clawbox & clawprobe)
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# `cli_sdk` — ClawNexus (`洞察·灵枢`) 零依赖商用双 CLI 套件 (v1.3)

> **模块定位**：面向外部商用客户、企业研发 CI/CD 与边缘路由探针的零第三方依赖 Python 标准库双 CLI 套件（强制 `TLS 1.3` + 默认开启边缘证书 `SPKI SHA-256` 公钥指纹固定校验 + `HMAC-SHA256 v2` 全请求体与排序查询串防重放签名鉴权）。

## 包含工具
1. **`clawbox`**（[clawbox_cli/cli.py](file:///Users/hzwzzhy/项目/ClawNexus/cli_sdk/clawbox_cli/cli.py)）：免解密加密流量应用识别、17 类第三方 SDK 识别、多子网分片分发类 PCDN 滑动窗口拓扑与包络技术检测（内置本地 `.fsk.jsonl.gz` `FlowSketch` 预提取器 [local_pcap_to_flowsketch.py](file:///Users/hzwzzhy/项目/ClawNexus/cli_sdk/clawbox_cli/local_pcap_to_flowsketch.py)）及设备级时间线分析 CLI。
2. **`clawprobe`**（[clawprobe_cli/cli.py](file:///Users/hzwzzhy/项目/ClawNexus/cli_sdk/clawprobe_cli/cli.py)）：移动应用 APK 300s 三阶段受控沙箱动态网络行为技术检测、研发隐私合规 CI 门禁（`--fail-on-preconsent`）与 JSON/PDF《移动应用网络行为与加密流量技术检测分析报告》拉取 CLI。

## 传输与签名安全机制
- **默认开启 `TLS 1.3` `SPKI` 公钥指纹固定（Certificate Pinning）**：客户端内置 `N100` 边缘网关证书与 `SubjectPublicKeyInfo` `SHA-256` 指纹（`PHijXDkakE3X7ORsNTDl9Gu+Dp2i30HnJgbkZ5Y++3g=`），在发送任何 `APIKEY` 或报文前完成公钥钉扎校验，彻底防御中间人劫持（后续切换公共 CA 证书时可通过 `--spki-pin` 平滑轮换）。
- **全报文规范签名（`HMAC-SHA256 v2`）**：签名规范串为 `METHOD\npath?sorted_query\nts\nnonce\nsha256(完整原始请求体)`，覆盖 URL 查询参数与所有 `multipart/form-data` 表单字段及二进制载荷。
- **客户合法授权声明（`--attest-authorized`）**：提交 APK 样本前须显式传入 `--attest-authorized`（对应服务端 `authorization_attested=true`），确认对被测样本拥有合法所有权或书面检测授权，参见《[ClawNexus 商业技术检测服务条款与客户授权声明（CNX-TOS-2026.10-v1）](file:///Users/hzwzzhy/项目/ClawNexus/docs/ClawNexus_商业技术检测服务条款与客户授权声明草案.md)》。

## 系统与运行环境要求（尤其 macOS `TLS 1.3` 说明）
- **Python 与 TLS 库版本硬性要求**：需 **Python 3.10+** 且底层链接 **`OpenSSL >= 1.1.1` / `OpenSSL 3.x`**（边缘网关 `N100 :58095` 强制纯 `TLS 1.3` + `SPKI` 公钥指纹固定校验）。
- **macOS 特别提醒**：macOS 系统自带的 `/usr/bin/python3`（`3.9.6`）底层链接 Apple `LibreSSL 2.8.3`（`ssl.HAS_TLSv1_3 == False`），直接运行会在 `TLS 1.3` 握手阶段报错。在 macOS 上请先通过 Homebrew 安装带 `OpenSSL 3` 的 Python 3.10+（推荐 `Python 3.12`）：
  ```bash
  brew install python@3.12
  /opt/homebrew/bin/python3.12 -c "import ssl; print(ssl.OPENSSL_VERSION, 'HAS_TLSv1_3=', ssl.HAS_TLSv1_3)"
  ```
  *(注：若终端开启了全局 TUN 虚拟网卡代理 `utun*`，请关闭代理或将 `122.224.166.126` 设为直连，避免代理劫持导致 `SPKI` 公钥钉扎拦截。)*

## 独立虚拟环境安装规范
```bash
# Linux (Ubuntu 22.04/24.04 等自带 Python 3.10+ & OpenSSL 3.x)：
python3 -m venv .venv_clawnexus_cli

# macOS (Apple Silicon Homebrew Python 3.12；Intel Mac 请改用 /usr/local/bin/python3.12)：
/opt/homebrew/bin/python3.12 -m venv .venv_clawnexus_cli

.venv_clawnexus_cli/bin/pip install --no-deps ./cli_sdk/dist/clawnexus_cli_sdk-1.3.0-py3-none-any.whl
```

## 快速上手
```bash
# 1. 登录并保存 APIKEY 与 HMAC 签名密钥（0600 权限落盘至 ~/.clawnexus/credentials.json，默认开启 SPKI 证书钉扎）
clawbox auth login --endpoint https://122.224.166.126:58095 --api-key cnx_live_xxx --secret sec_xxx

# 2. 加密流量包络识别、PCDN 多子网分片拓扑扫描与时间线查询
clawbox auth verify
clawbox status
clawbox profile ./capture.pcap --device-id office-gw-01 --format table
clawbox pcdn-scan ./campus_egress.pcap --device-id campus-core-01 --local-cidr 192.168.0.0/16 --format table
clawbox timeline --device-id campus-core-01 --window 3600 --pcdn-only --format table
clawbox timeline --device-id office-gw-01 --window 3600 --format table

# 3. 提交获授权 APK 执行 300s 三阶段动态技术检测并拉取 PDF/JSON 技术检测分析报告
clawprobe analyze ./app.apk --attest-authorized --mode privacy --fail-on-preconsent --out ./report.pdf --json-out ./report.json
clawprobe job <job_id> --out ./report.pdf --bundle ./tech_bundle.zip
```
