JACK-Chen415/Cyberspace_Security

# GuardFlow 《GuardFlow-TCRG：可信边界感知的上下文风险图谱运行时防护系统》 GuardFlow-TCRG 是一个专为 RAG 和基于 Agent 的 LLM 应用设计的防御性运行时安全网关。它会在数据跨越信任边界之前，对用户输入、上传的文档、RAG 文本块、模型输出以及模拟的 Agent 工具参数进行拦截检查。 ## 它所展示的功能 - 模拟隐私数据、凭证、token、cookies、数据库 URL、类 SSH 密钥内容以及 `.env` 泄露的敏感信息检测。 - Prompt Injection 和 RAG 污染检测，包括隐藏的 HTML 注释、Base64 payload、零宽字符、指令覆盖、系统 prompt 窃取以及数据外发意图。 - 用于模拟 `send_email`、`http_request`、`file_write` 和 `shell_command` 调用的 Agent 工具防火墙。 - 基于指纹的敏感数据流追踪与审计可视化。 - 信任边界感知的 `DataObject` 建模、置信度门控两阶段检测、上下文 `RiskGraph` 聚合、精确/模糊敏感指纹传播，以及 Agent 工具策略防火墙证据。 - 用于健康状态、策略配置文件、审计统计、dry-run 检查和留存清理的管理控制平面。 - 通过 `X-GuardFlow-Workspace` / `VITE_GUARDFLOW_WORKSPACE_ID` 实现的工作区隔离审计与策略上下文。 - 由数据库管理、用于运行时操作的 API key 和访问事件审计。 - 默认由本地模拟 LLM 支持的兼容 OpenAI 的 `/v1/chat/completions` 门面。 ## 安全边界 本项目是一个本地防御性演示。它不使用真实的隐私数据、真实的机密信息、真实的数据外发服务，也不执行真正危险的 shell 命令。仓库中的所有电话号码、身份号码、密钥、token、URL 和工具调用均为合成数据。 对于生产级部署，请设置 `GUARDFLOW_API_TOKEN` 作为管理员模式的 token，或设置 `GUARDFLOW_API_KEYS` 用于限定范围的密钥，例如 `viewer-token|demo|audit:read,policy:read|viewer`。管理页面还可以在 SQLite 中创建哈希加密的 API key，并将返回的 token 加载到浏览器会话中。将 token 留空可在本地演示和竞赛评审时禁用身份验证。请将审计数据存储在加密或受其他方式保护的存储上，轮转日志，并确保上游的 LLM 密钥不被包含在前端构建产物中。 ## 快速开始 后端： ``` cd backend python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt uvicorn app.main:app --host 127.0.0.1 --port 8000 ``` 前端： ``` cd frontend npm install npm run dev -- --host 127.0.0.1 --port 5173 ``` 然后打开 `http://127.0.0.1:5173`。 就绪检查： ``` curl http://127.0.0.1:8000/ready ``` 当设置了 `GUARDFLOW_API_TOKEN` 时，受保护的 endpoint 需要 bearer token；`/health` 和 `/ready` 保持公开： ``` curl http://127.0.0.1:8000/ready -H "Authorization: Bearer $GUARDFLOW_API_TOKEN" ``` Docker： ``` docker compose up --build ``` 如果端口 `8000` 或 `5173` 被占用，请在命令或 compose 文件中更改端口。前端 API 基础地址会在 Docker 构建时通过 `VITE_API_BASE_URL` 注入，或在您本地的 `.env` 中配置。 ## 演示场景 1. 检测并拦截 RAG 文档中隐藏的 Prompt Injection。 2. 检测并掩码处理 `.env`/代码配置中的机密信息。 3. 将诱导泄露电话号码/token 的 RAG 文本块标记为已被污染。 4. 模拟的 Agent `http_request`/`send_email` 数据外发行为被工具防火墙拦截。 5. 通过 RiskGraph 和指纹传播路径识别多轮上下文攻击。 ## 主要 API - `GET /health` - `GET /ready` - `POST /api/analyze` - `POST /api/analyze/session` - `POST /api/detect` - `POST /api/upload` - `POST /api/tool/firewall` - `GET /api/audits?source=user_input&action=block&scenario=demo&min_risk=50` - `GET /api/audits/search?limit=50&finding_type=api_key&min_risk=50` - `GET /api/audits/{session_id}` - `GET /api/audits/{session_id}/graph` - `GET /api/audits/stats` - `GET /api/audits/export` - `GET /api/audits/{session_id}/export` - `DELETE /api/audits/{session_id}` - `POST /api/audits/retention/run?days=30&dry_run=true` - `GET /api/tokens` - `POST /api/tokens` - `DELETE /api/tokens/{token_id}` - `GET /api/access-events` - `GET /api/system/status` - `GET /api/policies` - `GET /api/policies/active` - `PUT /api/policies/active` - `GET /api/policies/profiles` - `POST /api/policies/dry-run` - `GET /api/workspaces` - `GET /api/demo-scenarios` - `POST /api/demo-scenarios/{scenario_id}/run` - `GET /api/demo/scenarios` - `POST /api/demo/run/{scenario_id}` - `GET /api/evaluation/results` - `GET /api/evaluation/metrics` - `GET /api/evaluation/summary` - `POST /v1/chat/completions` 审计存储默认是保护隐私的：高风险的原始输入在持久化到审计会话字段和导出 payload 中之前，会被掩码处理、生成指纹、进行摘要或进行其他最小化处理。仅在隔离的调试环境中设置 `GUARDFLOW_AUDIT_PERSIST_RAW=true`。可通过管理页面和 `/api/audits/retention/run` 进行留存清理。工作区隔离依赖于 `X-GuardFlow-Workspace`；前端会在本地存储当前值并自动发送。 ## 评估 运行： ``` python3 scripts/run_evaluation.py python3 scripts/evaluate_tcrg.py ``` 该脚本会读取 `data/samples/eval_dataset.jsonl` 并写入 `reports/evaluation_report.md`、`reports/evaluation_summary.json`、`reports/error_analysis.md`、`reports/robustness_report.md` 和 `reports/per_category_metrics.csv`。它优先使用正在运行的后端，其次是进程内的 GuardFlow 分析器，只有在依赖项不可用时才会回退到离线启发式算法。 当前的评估文件包含 350 个合成样本，附带类别、攻击面、混淆、语言、难度、预期动作、攻击目标和基本原理等元数据。这些样本仅用于可重复的原型验证；它们不是生产基准，也不使用真实的个人数据、真实的凭证、真实的数据外发 endpoint 或真实的工具执行。独立的玩具级 RAG/Agent 测试工具可以通过 `python3 scripts/run_toy_rag_agent_eval.py` 重新生成。还可以通过 `python3 scripts/run_semirealistic_eval_scaffold.py` 获得半真实的脚手架，但它仅用于 dry-run/规划，不计作经验基准证据。 TCRG 评估器会读取 `data/samples/tcrg_eval_dataset.jsonl` 并写入 `reports/tcrg_evaluation_report.md` 以及 `reports/tcrg_evaluation_summary.json`。它会针对 `baseline_rule`、`rule_entropy`、`two_stage_gate`、`two_stage_graph` 和 `guardflow_tcrg_full` 报告 Precision、Recall、F1、Attack Success Rate、Leakage Blocking Rate、Tool Misallow Rate、Avg Latency、P95 Latency 和 LLM Review Ratio。 ## 测试命令 ``` cd backend PYTHONPATH=. python3 -m pytest -q tests cd ../frontend npm run build ``` 后端测试包括对可选/限定范围 token 身份验证、`/ready`、审计过滤器/搜索分页、审计统计/导出、活动策略/系统状态、工作区隔离、限定范围策略更新、留存/删除行为、数据库管理的 API key、访问事件日志记录、不支持的 OpenAI 流式传输/工具调用以及保护隐私的审计存储的操作契约覆盖。 ## 竞赛材料 面向竞赛的文档位于 `docs/` 下： - `DESIGN_REPORT.md` - `METHOD_INNOVATION.md` - `METHOD_INNOVATION_PLAN.md` - `TCRG_IMPLEMENTATION_PLAN.md` - `PAPER_METHOD_SECTION.md` - `PRESENTATION_METHOD_SLIDES.md` - `TEST_REPORT.md` - `PAPER_OUTLINE.md` - `PRESENTATION_OUTLINE.md` - `POSTER_COPY.md` - `DEFENSE_QA.md` - `DEMO_GUIDE.md` - `ACCEPTANCE_CHECKLIST.md` - `GUARDFLOW_FULL_PLAN.md` - `TASK_BREAKDOWN.md` - `PROGRESS.md` - `DECISIONS.md` 生成的最终二进制文件位于 `deliverables/artifacts/` 下： - `deliverables/artifacts/GuardFlow_Competition_Deck.pptx` - `deliverables/artifacts/GuardFlow_Course_Report.pdf` - `deliverables/artifacts/GuardFlow_Course_Report.docx` - `deliverables/artifacts/GuardFlow_Poster.pdf` 源代码生成器、HTML 源文件、视觉素材、图形导出和 QA 证据仍保留在各自现有的 `deliverables/` 子目录中。 使用以下命令打包它们： ``` bash scripts/package_deliverables.sh ``` 归档文件将写入 `reports/guardflow_deliverables.zip`。

标签：AI智能体防火墙, DNS 反向解析, LLM应用, StruQ, 大模型应用安全, 敏感信息审计, 数据流追踪, 网关防护, 请求拦截, 逆向工具