cognis-digital/scopeward

# scopeward **用于授权移动安全测试的授权与范围执行。** `scopeward` 是移动渗透测试工具包的授权层。在任何工具接触设备之前，它都以相同的方式解决一个问题： 如果答案是否定的，则拒绝该操作。如果是肯定的，则该决定将被写入防篡改审计日志中。这就是区分**授权评估**与测试你无权测试的 app 的关键，并且它是套件中所有其他工具（`apkprobe`、`ipaprobe`、`hookbench`、……）的硬性前提——除非 `scopeward` 表示授权范围涵盖该操作，否则它们不会运行模块。 `scopeward` **仅使用标准库**——没有第三方依赖——因此它可以被内置到任何工具中。 ## 为什么需要签名范围 渗透测试由合同定义：哪些 app、哪些设备、什么日期、你可以做什么和不可以做什么。`scopeward` 使该合同能够被机器强制执行。 - 该范围是一个小型的 JSON 文档（`examples/engagement.example.json`）。 - 它使用带外（out-of-band）提供的授权密钥通过 **HMAC-SHA256** 进行签名。该密钥永远不会出现在文档中。 - 签名后的任何编辑——偷偷添加额外的目标 app 或设备——都会破坏验证，从而导致授权停止。你无法悄悄扩大自己的授权。 ## 安装 ``` pip install -e . # or: pip install -e ".[dev]" for tests ``` ## CLI 签名密钥从环境变量中读取，因此它永远不会出现在 shell 历史记录或范围文件中。 ``` export SCOPEWARD_KEY="...engagement key..." # 1. 签署授权 scope（仅一次，由授权方执行） scopeward sign --scope engagement.json # 2. 在信任之前验证 scope scopeward verify --scope engagement.json # -> VALID # 3. 门控某个操作 — 每个工具在执行前都会调用此操作 scopeward check --scope engagement.json \ --module apkprobe \ --target android:com.acme.app \ --log evidence.jsonl # -> AUTHORIZED（并且一条记录会被追加到 evidence.jsonl） scopeward check --scope engagement.json --module apkprobe \ --target android:com.someoneelse.app # -> DENIED: target 'android:com.someoneelse.app' is not an authorized target app # 4. 验证审计追踪未被篡改 scopeward audit --log evidence.jsonl # -> INTACT: 3 record(s), hash chain verified ``` ## 库 ``` from scopeward import Scope, sign_scope, Authorizer, EvidenceLog, Target, Finding scope = Scope.load("engagement.json") log = EvidenceLog("evidence.jsonl", scope.engagement_id) authz = Authorizer(scope, key=KEY, evidence=log) # raises if signature is bad # 在一个测试模块中，在执行任何操作之前： authz.authorize("apkprobe", target=Target("android", "com.acme.app")) # -> 如果在 scope 内则静默返回；否则引发 ScopeViolation # 以 shared schema 输出结果： finding = Finding( title="Cleartext traffic permitted", severity="high", target="android:com.acme.app", masvs="MASVS-NETWORK-1", mastg_test="MASTG-TEST-0019", evidence="android:usesCleartextTraffic=\"true\"", ) log.record("finding", finding.to_dict()) ``` ## 内部模块 | 模块 | 职责 | |--------|----------------| | `scope.py` | 授权模型：目标、设备、窗口、ROE；规范化（签名稳定）的序列化。 | | `signing.py` | 分离式 HMAC-SHA256 签名 / 验证。 | | `authz.py` | `Authorizer` —— 每个模块都会查询的单一故障关闭（fail-closed）闸门。 | | `evidence.py` | 带有 SHA-256 哈希链（防篡改）的仅追加 JSONL 审计日志。 | | `findings.py` | `Finding` / `Severity` —— 整个套件共享的结果 schema，包含 MASVS/MASTG 参考。 | ## 使用范围 `scopeward` 专为**授权的**活动而构建——具有签名合同的渗透测试、自有 app 的内部安全评估、实验室工作以及 CTF/培训。它是一道护栏，而不是武器：其全部目的是确保工具只在获得许可的范围内行动。请以此方式使用它。 ## 许可证 Cognis 开放协作许可证 (COCL) v1.0。请参阅 [LICENSE](LICENSE)。

标签：Python, 合规与审计, 授权管控, 无后门, 时序数据库, 目录枚举, 移动安全, 逆向工具