The Documented Defence That Doesn't Exist: Trust Calibration in Security Products

Why documentation matters more in security products

For most software, documentation drift is a usability issue. Users discover what the product actually does through experimentation; the documentation becomes a tertiary source of truth. The cost is friction, occasionally support tickets, rarely an incident.

For security products, documentation drift is a different category. Procurement teams evaluate the product on the basis of its documented controls. Customer security questionnaires are answered by reference to the documentation. Internal architecture review approves integrations on the basis of what the documentation promises. The downstream decisions that depend on the documentation are not corrected by experimentation; they are made once and then carried forward.

If the documentation claims a defence that the implementation does not deliver, every one of those decisions is built on the wrong premise. The customer who adopts the product believing it provides a control receives a product that does not. The auditor who signs off on an integration receives reassurance that does not match what they would have observed in the code. The mismatch is not discovered until something goes wrong — at which point the documentation becomes evidence, not a reference.

How drift forms quietly

The pattern is rarely deliberate. It usually forms through several small steps:

• An aspirational document is written. The team describes the security posture they intend to build, in a tense that does not distinguish "intended" from "implemented."
• Implementation lags the document. A subset of the described controls ships; others are deferred to "next quarter" and accumulate.
• The document is referenced as if complete. Marketing material, customer questionnaires, and internal references all cite the document. The aspirational tense becomes invisible.
• Drift compounds with each cycle. Each new feature is documented with the same aspirational style; each one accumulates the same gap; the document gets steadily further from the code.

None of these steps is malicious. None is even unusual. The pattern is the predictable outcome of writing documentation first and never auditing it against the implementation later.

The Documented Defence That Doesn't Exist anti-pattern

A hypothetical procurement scenario

The following illustrates a plausible failure mode under the Documented Defence That Doesn't Exist anti-pattern. It is constructed from elements common to several reported industry patterns; no specific incident is implied.

A customer evaluates a security product as part of a procurement cycle. The product's documentation describes a layered defence against indirect prompt injection. The customer's security team reads the documentation, finds the controls described, and approves the procurement. The product is integrated into the customer's workflow.

Six months later, a real injection attempt influences the product's behaviour in a way that produces a misleading report. The customer's security team investigates and discovers that the documented controls were not, in fact, implemented in the configuration the customer was using — they were described as if always present, but required a configuration setting the customer's deployment did not select. No one had reconciled the documentation against the customer's actual configuration; no test had asserted the claim under representative conditions.

The technical fix is small. The relationship damage is larger. The customer now has to explain to their auditor why the procurement approval was based on documentation that did not match the deployed state. The supplier has to explain why the documentation said what it said.

A security product's documentation is part of its trust surface. It deserves the same discipline as its code.

The two-track fix

The remediation has two parallel tracks. Both are required.

Track one: raise the implementation to meet the documentation

For claims that should be true and are worth keeping — controls the product genuinely wants to provide — implement them. Add the missing tests, ship the missing configuration default, build the missing layer. The documentation becomes accurate by the implementation catching up.

Track two: rewrite the documentation to match the implementation

For claims that are aspirational, premature, or misleading — controls the product does not currently provide and is not committing to provide in the immediate term — rewrite them. The honest version frequently reads better than the marketing version, because it is specific rather than vague: "the product provides X under configuration Y" rather than "the product provides X automatically."

Both tracks need a recurring reconciliation. Documentation that was accurate at release will drift by the next release if the discipline is not built into the team's normal cycle. Make the reconciliation a release-gate item; the cost of including it is much smaller than the cost of not including it.

A practical checklist

• Customer-facing documentation distinguishes "implemented" from "planned" or "experimental" controls explicitly.
• Every documented control names the configuration required to activate it; defaults are stated plainly.
• Documented controls have corresponding tests that assert their presence and effect; tests run on every release.
• A documentation-versus-code reconciliation is performed at every release and recorded.
• The customer-facing security data sheet is reviewed and signed off by both engineering and security at every release.
• Customer security questionnaires are answered by reference to the data sheet, not by ad-hoc claims.
• Marketing language avoids unqualified terms like "automatic," "built-in," and "immune" for security properties.
• The product's threat model is published in summary form and reflects current implementation, not future intent.
• A named owner is responsible for documentation accuracy across releases.
• Incident post-mortems include a check for documentation that contributed to the incident; corrections are tracked alongside code corrections.

Test your own codebase in ten minutes

The fastest way to find out whether this anti-pattern is present in your own system is to ask an AI coding assistant to look for it. Run the prompt below in a fresh chat session, on its own — this check is precisely about whether the code backs up what the documentation claims, so the assistant must read both.

Search the whole repository to find where this applies — do not
wait for me to list files. Ignore generated, vendored, and dependency
folders (build output, node_modules, vendor). Read every source file
the failure mode could touch, and also read README.md and any docs/
file that mentions security, sandboxing, isolation, logging,
redaction, authentication, or permissions. List the search terms you
used so I can confirm nothing was missed.

You are looking for one specific failure mode: a security-relevant
claim in the documentation is not backed by an implementation in
the source.

For each claim, quote the doc sentence verbatim, then either point
to the file/lines that implement it or state "no implementation
found".

Respond with exactly these four sections:
1. VERDICT: one of [present / not present / unclear]
2. EVIDENCE: file path + line numbers + a one-line quote per claim
3. WHY IT MATTERS: two sentences, plain English
4. FIX: a concrete change, with a short before/after code snippet
   if applicable. If "unclear", list the one piece of context you
   need to decide.

Insist on the four-part answer: a verdict with a file path, a line number, and a one-line quote is something you can act on; a verdict on its own is just an opinion. If the result is present, the FIX section is your starting point — either implement the control the documentation promises, or correct the documentation so it matches the code. Re-run the same prompt after the change to confirm the verdict flips to not present.

Conclusion

Trust calibration is not a soft skill. For security products it is part of the engineering work. Documentation that matches the implementation produces accurate customer decisions, defensible audit answers, and a brand that strengthens over time. Documentation that drifts produces the opposite — and the difference is detected at the worst possible moment.

The discipline required is small relative to the consequences of its absence. Reconcile documentation to code at every release. Distinguish what is implemented from what is planned. State configurations explicitly. The next post-mortem will go differently.