dleecefft/p3pg

# p3pg **用于 LLM 支持的应用程序的确定性 pre-LLM prompt 注入传感器和 token 预算防护。** 它是一个绊线（tripwire）和遥测（telemetry）源——明确**不是**安全边界。 有关完整的详细说明，请参阅 [`p3pg/docs/README.md`](p3pg/docs/README.md)；有关其确切失效场景的指导实验， 请参阅 [`p3pg/docs/BYPASS_LAB.md`](p3pg/docs/BYPASS_LAB.md)；有关其构建原因， 请参阅 [ADR-001](docs/design/ADR-001-p3pg-sensor.md)。 ## 这是什么 每个由 LLM 支持的应用程序都面临两个风险：prompt 注入（OWASP LLM01）和 不受控的 token 开销（OWASP LLM10）。`p3pg` 通过**零成本的确定性检查**来解决这两个问题—— 对规范化文本进行 regex 匹配、滑动窗口重复命中传感器，以及 token 预算强制限制—— 而不是使用 LLM 裁决或 ML 分类器层级。 它无法阻止那些有决心的攻击者，他们会重新措辞、双重编码，或者将 payload 隐藏在您未筛查的文档中。 但它**确实**能以近乎零的成本阻止普通的复制粘贴攻击，并且其遥测数据 （尤其是重复命中升级）对于 SOC 来说是真正有用的早期预警信号。 构建它，*并且*对于任何重大操作，仍然要坚持最小权限原则、 做好输出处理，并保持人工干预（human-in-the-loop）。不要*用构建它来代替*这些措施。 ## 安装 ``` pip install -e . ``` （尚未发布到 PyPI —— `pyproject.toml` 已配置好，一旦发布，`pip install p3pg` 即可使用。 在此期间，可以从 git 检出中进行可编辑安装。） 该模块唯一的运行时依赖项是 `PyYAML`（用于规则文件）。没有其他依赖—— 没有 LLM SDK，运行时也没有网络 I/O。 ## 快速开始 ``` from p3pg import Guardrail, GuardrailMode guard = Guardrail( app_id="my_app", # required -- anonymous sensors help nobody principal="alice@example.com", # required -- attribution is the product mode=GuardrailMode.DEFAULT, max_call_tokens=4000, max_total_tokens=50_000, ) decision = guard.screen(user_text) if decision.proceed: reply = call_your_llm(user_text) # your own SDK call guard.record_usage(reply.usage) # token budgets + telemetry guard.check_model_refusal(reply) # provider-side refusals -> same event stream ``` `app_id` 和 `principal` 是必填项：该模块拒绝匿名运行，因为 无法归属的检测无法区分您的红队（red team）和被盗用的账户。 完整的 API、三种策略模式（`DEFAULT` / `PERMISSIVE` / `ANALYST`）、遥测 schema 和已知限制均记录在 [`p3pg/docs/README.md`](p3pg/docs/README.md) 中。 ## 仓库布局 ``` p3pg/ the module -- this is what you pip install __init__.py public API surface normalize.py deterministic text normalization for matching rules.py rule schema, loader, validator, integrity checking scanner.py matching engine policy.py GuardrailMode + screen_and_confirm decision flow telemetry.py structured JSONL event emission sensor.py repeat-hit / near-duplicate sliding-window detector tokens.py TokenTracker + preventive/detective budget controls model_refusal.py destination-model refusal detection guardrail.py Guardrail -- the single high-level entry point rules/core.yaml the shipped rule set (+ integrity manifest) docs/ README, BYPASS_LAB, SECURITY -- ships with the package examples/ toy demo app -- NOT part of the module, NOT production code lab2_math_tutor.py tiny math-tutor REPL showing p3pg wired into a real app conversation.py demo-only Anthropic SDK plumbing claude_client.py demo-only Anthropic client setup archives/ pre-p3pg iterations of the demo, kept for history tests/corpus/ regression corpus (attacks.txt / benign.txt) docs/ repo-level design docs: ADRs, build spec, public doc mirror logs/ telemetry output from example/local runs (gitignored) ``` 该模块（`p3pg/`）是使用者安装和导入的内容；此仓库中的其他所有内容 都是为了对其进行开发、演示和测试。如果您只需要该库，使用 `pip install p3pg`（一旦发布）或者直接引入（vendor）`p3pg/` 文件夹就足够了—— `examples/` 不是任何内容的依赖项。 ## 测试检测声明 ``` tests/corpus/attacks.txt -- strings that must be caught (+ documented known-gap misses) ``` 请参阅 [`p3pg/docs/BYPASS_LAB.md`](p3pg/docs/BYPASS_LAB.md)，在 demo 应用程序的 `analyst` 模式下运行这些测试， 并确切观察哪些会被捕获，哪些不会，以及原因。 ## 贡献 / 发现了绕过方法？ 发现了一个逃逸手段，能够绕过您认为本应捕获它的规则？这是预料之中的—— 针对 `tests/corpus/attacks.txt` 提交一个 PR，以便将这个遗漏变成一个有文档记录的、 受回归测试跟踪的已知缺陷。相反，如果发现了导致模块本身崩溃或挂起的方法？ 请参阅 [`p3pg/docs/SECURITY.md`](p3pg/docs/SECURITY.md)。 ## 许可证 MIT —— 请参阅 [`LICENSE`](LICENSE)。

标签：DLL 劫持, Python, TLS, 人工智能安全, 令牌限制, 合规性, 大语言模型, 恶意代码分类, 无后门, 逆向工具, 防御工具