Back to Details

sumsub-conformance

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Sumsub — Conformance (regulation ↔ deployed config)

Sumsub — 合规性检查（监管要求 ↔ 已部署配置）

Traces every requirement of a regulation through the live config graph and answers, per requirement: collected? → scored? → enforced? The headline finding it surfaces — that nothing else does — is COLLECTED-BUT-NOT-ENFORCED: the config gathers and scores the data a regulation needs, then doesn't act on it (e.g. an appropriateness questionnaire that's scored but never routed).
This is an advisory gap assistant, not a compliance guarantee. It verifies the config-representable parts deterministically and honestly delimits the rest (semantic intent = judgment; SDK/platform outcomes = out of scope). Get a human to sign off.
追踪监管要求中的每一项内容，贯穿实时配置图谱，并针对每项要求回答：已收集？→ 已评分？→ 已执行？ 该技能最核心的发现——也是其他工具无法提供的——是已收集但未执行：配置已收集并评分监管要求所需的数据，但未采取相应行动（例如，一份已评分但从未被路由的适用性调查问卷）。
这是一个合规缺口辅助工具，而非合规保证。它会确定性地验证可通过配置体现的部分，并诚实地界定其余内容（语义意图属于主观判断；SDK/平台结果不在范围内）。最终结果需由人工签字确认。

When to use

使用场景

  • Existing client: "here's our regulation, here's our tenant — what's actually enforced?"
  • New client who configured Sumsub with the create-* skills: close the generate → verify loop — did the assembled config end up enforcing the regulation it was built from?
  • 现有客户：“这是我们的监管要求，这是我们的租户——实际执行了哪些要求？”
  • 使用create-*系列技能配置Sumsub的新客户：完成生成→验证闭环——组装后的配置是否最终执行了其构建依据的监管要求？

Endpoints (read-only)

只读端点

All via 
scripts/sumsub_curl.sh
(App-Token HMAC). 
resolve_graph.sh
wraps these:
PurposeMethod + Path
Levels (find target)
GET /resources/applicants/-/levels
Workflows (auto-find the one referencing the level)
GET /resources/api/applicantWorkflows
+ 
GET /resources/api/applicantWorkflows/{id}
Questionnaire content + scores
GET /resources/api/questionnaires/{id}
PoA / cross-check preset
GET /resources/api/poaStepSettings/{id}
· 
GET /resources/api/crossCheckPresets/{id}
Entitlements (
allowedChecks
keys)
GET /resources/api/agent/settings/bgCheckTargets
所有端点均可通过
scripts/sumsub_curl.sh
（App-Token HMAC认证）调用。
resolve_graph.sh
封装了以下端点：
用途请求方法 + 路径
等级（查找目标）
GET /resources/applicants/-/levels
工作流（自动查找引用该等级的工作流）
GET /resources/api/applicantWorkflows
+ 
GET /resources/api/applicantWorkflows/{id}
问卷内容 + 评分
GET /resources/api/questionnaires/{id}
PoA / 交叉检查预设
GET /resources/api/poaStepSettings/{id}
· 
GET /resources/api/crossCheckPresets/{id}
权限（
allowedChecks
键）
GET /resources/api/agent/settings/bgCheckTargets

Auth — App Token + secret (sandbox only)

认证 — App Token + 密钥（仅沙箱环境）

This skill talks to the public Sumsub API and signs each request per the authentication reference. The how-it-works writeup lives in 
sumsub-api-auth
.
⚠️ Sandbox tokens only. Read-only, but still: do not accept a production App Token. If the user offers one, refuse and ask for a sandbox pair at https://cockpit.sumsub.com/checkus/devSpace/appTokens (toggle to Sandbox first). The helper rejects tokens that don't start with 
sbx:
.
VarExample
SUMSUB_APP_TOKEN
sbx:...
SUMSUB_SECRET_KEY
paired secret
SUMSUB_BASE
/ 
SUMSUB_ENV=dev
optional; 
dev
targets 
dev-api.sumsub.com
(internal).
此技能调用公开的Sumsub API，并按照认证参考文档对每个请求进行签名。其工作原理说明位于
sumsub-api-auth
中。
⚠️ 仅支持沙箱令牌。 虽然是只读操作，但仍需注意：请勿接受生产环境的App Token。如果用户提供生产令牌，请拒绝并要求其提供沙箱环境的令牌对，获取地址为https://cockpit.sumsub.com/checkus/devSpace/appTokens（需先切换至Sandbox模式）。辅助工具会拒绝所有非
sbx:
开头的令牌。
变量示例
SUMSUB_APP_TOKEN
sbx:...
SUMSUB_SECRET_KEY
配对的密钥
SUMSUB_BASE
/ 
SUMSUB_ENV=dev
可选；
dev
指向
dev-api.sumsub.com
（内部环境）。

