Add TruffleHog secret-leak warnings for uploaded skills

[Patrick-Erichsen]

Problem

Publishers can accidentally upload live API keys, tokens, private keys, or other credentials inside SKILL.md or bundled skill files. ClawHub currently has artifact security scanning, but leaked secrets need a narrower response: warn the publisher so they can rotate/remove the credential.

This should not become a ClawScan signal, moderation verdict, or install-blocking policy in v1.

Goal

Add async TruffleHog-based secret scanning for uploaded skill versions. When ClawHub detects a likely leaked secret, notify the publisher through owner-facing UI; when the secret is verified/live, also email the publisher so they see it quickly.

For a comparable implementation pattern, Hugging Face added TruffleHog to their automated scanning pipeline for uploaded repository content: https://huggingface.co/blog/trufflesecurity-partnership

Scope

• Scan uploaded skill version files after publish.
• Prefer the simplest hosted/API integration with Truffle Security if available.
• If no suitable hosted async API exists, use the thinnest separate secret-scan worker path.
• Store only sanitized finding metadata:
  • detector/type
  • verified/unverified status
  • redacted value
  • file path
  • line number when available
  • stable fingerprint/dedupe key
  • checked timestamp
• Show private warning UI to the skill owner/uploader for detected secrets.
• Send email notifications for verified/live secrets so publishers are alerted promptly.
• Do not email on unverified detections in v1, to avoid noisy alerts.
• Document that detected secrets should be rotated, not just removed from ClawHub.

Non-goals

• Do not feed TruffleHog findings into ClawScan prompts.
• Do not change ClawScan verdicts.
• Do not auto-hide, block installs, or mark skills malicious from this alone.
• Do not expose raw secrets publicly or privately.
• Do not email on unverified secrets in v1.
• Do not include packages/plugins in v1 unless it falls out naturally after skill support.

Proposed implementation notes

1. Add a separate secretLeakScanJobs/result path rather than reusing securityScanJobs.
2. On skill publish, enqueue a secret scan for the new skillVersionId.
3. First investigate Truffle Security options:
   • hosted async scan API for arbitrary artifact files
   • signed URL/file upload scan flow
   • result webhook or polling model
4. If hosted API is not available, run TruffleHog in a minimal separate scanner path, not inside the ClawScan worker.
5. Persist sanitized findings on the skill version or in a small child table if findings can grow.
6. Render owner-only warnings on skill detail/dashboard surfaces.
7. Add email delivery for verified/live findings only, with dedupe so the same finding does not email repeatedly.

Acceptance criteria

• Publishing a skill with a test credential fixture produces an owner-visible warning.
• Publishing a skill with a verified/live test fixture sends an email notification.
• Publishing a clean skill produces no warning and no email.
• Unverified findings are visible owner-side but do not send email.
• Raw secret values are never stored in Convex, logs, diagnostics, emails, or UI.
• Duplicate scans do not repeatedly email the same finding.
• TruffleHog findings do not affect ClawScan, moderation status, search visibility, or installability.
• Re-publishing a fixed version clears the warning for the latest version.
• Tests cover parsing/sanitization, storage, email gating/dedupe, and owner-only UI visibility.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed May 28, 2026, 3:34 PM ET / 19:34 UTC.

Summary
This should remain open: the issue is protected by the security label, and current main has repository/ClawScan security scanning but not a TruffleHog-style uploaded-skill secret warning, verified-secret email path, or sanitized secret-finding storage for skill versions.

Reproducibility: not applicable. this is a security feature request, not a report of broken existing behavior. Source inspection shows current main lacks the requested uploaded-skill secret-leak warning and email behavior.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.
• Include redacted logs or terminal output.

Next step
The request is valid and aligned, but the protected security label plus integration, redaction, and notification-policy choices need maintainer/security review before implementation.

Review details

Best possible solution:

Keep this issue open as the canonical security work item, then implement a separate sanitized secret-leak scan pipeline for uploaded skill versions with owner-only warnings and verified-secret email dedupe.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is a security feature request, not a report of broken existing behavior. Source inspection shows current main lacks the requested uploaded-skill secret-leak warning and email behavior.

