convez.ai
Agente
SuperMarioYL

promptshield

SuperMarioYL/promptshield

Ver no GitHub
InicialPluginScore · de 0 a 100

Scan the code your AI coding agent reads, before it obeys hidden prompt-injection instructions.

Instalação

$npx convez-ai SuperMarioYL/promptshield

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 1 mês
Versão
v0.16.0
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

English | 简体中文


目录


为什么需要它

Claude Code、Cursor 这类 coding agent 会把第三方仓库、PR、代码注释、commit message 直接读进上下文,然后照着读到的内容去执行——但在仓库和 agent 之间,没有任何一层把这些代码当作提示词来扫描。

这正是 r/LocalLLaMA 那条 "dev sneaks data-nuking prompt injection into their code" 帖子揭露的攻击面:有人把一句 rm -rf / 的销毁指令藏进注释里,等着别人的 agent 读到并执行。人工 review 的眼睛追不上 agent 的阅读吞吐——这是一种结构性的吞吐量不对称,不是"再仔细一点"能解决的。

Why now: agentic coding 的普及,把"agent 读到的代码"变成了"agent 会照做的代码"。Cursor 已有上百万开发者,affaan-m/everything-claude-code 这类 Claude Code 实战仓库让 agent 例行拉取外部 PR 与 vendored OSS。两年前主流还是人把片段复制进聊天框,agent 没有对外部仓库自主读取并执行的回路;MCP 与工具调用的扩张才让注入有了通往"动作"的路径。PromptShield 就是在 agent 读取之前,把这条注入面卡在 CI 里——离线、零 API key、几秒出结果。

PromptShield 引入的新原语是 Finding over a code-as-prompt surface:把 agent 将要读取的源文本视为攻击向量,而不是当作可执行代码或要做 CVE 扫描的依赖包。这与聊天越狱扫描(Garak)和依赖漏洞扫描(Socket / Snyk)是不同的威胁类别。


60 秒上手

pip install promptshield           # 或: uvx promptshield
promptshield scan .                # 扫描当前仓库,打印发现表
echo "退出码: $?"                  # 出现任何 HIGH 即为 1,可直接接入 CI
$ promptshield scan ./tests/fixtures/malicious_pr

                          PromptShield findings
┏━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━┓
┃ Sev  ┃ Rule                          ┃ Category        ┃ Location    ┃ Surf ┃
┡━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━┩
│ HIGH │ PS001-instruction-override-d… │ instruction_ov… │ utils.py:11 │ com… │
│ HIGH │ PS010-destructive-shell       │ data_destructi… │ utils.py:12 │ com… │
│ HIGH │ PS011-destructive-instruction │ data_destructi… │ utils.py:17 │ doc… │
│ HIGH │ PS020-exfil-secrets           │ exfiltration    │ utils.py:17 │ doc… │
└──────┴───────────────────────────────┴─────────────────┴─────────────┴──────┘

Scanned 31 surfaces · 8 HIGH · 0 MED · 0 LOW
✗ HIGH findings present — exit 1 (CI gate failed).

每一条 HIGH 都会附带一句 why,说明它为什么是注入——精度优先于召回,让你信得过每一个告警。

promptshield scan . 不需要 git 或 gh,也不发任何网络请求。只有用 --diff / --pr 时才会把它们当子进程调用。


演示

脚本:扫描 malicious_pr → 发现表 → --pr 退出码 1 让 CI 变红 → 现场命中真实的 Reddit 数据销毁注入。

asciicast

📼 上面是占位图。录制脚本见 assets/demo.tape,静态预览见 assets/demo.svg。在 assets/demo.tape 的命令下跑一次 asciinema rec 即可生成 README 嵌入的真实 cast。

demo


它扫描什么

PromptShield 把仓库或 diff 拆解成 Surface 记录(agent 会读到的每一段文本),再用 YAML 规则引擎把每段映射成零或多个 Finding。

扫描的 Surface(代码即提示词的面): 代码注释 · docstring · commit message · markdown / README · 配置文件 · 字符串字面量。

五类威胁(seed 规则集,v0.1):

类别含义代表规则
instruction_override直接对 agent 喊话、让它忽略此前指令PS001 PS002 PS003
data_destructive删库 / 销毁数据(Reddit 那类攻击)PS010 PS011 PS012
exfiltration读取密钥并外发PS020 PS021 PS022
tool_abuse诱导 agent 跳过确认、滥用工具自主权PS030 PS031
obfuscation零宽 / 双向 Unicode、编码载荷等规避人工 review 的手法PS040 PS041

严重度分三档:HIGH(令 CI 失败)· MED · LOW。为压低误报,部分高噪声动词规则用 requires 二次门控——只有同时出现 agent 喊话或"全部 / 递归 / 生产库"这类措辞时才会触发,避免一句"删掉临时缓存"的普通注释就被误报。


集成到 CI

把仓库自带的 .github/workflows/promptshield.yml 复制进任意仓库的 .github/workflows/,每个 PR 就会被自动门控:

  • PR 上:promptshield scan --diff origin/<base> 只扫改动过的 Surface(新增行 + 新 commit message)。
  • push 到 main:promptshield scan . 扫整棵树。
  • 出现任何 HIGH 即退出 1,让 check 变红。

也可以手动接入:

# 只扫本次相对 main 的改动
promptshield scan --diff origin/main

