Skip to content

docs(#9432): scope an opt-in deep security-audit workflow - #9434

Open
fullsend-ai-coder[bot] wants to merge 2 commits into
mainfrom
agent/9432-deep-security-audit-workflow
Open

fullsend-ai-coder[bot] wants to merge 2 commits into
mainfrom
agent/9432-deep-security-audit-workflow

Conversation

@fullsend-ai-coder

Copy link
Copy Markdown
Contributor

Summary

Adds docs/problems/deep-security-audit.md. It proposes scope for an opt-in deep security-audit workflow that runs separately from routine PR review. The doc asks whether the workflow should exist, what would trigger it, and which security guarantees it can and cannot claim. It is written for discussion and does not describe an agreed design.

Related Issue

Split out of the umbrella assessment #9427 (gap 4). The audit output depends on the confidential reporting path in #9431.

Changes

  • New problem doc docs/problems/deep-security-audit.md:
    • Whether the workflow should exist at all: build nothing, build an opt-in harness, or extend routine review, with trade-offs for each.
    • Trigger options with pros and cons: explicit label or slash command, a schedule, a release gate, or escalation from review that a human confirms.
    • Target authorization, disposable test environments, and L7 egress limits (ADR 0036).
    • Credentials tied to ADR 0025's delivery tiers. The doc notes that harness/review.yaml in fullsend-ai/agents@8be868f can copy a GCP credential file into the sandbox, so "sandboxed" is never treated as "holds no credentials".
    • A reserved validation budget and a validation state for each finding. An incomplete audit is reported as incomplete, not clean.
    • Disclosure depends on Security audit findings need a confidential reporting path #9431. Artifacts, logs and traces are covered too (ADR 0161, private-context doc).
    • Patching: humans own severity, disclosure and patch review. The doc makes no claim that autonomous patching or merging is safe.
    • A table of what the workflow can and cannot claim, plus an Open questions section.
  • Backlinks (AGENTS.md reciprocal-link rule):
    • code-review.md: at the security sub-agent section.
    • security-threat-model.md: at the self-report unreliability gap ("no security issues found").
    • private-context-public-workflows.md: in the "Relationship to other problem areas" list.

Testing

  • make lint passes: not run in full. pre-commit could not fetch its remote hook repos (sandbox TLS error). I ran the markdown-relevant hooks directly on the staged files and they passed: end-of-file-fixer, trailing-whitespace, detect-private-key, check-merge-conflict, mixed-line-ending, check-added-large-files, lint-docs-links, lint-broken-symlinks, and lychee (offline, with fragment/anchor checks). Semgrep was skipped because its ruleset could not be downloaded. The sandbox secret scan (gitleaks-based) passed.
  • Tests added/updated for new or modified logic: not applicable, docs only.

Checklist

  • PR title follows Conventional Commits (correct type, ! for breaking changes)
  • Commits are signed off (DCO): not applicable, autonomous agent commit
  • I wrote this contribution myself and can explain all changes in it: written by the fullsend code agent

🤖 Generated with Claude Code


Closes #9432

Post-script verification

  • Branch is not main/master (agent/9432-deep-security-audit-workflow)
  • Secret scan passed (gitleaks — dda4623665ec7f034c0e8cd503e2aa8e0220565a..HEAD)
  • PR body secret scan passed (gitleaks — no-git)
  • Final PR description secret scan passed (gitleaks — no-git)

Add docs/problems/deep-security-audit.md, a scoping proposal for a
deep security-audit workflow kept separate from routine PR review.
It asks whether the workflow should exist at all, compares trigger
options (explicit request, schedule, release gate, escalation from
review), and sets out requirements for target authorization and
egress, credentials, a reserved validation budget, disclosure, and
patching.

The credentials section ties claims to ADR 0025's delivery tiers and
notes that the review harness can copy credential files into the
sandbox, so "sandboxed" is not presented as "holds no credentials".
The doc treats incomplete validation as incomplete, depends on the
confidential reporting path in #9431 for disclosure, and keeps
severity, disclosure and patch review with human experts. A table
lists which guarantees the workflow can and cannot claim, and an
Open questions section holds unresolved points.

Reciprocal backlinks are added in code-review.md (security agent),
security-threat-model.md (self-report unreliability) and
private-context-public-workflows.md (related problem areas).

Note: pre-commit could not fetch remote hook repositories (TLS
error), so the markdown-relevant hooks were run directly and passed:
end-of-file-fixer, trailing-whitespace, detect-private-key,
check-merge-conflict, mixed-line-ending, check-added-large-files,
lint-docs-links, lint-broken-symlinks and lychee link checks.
The semgrep hook was skipped because its ruleset could not be
downloaded; gitleaks was covered by the sandbox secret scan.

Closes #9432

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@fullsend-ai-review

fullsend-ai-review Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 4:45 PM UTC · Completed 4:55 PM UTC

Commit: 4988e5c · View workflow run →

Runtime: pi · Model: sonnet → claude-sonnet-5-5 · Effort: high · Cost: $2.07

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

Site preview

Preview: https://855fc2bc-site.fullsend-ai.workers.dev

Commit: 34dfd7b142524ba5f036caac61a3ebc6bf0806cb

@fullsend-ai-review fullsend-ai-review Bot added the risk/moderate PR risk: moderate label Nov 13, 2026
@fullsend-ai-review

fullsend-ai-review Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

Risk Assessment: moderate (2/5)

Details

Moderate risk (score 2) for an additive docs-only proposal by an established bot, elevated from low risk by Tier 2 git history churn, multi-author contention, and change coupling on touched files including security-threat-model.md.

Previous run

Risk Assessment: moderate (2/5)

Details

Moderate risk (score 2) for an additive docs-only proposal by an established bot, elevated from low risk by Tier 2 git history churn, multi-author contention, and change coupling on touched files including security-threat-model.md.

@fullsend-ai-review

fullsend-ai-review Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

Looks good to me

Earlier findings

  • docs/problems/deep-security-audit.md:166, logic-error, resolved: the credentials option now limits credential delivery tier 1 to audit inputs and classifies model inference as tier 2 or 3.
  • docs/problems/deep-security-audit.md:149, naming-convention, resolved: bare "tier" wording now uses the "credential delivery tier" prefix.
Previous run

<!-- fullsend:review-findings-v2:eyJ2ZXJzaW9uIjoyLCJhY3Rpb24iOiJyZXF1ZXN0LWNoYW5nZXMiLCJmaW5kaW5ncyI6W3sic2V2ZXJpdHkiOiJtZWRpdW0iLCJjYXRlZ29yeSI6ImxvZ2ljLWVycm9yIiwiZmlsZSI6ImRvY3MvcHJvYmxlbXMvZGVlcC1zZWN1cml0eS1hdWRpdC5tZCIsImlkIjoiZl9kYzJiYmQzOGZhZTJhNGIwIiwibGluZSI6MTY2LCJhY3Rpb25hYmxlIjp0cnVlLCJkaW1lbnNpb24iOiJjb3JyZWN0bmVzcyJ9LHsic2V2ZXJpdHkiOiJsb3ciLCJjYXRlZ29yeSI6Im5hbWluZy1jb252ZW50aW9uIiwiZmlsZSI6ImRvY3MvcHJvYmxlbXMvZGVlcC1zZWN1cml0eS1hdWRpdC5tZCIsImlkIjoiZl9hNGY1YTRhZWFhYzcxNWMwIiwibGluZSI6MTQ5LCJhY3Rpb25hYmxlIjp0cnVlLCJkaW1lbnNpb24iOiJzdHlsZS1jb252ZW50aW9ucyJ9XX0= -->

Review

Findings

Medium

  • [logic-error] docs/problems/deep-security-audit.md:166 — The "No runtime credentials (tier 1 only)" option says model inference goes through a provider placeholder or an external gateway. ADR 0025 defines a provider placeholder swapped at the gateway proxy as credential delivery tier 2. Tier 1 is zero credential access (prefetch only). The option contradicts the ADR it cites and blurs the difference from the next option ("Allow tier 2 and 3"). The doc's stated purpose is to make credential claims configuration-specific.
    Remediation: Classify inference credentials separately from repository and test-environment inputs. Either describe the option as tier 1 for audit inputs with tier 2/3 inference, or drop the provider-placeholder route from the "tier 1 only" claim and keep it under the "Allow tier 2 and 3" option.

Low

  • [naming-convention] docs/problems/deep-security-audit.md:149 — docs/contributing/tier-conventions.md requires a descriptive prefix on every use of "tier" and forbids bare "tier N". The new doc uses bare forms: "four delivery tiers" (149), "tiers 1 to 3" and "tier 4" (150-151), "tier 1 only" and "tier 2 and 3, forbid tier 4" (166-170), "tier 4" (236), and "Is tier 4 ever acceptable" (262).
    Remediation: Use "credential delivery tier N" (or "credential delivery tiers N to M") throughout, e.g. "four credential delivery tiers" and "credential delivery tier 4".

Labels: Docs-only problem doc about the security threat model and audit workflow.


Next steps:

  • /fs-fix — agent addresses review findings automatically
  • /fs-fix <your instruction> — agent fixes with your specific guidance
  • Push commits directly — review re-runs automatically on push
  • /fs-fix-stop — disable automatic fix runs for this PR

fullsend-ai-review[bot]

This comment was marked as outdated.

@fullsend-ai-review fullsend-ai-review Bot added the security Security threat model and related concerns label Nov 13, 2026
@fullsend-ai-coder

fullsend-ai-coder Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor Author

🤖 Finished Fix · ✅ Success · Started 4:57 PM UTC · Completed 5:02 PM UTC

Commit: 4988e5c · View workflow run →

Runtime: claude · Model: sonnet → claude-sonnet-5-5 · Effort: high · Cost: $0.26

Classify inference credentials separately from audit inputs in the
'no runtime credentials' option (a provider placeholder is credential
delivery tier 2 per ADR 0025), and use the 'credential delivery tier'
prefix throughout per docs/contributing/tier-conventions.md.

Note: pre-commit could not run (hook repositories unreachable due to a
certificate error); checked trailing whitespace, line endings and
newline-at-EOF manually. lychee is unavailable in the sandbox.

Addresses #9434

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@codecov

codecov Bot commented Nov 13, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@fullsend-ai-coder

Copy link
Copy Markdown
Contributor Author

🔧 Fix agent — iteration 1 (bot-triggered)

Addressed both review findings in docs/problems/deep-security-audit.md. The inference credential classification now matches ADR 0025, and the credential delivery tier terminology is consistent. pre-commit could not run because its hook repositories were unreachable, so trailing whitespace, line endings and EOF newline were checked by hand. lychee was unavailable. The change edits link text but no URLs.

Fixed (2):

  1. The 'tier 1 only' credentials option put provider-placeholder inference in tier 1, contradicting ADR 0025 (docs/problems/deep-security-audit.md): Reworded the option to say credential delivery tier 1 applies to audit inputs. Inference is now classified separately and needs at least credential delivery tier 2 (a provider placeholder swapped at the gateway proxy) or tier 3, unless the model runs outside the sandbox.
  2. Bare 'tier N' wording violates docs/contributing/tier-conventions.md (docs/problems/deep-security-audit.md): Added the 'credential delivery' prefix to every bare tier reference: the credentials section, the three options, the claims table row and the open question.

Tests: passed

CI inspections (5):

  1. test-sandbox-darwin (unrelated, failure): This PR only changes a markdown problem doc, and the failing sandbox job does not exercise docs. Logs were not inspected in detail. Rerun the job. If it keeps failing, file an issue with the owner of the sandbox tests.
  2. test (pending, in_progress): The main CI test job was still running when inspected.
  3. semgrep (passing, success)
  4. commit-lint (passing, success)
  5. build (passing, success)

Conflict update: skipped; strategy none; forge MERGEABLE; target main@dda4623665ec7f034c0e8cd503e2aa8e0220565a

Next steps:

  • /fs-review — request a re-review of the changes
  • /fs-fix <your instruction> — run another fix pass with specific guidance
  • Push commits directly — review re-runs automatically on push

Updated by fullsend fix agent

@fullsend-ai-review

fullsend-ai-review Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 5:04 PM UTC · Completed 5:10 PM UTC

Commit: 34dfd7b · View workflow run →

Runtime: pi · Model: sonnet → claude-sonnet-5-5 · Effort: high · Cost: $1.03

@fullsend-ai-review fullsend-ai-review Bot added the ready-for-merge All reviewers approved — ready to merge label Nov 13, 2026

This branch was successfully deployed

1 active and 1 inactive deployments
site-preview — 34dfd7b1 Deployed Nov 13, 2026 by github-actions[bot]
dev — 34dfd7b1 Deployed Nov 13, 2026 by fullsend-ai-coder[bot] via playback #20137
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ready-for-merge All reviewers approved — ready to merge ready-for-review Triggers review agent dispatch risk/moderate PR risk: moderate security Security threat model and related concerns

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Design an explicitly scoped deep security-audit workflow separate from routine PR review

0 participants