Is this the best way to solve the issue?

Unclear until maintainers choose the integration model. The requested separation from ClawScan is directionally right, but hosted Truffle Security versus a minimal separate worker is a product/security decision.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• This is security-sensitive and already has the protected security label, so it should not be sent to an autonomous repair lane before maintainer review.
• The implementation needs a maintainer/security decision on hosted Truffle Security API versus a separate worker, plus retention, redaction, email dedupe, and owner-only visibility rules.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 327231535f51.

Label changes

Label changes:

• add P2: The request is a bounded security improvement for uploaded skills, but it is not an active exploit, outage, or release-blocking regression.
• add impact:security: The issue concerns accidental credential exposure, secret handling, and owner notifications for uploaded skill artifacts.
• add issue-rating: 🌊 off-meta tidepool: Current issue advisory state selects this label.
• add clawsweeper:no-new-fix-pr: Current issue advisory state selects this label.
• add clawsweeper:needs-maintainer-review: Current issue advisory state selects this label.
• add clawsweeper:needs-product-decision: Current issue advisory state selects this label.
• add clawsweeper:needs-security-review: Current issue advisory state selects this label.

Label justifications:

• P2: The request is a bounded security improvement for uploaded skills, but it is not an active exploit, outage, or release-blocking regression.
• impact:security: The issue concerns accidental credential exposure, secret handling, and owner notifications for uploaded skill artifacts.

Evidence reviewed

Acceptance criteria:

• After maintainer design approval, add focused tests for parsing/sanitization, storage, email gating/dedupe, and owner-only UI visibility.
• Run bun run ci:static and bun run ci:unit; run Convex/type/build gates if schema, worker, or backend API code changes.

What I checked:

• Protected issue context: The provided GitHub context shows the issue is open, contributor-authored, and labeled security, which ClawSweeper policy treats as requiring explicit maintainer handling rather than auto-close or autofix routing.
• Repository policy applied: AGENTS.md was read fully; its durable-intent guidance for security-sensitive scanner outcomes and protected security flows applies to this review. (AGENTS.md:1, 327231535f51)
• Vision fit: VISION.md prioritizes security and safe defaults, so uploaded-skill credential exposure warnings fit the current project direction. (VISION.md:14, 327231535f51)
• Existing repo secret scan is not uploaded-skill scanning: Current main has a TruffleHog GitHub Actions secret gate for repository pushes/PRs, but that scans this repo checkout and does not scan user-uploaded skill versions or notify skill owners. (.github/workflows/secret-scan.yml:50, 327231535f51)
• Existing skill-version scan fields: skillVersions currently stores staticScan/apiKeyRequired and scanner analyses, but there is no field or child table for sanitized TruffleHog findings, verified status, fingerprint dedupe, email state, or owner-only leaked-secret warning metadata. (convex/schema.ts:706, 327231535f51)
• Existing scan job queue: The existing securityScanJobs queue targets skill versions and package releases for ClawScan-style security scanning; no separate secret-leak scan job/result path was found. (convex/schema.ts:1107, 327231535f51)

Likely related people:

• Patrick-Erichsen: CODEOWNERS names Patrick-Erichsen on Convex backend/publish/scan enforcement, and git history shows recent commits on securityScan, skills scan routing, scan specs, and the repo-level TruffleHog workflow. (role: CODEOWNERS-listed backend/security scan owner and recent area contributor; confidence: high; commits: 875f026a2300, cc16d7fbd924, 57bc9f2a461e; files: .github/CODEOWNERS, convex/schema.ts, convex/securityScan.ts)
• Vyctor H. Brzezowski: Recent commits touched skill publish ownership, moderated skill access, and package resource hiding, which are adjacent to uploaded artifact trust and owner visibility boundaries. (role: recent adjacent security/publish contributor; confidence: medium; commits: d854449610b1, 97023d3123f4, 6f893b54f431; files: convex/skills.ts, specs/security-moderation.md, src/components/SkillDetailPage.tsx)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.