clawprobe 1.3.0__py3-none-any.whl

clawprobe/__init__.py

@@ -0,0 +1,3 @@
+"""ClawProbe — Zero-Dependency Mobile APK 300s Live Dynamic Privacy Inspection & CI/CD Gate CLI."""
+
+__version__ = "1.3.0"

clawprobe/__main__.py

@@ -0,0 +1,8 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Enable `python -m clawprobe` and `pipx run clawprobe` execution."""
+
+from clawprobe.cli import main
+
+if __name__ == "__main__":
+    main()

clawprobe/cli.py

@@ -0,0 +1,383 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+`clawprobe` — Mobile Application 300s Live Dynamic Technical Inspection & CI/CD Privacy Gate CLI:
+  - `clawprobe doctor`
+  - `clawprobe auth login --api-key cnx_live_xxx --secret sec_xxx [--endpoint https://www.atooli.com]`
+  - `clawprobe auth verify`
+  - `clawprobe analyze ./app.apk --attest-authorized --mode privacy --fail-on-preconsent --reclaim --out ./report.pdf`
+  - `clawprobe job <job_id> [--out ./report.pdf] [--json-out ./report.json] [--bundle ./bundle.zip] [--reclaim]`
+  - `clawprobe reclaim <job_id>`
+
+Exit Codes:
+  - `0`: Completed cleanly (and 0 Stage-1 pre-consent flows when `--fail-on-preconsent` is set)
+  - `1`: Usage, argument, file-not-found, or authentication/attestation error
+  - `2`: CI/CD Privacy Gate Triggered (`--fail-on-preconsent` set and Stage-1 pre-consent flows detected)
+  - `3`: Quota or bound-package limit exceeded (`ERR_QUOTA_EXCEEDED` / `ERR_PACKAGE_QUOTA_EXCEEDED`)
+  - `4`: Network, service unavailability, or sandbox queue timeout
+"""
+
+from __future__ import annotations
+
+import argparse
+import email.utils
+import json
+import os
+import ssl
+import stat
+import sys
+import time
+from pathlib import Path
+
+from clawprobe import __version__
+from clawprobe.client import (
+    CRED_PATH,
+    DEFAULT_PUBLIC_ENDPOINT,
+    ClawNexusClient,
+    load_credentials,
+    save_credentials,
+)
+
+
+def _build_client(args: argparse.Namespace) -> ClawNexusClient:
+    creds = load_credentials(
+        endpoint=getattr(args, "endpoint", None),
+        api_key=getattr(args, "api_key", None),
+        sign_secret=getattr(args, "secret", None),
+        spki_pin=getattr(args, "spki_pin", None),
+    )
+    return ClawNexusClient(
+        endpoint=creds["endpoint"],
+        api_key=creds["api_key"],
+        sign_secret=creds["sign_secret"],
+        ca_cert=getattr(args, "ca_cert", None),
+        spki_pins=creds["spki_pins"],
+        pin_mode=getattr(args, "pin_mode", None),
+        timeout=60.0,
+    )
+
+
+def _run_doctor(client: ClawNexusClient) -> int:
+    checks: dict = {
+        "cli_version": __version__,
+        "python_version": sys.version.split()[0],
+        "openssl_version": ssl.OPENSSL_VERSION,
+        "tls13_supported": bool(getattr(ssl, "HAS_TLSv1_3", False)),
+        "endpoint": client.endpoint,
+        "pin_mode": client.pin_mode,
+    }
+    ok = sys.version_info >= (3, 9)
+
+    if CRED_PATH.exists():
+        mode_oct = stat.S_IMODE(os.stat(CRED_PATH).st_mode)
+        checks["credentials_file"] = str(CRED_PATH)
+        checks["credentials_permissions"] = f"0{mode_oct:o}"
+        if os.name != "nt" and (mode_oct & 0o077) != 0:
+            checks["credentials_warning"] = "Permissions broader than 0600; run chmod 600 ~/.clawnexus/credentials.json"
+    else:
+        checks["credentials_file"] = "not_configured (using env vars or anonymous doctor)"
+
+    try:
+        t0 = time.time()
+        st, hdrs, _ = client.request_raw("GET", "/api/v1/health", require_auth=False, retries=1)
+        rtt_ms = round((time.time() - t0) * 1000.0, 1)
+        checks["health_http_status"] = st
+        checks["rtt_ms"] = rtt_ms
+        checks["peer_spki_sha256"] = client.last_peer_spki_sha256
+        checks["spki_pin_matched"] = client.last_spki_pin_matched
+        if st != 200:
+            ok = False
+        date_hdr = hdrs.get("date")
+        if date_hdr:
+            dt = email.utils.parsedate_to_datetime(date_hdr)
+            skew_sec = round(abs(time.time() - dt.timestamp()), 2)
+            checks["clock_skew_sec"] = skew_sec
+            checks["clock_skew_ok"] = skew_sec <= 60.0
+            if skew_sec > 60.0:
+                ok = False
+                checks["clock_warning"] = f"Clock skew {skew_sec}s exceeds ±60s HMAC v2 anti-replay window"
+    except Exception as exc:
+        ok = False
+        checks["connection_error"] = str(exc)
+
+    checks["status"] = "ok" if ok else "failed"
+    print(json.dumps(checks, indent=2, ensure_ascii=False))
+    return 0 if ok else 4
+
+
+def _download_artifacts(
+    client: ClawNexusClient,
+    job_id: str,
+    pdf_out: str | None,
+    json_out: str | None,
+    bundle_out: str | None,
+) -> dict:
+    downloaded = {}
+    st_j, _, raw_j = client.request_raw("GET", f"/api/v1/inspect/jobs/{job_id}/report.json")
+    if st_j != 200:
+        raise RuntimeError(f"Failed to fetch report.json (HTTP {st_j}): {raw_j.decode('utf-8', errors='replace')}")
+    report_obj = json.loads(raw_j.decode("utf-8"))
+    if json_out:
+        jp = Path(json_out)
+        jp.parent.mkdir(parents=True, exist_ok=True)
+        jp.write_bytes(raw_j)
+        downloaded["report_json"] = str(jp)
+    if pdf_out:
+        st_p, _, raw_p = client.request_raw("GET", f"/api/v1/inspect/jobs/{job_id}/report.pdf")
+        if st_p != 200:
+            raise RuntimeError(f"Failed to fetch report.pdf (HTTP {st_p})")
+        pp = Path(pdf_out)
+        pp.parent.mkdir(parents=True, exist_ok=True)
+        pp.write_bytes(raw_p)
+        downloaded["report_pdf"] = str(pp)
+    if bundle_out:
+        st_b, _, raw_b = client.request_raw("GET", f"/api/v1/inspect/jobs/{job_id}/bundle.zip")
+        if st_b != 200:
+            raise RuntimeError(f"Failed to fetch bundle.zip (HTTP {st_b})")
+        bp = Path(bundle_out)
+        bp.parent.mkdir(parents=True, exist_ok=True)
+        bp.write_bytes(raw_b)
+        downloaded["bundle_zip"] = str(bp)
+    return {"report": report_obj, "downloaded": downloaded}
+
+
+def _reclaim_job(client: ClawNexusClient, job_id: str) -> dict:
+    payload = json.dumps({"confirm_reclaim": True}).encode("utf-8")
+    st, _, raw = client.request_raw(
+        "POST",
+        f"/api/v1/inspect/jobs/{job_id}/reclaim",
+        body=payload,
+        content_type="application/json",
+    )
+    body = json.loads(raw.decode("utf-8", errors="replace"))
+    if st != 200:
+        raise RuntimeError(f"Failed to reclaim job {job_id} (HTTP {st}): {body}")
+    return body.get("reclaim_receipt", body)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="clawprobe",
+        description="ClawProbe APK 300s Live Dynamic Technical Inspection & CI/CD Privacy Gate CLI (v1.3)",
+    )
+    parser.add_argument("--version", action="version", version=f"clawprobe {__version__}")
+    parser.add_argument("--endpoint", default=None, help=f"Gateway URL (default: {DEFAULT_PUBLIC_ENDPOINT})")
+    parser.add_argument("--api-key", default=None, help="Commercial API Key (cnx_live_* or env CLAWNEXUS_API_KEY)")
+    parser.add_argument("--secret", default=None, help="HMAC-SHA256 Sign Secret (sec_* or env CLAWNEXUS_SIGN_SECRET)")
+    parser.add_argument("--ca-cert", default=None, help="Optional custom TLS CA PEM path")
+    parser.add_argument("--spki-pin", default=None, help="Optional comma-separated SPKI SHA-256 Base64 pins")
+    parser.add_argument("--pin-mode", choices=["ca", "strict", "off"], default=None, help="TLS pin policy (default: ca)")
+
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    sub.add_parser("doctor", help="Check Python/OpenSSL TLS 1.3 support, certificate chain, and ±60s clock skew")
+
+    p_auth = sub.add_parser("auth", help="Manage CLI authentication credentials")
+    auth_sub = p_auth.add_subparsers(dest="auth_cmd", required=True)
+    p_login = auth_sub.add_parser("login", help="Store APIKEY, HMAC secret, and endpoint in ~/.clawnexus/credentials.json")
+    p_login.add_argument("--endpoint", default=DEFAULT_PUBLIC_ENDPOINT, help=f"Service endpoint (default: {DEFAULT_PUBLIC_ENDPOINT})")
+    p_login.add_argument("--api-key", required=True)
+    p_login.add_argument("--secret", required=True)
+    p_login.add_argument("--spki-pin", default=None)
+    auth_sub.add_parser("verify", help="Verify TLS 1.3 handshake, HMAC v2 authentication, and inspection credits")
+
+    p_an = sub.add_parser("analyze", help="Submit APK for 300s 3-stage live sandbox technical inspection")
+    p_an.add_argument("apk", help="Path to target .apk file")
+    p_an.add_argument(
+        "--attest-authorized",
+        action="store_true",
+        default=False,
+        help="Mandatory: Attest that you hold lawful ownership or written authorization to submit this APK for technical testing",
+    )
+    p_an.add_argument("--mode", choices=["privacy", "forensic", "sdk-hunt"], default="privacy")
+    p_an.add_argument("--confidential", action="store_true", default=False, help="Enable confidential vault + TTL shred")
+    p_an.add_argument("--ttl", type=int, default=72, help="Confidential retention TTL in hours (default 72)")
+    p_an.add_argument("--fail-on-preconsent", action="store_true", default=False, help="Exit code 2 if Stage-1 pre-consent flows exist")
+    p_an.add_argument("--queue-timeout", type=int, default=900, help="Max seconds to wait in queue if all sandboxes are busy (default 900)")
+    p_an.add_argument("--no-wait", action="store_true", default=False, help="Return job_id immediately without polling")
+    p_an.add_argument("--out", default=None, help="Output path for PDF Technical Inspection Report")
+    p_an.add_argument("--json-out", default=None, help="Output path for JSON Technical Inspection Report")
+    p_an.add_argument("--bundle", default=None, help="Output path for full ZIP bundle (PDF+JSON+PCAP+SHA256)")
+    p_an.add_argument(
+        "--reclaim",
+        action="store_true",
+        default=False,
+        help="Immediately 3-pass overwrite & zero-shred server-side job artifacts after downloading local deliverables",
+    )
+
+    p_job = sub.add_parser("job", help="Query inspection job status and download technical report deliverables")
+    p_job.add_argument("job_id", help="Job ID (cn_apk_*)")
+    p_job.add_argument("--out", default=None, help="Output path for PDF report")
+    p_job.add_argument("--json-out", default=None, help="Output path for JSON report")
+    p_job.add_argument("--bundle", default=None, help="Output path for ZIP bundle")
+    p_job.add_argument("--fail-on-preconsent", action="store_true", default=False)
+    p_job.add_argument(
+        "--reclaim",
+        action="store_true",
+        default=False,
+        help="Immediately 3-pass overwrite & zero-shred server-side job artifacts after downloading",
+    )
+
+    p_rec = sub.add_parser("reclaim", help="Immediately 3-pass overwrite & zero-shred server-side artifacts for a completed job")
+    p_rec.add_argument("job_id", help="Job ID (cn_apk_*)")
+
+    args = parser.parse_args()
+
+    if args.cmd == "auth" and args.auth_cmd == "login":
+        saved = save_credentials(args.endpoint, args.api_key, args.secret, spki_pin=args.spki_pin)
+        print(
+            json.dumps(
+                {
+                    "status": "saved",
+                    "credentials_file": str(saved),
+                    "endpoint": (args.endpoint or DEFAULT_PUBLIC_ENDPOINT).rstrip("/"),
+                    "spki_pinning": "strict" if args.spki_pin else "ca_chain_verified",
+                },
+                indent=2,
+            )
+        )
+        return
+
+    client = _build_client(args)
+
+    if args.cmd == "doctor":
+        sys.exit(_run_doctor(client))
+
+    if args.cmd == "auth" and args.auth_cmd == "verify":
+        st, body = client.request_json("GET", "/api/v1/auth/verify")
+        print(json.dumps(body, indent=2, ensure_ascii=False))
+        sys.exit(0 if st == 200 else 1)
+
+    if args.cmd == "analyze":
+        if not args.attest_authorized:
+            print(
+                json.dumps(
+                    {
+                        "status": "error",
+                        "error_code": "ERR_AUTHORIZATION_ATTESTATION_REQUIRED",
+                        "message": "Mandatory flag `--attest-authorized` missing: you must attest lawful ownership or written authorization to submit this APK under ClawNexus Terms of Service.",
+                    },
+                    ensure_ascii=False,
+                    indent=2,
+                ),
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+        apk_p = Path(args.apk)
+        if not apk_p.exists():
+            print(json.dumps({"status": "error", "message": f"APK not found: {apk_p}"}), file=sys.stderr)
+            sys.exit(1)
+
+        q_deadline = time.time() + max(0, int(args.queue_timeout))
+        q_attempt = 0
+        while True:
+            try:
+                st, sub_resp = client.upload_multipart(
+                    "/api/v1/inspect/submit",
+                    file_path=apk_p,
+                    fields={
+                        "mode": args.mode,
+                        "confidential": "true" if args.confidential else "false",
+                        "ttl_hours": str(args.ttl),
+                        "authorization_attested": "true",
+                        "wait": "false",
+                    },
+                )
+            except Exception as net_exc:
+                print(json.dumps({"status": "error", "error_code": "ERR_NETWORK_UNAVAILABLE", "message": str(net_exc)}), file=sys.stderr)
+                sys.exit(4)
+
+            err_code = str(sub_resp.get("error_code") or "")
+            if st == 429 and err_code == "ERR_P0_HOT_SPARE_BUSY" and time.time() < q_deadline:
+                q_attempt += 1
+                wait_s = min(60, 15 * (2 ** min(q_attempt - 1, 2)))
+                rem_q = int(max(0.0, q_deadline - time.time()))
+                print(
+                    f"[clawprobe] All clean sandboxes busy (attempt #{q_attempt}); retrying in {wait_s}s (queue timeout remaining: {rem_q}s)...",
+                    file=sys.stderr,
+                )
+                time.sleep(wait_s)
+                continue
+            break
+
+        if st != 200:
+            print(json.dumps(sub_resp, indent=2, ensure_ascii=False), file=sys.stderr)
+            err_code = str(sub_resp.get("error_code") or "")
+            if err_code in ("ERR_QUOTA_EXCEEDED", "ERR_PACKAGE_QUOTA_EXCEEDED", "ERR_PACKAGE_NOT_IN_WHITELIST"):
+                sys.exit(3)
+            if st in (429, 502, 503, 504):
+                sys.exit(4)
+            sys.exit(1)
+
+        job_id = sub_resp["job_id"]
+        if args.no_wait:
+            print(json.dumps(sub_resp, indent=2, ensure_ascii=False))
+            return
+
+        deadline = time.time() + 420.0
+        st_body: dict = {}
+        while time.time() < deadline:
+            time.sleep(2.5)
+            _, st_body = client.request_json("GET", f"/api/v1/inspect/jobs/{job_id}")
+            jst = st_body.get("job_status", "")
+            if jst == "COMPLETED":
+                break
+            if jst == "FAILED":
+                print(json.dumps(st_body, indent=2, ensure_ascii=False), file=sys.stderr)
+                sys.exit(1)
+        else:
+            print(json.dumps({"status": "error", "error_code": "ERR_INSPECT_TIMEOUT", "message": "Timed out waiting for inspection completion", "job_id": job_id}), file=sys.stderr)
+            sys.exit(4)
+
+        dl = _download_artifacts(client, job_id, args.out, args.json_out, args.bundle)
+        reclaim_receipt = _reclaim_job(client, job_id) if args.reclaim else None
+        rep = dl["report"]
+        summary = rep.get("layer1_deterministic_network_ledger", {}).get("summary", {})
+        pre_detected = bool(summary.get("pre_consent_network_detected"))
+        out_payload = {
+            "status": "ok",
+            "report_title": rep.get("report_title"),
+            "job_id": job_id,
+            "package_name": rep.get("layer1_deterministic_network_ledger", {}).get("package_name"),
+            "wall_time_sec": st_body.get("wall_time_sec"),
+            "authorization_attestation": rep.get("report_metadata", {}).get("customer_authorization_attestation"),
+            "summary": summary,
+            "anchored_findings": rep.get("anchored_technical_synthesis", {}).get("verified_anchored_findings", []),
+            "downloaded_files": dl["downloaded"],
+        }
+        if reclaim_receipt is not None:
+            out_payload["reclaim_receipt"] = reclaim_receipt
+        print(json.dumps(out_payload, indent=2, ensure_ascii=False))
+        if args.fail_on_preconsent and pre_detected:
+            sys.exit(2)
+        return
+
+    if args.cmd == "reclaim":
+        receipt = _reclaim_job(client, args.job_id)
+        print(json.dumps({"status": "ok", "reclaim_receipt": receipt}, indent=2, ensure_ascii=False))
+        return
+
+    if args.cmd == "job":
+        st, st_body = client.request_json("GET", f"/api/v1/inspect/jobs/{args.job_id}")
+        if st != 200:
+            print(json.dumps(st_body, indent=2, ensure_ascii=False), file=sys.stderr)
+            sys.exit(1)
+        if st_body.get("job_status") != "COMPLETED" or not (args.out or args.json_out or args.bundle or args.reclaim):
+            print(json.dumps(st_body, indent=2, ensure_ascii=False))
+            return
+        dl = _download_artifacts(client, args.job_id, args.out, args.json_out, args.bundle) if (args.out or args.json_out or args.bundle) else {"report": {}, "downloaded": {}}
+        reclaim_receipt = _reclaim_job(client, args.job_id) if args.reclaim else None
+        rep = dl["report"]
+        summary = rep.get("layer1_deterministic_network_ledger", {}).get("summary", {})
+        res_out = {**st_body, "summary": summary, "downloaded_files": dl["downloaded"]}
+        if reclaim_receipt is not None:
+            res_out["reclaim_receipt"] = reclaim_receipt
+            res_out["job_status"] = "RECLAIMED_SHREDDED"
+        print(json.dumps(res_out, indent=2, ensure_ascii=False))
+        if args.fail_on_preconsent and summary.get("pre_consent_network_detected"):
+            sys.exit(2)
+
+
+if __name__ == "__main__":
+    main()

clawprobe/client.py

@@ -0,0 +1,471 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+ClawProbe — Zero-dependency stdlib TLS 1.3 + Certificate Chain / SPKI Verification +
+Canonical HMAC-SHA256 v2 (Sorted Query + Full Raw HTTP Body) Anti-Replay HTTP Client.
+
+Licensed under the Apache License, Version 2.0.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import http.client
+import json
+import os
+import secrets
+import socket
+import ssl
+import time
+import urllib.parse
+from pathlib import Path
+from typing import Any
+
+CRED_PATH = Path(os.path.expanduser("~/.clawnexus/credentials.json"))
+DEFAULT_PUBLIC_ENDPOINT = "https://www.atooli.com"
+
+# Default SPKI SHA-256 Pins for https://www.atooli.com:
+#   1. DigiCert Intermediate CA (Encryption Everywhere DV TLS CA - G2) — survives leaf cert rotation
+#   2. DigiCert Global Root G2 — root trust anchor SPKI
+#   3. www.atooli.com current leaf SPKI
+DEFAULT_PINNED_SPKI_SHA256: tuple[str, ...] = (
+    "gxeKFFaZ2HFJIsTdTjEl6nVo3ckTCX+qzRMqb9Xoa1w=",
+    "i7WTqTvh0OioIruIfFR4kMPnBqrS2rdiVPl/s2uC/CY=",
+    "h3mQK/w8dMmMne2+T0gN9L5DAL5BrhfskqFXjK5oOSo=",
+)
+
+EMBEDDED_PUBLIC_CA_CHAIN_PEM = """-----BEGIN CERTIFICATE-----
+MIIEqjCCA5KgAwIBAgIQDeD/te5iy2EQn2CMnO1e0zANBgkqhkiG9w0BAQsFADBh
+MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMRkwFwYDVQQLExB3
+d3cuZGlnaWNlcnQuY29tMSAwHgYDVQQDExdEaWdpQ2VydCBHbG9iYWwgUm9vdCBH
+MjAeFw0xNzExMjcxMjQ2NDBaFw0yNzExMjcxMjQ2NDBaMG4xCzAJBgNVBAYTAlVT
+MRUwEwYDVQQKEwxEaWdpQ2VydCBJbmMxGTAXBgNVBAsTEHd3dy5kaWdpY2VydC5j
+b20xLTArBgNVBAMTJEVuY3J5cHRpb24gRXZlcnl3aGVyZSBEViBUTFMgQ0EgLSBH
+MjCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAO8Uf46i/nr7pkgTDqnE
+eSIfCFqvPnUq3aF1tMJ5hh9MnO6Lmt5UdHfBGwC9Si+XjK12cjZgxObsL6Rg1njv
+NhAMJ4JunN0JGGRJGSevbJsA3sc68nbPQzuKp5Jc8vpryp2mts38pSCXorPR+sch
+QisKA7OSQ1MjcFN0d7tbrceWFNbzgL2csJVQeogOBGSe/KZEIZw6gXLKeFe7mupn
+NYJROi2iC11+HuF79iAttMc32Cv6UOxixY/3ZV+LzpLnklFq98XORgwkIJL1HuvP
+ha8yvb+W6JislZJL+HLFtidoxmI7Qm3ZyIV66W533DsGFimFJkz3y0GeHWuSVMbI
+lfsCAwEAAaOCAU8wggFLMB0GA1UdDgQWBBR435GQX+7erPbFdevVTFVT7yRKtjAf
+BgNVHSMEGDAWgBROIlQgGJXm427mD/r6uRLtBhePOTAOBgNVHQ8BAf8EBAMCAYYw
+HQYDVR0lBBYwFAYIKwYBBQUHAwEGCCsGAQUFBwMCMBIGA1UdEwEB/wQIMAYBAf8C
+AQAwNAYIKwYBBQUHAQEEKDAmMCQGCCsGAQUFBzABhhhodHRwOi8vb2NzcC5kaWdp
+Y2VydC5jb20wQgYDVR0fBDswOTA3oDWgM4YxaHR0cDovL2NybDMuZGlnaWNlcnQu
+Y29tL0RpZ2lDZXJ0R2xvYmFsUm9vdEcyLmNybDBMBgNVHSAERTBDMDcGCWCGSAGG
+/WwBAjAqMCgGCCsGAQUFBwIBFhxodHRwczovL3d3dy5kaWdpY2VydC5jb20vQ1BT
+MAgGBmeBDAECATANBgkqhkiG9w0BAQsFAAOCAQEAoBs1eCLKakLtVRPFRjBIJ9LJ
+L0s8ZWum8U8/1TMVkQMBn+CPb5xnCD0GSA6L/V0ZFrMNqBirrr5B241OesECvxIi
+98bZ90h9+q/X5eMyOD35f8YTaEMpdnQCnawIwiHx06/0BfiTj+b/XQih+mqt3ZXe
+xNCJqKexdiB2IWGSKcgahPacWkk/BAQFisKIFYEqHzV974S3FAz/8LIfD58xnsEN
+GfzyIDkH3JrwYZ8caPTf6ZX9M1GrISN8HnWTtdNCH2xEajRa/h9ZBXjUyFKQrGk2
+n2hcLrfZSbynEC/pSw/ET7H5nWwckjmAJ1l9fcnbqkU/pf6uMQmnfl0JQjJNSg==
+-----END CERTIFICATE-----
+-----BEGIN CERTIFICATE-----
+MIIDjjCCAnagAwIBAgIQAzrx5qcRqaC7KGSxHQn65TANBgkqhkiG9w0BAQsFADBh
+MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMRkwFwYDVQQLExB3
+d3cuZGlnaWNlcnQuY29tMSAwHgYDVQQDExdEaWdpQ2VydCBHbG9iYWwgUm9vdCBH
+MjAeFw0xMzA4MDExMjAwMDBaFw0zODAxMTUxMjAwMDBaMGExCzAJBgNVBAYTAlVT
+MRUwEwYDVQQKEwxEaWdpQ2VydCBJbmMxGTAXBgNVBAsTEHd3dy5kaWdpY2VydC5j
+b20xIDAeBgNVBAMTF0RpZ2lDZXJ0IEdsb2JhbCBSb290IEcyMIIBIjANBgkqhkiG
+9w0BAQEFAAOCAQ8AMIIBCgKCAQEAuzfNNNx7a8myaJCtSnX/RrohCgiN9RlUyfuI
+2/Ou8jqJkTx65qsGGmvPrC3oXgkkRLpimn7Wo6h+4FR1IAWsULecYxpsMNzaHxmx
+1x7e/dfgy5SDN67sH0NO3Xss0r0upS/kqbitOtSZpLYl6ZtrAGCSYP9PIUkY92eQ
+q2EGnI/yuum06ZIya7XzV+hdG82MHauVBJVJ8zUtluNJbd134/tJS7SsVQepj5Wz
+tCO7TG1F8PapspUwtP1MVYwnSlcUfIKdzXOS0xZKBgyMUNGPHgm+F6HmIcr9g+UQ
+vIOlCsRnKPZzFBQ9RnbDhxSJITRNrw9FDKZJobq7nMWxM4MphQIDAQABo0IwQDAP
+BgNVHRMBAf8EBTADAQH/MA4GA1UdDwEB/wQEAwIBhjAdBgNVHQ4EFgQUTiJUIBiV
+5uNu5g/6+rkS7QYXjzkwDQYJKoZIhvcNAQELBQADggEBAGBnKJRvDkhj6zHd6mcY
+1Yl9PMWLSn/pvtsrF9+wX3N3KjITOYFnQoQj8kVnNeyIv/iPsGEMNKSuIEyExtv4
+NeF22d+mQrvHRAiGfzZ0JFrabA0UWTW98kndth/Jsw1HKj2ZL7tcu7XUIOGZX1NG
+Fdtom/DzMNU+MeKNhJ7jitralj41E6Vf8PlwUHBHQRFXGU7Aj64GxJUTFy8bJZ91
+8rGOmaFvE7FBcf6IKshPECBV1/MUReXgRPTqh5Uykw7+U0b6LJ3/iyK5S9kJRaTe
+pLiaWN0bfVKfjllDiIGknibVb63dDcY3fe0Dkhvld1927jyNxF1WW6LZZm6zNTfl
+MrY=
+-----END CERTIFICATE-----
+"""
+
+
+class SPKIPinMismatchError(ssl.SSLCertVerificationError):
+    """Raised when the peer TLS 1.3 certificate SPKI SHA-256 fingerprint does not match pinned SPKI hashes."""
+
+
+def _read_asn1_tlv(data: bytes, offset: int) -> tuple[int, int, int, int]:
+    """Parse one ASN.1 DER TLV -> (tag, header_start, value_start, next_offset)."""
+    if offset >= len(data):
+        raise ValueError("Truncated ASN.1 DER at tag")
+    tag = data[offset]
+    if offset + 1 >= len(data):
+        raise ValueError("Truncated ASN.1 DER at length")
+    first_len = data[offset + 1]
+    if (first_len & 0x80) == 0:
+        length = first_len
+        val_start = offset + 2
+    else:
+        num_len_bytes = first_len & 0x7F
+        if num_len_bytes == 0 or num_len_bytes > 4 or offset + 2 + num_len_bytes > len(data):
+            raise ValueError("Invalid ASN.1 DER length octets")
+        length = int.from_bytes(data[offset + 2 : offset + 2 + num_len_bytes], "big")
+        val_start = offset + 2 + num_len_bytes
+    next_off = val_start + length
+    if next_off > len(data):
+        raise ValueError("Truncated ASN.1 DER value")
+    return tag, offset, val_start, next_off
+
+
+def extract_spki_der_from_x509_der(cert_der: bytes) -> bytes:
+    """Extract raw DER `SubjectPublicKeyInfo` (`RFC 5280 §4.1`) from an X.509 DER certificate using pure stdlib."""
+    c_tag, _, c_val, _ = _read_asn1_tlv(cert_der, 0)
+    if c_tag != 0x30:
+        raise ValueError("X.509 certificate outer element is not SEQUENCE")
+    tbs_tag, _, tbs_val, tbs_end = _read_asn1_tlv(cert_der, c_val)
+    if tbs_tag != 0x30:
+        raise ValueError("X.509 tbsCertificate is not SEQUENCE")
+
+    pos = tbs_val
+    t0, _, _, next0 = _read_asn1_tlv(cert_der, pos)
+    if t0 == 0xA0:  # [0] EXPLICIT Version
+        pos = next0
+    # Skip serialNumber, signature, issuer, validity, subject
+    for _ in range(5):
+        _, _, _, pos = _read_asn1_tlv(cert_der, pos)
+
+    spki_tag, spki_hdr, _, spki_end = _read_asn1_tlv(cert_der, pos)
+    if spki_tag != 0x30 or spki_end > tbs_end:
+        raise ValueError("Malformed X.509 SubjectPublicKeyInfo")
+    return cert_der[spki_hdr:spki_end]
+
+
+def extract_spki_sha256_b64(cert_der: bytes) -> str:
+    """Compute Base64-encoded SHA-256 fingerprint of the X.509 certificate's `SubjectPublicKeyInfo` DER."""
+    spki_der = extract_spki_der_from_x509_der(cert_der)
+    return base64.b64encode(hashlib.sha256(spki_der).digest()).decode("ascii")
+
+
+def canonicalize_path_and_query(path: str, raw_query: str = "") -> str:
+    """
+    Canonical Path + Sorted Query String:
+      `path?k1=v1&k2=v2` (sorted lexicographically by `(key, value)`, RFC 3986 percent-encoded)
+      or `path` when query is empty.
+    """
+    if "?" in path:
+        base_path, q_in_path = path.split("?", 1)
+        eff_query = raw_query if raw_query else q_in_path
+    else:
+        base_path = path
+        eff_query = raw_query
+    if not eff_query:
+        return base_path
+    pairs = urllib.parse.parse_qsl(eff_query, keep_blank_values=True)
+    if not pairs:
+        return base_path
+    sorted_pairs = sorted(pairs, key=lambda kv: (kv[0], kv[1]))
+    sorted_qs = urllib.parse.urlencode(sorted_pairs, doseq=True, quote_via=urllib.parse.quote)
+    return f"{base_path}?{sorted_qs}"
+
+
+def compute_hmac_signature_v2(
+    sign_secret: str,
+    method: str,
+    path_with_query: str,
+    timestamp: str,
+    nonce: str,
+    full_raw_body_sha256: str,
+) -> str:
+    """
+    Canonical HMAC-SHA256 v2:
+      `METHOD\\npath?sorted_query\\nts\\nnonce\\nsha256(full_raw_http_body)`
+    """
+    canon_target = canonicalize_path_and_query(path_with_query)
+    canonical = f"{method.upper()}\n{canon_target}\n{timestamp}\n{nonce}\n{full_raw_body_sha256.lower()}".encode("utf-8")
+    return hmac.new(sign_secret.encode("utf-8"), canonical, hashlib.sha256).hexdigest()
+
+
+def save_credentials(
+    endpoint: str | None,
+    api_key: str,
+    sign_secret: str,
+    spki_pin: str | None = None,
+) -> Path:
+    CRED_PATH.parent.mkdir(parents=True, exist_ok=True)
+    ep = (endpoint or DEFAULT_PUBLIC_ENDPOINT).strip().rstrip("/")
+    explicit_pins = [p.strip() for p in (spki_pin or "").split(",") if p.strip()]
+    payload = {
+        "endpoint": ep,
+        "api_key": api_key.strip(),
+        "sign_secret": sign_secret.strip(),
+        "spki_pins": explicit_pins,
+        "updated_at": int(time.time()),
+    }
+    CRED_PATH.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+    os.chmod(CRED_PATH, 0o600)
+    return CRED_PATH
+
+
+def load_credentials(
+    endpoint: str | None = None,
+    api_key: str | None = None,
+    sign_secret: str | None = None,
+    spki_pin: str | None = None,
+) -> dict[str, Any]:
+    stored: dict[str, Any] = {}
+    if CRED_PATH.exists():
+        try:
+            stored = json.loads(CRED_PATH.read_text(encoding="utf-8"))
+        except Exception:
+            stored = {}
+    stored_ep = str(stored.get("endpoint") or "").rstrip("/")
+    ep = (
+        endpoint
+        or os.environ.get("CLAW_ENDPOINT")
+        or os.environ.get("CLAWNEXUS_ENDPOINT")
+        or (stored_ep if stored_ep.startswith("https://www.atooli.com") else "")
+        or DEFAULT_PUBLIC_ENDPOINT
+    ).rstrip("/")
+    ak = (
+        api_key
+        or os.environ.get("CLAW_API_KEY")
+        or os.environ.get("CLAWNEXUS_API_KEY")
+        or stored.get("api_key")
+        or ""
+    ).strip()
+    sk = (
+        sign_secret
+        or os.environ.get("CLAW_API_SECRET")
+        or os.environ.get("CLAW_SIGN_SECRET")
+        or os.environ.get("CLAWNEXUS_SIGN_SECRET")
+        or stored.get("sign_secret")
+        or ""
+    ).strip()
+    pin_arg = spki_pin or os.environ.get("CLAW_SPKI_PIN") or os.environ.get("CLAWNEXUS_SPKI_PIN") or ""
+    if pin_arg.strip():
+        pins: tuple[str, ...] | None = tuple(p.strip() for p in pin_arg.split(",") if p.strip())
+    elif stored_ep == ep and isinstance(stored.get("spki_pins"), list) and stored["spki_pins"]:
+        stored_tuple = tuple(str(p).strip() for p in stored["spki_pins"] if str(p).strip())
+        pins = None if (not stored_tuple or set(stored_tuple).issubset(set(DEFAULT_PINNED_SPKI_SHA256))) else stored_tuple
+    else:
+        pins = None
+    return {"endpoint": ep, "api_key": ak, "sign_secret": sk, "spki_pins": pins}
+
+
+class ClawNexusClient:
+    def __init__(
+        self,
+        endpoint: str = DEFAULT_PUBLIC_ENDPOINT,
+        api_key: str = "",
+        sign_secret: str = "",
+        ca_cert: str | None = None,
+        spki_pins: tuple[str, ...] | list[str] | None = None,
+        pin_mode: str | None = None,
+        timeout: float = 45.0,
+    ) -> None:
+        self.endpoint = (endpoint or DEFAULT_PUBLIC_ENDPOINT).rstrip("/")
+        self.api_key = api_key
+        self.sign_secret = sign_secret
+        self.ca_cert = ca_cert
+        self._explicit_spki_pins = spki_pins is not None
+        self.spki_pins: tuple[str, ...] = (
+            tuple(spki_pins) if spki_pins is not None else DEFAULT_PINNED_SPKI_SHA256
+        )
+        self.timeout = timeout
+        parsed = urllib.parse.urlparse(self.endpoint)
+        self.scheme = parsed.scheme.lower()
+        self.host = parsed.hostname or "127.0.0.1"
+        self.port = parsed.port or (443 if self.scheme == "https" else 80)
+        raw_mode = (pin_mode or os.environ.get("CLAWNEXUS_PIN_MODE") or "").strip().lower()
+        if raw_mode in ("strict", "ca", "off"):
+            self.pin_mode = raw_mode
+        else:
+            self.pin_mode = "strict" if self._explicit_spki_pins else "ca"
+        self.last_peer_spki_sha256: str = ""
+        self.last_spki_pin_matched: bool = False
+
+    def _ssl_context(self) -> ssl.SSLContext:
+        ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+        if getattr(ssl, "HAS_TLSv1_3", False):
+            try:
+                ctx.minimum_version = ssl.TLSVersion.TLSv1_3
+            except ValueError:
+                ctx.minimum_version = ssl.TLSVersion.TLSv1_2
+        else:
+            ctx.minimum_version = ssl.TLSVersion.TLSv1_2
+        ctx.verify_mode = ssl.CERT_REQUIRED
+        ctx.check_hostname = True
+        try:
+            ctx.load_default_certs(ssl.Purpose.SERVER_AUTH)
+        except Exception:
+            pass
+        ctx.load_verify_locations(cadata=EMBEDDED_PUBLIC_CA_CHAIN_PEM)
+        if self.ca_cert:
+            ctx.load_verify_locations(cafile=self.ca_cert)
+        return ctx
+
+    def _verify_peer_spki_pin(self, tls_sock: ssl.SSLSocket) -> None:
+        peer_der = tls_sock.getpeercert(binary_form=True)
+        if not peer_der:
+            raise SPKIPinMismatchError("Peer did not present an X.509 certificate during TLS 1.3 handshake")
+        actual_pin = extract_spki_sha256_b64(peer_der)
+        self.last_peer_spki_sha256 = actual_pin
+
+        candidate_pins = [actual_pin]
+        if hasattr(tls_sock, "get_verified_chain"):
+            try:
+                for c_der in tls_sock.get_verified_chain() or []:
+                    if isinstance(c_der, (bytes, bytearray)):
+                        candidate_pins.append(extract_spki_sha256_b64(bytes(c_der)))
+            except Exception:
+                pass
+
+        matched = any(
+            hmac.compare_digest(cp, exp)
+            for cp in candidate_pins
+            for exp in self.spki_pins
+        )
+        self.last_spki_pin_matched = matched
+        if self.pin_mode == "off" or not self.spki_pins:
+            return
+        if self.pin_mode == "strict" and not matched:
+            raise SPKIPinMismatchError(
+                f"TLS 1.3 SPKI pin verification failed: peer SPKI sha256={actual_pin} not in pinned set {self.spki_pins}"
+            )
+
+    def request_raw(
+        self,
+        method: str,
+        path_with_query: str,
+        body: bytes = b"",
+        content_type: str = "",
+        require_auth: bool = True,
+        retries: int = 2,
+    ) -> tuple[int, dict[str, str], bytes]:
+        full_body_sha = hashlib.sha256(body).hexdigest().lower()
+
+        last_err: Exception | None = None
+        default_port = (self.scheme == "https" and self.port == 443) or (self.scheme == "http" and self.port == 80)
+        host_hdr = self.host if default_port else f"{self.host}:{self.port}"
+        for attempt in range(retries + 1):
+            headers: dict[str, str] = {"Host": host_hdr}
+            if content_type:
+                headers["Content-Type"] = content_type
+            if method.upper() == "POST":
+                headers["Content-Length"] = str(len(body))
+            if require_auth:
+                if not self.api_key or not self.sign_secret:
+                    raise ValueError("Missing API key or sign_secret; run `clawprobe auth login` or set CLAWNEXUS_API_KEY & CLAWNEXUS_SIGN_SECRET")
+                ts = str(int(time.time()))
+                nonce = secrets.token_hex(12)
+                sig = compute_hmac_signature_v2(
+                    self.sign_secret,
+                    method,
+                    path_with_query,
+                    ts,
+                    nonce,
+                    full_body_sha,
+                )
+                headers.update(
+                    {
+                        "X-API-Key": self.api_key,
+                        "X-Claw-Sig-Version": "v2",
+                        "X-Claw-Timestamp": ts,
+                        "X-Claw-Nonce": nonce,
+                        "X-Claw-Signature": sig,
+                        "X-Claw-Body-SHA256": full_body_sha,
+                    }
+                )
+
+            sock: socket.socket | ssl.SSLSocket | None = None
+            try:
+                raw_sock = socket.create_connection((self.host, self.port), timeout=self.timeout)
+                if self.scheme == "https":
+                    tls_sock = self._ssl_context().wrap_socket(raw_sock, server_hostname=self.host)
+                    self._verify_peer_spki_pin(tls_sock)
+                    sock = tls_sock
+                else:
+                    sock = raw_sock
+                req_head = (
+                    f"{method.upper()} {path_with_query} HTTP/1.1\r\n"
+                    + "\r\n".join(f"{k}: {v}" for k, v in headers.items())
+                    + "\r\nConnection: close\r\n\r\n"
+                ).encode("latin-1")
+                sock.sendall(req_head)
+                if body:
+                    sock.sendall(body)
+                resp = http.client.HTTPResponse(sock)
+                resp.begin()
+                resp_bytes = resp.read()
+                resp_hdrs = {k.lower(): v for k, v in resp.getheaders()}
+                status = resp.status
+                sock.close()
+                if status in (502, 504) and attempt < retries:
+                    time.sleep(0.4 * (attempt + 1))
+                    continue
+                return status, resp_hdrs, resp_bytes
+            except ssl.SSLError:
+                if sock is not None:
+                    try:
+                        sock.close()
+                    except Exception:
+                        pass
+                raise
+            except (socket.timeout, ConnectionError, OSError) as exc:
+                last_err = exc
+                if sock is not None:
+                    try:
+                        sock.close()
+                    except Exception:
+                        pass
+                if attempt < retries:
+                    time.sleep(0.4 * (attempt + 1))
+                    continue
+                raise
+        raise RuntimeError(f"Request failed after retries: {last_err}")
+
+    def request_json(
+        self,
+        method: str,
+        path_with_query: str,
+        payload: dict[str, Any] | None = None,
+        require_auth: bool = True,
+    ) -> tuple[int, dict[str, Any]]:
+        body = json.dumps(payload, ensure_ascii=False).encode("utf-8") if payload is not None else b""
+        ctype = "application/json; charset=utf-8" if payload is not None else ""
+        st, _, raw = self.request_raw(method, path_with_query, body=body, content_type=ctype, require_auth=require_auth)
+        try:
+            return st, json.loads(raw.decode("utf-8"))
+        except Exception:
+            return st, {"raw_text": raw.decode("utf-8", errors="replace")}
+
+    def upload_multipart(
+        self,
+        path_with_query: str,
+        file_path: Path,
+        fields: dict[str, str],
+    ) -> tuple[int, dict[str, Any]]:
+        file_bytes = file_path.read_bytes()
+        boundary = f"----ClawNexusCLIBoundary{secrets.token_hex(12)}"
+        parts: list[bytes] = []
+        for k, v in fields.items():
+            parts.append(f"--{boundary}\r\n".encode("utf-8"))
+            parts.append(f'Content-Disposition: form-data; name="{k}"\r\n\r\n{v}\r\n'.encode("utf-8"))
+        parts.append(f"--{boundary}\r\n".encode("utf-8"))
+        parts.append(
+            f'Content-Disposition: form-data; name="file"; filename="{file_path.name}"\r\n'
+            f"Content-Type: application/octet-stream\r\n\r\n".encode("utf-8")
+        )
+        parts.append(file_bytes)
+        parts.append(f"\r\n--{boundary}--\r\n".encode("utf-8"))
+        multipart_body = b"".join(parts)
+
+        st, _, raw = self.request_raw(
+            "POST",
+            path_with_query,
+            body=multipart_body,
+            content_type=f"multipart/form-data; boundary={boundary}",
+            require_auth=True,
+        )
+        try:
+            return st, json.loads(raw.decode("utf-8"))
+        except Exception:
+            return st, {"raw_text": raw.decode("utf-8", errors="replace")}

clawprobe-1.3.0.dist-info/METADATA

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: clawprobe
+Version: 1.3.0
+Summary: ClawProbe (洞察·灵枢): Zero-Dependency Mobile APK 300s Live Dynamic Privacy Inspection & CI/CD Gate CLI
+Author-email: ClawProbe Security Team <876387@gmail.com>
+License: Apache-2.0
+Project-URL: Homepage, https://www.atooli.com
+Project-URL: Documentation, https://www.atooli.com/#docs-cli
+Project-URL: Repository, https://github.com/876387/clawprobe
+Project-URL: Issues, https://github.com/876387/clawprobe/issues
+Keywords: android,apk,privacy,compliance,miit,devsecops,ci-cd,security-testing,network-analysis
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# ClawProbe CLI (`clawprobe`)
+
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-0%20(stdlib%20only)-brightgreen.svg)](https://pypi.org/project/clawprobe/)
+
+**ClawProbe CLI** 是 **ClawProbe 移动应用 300 秒真机动态技术体检与 CI/CD 隐私门禁平台**（[https://www.atooli.com](https://www.atooli.com)）的官方命令行客户端。
+
+基于 **100% Python 标准库（Zero Third-Party Dependencies）** 构建，内置 **HMAC-SHA256 v2 全报文防重放签名** 与 **证书链公钥指纹校验（SPKI Pinning / Embedded CA）**，开箱即可嵌入 GitHub Actions、GitLab CI、Jenkins 等企业级 DevSecOps 流水线，在每次发版前自动拦截 **「用户点击隐私弹窗同意前抢跑联网」** 等隐私合规隐患。
+
+---
+
+## 核心特性 (Key Features)
+
+1. **零第三方依赖 (Zero External Dependencies)**：仅依赖 Python 3.9+ 标准库（`ssl`、`http.client`、`hashlib`、`hmac`、`json`），无需编译 C 扩展，无第三方供应链依赖风险。
+2. **300 秒三阶段真机沙箱时序体检 (300s 3-Stage Live Sandbox Inspection)**：
+   - **Stage 1 (`pre_consent` · 0~45s)**：冷启动静默期（未点击隐私弹窗同意前）网络通信五元组、DNS/SNI 与敏感留痕检测；
+   - **Stage 2 (`post_consent` · 45~255s)**：点击同意隐私弹窗后 UI 自动化遍历与第三方 SDK 加密框架清单盘点；
+   - **Stage 3 (`background` · 255~300s)**：退后台静默期心跳、唤醒、静默上传与高损耗 UDP/PCDN 传输行为观测。
+3. **CI/CD 确定性退出码门禁 (Deterministic Exit Codes)**：通过 `--fail-on-preconsent` 自动阻断存在未同意前抢跑通信的构建任务（返回 `Exit Code 2`）。
+4. **队列拥塞智能指数退避 (Smart Queue Backoff)**：高并发场景下遇 `HTTP 429 (ERR_P0_HOT_SPARE_BUSY)` 自动在 `--queue-timeout` 窗口内指数退避重试，保障夜间流水线稳定收敛。
+5. **一键 3 遍覆写物理销毁 (`--reclaim`)**：下载完本地 PDF/JSON/ZIP 证据包后，支持在流水线末尾自动触发云端工件 3 遍覆写物理清零并返回 SHA-256 销毁回执。
+
+---
+
+## 快速安装 (Installation)
+
+推荐使用 `pipx` 或 `pip` 直接从官方 PyPI 安装：
+
+```bash
+# 推荐：使用 pipx 隔离安装全局命令（含官方 PEP 503 高速镜像源，国内 20ms 直连）
+pipx install --pip-args="--extra-index-url https://www.atooli.com/simple" clawprobe
+
+# 或使用 pip 安装
+pip install -U --extra-index-url https://www.atooli.com/simple clawprobe
+
+# 也可直接从 GitHub Release 安装
+pip install -U https://github.com/876387/clawprobe/releases/download/v1.3.0/clawprobe-1.3.0-py3-none-any.whl
+```
+
+安装完成后，可执行一键环境与链路自检（无需 API Key）：
+
+```bash
+clawprobe doctor
+```
+
+---
+
+## 快速上手 (Quick Start)
+
+### 1. 配置访问凭据
+
+前往 [ClawProbe 官网工作台 (https://www.atooli.com)](https://www.atooli.com) 申请试用或生产凭据后，配置环境变量或执行 `auth login`：
+
+```bash
+# 方式 A：环境变量（适合 CI/CD 流水线）
+export CLAW_API_KEY="cnx_live_your_key_id"
+export CLAW_API_SECRET="sec_your_hmac_secret"
+
+# 方式 B：本地持久化登录（权限自动锁定为 0600）
+clawprobe auth login --api-key cnx_live_your_key_id --secret sec_your_hmac_secret
+
+# 验证鉴权与当前剩余额度
+clawprobe auth verify
+```
+
+### 2. 提交 APK 并启用发版前隐私门禁
+
+```bash
+clawprobe analyze ./app-release.apk \
+  --attest-authorized \
+  --mode privacy \
+  --fail-on-preconsent \
+  --queue-timeout 900 \
+  --out ./clawprobe-report.pdf \
+  --json-out ./clawprobe-report.json \
+  --reclaim
+```
+
+- 若检测完成且 **Stage 1（未同意隐私政策前）** 未发现抢跑外联，命令返回 `Exit Code 0`，并将结构化 JSON 与中英双语 PDF 技术体检报告写入本地。
+- 若发现未同意前抢跑外联，命令在终端打印 `[FL-xxxx]` 证据锚点摘要并返回 `Exit Code 2`，直接阻断 CI 发版流水线。
+
+### 3. 查询历史任务与手动物理销毁云端工件
+
+```bash
+# 查询任务并下载完整 ZIP 证据包（含 PDF + JSON + PCAP + SHA256 清单）
+clawprobe job <job_id> \
+  --out ./report.pdf \
+  --json-out ./report.json \
+  --bundle ./evidence-bundle.zip
+
+# 立即触发云端任务工件 3 遍覆写物理销毁
+clawprobe reclaim <job_id>
+```
+
+---
+
+## CI/CD 退出码规范 (Exit Codes)
+
+| Exit Code | 含义 (Meaning) | 触发场景 (Scenario) |
+| :--- | :--- | :--- |
+| `0` | **PASS (合规通过)** | 任务完成，且未触发 `--fail-on-preconsent` 门禁条件 |
+| `1` | **USAGE_OR_AUTH_ERROR (参数/鉴权异常)** | 参数缺失、未勾选 `--attest-authorized`、API Key 或 HMAC 签名错误 |
+| `2` | **PRIVACY_GATE_TRIGGERED (门禁拦截)** | 启用 `--fail-on-preconsent` 时，检测到同意隐私政策前发生抢跑联网行为 |
+| `3` | **QUOTA_EXCEEDED (配额/包名超限)** | 检测额度耗尽 (`ERR_QUOTA_EXCEEDED`) 或超出账号绑定的包名上限 |
+| `4` | **NETWORK_OR_QUEUE_TIMEOUT (网络/排队超时)** | 网络不可达、SPKI 证书指纹校验失败或超过 `--queue-timeout` 等待窗口 |
+
+---
+
+## CI/CD 流水线集成模板 (CI/CD Templates)
+
+仓库内置开箱即用的流水线模板，可直接复制到您的工程中：
+
+- **GitHub Actions**：[`ci-templates/github/privacy-gate.yml`](./ci-templates/github/privacy-gate.yml)
+- **GitLab CI**：[`ci-templates/gitlab/.gitlab-ci.yml`](./ci-templates/gitlab/.gitlab-ci.yml)
+- **结构化报告样卷**：[`samples/sample_report.json`](./samples/sample_report.json)
+
+---
+
+## 合规与安全声明 (Compliance & Security Notice)
+
+1. **合法授权使用**：用户仅可上传并检测其拥有合法著作权或已获明确书面授权的自有 Android 应用包（APK），调用时须显式传入 `--attest-authorized`。
+2. **客观技术留痕**：本工具及云端沙箱输出的检测报告仅客观记录特定运行环境与特定时间窗口内的网络通信五元组、TLS 握手特征及第三方 SDK 特征留痕（`[FL-xxxx]` 锚点），供研发与安全团队开展内部合规自查，不构成任何法律意见或行政/司法鉴定结论。
+3. **开源许可**：本命令行客户端（`clawprobe`）采用 [Apache-2.0 License](./LICENSE) 开源发布。
+
+---
+
+- **官方网站与在线免登录快检**：[https://www.atooli.com](https://www.atooli.com)
+- **问题反馈 (Issues)**：[https://github.com/876387/clawprobe/issues](https://github.com/876387/clawprobe/issues)

clawprobe-1.3.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+clawprobe/__init__.py,sha256=Bt7vQ2s5JWuEGBmy2GLtZ0D6MPuqPsO4L-gMFsP21iM,125
+clawprobe/__main__.py,sha256=-TDZ0Gsk0zLD_gFj_IxKi55aV3jFuqqScQBW0V7U6uY,189
+clawprobe/cli.py,sha256=kwmA78WvLMIUFeaOiQ5rIIvrVxqGUw2_sLxaZM4KdJE,17498
+clawprobe/client.py,sha256=IjQGz5G66F_js_fc6G170l7ICgymtOLdFFWvrrGMfhY,19492
+clawprobe-1.3.0.dist-info/licenses/LICENSE,sha256=fCkLdQSHhTRBGfIwOBmxR87jvEI7O_oBbx4ruYccTqw,5517
+clawprobe-1.3.0.dist-info/METADATA,sha256=8R1TFuI_jGQxheIPlYvUaYJ5-Lvka091OgkHdPkUMxQ,8126
+clawprobe-1.3.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+clawprobe-1.3.0.dist-info/entry_points.txt,sha256=vjwIzVhCWa4YrhJ3TERZGObqbTyKUJ_pl68rnwGtCQw,49
+clawprobe-1.3.0.dist-info/top_level.txt,sha256=3VnC7IqdMHy9PaM4BwBdX54TplNE50tHkBHr0l-B6ag,10
+clawprobe-1.3.0.dist-info/RECORD,,

clawprobe-1.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

clawprobe-1.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+clawprobe = clawprobe.cli:main

clawprobe-1.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,108 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work.
+
+   Copyright 2026 ClawProbe (https://www.atooli.com)
+   Licensed under the Apache License, Version 2.0 (the "License").

clawprobe-1.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+clawprobe