clawprobe 1.3.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- clawprobe-1.3.0/LICENSE +108 -0
- clawprobe-1.3.0/PKG-INFO +159 -0
- clawprobe-1.3.0/README.md +129 -0
- clawprobe-1.3.0/pyproject.toml +57 -0
- clawprobe-1.3.0/setup.cfg +4 -0
- clawprobe-1.3.0/src/clawprobe/__init__.py +3 -0
- clawprobe-1.3.0/src/clawprobe/__main__.py +8 -0
- clawprobe-1.3.0/src/clawprobe/cli.py +383 -0
- clawprobe-1.3.0/src/clawprobe/client.py +471 -0
- clawprobe-1.3.0/src/clawprobe.egg-info/PKG-INFO +159 -0
- clawprobe-1.3.0/src/clawprobe.egg-info/SOURCES.txt +13 -0
- clawprobe-1.3.0/src/clawprobe.egg-info/dependency_links.txt +1 -0
- clawprobe-1.3.0/src/clawprobe.egg-info/entry_points.txt +2 -0
- clawprobe-1.3.0/src/clawprobe.egg-info/top_level.txt +1 -0
- clawprobe-1.3.0/tests/test_clawprobe_offline.py +102 -0
clawprobe-1.3.0/LICENSE
ADDED
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
Apache License
|
|
2
|
+
Version 2.0, January 2004
|
|
3
|
+
http://www.apache.org/licenses/
|
|
4
|
+
|
|
5
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
6
|
+
|
|
7
|
+
1. Definitions.
|
|
8
|
+
|
|
9
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
10
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
11
|
+
|
|
12
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
13
|
+
the copyright owner that is granting the License.
|
|
14
|
+
|
|
15
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
16
|
+
other entities that control, are controlled by, or are under common
|
|
17
|
+
control with that entity.
|
|
18
|
+
|
|
19
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
20
|
+
exercising permissions granted by this License.
|
|
21
|
+
|
|
22
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
23
|
+
including but not limited to software source code, documentation
|
|
24
|
+
source, and configuration files.
|
|
25
|
+
|
|
26
|
+
"Object" form shall mean any form resulting from mechanical
|
|
27
|
+
transformation or translation of a Source form, including but
|
|
28
|
+
not limited to compiled object code, generated documentation,
|
|
29
|
+
and conversions to other media types.
|
|
30
|
+
|
|
31
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
32
|
+
Object form, made available under the License, as indicated by a
|
|
33
|
+
copyright notice that is included in or attached to the work.
|
|
34
|
+
|
|
35
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
36
|
+
form, that is based on (or derived from) the Work and for which the
|
|
37
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
38
|
+
represent, as a whole, an original work of authorship.
|
|
39
|
+
|
|
40
|
+
"Contribution" shall mean any work of authorship, including
|
|
41
|
+
the original version of the Work and any modifications or additions
|
|
42
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
43
|
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
|
44
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
45
|
+
the copyright owner.
|
|
46
|
+
|
|
47
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
48
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
49
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
50
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
51
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
52
|
+
Work and such Derivative Works in Source or Object form.
|
|
53
|
+
|
|
54
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
55
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
56
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
57
|
+
(except as stated in this section) patent license to make, have made,
|
|
58
|
+
use, offer to sell, sell, import, and otherwise transfer the Work.
|
|
59
|
+
|
|
60
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
61
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
62
|
+
modifications, and in Source or Object form, provided that You
|
|
63
|
+
meet the following conditions:
|
|
64
|
+
|
|
65
|
+
(a) You must give any other recipients of the Work or
|
|
66
|
+
Derivative Works a copy of this License; and
|
|
67
|
+
|
|
68
|
+
(b) You must cause any modified files to carry prominent notices
|
|
69
|
+
stating that You changed the files; and
|
|
70
|
+
|
|
71
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
72
|
+
that You distribute, all copyright, patent, trademark, and
|
|
73
|
+
attribution notices from the Source form of the Work; and
|
|
74
|
+
|
|
75
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
76
|
+
distribution, then any Derivative Works that You distribute must
|
|
77
|
+
include a readable copy of the attribution notices contained
|
|
78
|
+
within such NOTICE file.
|
|
79
|
+
|
|
80
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
81
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
82
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
83
|
+
this License, without any additional terms or conditions.
|
|
84
|
+
|
|
85
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
86
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
87
|
+
except as required for reasonable and customary use in describing the
|
|
88
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
89
|
+
|
|
90
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
91
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
92
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
93
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
94
|
+
implied, including, without limitation, any warranties or conditions
|
|
95
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
96
|
+
PARTICULAR PURPOSE.
|
|
97
|
+
|
|
98
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
99
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
100
|
+
unless required by applicable law (such as deliberate and grossly
|
|
101
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
102
|
+
liable to You for damages, including any direct, indirect, special,
|
|
103
|
+
incidental, or consequential damages of any character arising as a
|
|
104
|
+
result of this License or out of the use or inability to use the
|
|
105
|
+
Work.
|
|
106
|
+
|
|
107
|
+
Copyright 2026 ClawProbe (https://www.atooli.com)
|
|
108
|
+
Licensed under the Apache License, Version 2.0 (the "License").
|
clawprobe-1.3.0/PKG-INFO
ADDED
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: clawprobe
|
|
3
|
+
Version: 1.3.0
|
|
4
|
+
Summary: ClawProbe (洞察·灵枢): Zero-Dependency Mobile APK 300s Live Dynamic Privacy Inspection & CI/CD Gate CLI
|
|
5
|
+
Author-email: ClawProbe Security Team <876387@gmail.com>
|
|
6
|
+
License: Apache-2.0
|
|
7
|
+
Project-URL: Homepage, https://www.atooli.com
|
|
8
|
+
Project-URL: Documentation, https://www.atooli.com/#docs-cli
|
|
9
|
+
Project-URL: Repository, https://github.com/876387/clawprobe
|
|
10
|
+
Project-URL: Issues, https://github.com/876387/clawprobe/issues
|
|
11
|
+
Keywords: android,apk,privacy,compliance,miit,devsecops,ci-cd,security-testing,network-analysis
|
|
12
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
13
|
+
Classifier: Environment :: Console
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Intended Audience :: Information Technology
|
|
16
|
+
Classifier: License :: OSI Approved :: Apache Software License
|
|
17
|
+
Classifier: Operating System :: OS Independent
|
|
18
|
+
Classifier: Programming Language :: Python :: 3
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
23
|
+
Classifier: Topic :: Security
|
|
24
|
+
Classifier: Topic :: Software Development :: Quality Assurance
|
|
25
|
+
Classifier: Topic :: Software Development :: Testing
|
|
26
|
+
Requires-Python: >=3.9
|
|
27
|
+
Description-Content-Type: text/markdown
|
|
28
|
+
License-File: LICENSE
|
|
29
|
+
Dynamic: license-file
|
|
30
|
+
|
|
31
|
+
# ClawProbe CLI (`clawprobe`)
|
|
32
|
+
|
|
33
|
+
[](https://opensource.org/licenses/Apache-2.0)
|
|
34
|
+
[](https://www.python.org/downloads/)
|
|
35
|
+
[-brightgreen.svg)](https://pypi.org/project/clawprobe/)
|
|
36
|
+
|
|
37
|
+
**ClawProbe CLI** 是 **ClawProbe 移动应用 300 秒真机动态技术体检与 CI/CD 隐私门禁平台**([https://www.atooli.com](https://www.atooli.com))的官方命令行客户端。
|
|
38
|
+
|
|
39
|
+
基于 **100% Python 标准库(Zero Third-Party Dependencies)** 构建,内置 **HMAC-SHA256 v2 全报文防重放签名** 与 **证书链公钥指纹校验(SPKI Pinning / Embedded CA)**,开箱即可嵌入 GitHub Actions、GitLab CI、Jenkins 等企业级 DevSecOps 流水线,在每次发版前自动拦截 **「用户点击隐私弹窗同意前抢跑联网」** 等隐私合规隐患。
|
|
40
|
+
|
|
41
|
+
---
|
|
42
|
+
|
|
43
|
+
## 核心特性 (Key Features)
|
|
44
|
+
|
|
45
|
+
1. **零第三方依赖 (Zero External Dependencies)**:仅依赖 Python 3.9+ 标准库(`ssl`、`http.client`、`hashlib`、`hmac`、`json`),无需编译 C 扩展,无第三方供应链依赖风险。
|
|
46
|
+
2. **300 秒三阶段真机沙箱时序体检 (300s 3-Stage Live Sandbox Inspection)**:
|
|
47
|
+
- **Stage 1 (`pre_consent` · 0~45s)**:冷启动静默期(未点击隐私弹窗同意前)网络通信五元组、DNS/SNI 与敏感留痕检测;
|
|
48
|
+
- **Stage 2 (`post_consent` · 45~255s)**:点击同意隐私弹窗后 UI 自动化遍历与第三方 SDK 加密框架清单盘点;
|
|
49
|
+
- **Stage 3 (`background` · 255~300s)**:退后台静默期心跳、唤醒、静默上传与高损耗 UDP/PCDN 传输行为观测。
|
|
50
|
+
3. **CI/CD 确定性退出码门禁 (Deterministic Exit Codes)**:通过 `--fail-on-preconsent` 自动阻断存在未同意前抢跑通信的构建任务(返回 `Exit Code 2`)。
|
|
51
|
+
4. **队列拥塞智能指数退避 (Smart Queue Backoff)**:高并发场景下遇 `HTTP 429 (ERR_P0_HOT_SPARE_BUSY)` 自动在 `--queue-timeout` 窗口内指数退避重试,保障夜间流水线稳定收敛。
|
|
52
|
+
5. **一键 3 遍覆写物理销毁 (`--reclaim`)**:下载完本地 PDF/JSON/ZIP 证据包后,支持在流水线末尾自动触发云端工件 3 遍覆写物理清零并返回 SHA-256 销毁回执。
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
## 快速安装 (Installation)
|
|
57
|
+
|
|
58
|
+
推荐使用 `pipx` 或 `pip` 直接从官方 PyPI 安装:
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
# 推荐:使用 pipx 隔离安装全局命令(含官方 PEP 503 高速镜像源,国内 20ms 直连)
|
|
62
|
+
pipx install --pip-args="--extra-index-url https://www.atooli.com/simple" clawprobe
|
|
63
|
+
|
|
64
|
+
# 或使用 pip 安装
|
|
65
|
+
pip install -U --extra-index-url https://www.atooli.com/simple clawprobe
|
|
66
|
+
|
|
67
|
+
# 也可直接从 GitHub Release 安装
|
|
68
|
+
pip install -U https://github.com/876387/clawprobe/releases/download/v1.3.0/clawprobe-1.3.0-py3-none-any.whl
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
安装完成后,可执行一键环境与链路自检(无需 API Key):
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
clawprobe doctor
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
---
|
|
78
|
+
|
|
79
|
+
## 快速上手 (Quick Start)
|
|
80
|
+
|
|
81
|
+
### 1. 配置访问凭据
|
|
82
|
+
|
|
83
|
+
前往 [ClawProbe 官网工作台 (https://www.atooli.com)](https://www.atooli.com) 申请试用或生产凭据后,配置环境变量或执行 `auth login`:
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
# 方式 A:环境变量(适合 CI/CD 流水线)
|
|
87
|
+
export CLAW_API_KEY="cnx_live_your_key_id"
|
|
88
|
+
export CLAW_API_SECRET="sec_your_hmac_secret"
|
|
89
|
+
|
|
90
|
+
# 方式 B:本地持久化登录(权限自动锁定为 0600)
|
|
91
|
+
clawprobe auth login --api-key cnx_live_your_key_id --secret sec_your_hmac_secret
|
|
92
|
+
|
|
93
|
+
# 验证鉴权与当前剩余额度
|
|
94
|
+
clawprobe auth verify
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
### 2. 提交 APK 并启用发版前隐私门禁
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
clawprobe analyze ./app-release.apk \
|
|
101
|
+
--attest-authorized \
|
|
102
|
+
--mode privacy \
|
|
103
|
+
--fail-on-preconsent \
|
|
104
|
+
--queue-timeout 900 \
|
|
105
|
+
--out ./clawprobe-report.pdf \
|
|
106
|
+
--json-out ./clawprobe-report.json \
|
|
107
|
+
--reclaim
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
- 若检测完成且 **Stage 1(未同意隐私政策前)** 未发现抢跑外联,命令返回 `Exit Code 0`,并将结构化 JSON 与中英双语 PDF 技术体检报告写入本地。
|
|
111
|
+
- 若发现未同意前抢跑外联,命令在终端打印 `[FL-xxxx]` 证据锚点摘要并返回 `Exit Code 2`,直接阻断 CI 发版流水线。
|
|
112
|
+
|
|
113
|
+
### 3. 查询历史任务与手动物理销毁云端工件
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
# 查询任务并下载完整 ZIP 证据包(含 PDF + JSON + PCAP + SHA256 清单)
|
|
117
|
+
clawprobe job <job_id> \
|
|
118
|
+
--out ./report.pdf \
|
|
119
|
+
--json-out ./report.json \
|
|
120
|
+
--bundle ./evidence-bundle.zip
|
|
121
|
+
|
|
122
|
+
# 立即触发云端任务工件 3 遍覆写物理销毁
|
|
123
|
+
clawprobe reclaim <job_id>
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
---
|
|
127
|
+
|
|
128
|
+
## CI/CD 退出码规范 (Exit Codes)
|
|
129
|
+
|
|
130
|
+
| Exit Code | 含义 (Meaning) | 触发场景 (Scenario) |
|
|
131
|
+
| :--- | :--- | :--- |
|
|
132
|
+
| `0` | **PASS (合规通过)** | 任务完成,且未触发 `--fail-on-preconsent` 门禁条件 |
|
|
133
|
+
| `1` | **USAGE_OR_AUTH_ERROR (参数/鉴权异常)** | 参数缺失、未勾选 `--attest-authorized`、API Key 或 HMAC 签名错误 |
|
|
134
|
+
| `2` | **PRIVACY_GATE_TRIGGERED (门禁拦截)** | 启用 `--fail-on-preconsent` 时,检测到同意隐私政策前发生抢跑联网行为 |
|
|
135
|
+
| `3` | **QUOTA_EXCEEDED (配额/包名超限)** | 检测额度耗尽 (`ERR_QUOTA_EXCEEDED`) 或超出账号绑定的包名上限 |
|
|
136
|
+
| `4` | **NETWORK_OR_QUEUE_TIMEOUT (网络/排队超时)** | 网络不可达、SPKI 证书指纹校验失败或超过 `--queue-timeout` 等待窗口 |
|
|
137
|
+
|
|
138
|
+
---
|
|
139
|
+
|
|
140
|
+
## CI/CD 流水线集成模板 (CI/CD Templates)
|
|
141
|
+
|
|
142
|
+
仓库内置开箱即用的流水线模板,可直接复制到您的工程中:
|
|
143
|
+
|
|
144
|
+
- **GitHub Actions**:[`ci-templates/github/privacy-gate.yml`](./ci-templates/github/privacy-gate.yml)
|
|
145
|
+
- **GitLab CI**:[`ci-templates/gitlab/.gitlab-ci.yml`](./ci-templates/gitlab/.gitlab-ci.yml)
|
|
146
|
+
- **结构化报告样卷**:[`samples/sample_report.json`](./samples/sample_report.json)
|
|
147
|
+
|
|
148
|
+
---
|
|
149
|
+
|
|
150
|
+
## 合规与安全声明 (Compliance & Security Notice)
|
|
151
|
+
|
|
152
|
+
1. **合法授权使用**:用户仅可上传并检测其拥有合法著作权或已获明确书面授权的自有 Android 应用包(APK),调用时须显式传入 `--attest-authorized`。
|
|
153
|
+
2. **客观技术留痕**:本工具及云端沙箱输出的检测报告仅客观记录特定运行环境与特定时间窗口内的网络通信五元组、TLS 握手特征及第三方 SDK 特征留痕(`[FL-xxxx]` 锚点),供研发与安全团队开展内部合规自查,不构成任何法律意见或行政/司法鉴定结论。
|
|
154
|
+
3. **开源许可**:本命令行客户端(`clawprobe`)采用 [Apache-2.0 License](./LICENSE) 开源发布。
|
|
155
|
+
|
|
156
|
+
---
|
|
157
|
+
|
|
158
|
+
- **官方网站与在线免登录快检**:[https://www.atooli.com](https://www.atooli.com)
|
|
159
|
+
- **问题反馈 (Issues)**:[https://github.com/876387/clawprobe/issues](https://github.com/876387/clawprobe/issues)
|
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
# ClawProbe CLI (`clawprobe`)
|
|
2
|
+
|
|
3
|
+
[](https://opensource.org/licenses/Apache-2.0)
|
|
4
|
+
[](https://www.python.org/downloads/)
|
|
5
|
+
[-brightgreen.svg)](https://pypi.org/project/clawprobe/)
|
|
6
|
+
|
|
7
|
+
**ClawProbe CLI** 是 **ClawProbe 移动应用 300 秒真机动态技术体检与 CI/CD 隐私门禁平台**([https://www.atooli.com](https://www.atooli.com))的官方命令行客户端。
|
|
8
|
+
|
|
9
|
+
基于 **100% Python 标准库(Zero Third-Party Dependencies)** 构建,内置 **HMAC-SHA256 v2 全报文防重放签名** 与 **证书链公钥指纹校验(SPKI Pinning / Embedded CA)**,开箱即可嵌入 GitHub Actions、GitLab CI、Jenkins 等企业级 DevSecOps 流水线,在每次发版前自动拦截 **「用户点击隐私弹窗同意前抢跑联网」** 等隐私合规隐患。
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## 核心特性 (Key Features)
|
|
14
|
+
|
|
15
|
+
1. **零第三方依赖 (Zero External Dependencies)**:仅依赖 Python 3.9+ 标准库(`ssl`、`http.client`、`hashlib`、`hmac`、`json`),无需编译 C 扩展,无第三方供应链依赖风险。
|
|
16
|
+
2. **300 秒三阶段真机沙箱时序体检 (300s 3-Stage Live Sandbox Inspection)**:
|
|
17
|
+
- **Stage 1 (`pre_consent` · 0~45s)**:冷启动静默期(未点击隐私弹窗同意前)网络通信五元组、DNS/SNI 与敏感留痕检测;
|
|
18
|
+
- **Stage 2 (`post_consent` · 45~255s)**:点击同意隐私弹窗后 UI 自动化遍历与第三方 SDK 加密框架清单盘点;
|
|
19
|
+
- **Stage 3 (`background` · 255~300s)**:退后台静默期心跳、唤醒、静默上传与高损耗 UDP/PCDN 传输行为观测。
|
|
20
|
+
3. **CI/CD 确定性退出码门禁 (Deterministic Exit Codes)**:通过 `--fail-on-preconsent` 自动阻断存在未同意前抢跑通信的构建任务(返回 `Exit Code 2`)。
|
|
21
|
+
4. **队列拥塞智能指数退避 (Smart Queue Backoff)**:高并发场景下遇 `HTTP 429 (ERR_P0_HOT_SPARE_BUSY)` 自动在 `--queue-timeout` 窗口内指数退避重试,保障夜间流水线稳定收敛。
|
|
22
|
+
5. **一键 3 遍覆写物理销毁 (`--reclaim`)**:下载完本地 PDF/JSON/ZIP 证据包后,支持在流水线末尾自动触发云端工件 3 遍覆写物理清零并返回 SHA-256 销毁回执。
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## 快速安装 (Installation)
|
|
27
|
+
|
|
28
|
+
推荐使用 `pipx` 或 `pip` 直接从官方 PyPI 安装:
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
# 推荐:使用 pipx 隔离安装全局命令(含官方 PEP 503 高速镜像源,国内 20ms 直连)
|
|
32
|
+
pipx install --pip-args="--extra-index-url https://www.atooli.com/simple" clawprobe
|
|
33
|
+
|
|
34
|
+
# 或使用 pip 安装
|
|
35
|
+
pip install -U --extra-index-url https://www.atooli.com/simple clawprobe
|
|
36
|
+
|
|
37
|
+
# 也可直接从 GitHub Release 安装
|
|
38
|
+
pip install -U https://github.com/876387/clawprobe/releases/download/v1.3.0/clawprobe-1.3.0-py3-none-any.whl
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
安装完成后,可执行一键环境与链路自检(无需 API Key):
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
clawprobe doctor
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
---
|
|
48
|
+
|
|
49
|
+
## 快速上手 (Quick Start)
|
|
50
|
+
|
|
51
|
+
### 1. 配置访问凭据
|
|
52
|
+
|
|
53
|
+
前往 [ClawProbe 官网工作台 (https://www.atooli.com)](https://www.atooli.com) 申请试用或生产凭据后,配置环境变量或执行 `auth login`:
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
# 方式 A:环境变量(适合 CI/CD 流水线)
|
|
57
|
+
export CLAW_API_KEY="cnx_live_your_key_id"
|
|
58
|
+
export CLAW_API_SECRET="sec_your_hmac_secret"
|
|
59
|
+
|
|
60
|
+
# 方式 B:本地持久化登录(权限自动锁定为 0600)
|
|
61
|
+
clawprobe auth login --api-key cnx_live_your_key_id --secret sec_your_hmac_secret
|
|
62
|
+
|
|
63
|
+
# 验证鉴权与当前剩余额度
|
|
64
|
+
clawprobe auth verify
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
### 2. 提交 APK 并启用发版前隐私门禁
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
clawprobe analyze ./app-release.apk \
|
|
71
|
+
--attest-authorized \
|
|
72
|
+
--mode privacy \
|
|
73
|
+
--fail-on-preconsent \
|
|
74
|
+
--queue-timeout 900 \
|
|
75
|
+
--out ./clawprobe-report.pdf \
|
|
76
|
+
--json-out ./clawprobe-report.json \
|
|
77
|
+
--reclaim
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
- 若检测完成且 **Stage 1(未同意隐私政策前)** 未发现抢跑外联,命令返回 `Exit Code 0`,并将结构化 JSON 与中英双语 PDF 技术体检报告写入本地。
|
|
81
|
+
- 若发现未同意前抢跑外联,命令在终端打印 `[FL-xxxx]` 证据锚点摘要并返回 `Exit Code 2`,直接阻断 CI 发版流水线。
|
|
82
|
+
|
|
83
|
+
### 3. 查询历史任务与手动物理销毁云端工件
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
# 查询任务并下载完整 ZIP 证据包(含 PDF + JSON + PCAP + SHA256 清单)
|
|
87
|
+
clawprobe job <job_id> \
|
|
88
|
+
--out ./report.pdf \
|
|
89
|
+
--json-out ./report.json \
|
|
90
|
+
--bundle ./evidence-bundle.zip
|
|
91
|
+
|
|
92
|
+
# 立即触发云端任务工件 3 遍覆写物理销毁
|
|
93
|
+
clawprobe reclaim <job_id>
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
---
|
|
97
|
+
|
|
98
|
+
## CI/CD 退出码规范 (Exit Codes)
|
|
99
|
+
|
|
100
|
+
| Exit Code | 含义 (Meaning) | 触发场景 (Scenario) |
|
|
101
|
+
| :--- | :--- | :--- |
|
|
102
|
+
| `0` | **PASS (合规通过)** | 任务完成,且未触发 `--fail-on-preconsent` 门禁条件 |
|
|
103
|
+
| `1` | **USAGE_OR_AUTH_ERROR (参数/鉴权异常)** | 参数缺失、未勾选 `--attest-authorized`、API Key 或 HMAC 签名错误 |
|
|
104
|
+
| `2` | **PRIVACY_GATE_TRIGGERED (门禁拦截)** | 启用 `--fail-on-preconsent` 时,检测到同意隐私政策前发生抢跑联网行为 |
|
|
105
|
+
| `3` | **QUOTA_EXCEEDED (配额/包名超限)** | 检测额度耗尽 (`ERR_QUOTA_EXCEEDED`) 或超出账号绑定的包名上限 |
|
|
106
|
+
| `4` | **NETWORK_OR_QUEUE_TIMEOUT (网络/排队超时)** | 网络不可达、SPKI 证书指纹校验失败或超过 `--queue-timeout` 等待窗口 |
|
|
107
|
+
|
|
108
|
+
---
|
|
109
|
+
|
|
110
|
+
## CI/CD 流水线集成模板 (CI/CD Templates)
|
|
111
|
+
|
|
112
|
+
仓库内置开箱即用的流水线模板,可直接复制到您的工程中:
|
|
113
|
+
|
|
114
|
+
- **GitHub Actions**:[`ci-templates/github/privacy-gate.yml`](./ci-templates/github/privacy-gate.yml)
|
|
115
|
+
- **GitLab CI**:[`ci-templates/gitlab/.gitlab-ci.yml`](./ci-templates/gitlab/.gitlab-ci.yml)
|
|
116
|
+
- **结构化报告样卷**:[`samples/sample_report.json`](./samples/sample_report.json)
|
|
117
|
+
|
|
118
|
+
---
|
|
119
|
+
|
|
120
|
+
## 合规与安全声明 (Compliance & Security Notice)
|
|
121
|
+
|
|
122
|
+
1. **合法授权使用**:用户仅可上传并检测其拥有合法著作权或已获明确书面授权的自有 Android 应用包(APK),调用时须显式传入 `--attest-authorized`。
|
|
123
|
+
2. **客观技术留痕**:本工具及云端沙箱输出的检测报告仅客观记录特定运行环境与特定时间窗口内的网络通信五元组、TLS 握手特征及第三方 SDK 特征留痕(`[FL-xxxx]` 锚点),供研发与安全团队开展内部合规自查,不构成任何法律意见或行政/司法鉴定结论。
|
|
124
|
+
3. **开源许可**:本命令行客户端(`clawprobe`)采用 [Apache-2.0 License](./LICENSE) 开源发布。
|
|
125
|
+
|
|
126
|
+
---
|
|
127
|
+
|
|
128
|
+
- **官方网站与在线免登录快检**:[https://www.atooli.com](https://www.atooli.com)
|
|
129
|
+
- **问题反馈 (Issues)**:[https://github.com/876387/clawprobe/issues](https://github.com/876387/clawprobe/issues)
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=64"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "clawprobe"
|
|
7
|
+
version = "1.3.0"
|
|
8
|
+
description = "ClawProbe (洞察·灵枢): Zero-Dependency Mobile APK 300s Live Dynamic Privacy Inspection & CI/CD Gate CLI"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.9"
|
|
11
|
+
license = {text = "Apache-2.0"}
|
|
12
|
+
authors = [
|
|
13
|
+
{name = "ClawProbe Security Team", email = "876387@gmail.com"}
|
|
14
|
+
]
|
|
15
|
+
keywords = [
|
|
16
|
+
"android",
|
|
17
|
+
"apk",
|
|
18
|
+
"privacy",
|
|
19
|
+
"compliance",
|
|
20
|
+
"miit",
|
|
21
|
+
"devsecops",
|
|
22
|
+
"ci-cd",
|
|
23
|
+
"security-testing",
|
|
24
|
+
"network-analysis"
|
|
25
|
+
]
|
|
26
|
+
classifiers = [
|
|
27
|
+
"Development Status :: 5 - Production/Stable",
|
|
28
|
+
"Environment :: Console",
|
|
29
|
+
"Intended Audience :: Developers",
|
|
30
|
+
"Intended Audience :: Information Technology",
|
|
31
|
+
"License :: OSI Approved :: Apache Software License",
|
|
32
|
+
"Operating System :: OS Independent",
|
|
33
|
+
"Programming Language :: Python :: 3",
|
|
34
|
+
"Programming Language :: Python :: 3.10",
|
|
35
|
+
"Programming Language :: Python :: 3.11",
|
|
36
|
+
"Programming Language :: Python :: 3.12",
|
|
37
|
+
"Programming Language :: Python :: 3.13",
|
|
38
|
+
"Topic :: Security",
|
|
39
|
+
"Topic :: Software Development :: Quality Assurance",
|
|
40
|
+
"Topic :: Software Development :: Testing"
|
|
41
|
+
]
|
|
42
|
+
dependencies = []
|
|
43
|
+
|
|
44
|
+
[project.urls]
|
|
45
|
+
Homepage = "https://www.atooli.com"
|
|
46
|
+
Documentation = "https://www.atooli.com/#docs-cli"
|
|
47
|
+
Repository = "https://github.com/876387/clawprobe"
|
|
48
|
+
Issues = "https://github.com/876387/clawprobe/issues"
|
|
49
|
+
|
|
50
|
+
[project.scripts]
|
|
51
|
+
clawprobe = "clawprobe.cli:main"
|
|
52
|
+
|
|
53
|
+
[tool.setuptools]
|
|
54
|
+
package-dir = {"" = "src"}
|
|
55
|
+
|
|
56
|
+
[tool.setuptools.packages.find]
|
|
57
|
+
where = ["src"]
|