Procedure

操作流程

Use the scripts — do not hand-roll the deterministic steps. The whole point of this skill is that resolution and the verdict are deterministic, not re-derived by eyeball each run:
  • Resolve the graph ONLY via 
    resolve_graph.sh
    .     Do not call 
    /resources/...
    endpoints directly, list levels by hand, or strip the 
    HTTP <code>
    trailer yourself — the script does all of that and emits one clean graph.
  • If the graph can't be resolved, STOP — never work around the failure. A 
    401
    /
    403
    , a 
    404
    , or 
    0 levels
    / "level not found" from 
    resolve_graph.sh
    means the run cannot proceed. Report the failure plainly (likely a bad/non-sandbox token or wrong level name) and stop. Do not edit 
    resolve_graph.sh
    (or any script) to route around the error, add a by-id fallback, retry a different endpoint, or otherwise improvise a graph — and never emit a report, bucket counts, or a CONFORMANT verdict from a partial or substituted graph. No resolved graph → no findings.
  • Derive the verdict ONLY from 
    trace.py
    / 
    report.py
    .     Do not read the workflow/questionnaire JSON by eye and decide "enforced / not enforced" yourself — that re-introduces variance and hallucination. The 
    COLLECTED-NOT-ENFORCED
    finding must come from the engine.
  • If a script already ran, trust its output — do not re-verify it with manual API calls.
  • To inspect the graph for the Map step, run 
    python3 scripts/graph_summary.py "$CONFIG"
    .     Do not hand-iterate the graph JSON: 
    questionnaires
    /
    poaPresets
    /
    crossCheckPresets
    are dicts keyed by id (iterating yields id strings → 
    'str' has no attribute 'get'
    ) and 
    entitlements
    is a list. 
    graph_summary.py
    prints the section/item indices + scores you need, correctly. The agent's judgment belongs to two steps only: ingest (reading the regulation) and map (matching requirements to deployed config elements — questions, docSets, fields, countries, entitlements). Everything else is the scripts.
