Back to Details

intended-vs-implemented

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Intended vs. Implemented: Auditing the Gap

预期功能 vs 实际实现：审计差距

Purpose

目的

A linter scans code in a vacuum. It can tell you the code is internally consistent; it cannot tell you the code does what you meant, because it has no model of your intent. The highest-value security and correctness bugs live in that gap — a permission documented but never enforced, a "cron-only" endpoint anyone can call, a field marked public-only that leaks private data.
This skill is the method for finding that gap. It is the differentiator: it only works when intent has been written down first (see the shipping-artifacts skill), and that's exactly why commodity tools can't replicate it.
Linter（代码检查工具）在孤立环境中扫描代码。它能告诉你代码在内部是一致的，但无法判断代码是否符合你的预期，因为它没有你的意图模型。最高价值的安全和正确性漏洞就存在于这个差距之中——比如文档中记录了权限但从未执行、标记为“仅cron可用”的端点任何人都能调用、标记为仅公开的字段泄露了私有数据。
这个技能就是找出该差距的方法。它的独特之处在于：只有当先记录了意图（参见shipping-artifacts技能）时才能生效，而这正是通用工具无法复制它的原因。

Context

适用场景

Use this when documented intent exists — 
permissions.md
, 
architecture.md
, 
variables.md
, etc. If those docs are absent or stale, that absence is itself the first finding: you cannot audit intent you never recorded. Recommend documenting first, then auditing.
当存在已记录的意图时使用此方法，比如
permissions.md
、
architecture.md
、
variables.md
等文档。如果这些文档缺失或过时，那么缺失本身就是第一个发现：你无法审计从未记录的意图。建议先编写文档，再进行审计。

Method

方法

  1. Establish intent. Read the 
    /documentation/*.md
    set as the source of truth for what should be true: who may access what, which boundaries are trusted, which data is public. Treat the docs as claims to verify, not as proof.
  2. Gather implementation evidence. Read the code that enforces (or fails to enforce) each claim. Evidence is a cited file and line — the actual authorization check, the actual query filter, the actual sanitizer. "It's probably handled upstream" is not evidence; the code path is.
  3. Compare claim to code, one boundary at a time. For each documented rule, ask: does an enforcement point actually implement it, on the server, on every path? Distrust comments like "internal only," "admin only," or "validated elsewhere" — verify them in code.
  4. Classify each mismatch by whether it matters. A mismatch matters when crossing it lets a real actor reach data, money, infrastructure, or another tenant they shouldn't. It does not matter when the only person affected is the actor themselves on their own data. Drop cosmetic drift; keep boundary-crossing drift.
  5. Avoid hand-wavy findings. Every finding names: the documented intent (quote the doc), the implemented reality (cite the code), the attacker and victim, and the concrete fix. If you cannot cite both sides of the gap, it is a question to investigate, not a finding to report.
  1. 确立意图：将
    /documentation/*.md
    文档集作为系统“应然”状态的唯一来源：谁可以访问什么内容、哪些边界是可信的、哪些数据是公开的。将文档视为需要验证的声明，而非证据。
  2. 收集实现证据：阅读执行（或未执行）每项声明的代码。证据是引用的文件和行号——实际的授权检查、实际的查询过滤器、实际的清理器。“可能在上游处理”不算证据，代码路径才算。
  3. 逐一对比声明与代码：对于每条文档化规则，询问：服务器上是否在所有路径上都有一个执行点来实现该规则？不要轻信“仅内部可用”、“仅管理员可用”或“在其他地方已验证”等注释——要在代码中验证它们。
  4. 对每个不匹配问题进行重要性分类：当跨越该差距会让真实角色获取到他们本不应访问的数据、资金、基础设施或其他租户资源时，该不匹配问题才至关重要。如果只有角色自身的受影响数据受到影响，则无关紧要。忽略表面差异；保留跨越边界的差异。
  5. 避免模糊不清的发现：每个发现都应明确：已记录的意图（引用文档内容）、实际实现情况（引用代码）、攻击者与受害者，以及具体修复方案。如果你无法引用差距的双方，那这是一个需要调查的问题，而非可报告的发现。

What counts

判定标准

  • Intent: a documented rule, boundary, scope, or public/private classification.
  • Implementation evidence: a cited enforcement point (or its provable absence) in the code.
  • A mismatch that matters: doc says one thing, code does another, and the difference crosses a trust, cost, data, or tenant boundary.
  • 意图：文档化的规则、边界、范围，或公开/私有分类。
  • 实现证据：代码中引用的执行点（或可证明其不存在）。
  • 重要的不匹配问题：文档说明的内容与代码实际执行的内容不符，且这种差异跨越了信任、成本、数据或租户边界。

Notes

注意事项

  • Documented-but-unenforced is a finding on its own — rank it by what crossing the gap exposes.
  • Undocumented-but-enforced is usually fine, but flag it: the docs are now stale, which weakens the next audit.
  • This method feeds the security and performance audits; it does not replace their sink-level analysis — it adds the intent axis they lack.
  • Never fabricate intent to manufacture a gap. If the docs are silent, say the docs are silent.
  • 仅在文档中记录但未执行的情况本身就是一个发现——根据跨越差距所暴露的内容进行分级。
  • 未在文档中记录但已执行的情况通常没问题，但要标记出来：文档现已过时，这会削弱下一次审计的效果。
  • 此方法为安全和性能审计提供支持；它不会取代这些审计的底层分析——而是增加了它们所缺少的意图维度。
  • 切勿为制造差距而编造意图。如果文档未提及相关内容，就说明文档存在空白。