Code Security: guarantees, setup, incident, privacy and reason-code docs

[maximelb]

Summary

Public documentation for Code Security's evidence chain, image lineage, runtime checks and remediation runs, in four sets:

• Configuration: containment-setup.md covers the cloudsec.respond permission (separate from cloudsec.set, needed for AutoFix and remediation decisions), connection permissions (GitHub App Attestations: Read-only, Artifact Analysis Occurrences Viewer), webhooks, image lineage statuses, build provenance, Terraform maps, pull-request disclosure (pr_live_context), remediation runs, response playbooks and exclusions. configuration.md gets the current collection-exclusion rules (per-row account/provider/region, rows kept when a fact is missing, relationship removal, delete events) and the scanning list.
• Support: reasons.md lists every unknown, partial and refusal reason code with the action to take. troubleshooting.md links to it.
• Incident: incident-response.md covers what happens automatically, what never does, and how to cancel or undo a remediation.
• Privacy: data-handling.md covers what is read, what is kept, secret handling, retention and purge. The purge text keeps the backup qualifier.

guarantees.md states the product's rules in plain terms. autofix.md now describes AutoFix as a remediation run that needs cloudsec.respond. index.md no longer says file contents are never stored: it now says findings never hold them and that transient packages are deleted.

This complements #453 (the provider-setup steps for the two new read permissions). The two PRs touch different hunks of index.md.

Before merging

Merge this when the matching features reach production, not before:

• AutoFix requiring cloudsec.respond and running as a remediation run is not yet the production behavior.
• The CLI commands shown here (cloudsec remediation ..., cloudsec code iac-map extract|push) are on the CLI's main branch but not in the latest PyPI release (5.6.2).
• The iac-map-extract binary that iac-map extract calls needs a public download location before the Terraform map section is usable.

Validation

• mkdocs build --strict passes. Every new #anchor link was checked against the built site.
• markdownlint-cli2 reports 0 issues.
• Each code, limit and permission was checked against the service code. An adversarial review of the pristine commit runs next, and its findings will be posted on this PR.
• The diff was checked for private repository names, internal hostnames and identifiers. None are present.

This is a public repository. It is left open for maintainer review and merge.

🤖 Generated with Claude Code

[maximelb]

Adversarial review, first pass (commit 493bc8f), and fixes (commit 9365787)

An independent reviewer checked every claim on these pages against the service code. It found 12 high, 3 medium and 1 low findings. All are fixed in 9365787:

• Verified fixes. The rule now includes three conditions that were missing: every running digest must be a proven build of the fix; the clean scan must come from a scanner that reported the original vulnerability; and a repository fix with no deployment in scope ends expired with pr_merged_unverifiable, never verified. AutoFix and the incident page now say the same.
• Lineage. inferred names the repository but never the build commit or a commit range. verified also covers a pushed statement that matches a trusted identity in provenance_trust. The "only Google Cloud Build and GitHub" wording now applies only to evidence Code Security collects itself.
• Runtime. Incomplete telemetry gives present or unknown with a reason, and never not_observed. A package already seen running stays positive. A runtime check starts package-evidence collection on the finding's sensors, so it is no longer described as read-only.
• Pull-request disclosure. resource_details adds per-declaration detail but still leaves resource names out of the pull request.
• Incident page. Closing a fix pull request does not end the run immediately; the run ends at its deadline. An unproven fix ends persists (old digest still running) or expired with deadline, not window_ended.
• Privacy. "Keyed to your organization" is now limited to records that hold customer data. The AI line now says AutoFix sends no code to a language model and that no AI-generated fix feature is available.
• Reasons page. The field table is limited to chain and coverage fields, and the reason_domain/reason order is fixed. The page now says it covers the generally available workflows.
• Reference and configuration. The permission summary names the runtime-check and remediation exceptions. A tenant-wide collector can also be excluded by a matching provider rule.

Release timing, not a documentation error: the remediation and iac-map CLI commands are on the CLI's main branch but not in PyPI 5.6.2.

A second review pass is running on 9365787.

[maximelb]

Second review pass (commit 9365787) and fixes (commit ce2cd99)

The second pass found 6 high, 5 medium and 1 low. Fixed in ce2cd99:

• The opening sentence on guarantees.md now says incomplete evidence is reported as unknown, partial or present with a reason, not always as unknown.
• A fix build means an uncontested build record, asserted or verified, that names the fix commit. It no longer claims "proven".
• Only a merged repository fix with no deployment in scope ends as unverifiable. An image fix keeps watching.
• Inferred and label-based lineage needs no pipeline change. A verified link needs a signed attestation, and the build has to produce that attestation.
• Isolation expires after at most 4 hours and cleanup releases it. If a release fails, cleanup retries and a HIGH finding opens. The docs no longer promise a hard release.
• The scanning exclusion list is accepted but has no effect today, because the agentless workload scanner is not available.
• The reference permission summary now names the map-status read (cloudsec.set).
• The data-handling wording on build records now matches the lineage levels.
• The reasons page says which catalog codes are for validation templates that are not generally available.
• The exclusion note wording no longer mentions a count.
• GitLab and Bitbucket writes are now described as "not enabled yet", consistent with the reference page.

Not changed: the reviewer said closing a fix pull request ends the run with pr_closed. The verifier handles a closed pull request, but the current pull-request follow-up reports merges only, and no component reports a close. The page therefore keeps "the run keeps monitoring until its deadline and then ends expired", which is what happens today. That line will need an update when close reporting ships.

[maximelb]

Reviewed the new commit from a pristine archive. The four changed pages consistently say that a person or API key with cloudsec.respond may approve an AutoFix request, and that the same identity is recorded as requester and approver. I checked the changed files for broken links, private references, and conflicting human-only wording; no issues found. This PR remains open for the documented release timing.

[limacharlie-refractionpoint]

LimaCharlie Cloud Security — code scan

No new code findings were introduced by this pull request.

This check reports and never fails: no gating.fail_on is set on the code_scanning policy.

Scanned refractionPOINT/documentation e2922ee…30b3b7f — only findings new in the head commit are listed; anything already on the base branch is the repository's own finding set, on the Cloud Security Code page.

This comment is updated in place on every push to this pull request.