Artifacts — MANDATORY location & naming. Every run MUST write its artifacts into the same directory as the source regulation file, named from its stem (filename without extension). Never save in the cwd or under improvised names. Derive the exact paths once, up front:
eval "$(python3 scripts/artifact_paths.py "<path/to/RegFile.pdf>")"
#  $REQUIREMENTS = <dir>/<stem>_regulations.json   (the requirements you build in steps 1+3)
#  $CONFIG       = <dir>/<stem>_config.json         (resolve_graph output, step 2)
#  $REPORT       = <dir>/<stem>_report.md           (the rendered report, step 6)
e.g. 
Level4regulations.pdf
→ 
Level4regulations_regulations.json
, 
Level4regulations_config.json
, 
Level4regulations_report.md
. Use 
$REQUIREMENTS
/ 
$CONFIG
/ 
$REPORT
verbatim in the steps below.
  1. Ingest the regulation (judgment). Just Read the document with the Read tool — it reads PDFs natively (renders pages + extracts text), so nothing needs to be installed. For a PDF over ~10 pages, Read it in page ranges (the Read tool's 
    pages
    parameter, ≤20 pages per call). Reading visually is equal or better than a text extractor — it preserves tables, headings and layout that flat-text extraction loses. Optional, only if already installed and never a blocker: 
    pypdf
    /
    pdftotext
    can pull a long, text-heavy PDF in one shot, and 
    scripts/render_regulation.py
    (PyMuPDF) pre-renders a scanned/image-only PDF to PNGs for explicit DPI control — see 
    references/conformance-method.md
     step 1. If a library is absent, just Read the PDF directly. Then extract requirements and write them to 
    $REQUIREMENTS
     (the 
    <stem>_regulations.json
    beside the source — see the Artifacts rule above), per 
    references/requirements-schema.md
    : each = 
    {id, source, text, type, enforceable, …}
    . Always capture 
    source
     — the citation into the original document (section number / heading / page, e.g. 
    "§5.9.2"
    , 
    "Section 2 — Scoring Result"
    , 
    "p.21"
    ); the report leads with it so findings trace back to the regulation, not to an artificial id. Mark outcomes that live in SDK/platform/CRM as 
    enforceable: sdk|platform
    . Show the extracted requirements to the user and confirm before tracing — this is the highest-risk step.
  2. Resolve the deployed graph (deterministic). 
    bash scripts/resolve_graph.sh <levelNameOrId> > "$CONFIG"
    (level + questionnaires-with-scores + presets + auto-found workflow + entitlements). This one command replaces any manual level-listing / curl / HTTP-trailer stripping — don't do those by hand.
  3. Map (judgment). First inspect the graph: 
    python3 scripts/graph_summary.py "$CONFIG"
     — it prints questionnaires with 
    [section]/[item]
    indices + option scores, docSets, APPLICANT_DATA fields, geo, entitlements, and the workflow (don't hand-iterate the JSON). Then for each requirement pick the right 
    type
    and fill its 
    match
    — not everything is a questionnaire question. The per-type 
    match
    shapes are in 
    references/requirements-schema.md
    :
    • questionnaire question/score → 
      match: {questionnaire, section, item}
      (+ 
      expectScores
      );
    • document collected → 
      match: {docSet: "IDENTITY", types: [...]}
      ;
    • applicant-data field present → 
      type: data-field
      , 
      match: {field: "dob"}
      / 
      {fields: [...]}
      ;
    • country allowlist / prohibited jurisdictions → 
      type: country-eligibility
      , 
      match: {mustHaveAllowlist: true}
      / 
      {mustExclude: [...]}
      ;
    • selfie liveness → 
      type: liveness
      , 
      match: {}
      ;
    • capability provisioned → 
      type: entitlement
      , 
      match: {entitlement: "WATCHLISTS"}
      ;
    • screening/routing outcome → set a discriminating 
      enforcementSignal
      (NOT a generic token). Be conservative: if unsure a thing exists, leave 
      match: null
      (→ MISSING) rather than guess.
  4. Trace (deterministic). 
    python3 scripts/trace.py --requirements "$REQUIREMENTS" --graph "$CONFIG"
    → findings bucketed MISSING / SCORING-MISMATCH / COLLECTED-NOT-ENFORCED / NOT-CONFIG-REPRESENTABLE / CONFORMANT, each with evidence + a 
    basis
    (deterministic vs judgment). The bucket verdict comes from here — do not decide "enforced / not enforced" by reading the workflow JSON yourself.
  5. (Optional) hygiene sub-pass. Pipe the same graph through the bundled linter to catch silent misconfigurations (entitlement gaps, dangling preset/questionnaire refs, deprecated SDK, invalid AML provider) alongside conformance — entitlements are read straight from the graph: 
    bash scripts/resolve_graph.sh <level> | python3 scripts/lint_config.py
    . Rule catalog in 
    references/lint-rules.md
     (generated from 
    references/rules.json
    ).
  6. Report — render with the canonical formatter to 
    $REPORT
    , do NOT hand-format.     The format is fixed so every run looks identical: 
    python3 scripts/trace.py --requirements "$REQUIREMENTS" --graph "$CONFIG" | python3 scripts/report.py --date <today> > "$REPORT"
    → Markdown with a headline status, a fixed bucket-count table, findings grouped in fixed order (each with evidence + 
    basis
    ), and a fixed caveats footer. Present 
    $REPORT
    verbatim. Do not re-summarise it in prose — that's what made past runs differ. (The 
    trace.py
    JSON is the other canonical format for tooling — save it beside the others if a machine consumer needs it.)