# 扫一份 gh api PR-files JSON(CI 里无需 checkout 全量历史)
gh api repos/OWNER/REPO/pulls/123/files > pr.json
promptshield scan --pr pr.json        # 有 HIGH 即 exit 1

基线工作流

在有历史包袱的老仓库上,先把当前所有 Finding 记成"已接受",之后只对新增注入告警:

promptshield scan . --update-baseline        # 写入 .promptshield-baseline.yaml,并 exit 0
git add .promptshield-baseline.yaml
promptshield scan .                          # 旧 Finding 被抑制,只报新出现的

基线按指纹(rule_id + 文件 + excerpt 哈希)抑制,所以一旦真有新注入潜入,它仍会浮出水面。


对比同类方案

定位,不是吹嘘——在该认输的地方如实认输。

vs affaan-m/ECC(Claude Code / Cursor 实战配置仓库,代表"agent 例行吞入外部代码"的工作流):

能力轴PromptShieldGarak / PromptBenchSocket / Snyk
扫描源码注释 / commit / markdown 中的注入✓✗✗
离线、零 API key、几秒出结果✓partial✓
依赖包 CVE / 供应链漏洞✗✗✓
聊天越狱 / 红队语料成熟度partial✓✗
一行接入 PR 门控(GitHub Action)✓partial✓

Garak 在聊天提示词红队上更成熟,Socket / Snyk 在依赖供应链上无可替代——它们和 PromptShield 是互补关系。PromptShield 只专注一件它们都没碰的事:把你的 coding agent 会读进上下文并照做的源文本,当作提示词来扫描。


配置项

scan 命令的主要选项:

选项类型默认值含义
PATH路径.要扫描的目录或文件
--diff REF字符串无只扫 git diff REF 的新增行 + 新 commit message
--pr FILE.json路径无扫一份 gh api .../files 的 PR-files JSON
--baseline FILE路径.promptshield-baseline.yaml用于抑制已接受 Finding 的基线文件
--update-baseline开关false把当前所有 Finding 写入基线并 exit 0
--rules FILE路径内置规则集使用自定义 rules.yaml
--json开关false输出机器可读 JSON 而非 Rich 表格
--no-color开关false关闭彩色输出
--repo DIR路径.--diff 使用的仓库目录

--diff 与 --pr 互斥。


付费 · PromptShield Cloud

CLI 与 GitHub Action 永久开源免费,它们是漏斗的入口;营收来自托管的 PromptShield Cloud 团队版——把 CLI 之上的团队协作能力变成订阅。

开源 CLI / ActionPromptShield Cloud(团队版)
本地 / CI 扫描✓✓
五类 seed 规则集✓✓
单仓库基线✓✓
组织级 PR 门控(多仓库统一策略)✗✓
共享 / 中心化基线(跨仓库)✗✓
统一 Finding 看板✗✓
Slack / 飞书 告警(命中 HIGH 即推送)✗✓
托管的攻击签名 / 规则订阅源✗✓

定价: $8 / 席位 / 月(年付),或 $99 / 月封顶团队版(含 15 席)——比一个 Snyk 席位更省,同时是免费 CLI 之上清晰的"团队协作"升级。

最短付费路径: Cloud 看板用一个 token 接入团队现有的 Action 输出 → 展示全组织 Finding + 跨仓库共享基线 → 14 天试用 → Stripe Checkout 自助下单。最有说服力的演示:你的 6 个仓库,一块看板,一份基线,HIGH 命中即 Slack 告警。

目标客户:已经在 vendored OSS / 外部 PR 上跑 Claude Code / Cursor 的 5–30 人 AI 工具与安全团队。想成为设计合作伙伴?欢迎在 Issues 留言。


路线图

  • m1 — scan <path>:遍历仓库,抽取注释 / docstring / markdown / 字符串字面量为 Surface,跑 YAML 规则引擎,打印 Rich 发现表 + 严重度计数。
  • m2 — diff 与 CI:scan --diff <ref>(git diff 新增行)+ scan --pr <file.json>(gh PR-files JSON),HIGH → exit 1,附带 promptshield.yml Action。
  • m3 — 基线与演示:.promptshield-baseline.yaml 抑制;复现真实 Reddit 数据销毁注入的 tests/fixtures/malicious_pr/;asciinema 演示;双语 README。
  • 语义检测(可选、需开关)——在 regex / 启发式之上叠加,提升对绕过手法的召回。
  • 托管攻击签名 / 规则订阅源(PromptShield Cloud)。
  • 上架 GitHub Marketplace,进入 awesome-claude-code / awesome-ai-coding 等清单。

明确不在 v0.1 范围:Web UI / 看板、LLM 语义检测、逐语言 AST 解析、自动修复、IDE / 编辑器插件、SARIF / SBOM 输出、自训练分类器。


许可证与贡献

MIT。欢迎 PR 与 Issue——发现误报或漏报?带上能复现的最小样本,到 Issues 开一条,我们会据此收紧规则。

变更记录见 CHANGELOG.md。


Share this

PromptShield — 在你的 Claude Code / Cursor agent 读取代码之前,扫描其中隐藏的提示词注入。
离线、零 API key、一行接入 CI。现场拦下 Reddit 那条 rm -rf 数据销毁注入。
https://github.com/SuperMarioYL/promptshield
Ver o original no GitHub

Bom para

Relacionados