ai-traceguard 0.1.0__tar.gz

ai_traceguard-0.1.0/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: ve-loma

ai_traceguard-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,21 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine upload dist/* --skip-existing
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}

ai_traceguard-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+.venv/
+venv/
+*.db
+traceguard-policy.yaml
+dev-keys/

ai_traceguard-0.1.0/AGENTS.md

@@ -0,0 +1,28 @@
+# TraceGuard — Agent Runtime Guard
+
+## Project Overview
+TraceGuard 是一个本地 Python 库，拦截 AI Agent 的危险工具调用，
+在执行前阻断或要求人工审批。零服务器依赖，数据不出用户本机。
+
+## Architecture
+- `src/traceguard/guard.py` — 拦截层核心
+- `src/traceguard/audit.py` — SHA-256 哈希链审计
+- `src/traceguard/cli.py` — CLI 入口
+- `policies/*.yaml` — 预置策略模板
+- `tests/` — 拦截层验证
+
+## Build Commands
+- 安装：`pip install -e ".[dev]"`
+- 测试：`pytest tests/ -v`
+- 构建：`python -m build`
+
+## Coding Conventions
+- Python 3.11+，使用 type hints
+- 拦截层逻辑必须是确定性的，不依赖模型推理
+- 策略文件使用 YAML，字段名小写加下划线
+
+## Guardrails
+- 绝不添加任何网络请求代码到拦截层
+- 绝不收集或上传用户数据
+- 绝不提供模型 API 接口
+- 审计数据仅存储在本地 SQLite 文件

ai_traceguard-0.1.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## [0.1.0] - 2026-10-16
+
+### Added
+- 核心拦截层 `TraceGuard` 类
+- SHA-256 哈希链审计
+- CLI：init / test / verify
+- 策略模板：base / anti-delete / anti-token-runaway / anti-data-leak
+- 完整测试覆盖
+- GitHub Actions 自动发布

ai_traceguard-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,22 @@
+# Contributing to TraceGuard
+
+## Development Setup
+
+```bash
+git clone https://github.com/ve-loma/traceguard
+cd traceguard
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+## Adding a Guard Pack
+
+1. Create `policies/pack-<name>.yaml`
+2. Add test in `tests/test_intercept.py`
+3. Update README with the new pack
+
+## Code Style
+
+- Python 3.11+, type hints required
+- Deterministic logic only, no model calls in the intercept path
+- No network requests in the guard layer

ai_traceguard-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TraceGuard Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ai_traceguard-0.1.0/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.5
+Name: ai-traceguard
+Version: 0.1.0
+Summary: Runtime guardrail for AI agents — intercept dangerous tool calls before execution
+Project-URL: Homepage, https://github.com/ve-loma/traceguard
+Project-URL: Repository, https://github.com/ve-loma/traceguard
+Project-URL: Issues, https://github.com/ve-loma/traceguard/issues
+Author: TraceGuard Contributors
+License: MIT
+License-File: LICENSE
+Keywords: agent,ai,guardrails,mcp,policy,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# TraceGuard
+
+**AI Agent 的工具调用前置拦截器。在执行之前，把危险动作拦下来。**
+
+[![PyPI](https://img.shields.io/pypi/v/ai-traceguard?color=FF5C36&label=pypi&logo=pypi&logoColor=white)](https://pypi.org/project/ai-traceguard/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-39FF88.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](pyproject.toml)
+
+---
+
+## 它解决什么问题
+
+AI Agent 会**删掉生产库、把 API Key 发到外部、在死循环里把 Token 烧光**。
+市面上的可观测 / 追踪工具只能**事后记录**——等你看到日志，数据已经没了。
+
+TraceGuard 不同：它站在**工具调用的执行路径上**，在动作发生**之前**做出确定性的允许 / 阻断判断。
+
+> 追踪工具告诉你「凌晨 3 点删了什么」；
+> TraceGuard 让它在「凌晨 3 点删不掉」。
+
+---
+
+## 安装
+
+```bash
+pip install ai-traceguard
+```
+
+零依赖服务、零配置文件、零网络请求。装完即用。
+
+---
+
+## 快速开始
+
+```python
+from traceguard import TraceGuard
+
+guard = TraceGuard(policy="policies/base.yaml", mode="strict")
+
+decision = guard.check("delete_file", {"path": "/data/users.csv"})
+if not decision.allowed:
+    print(f"已阻断：{decision.reason}")
+else:
+    # 执行真正的工具逻辑
+    pass
+```
+
+CLI 自检：
+
+```bash
+traceguard test
+# delete_file: BLOCKED
+# read_file: ALLOWED
+```
+
+---
+
+## 策略包（Guard Packs）
+
+开箱即用的策略模板，覆盖最常见的翻车场景：
+
+| 策略包 | 作用 |
+|---|---|
+| `pack-anti-delete` | 拦截文件 / 数据库删除 |
+| `pack-anti-token-runaway` | 拦截 Token 预算超支 |
+| `pack-anti-data-leak` | 拦截敏感数据外发 |
+
+```bash
+traceguard init --pack anti-delete
+# 生成 traceguard-policy.yaml
+```
+
+---
+
+## 审计链（Audit Chain）
+
+每一次裁决都会写入本地的 **SHA-256 哈希链**。任何后续篡改都会破坏链条，可被检出。
+
+```bash
+traceguard verify
+# 审计链有效
+```
+
+导出给审计 / 合规团队（Pro 能力）：
+
+```python
+from traceguard_pro import export_audit_jsonl, verify_exported_jsonl
+
+export_audit_jsonl("traceguard-audit.db", "audit-export.jsonl")
+assert verify_exported_jsonl("audit-export.jsonl")   # 第三方可独立复核
+```
+
+---
+
+## 三种模式
+
+| 模式 | 行为 |
+|---|---|
+| `strict` | HIGH 风险阻断，MEDIUM 需要审批 |
+| `balanced` | HIGH 需要审批，MEDIUM 放行 |
+| `observe` | 全部放行，全部记录（灰度 / 观测用） |
+
+---
+
+## 合规与安全
+
+TraceGuard 的设计目标是**架构上零风险**：
+
+- **无网络请求。** 拦截层永不联系外部服务器，因此没有可被拦截、泄露或审查的东西。
+- **无模型 API。** 不代理、不转售、不路由任何模型调用。
+- **只存本地 SQLite。** 审计数据属于你，永远不出本机。
+- **离线授权。** 授权码本地 HMAC 验签，可在气隙环境中运行。
+
+因此：**无需 ICP 备案、无需生成式 AI 备案、无数据出境评估**。详见 [`docs/compliance.md`](docs/compliance.md)。
+
+---
+
+## 商业版（TraceGuard Pro）
+
+开源核心（MIT）足够个人使用；**生产与合规场景**需要的确定性能力放在 Pro：
+
+| 能力 | 说明 | 版本 |
+|---|---|---|
+| 参数级敏感信息扫描 | 拦截参数里的 `api_key` / `password` / `private_key` / PII | Pro |
+| Token 预算 + 死循环拦截 | 会话超预算、同调用反复重试时阻断 | Pro |
+| 可校验审计导出 | JSONL 导出，第三方可独立重算哈希链 | Pro |
+| 行业策略包 | 金融 / 医疗 / DevOps 预设 | Pro |
+| 人工审批流 | MEDIUM 风险改为人工审批而非静默放行 | Team |
+| 席位报表 / 自定义包 / SLA | — | Enterprise |
+
+> 未持有效授权时，`ProGuard` 会**优雅降级为开源核心行为**，方便先试后买。
+
+---
+
+## 文档
+
+- [快速开始](docs/quickstart.md)（[中文版](docs/quickstart.zh.md)）
+- [合规说明](docs/compliance.md)
+- [安全策略](SECURITY.md)
+- [贡献指南](CONTRIBUTING.md)
+- [变更日志](CHANGELOG.md)
+
+---
+
+## 许可证
+
+核心：**MIT**。商业增值包 `traceguard-pro` 采用商业许可，详见其 README。
+
+---
+
+## English (short)
+
+TraceGuard is a **local runtime guardrail for AI agents**. It intercepts dangerous
+tool calls *before* execution — no network, no server, deterministic decisions, and a
+tamper-evident local SHA-256 audit chain. Install with `pip install ai-traceguard`.
+Full English docs: [`README.en.md`](README.en.md).

ai_traceguard-0.1.0/README.en.md

@@ -0,0 +1,69 @@
+# TraceGuard
+
+Runtime guardrail for AI agents. Intercepts dangerous tool calls before execution.
+
+[中文文档](README.md) · [PyPI](https://pypi.org/project/ai-traceguard/)
+
+## The Problem
+
+AI agents delete production data, leak API keys, and burn through token budgets. Existing observability tools only record what happened — after the damage is done. TraceGuard blocks the action before it executes.
+
+## Install
+
+```bash
+pip install ai-traceguard
+```
+
+## Quick Start
+
+```python
+from traceguard import TraceGuard
+
+guard = TraceGuard(policy="policies/base.yaml", mode="strict")
+
+decision = guard.check("delete_file", {"path": "/data/users.csv"})
+if not decision.allowed:
+    print(f"Blocked: {decision.reason}")
+else:
+    # execute the tool
+    pass
+```
+
+## Guard Packs
+
+Pre-built policy templates for common scenarios:
+
+- `pack-anti-delete` — blocks file/database deletion
+- `pack-anti-token-runaway` — blocks token budget overrun
+- `pack-anti-data-leak` — blocks sensitive data exfiltration
+
+```bash
+traceguard init --pack anti-delete
+```
+
+## Audit Chain
+
+Every decision is written to a local SHA-256 hash chain. Any tampering breaks the chain and is detectable.
+
+```bash
+traceguard verify
+# CHAIN VALID
+```
+
+## Modes
+
+| Mode | Behavior |
+|---|---|
+| `strict` | HIGH risk blocked, MEDIUM requires approval |
+| `balanced` | HIGH requires approval, MEDIUM allowed |
+| `observe` | Everything allowed, everything logged |
+
+## Compliance
+
+- No network requests. Data never leaves your machine.
+- No server dependency. Runs entirely in-process.
+- Local SQLite storage. You own your data.
+
+## License
+
+MIT

ai_traceguard-0.1.0/README.md

@@ -0,0 +1,156 @@
+# TraceGuard
+
+**AI Agent 的工具调用前置拦截器。在执行之前，把危险动作拦下来。**
+
+[![PyPI](https://img.shields.io/pypi/v/ai-traceguard?color=FF5C36&label=pypi&logo=pypi&logoColor=white)](https://pypi.org/project/ai-traceguard/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-39FF88.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](pyproject.toml)
+
+---
+
+## 它解决什么问题
+
+AI Agent 会**删掉生产库、把 API Key 发到外部、在死循环里把 Token 烧光**。
+市面上的可观测 / 追踪工具只能**事后记录**——等你看到日志，数据已经没了。
+
+TraceGuard 不同：它站在**工具调用的执行路径上**，在动作发生**之前**做出确定性的允许 / 阻断判断。
+
+> 追踪工具告诉你「凌晨 3 点删了什么」；
+> TraceGuard 让它在「凌晨 3 点删不掉」。
+
+---
+
+## 安装
+
+```bash
+pip install ai-traceguard
+```
+
+零依赖服务、零配置文件、零网络请求。装完即用。
+
+---
+
+## 快速开始
+
+```python
+from traceguard import TraceGuard
+
+guard = TraceGuard(policy="policies/base.yaml", mode="strict")
+
+decision = guard.check("delete_file", {"path": "/data/users.csv"})
+if not decision.allowed:
+    print(f"已阻断：{decision.reason}")
+else:
+    # 执行真正的工具逻辑
+    pass
+```
+
+CLI 自检：
+
+```bash
+traceguard test
+# delete_file: BLOCKED
+# read_file: ALLOWED
+```
+
+---
+
+## 策略包（Guard Packs）
+
+开箱即用的策略模板，覆盖最常见的翻车场景：
+
+| 策略包 | 作用 |
+|---|---|
+| `pack-anti-delete` | 拦截文件 / 数据库删除 |
+| `pack-anti-token-runaway` | 拦截 Token 预算超支 |
+| `pack-anti-data-leak` | 拦截敏感数据外发 |
+
+```bash
+traceguard init --pack anti-delete
+# 生成 traceguard-policy.yaml
+```
+
+---
+
+## 审计链（Audit Chain）
+
+每一次裁决都会写入本地的 **SHA-256 哈希链**。任何后续篡改都会破坏链条，可被检出。
+
+```bash
+traceguard verify
+# 审计链有效
+```
+
+导出给审计 / 合规团队（Pro 能力）：
+
+```python
+from traceguard_pro import export_audit_jsonl, verify_exported_jsonl
+
+export_audit_jsonl("traceguard-audit.db", "audit-export.jsonl")
+assert verify_exported_jsonl("audit-export.jsonl")   # 第三方可独立复核
+```
+
+---
+
+## 三种模式
+
+| 模式 | 行为 |
+|---|---|
+| `strict` | HIGH 风险阻断，MEDIUM 需要审批 |
+| `balanced` | HIGH 需要审批，MEDIUM 放行 |
+| `observe` | 全部放行，全部记录（灰度 / 观测用） |
+
+---
+
+## 合规与安全
+
+TraceGuard 的设计目标是**架构上零风险**：
+
+- **无网络请求。** 拦截层永不联系外部服务器，因此没有可被拦截、泄露或审查的东西。
+- **无模型 API。** 不代理、不转售、不路由任何模型调用。
+- **只存本地 SQLite。** 审计数据属于你，永远不出本机。
+- **离线授权。** 授权码本地 HMAC 验签，可在气隙环境中运行。
+
+因此：**无需 ICP 备案、无需生成式 AI 备案、无数据出境评估**。详见 [`docs/compliance.md`](docs/compliance.md)。
+
+---
+
+## 商业版（TraceGuard Pro）
+
+开源核心（MIT）足够个人使用；**生产与合规场景**需要的确定性能力放在 Pro：
+
+| 能力 | 说明 | 版本 |
+|---|---|---|
+| 参数级敏感信息扫描 | 拦截参数里的 `api_key` / `password` / `private_key` / PII | Pro |
+| Token 预算 + 死循环拦截 | 会话超预算、同调用反复重试时阻断 | Pro |
+| 可校验审计导出 | JSONL 导出，第三方可独立重算哈希链 | Pro |
+| 行业策略包 | 金融 / 医疗 / DevOps 预设 | Pro |
+| 人工审批流 | MEDIUM 风险改为人工审批而非静默放行 | Team |
+| 席位报表 / 自定义包 / SLA | — | Enterprise |
+
+> 未持有效授权时，`ProGuard` 会**优雅降级为开源核心行为**，方便先试后买。
+
+---
+
+## 文档
+
+- [快速开始](docs/quickstart.md)（[中文版](docs/quickstart.zh.md)）
+- [合规说明](docs/compliance.md)
+- [安全策略](SECURITY.md)
+- [贡献指南](CONTRIBUTING.md)
+- [变更日志](CHANGELOG.md)
+
+---
+
+## 许可证
+
+核心：**MIT**。商业增值包 `traceguard-pro` 采用商业许可，详见其 README。
+
+---
+
+## English (short)
+
+TraceGuard is a **local runtime guardrail for AI agents**. It intercepts dangerous
+tool calls *before* execution — no network, no server, deterministic decisions, and a
+tamper-evident local SHA-256 audit chain. Install with `pip install ai-traceguard`.
+Full English docs: [`README.en.md`](README.en.md).

ai_traceguard-0.1.0/SECURITY.md

@@ -0,0 +1,14 @@
+# Security Policy
+
+## Design Principles
+
+TraceGuard is designed to be zero-risk by architecture:
+
+- **No network requests.** The guard layer never contacts external servers.
+- **No data collection.** All audit data stays in local SQLite.
+- **No model API.** TraceGuard does not proxy, resell, or route model calls.
+- **No server dependency.** Runs entirely in the user's process.
+
+## Reporting a Vulnerability
+
+Open an issue at https://github.com/ve-loma/traceguard/issues

ai_traceguard-0.1.0/VERIFY.md

@@ -0,0 +1,12 @@
+# Verification steps
+# After building, run from the project root:
+
+#   pip install -e ".[dev]"
+#   pytest tests/ -v
+#   expected: 5 passed
+#
+# then:
+#   traceguard test
+#   expected:
+#     delete_file: BLOCKED
+#     read_file: ALLOWED

ai_traceguard-0.1.0/docs/assets/README.md

@@ -0,0 +1,30 @@
+# 收款码放这里
+
+把这两张图放进本文件夹，官网会自动显示（不用改任何代码）：
+
+| 文件名 | 内容 |
+|---|---|
+| `wechat-pay.png` | 你的**微信**收款码 |
+| `alipay-pay.png` | 你的**支付宝**收款码 |
+
+## 怎么拿到自己的收款码
+
+- **微信**：打开微信 → 我 → 服务 → 收付款 → 二维码收款 → 保存收款码
+- **支付宝**：打开支付宝 → 我的 → 收钱 → 保存图片
+
+## 注意
+
+- 文件名必须**完全一致**（区分大小写）：
+  `wechat-pay.png`、`alipay-pay.png`
+- 建议用**正方形**图片，导出为 PNG。
+- 没放图时，官网会显示一个虚线占位框，不影响其它功能。
+
+## 还要改一处：邮箱
+
+打开上一层的 `index.html`，在最底部 `<script>` 开头的 `CONFIG` 里，把
+
+```js
+email: "your-email@example.com",
+```
+
+改成你自己能收信的邮箱。改完保存即可——官网上的邮箱、下单按钮会自动更新。

ai_traceguard-0.1.0/docs/compliance.md

@@ -0,0 +1,23 @@
+# Compliance
+
+TraceGuard is a local developer tool, not a network service.
+
+## What TraceGuard Does Not Do
+
+- No model API proxying or resale
+- No user data collection or upload
+- No account pools or reverse proxies
+- No public-facing service
+
+## Regulatory Position
+
+- **ICP filing**: Not applicable (no server in mainland China)
+- **Generative AI filing**: Not applicable (no public AI service)
+- **Data export assessment**: Not applicable (data never leaves local machine)
+- **Public security filing**: Not applicable (no public-facing service)
+
+## Audit Chain for Compliance
+
+EU AI Act Article 12 requires automatic event logging for high-risk AI systems.
+TraceGuard's SHA-256 hash chain provides tamper-evident local audit records
+that can be independently verified.