请使用脚本——不要手动执行确定性步骤。 此技能的核心价值在于解析和结论的确定性，而非每次运行都依赖人工推导：
  • 仅通过
    resolve_graph.sh
    解析图谱。     请勿直接调用
    /resources/...
    端点、手动列出等级或自行去除
    HTTP <code>
    尾部内容——脚本会完成所有这些操作，并输出一份清晰的图谱。
  • 如果图谱无法解析，请立即停止——切勿绕过失败。 若
    resolve_graph.sh
    返回
    401
    /
    403
    、
    404
    或
    0 levels
    / “未找到等级”，则意味着无法继续运行。请直接报告失败原因（可能是令牌无效/非沙箱令牌，或等级名称错误）并停止操作。请勿编辑
    resolve_graph.sh
    （或任何脚本）以绕过错误、添加按ID回退、重试其他端点或临时生成图谱——并且绝对不要基于部分或替代图谱生成报告、统计分类数量或给出“合规”结论。无法解析图谱→无检查结果。
  • 仅从
    trace.py
    / 
    report.py
    推导结论。     请勿手动读取工作流/问卷JSON并自行判断“已执行/未执行”——这会重新引入差异和幻觉。“已收集但未执行”的发现必须来自引擎。
  • 如果脚本已运行，请信任其输出——不要通过手动API调用重新验证。
  • 如需查看图谱中的映射步骤，请运行
    python3 scripts/graph_summary.py "$CONFIG"
    。     请勿手动遍历图谱JSON：
    questionnaires
    /
    poaPresets
    /
    crossCheckPresets
    是以ID为键的字典（遍历会得到ID字符串→
    'str'对象没有'get'属性
    ），而
    entitlements
    是列表。
    graph_summary.py
    会正确打印你需要的章节/条目索引和评分。 代理的判断仅适用于两个步骤：摄取（读取监管要求）和映射（将要求与已部署的配置元素匹配——问题、文档集、字段、国家、权限）。其余所有步骤均由脚本完成。
工件——强制要求的存储位置和命名规则。 每次运行必须将工件写入源监管文件所在的同一目录，并以文件的主干名（不含扩展名的文件名）命名。切勿保存到当前工作目录或使用临时名称。请提前一次性确定准确路径：
eval "$(python3 scripts/artifact_paths.py "<path/to/RegFile.pdf>")"
#  $REQUIREMENTS = <dir>/<stem>_regulations.json   （步骤1+3中生成的要求文件）
#  $CONFIG       = <dir>/<stem>_config.json         （步骤2中resolve_graph的输出）
#  $REPORT       = <dir>/<stem>_report.md           （步骤6中生成的渲染报告）
例如：
Level4regulations.pdf
→ 
Level4regulations_regulations.json
、
Level4regulations_config.json
、
Level4regulations_report.md
。请在以下步骤中直接使用
$REQUIREMENTS
/ 
$CONFIG
/ 
$REPORT
变量。
  1. 摄取监管要求（主观判断）。只需使用Read工具读取文档——该工具原生支持PDF（渲染页面+提取文本），因此无需安装任何额外工具。 对于超过约10页的PDF，请分页面范围读取（使用Read工具的
    pages
    参数，每次调用最多读取20页）。可视化读取效果等同于或优于文本提取工具——它能保留纯文本提取会丢失的表格、标题和布局。可选操作，仅在已安装且不会造成阻塞时使用： 
    pypdf
    /
    pdftotext
    可一次性提取长篇纯文本PDF，
    scripts/render_regulation.py
    （基于PyMuPDF）可将扫描件/纯图片PDF预渲染为PNG，以便显式控制DPI——详见
    references/conformance-method.md
    步骤1。如果缺少相关库，请直接使用Read工具读取PDF。 然后提取要求并写入**
    $REQUIREMENTS
    **（源文件旁的
    <stem>_regulations.json
    ——见上述工件规则），需符合
    references/requirements-schema.md
    的规范：每项要求格式为
    {id, source, text, type, enforceable, …}
    。务必捕获
    source
    字段    ——即原始文档中的引用（章节号/标题/页码，例如
    "§5.9.2"
    、
    "Section 2 — Scoring Result"
    、
    "p.21"
    ）；报告将以此开头，以便追溯至监管要求原文，而非人工生成的ID。将SDK/平台/CRM中的结果标记为
    enforceable: sdk|platform
    。 在追踪前，请向用户展示提取的要求并确认——这是风险最高的步骤。
  2. 解析已部署的图谱（确定性操作）。运行
    bash scripts/resolve_graph.sh <levelNameOrId> > "$CONFIG"
    （包含等级+带评分的问卷+预设+自动查找的工作流+权限）。此命令可替代所有手动列等级/调用curl/去除HTTP尾部内容的操作——请勿手动执行这些步骤。
  3. 映射（主观判断）。首先检查图谱：运行
    python3 scripts/graph_summary.py "$CONFIG"
    ——它会打印带
    [section]/[item]
    索引和选项评分的问卷、文档集、APPLICANT_DATA字段、地域、权限以及工作流（请勿手动遍历JSON）。然后为每项要求选择正确的
    type
    并填写
    match
    字段——并非所有内容都是问卷问题。各类型的
    match
    格式详见
    references/requirements-schema.md
    ：
    • 问卷问题/评分 → 
      match: {questionnaire, section, item}
      （+ 
      expectScores
      ）；
    • 已收集的文档 → 
      match: {docSet: "IDENTITY", types: [...]}
      ；
    • 存在申请人数据字段 → 
      type: data-field
      , 
      match: {field: "dob"}
      / 
      {fields: [...]}
      ；
    • 国家白名单/禁止管辖区域 → 
      type: country-eligibility
      , 
      match: {mustHaveAllowlist: true}
      / 
      {mustExclude: [...]}
      ；
    • 自拍活体检测 → 
      type: liveness
      , 
      match: {}
      ；
    • 已配置的功能 → 
      type: entitlement
      , 
      match: {entitlement: "WATCHLISTS"}
      ；
    • 筛查/路由结果 → 设置一个具有区分度的
      enforcementSignal
      （而非通用令牌）。 请保持谨慎：如果不确定某内容是否存在，请将
      match: null
      （→ 标记为缺失），而非猜测。
  4. 追踪（确定性操作）。运行
    python3 scripts/trace.py --requirements "$REQUIREMENTS" --graph "$CONFIG"
    → 检查结果将被归类为缺失/评分不匹配/已收集但未执行/无法通过配置体现/合规，每个类别均包含证据和
    basis
    （确定性结论 vs 主观判断）。分类结论来自此步骤——请勿通过读取工作流JSON自行判断“已执行/未执行”。
  5. （可选）健康检查子流程。将同一图谱传入附带的检查工具，以在合规性检查之外发现隐性配置错误（权限缺口、悬空的预设/问卷引用、已弃用的SDK、无效的AML提供商）——权限直接从图谱中读取： 
    bash scripts/resolve_graph.sh <level> | python3 scripts/lint_config.py
    。规则目录位于
    references/lint-rules.md
    （由
    references/rules.json
    生成）。
  6. 报告——使用标准格式化工具生成
    $REPORT
    ，请勿手动格式化。     格式固定，确保每次运行的报告外观一致： 
    python3 scripts/trace.py --requirements "$REQUIREMENTS" --graph "$CONFIG" | python3 scripts/report.py --date <today> > "$REPORT"
    → 生成Markdown格式报告，包含标题状态、固定的分类统计表格、按固定顺序分组的检查结果（每个结果包含证据+
    basis
    ）以及固定的免责声明页脚。请直接呈现
    $REPORT
    内容，请勿用 prose 重新总结——这正是过去运行结果不一致的原因。（
    trace.py
    输出的JSON是供工具使用的另一种标准格式——如果有机器消费者需要，请将其与其他工件保存在一起。）

What it does NOT do (say it)

不支持的功能（请明确告知用户）

  • Not a compliance guarantee or a replacement for a compliance officer.
  • Does not verify semantic correctness beyond presence + scores + routing-enforcement (e.g. whether a question's wording is legally adequate is judgment).
  • Cannot verify SDK/platform/CRM outcomes (disclosure pop-ups, demo accounts, read-only mode, the 25%/10% restriction, CRM timestamps) — these are bucketed 
    NOT-CONFIG-REPRESENTABLE
    .
  • 并非合规保证，也不能替代合规专员。
  • 除了存在性+评分+路由执行之外，不验证语义正确性（例如，问题措辞是否合法合规属于主观判断）。
  • 无法验证SDK/平台/CRM的结果（披露弹窗、演示账户、只读模式、25%/10%限制、CRM时间戳）——这些将被归类为
    无法通过配置体现
    。

Guardrails

约束规则

  • Keep deterministic facts separate from judgment (the 
    basis
    field). Never present a mapping guess as a verified finding.
  • The trace walks requirements → deployment only — it never flags a deployed question as "extraneous" (avoids the false-positive class). Report extra questions, if at all, as an explicit advisory note.
  • enforcementSignal
    must be discriminating — a generic token (
    country
    ) matches catch-all edges and yields false CONFORMANT. See 
    references/requirements-schema.md
    .
  • Fail honestly — never work around a resolution failure. If 
    resolve_graph.sh
    returns an auth error / 404 / 
    0 levels
    , stop and report it. Do not edit the scripts to bypass it or fabricate a report from a partial graph (see the Procedure callout).
  • 请将确定性事实与主观判断分开（通过
    basis
    字段）。切勿将映射猜测作为已验证的检查结果呈现。
  • 追踪仅按照要求→部署的方向进行——绝不会将已部署的标记为“多余”（避免误报）。如需报告额外问题，请作为明确的建议说明。
  • enforcementSignal
    必须具有区分度——通用令牌（如
    country
    ）会匹配所有边缘情况，导致错误的“合规”结论。详见
    references/requirements-schema.md
    。
  • 诚实地面对失败——切勿绕过解析失败。 如果
    resolve_graph.sh
    返回认证错误/404/
    0 levels
    ，请停止操作并报告。请勿编辑脚本以绕过错误，或基于部分图谱生成报告（见操作流程中的提示）。

See also

相关链接

  • references/requirements-schema.md — the requirement model + buckets.
  • references/conformance-method.md — the five steps, guardrails, scope.
  • references/lint-rules.md — the bundled hygiene-lint rule catalog (sub-pass).
  • sumsub-analyze-regulation
     — the opposite direction (regulation → build plan).
  • references/requirements-schema.md — 要求模型+分类规则。
  • references/conformance-method.md — 五个步骤、约束规则、适用范围。
  • references/lint-rules.md — 附带的健康检查规则目录（子流程）。
  • sumsub-analyze-regulation
     — 反向流程（监管要求→构建计划）。

Worked examples (
examples/
)

示例（
examples/
目录下）

  • sample-requirements.json
    + 
    sample-graph.json
    — synthetic, exercise every bucket (drive 
    test_trace.py
    ).
  • fiu-india-vasp-mapped.json
    + 
    vasp-graph.json
    — a broad AML guideline mapped against a hypothetical VASP level; self-contained, trace them together offline: 
    python3 scripts/trace.py --requirements examples/fiu-india-vasp-mapped.json --graph examples/vasp-graph.json | python3 scripts/report.py
    .
  • cfd-requirements.json
    — real CFD/MiFID requirements (run against a live 
    cfd-onboarding-eu
    graph).
  • fiu-india-requirements.json
    — the ingest-stage output for that broad guideline (before mapping).
  • audit-input{,-dirty}.json
    — hygiene-linter fixtures (drive 
    test_lint.py
    ).
  • sample-requirements.json
    + 
    sample-graph.json
    — 合成示例，覆盖所有分类（用于
    test_trace.py
    测试）。
  • fiu-india-vasp-mapped.json
    + 
    vasp-graph.json
    — 将广泛的AML指南映射到假设的VASP等级；可独立运行，离线追踪： 
    python3 scripts/trace.py --requirements examples/fiu-india-vasp-mapped.json --graph examples/vasp-graph.json | python3 scripts/report.py
    。
  • cfd-requirements.json
    — 真实的CFD/MiFID要求（针对实时
    cfd-onboarding-eu
    图谱运行）。
  • fiu-india-requirements.json
    — 上述广泛指南的摄取阶段输出（映射前）。
  • audit-input{,-dirty}.json
    — 健康检查工具的测试用例（用于
    test_lint.py
    测试）。