🪞 八咫 · Yata

适用于 AI Agent 的通用安全审计 Playbook。
仅需一个 .md 文件，即可将任何代码 Agent 变成严苛的安全审计员。

得名于日本神话中的神器 八咫镜（八咫鏡），象征着揭示真相。Yata 为你的代码举起一面明镜，照出其中隐藏的秘密。

🪞 包含动画与快速开始的官网 → kitay-sudo.github.io/yata

## 💡 这是什么 **Yata** 是一个独立自足的指令文件 [`YATA.md`](./YATA.md)，你可以将其“喂”给任何代码 Agent（如 Claude Code、Cursor、Codex、Aider 或自定义的 LLM harness）。 阅读该文件后，Agent 会按顺序理解以下内容： - 面前的**是什么项目**以及它使用了**什么技术栈**（通过标记文件自动检测）； - **如何正确地对项目进行检查**以及执行的**顺序**； - 需要执行**什么样的审计计划**——从侦察到最终的“是否可以上线生产环境”的结论； - **具体要寻找什么**——路由漏洞、逻辑错误、输入验证、注入、数据库操作、可疑的外部输出（邮件/Webhook/第三方）、易受攻击的包和库、机密信息泄漏、哪里需要 **rate limit** 以及高负载下的稳定性； - **如何输出结果**——包含按 severity 分级的 findings 以及用于修复每个漏洞的**现成 `diff` 补丁**。 目标：经过一次完整的审计流程后，项目可以安全地运行在生产环境中，无需担心被黑客攻击、数据泄漏或在负载下崩溃。 ## 🚀 如何使用 ### ⚡ 方式 1. 通过一条链接快速引导（无需复制任何内容）—— 推荐 在待检查项目**内部**，向 Agent 发送以下 prompt： Agent 会自动阅读 playbook，理解技术栈，执行审计并创建一个**独立的文件夹**： ``` yata/ ├── README.md ← начни отсюда: вердикт + счётчик severity + ссылки + как применять фиксы ├── SECURITY_AUDIT_REPORT.md ← полный отчёт ├── findings/ ← по файлу на каждую проблему ├── fixes/ ← по .diff на каждую проблему (git apply) ├── route-inventory.md └── appendix/ ← сырой вывод инструментов ``` 在你准备好（请先查看每个 diff）后应用修复： ``` git apply --check yata/fixes/CRIT-01-*.diff # проверить git apply yata/fixes/CRIT-01-.diff # применить один ``` ### 方式 2. 将文件放入项目仓库 1. 将 [`YATA.md`](./YATA.md) 和 [`REPORT_TEMPLATE.md`](./REPORT_TEMPLATE.md) 复制到项目的根目录。 2. 向 Agent 发送 playbook 第 24 节中的 prompt（**Quick-start prompt**）——它会创建相同的 `yata/` 文件夹。 ### 方式 3. 快速局部审计 如果时间紧迫——可以让 Agent 仅执行高优先级的阶段： **0 → 1 → 2 → 4 → 5 → 9**（侦察、依赖、机密、授权、注入、rate limit）。Agent 必须在报告中明确指出其余部分不在审计范围（scope）内。 ## 🗺️ 计划检查的内容（17 个阶段） | # | 阶段 | 检查重点 | |---|------|-------| | 0 | Recon & threat model | 项目信息、技术栈、入口点、信任边界、“crown jewels” | | 1 | Dependencies / supply chain | 易受攻击和恶意的包、lockfile、typosquatting | | 2 | Secrets & configuration | 泄漏的机密、不安全的默认配置、Headers、CORS、TLS | | 3 | Routes & attack surface | 清点所有入口点 + 路由逻辑错误、IDOR/BOLA | | 4 | AuthN & AuthZ | 密码、会话、JWT、OAuth、访问控制、权限提升 | | 5 | Input validation & injection | SQLi、XSS、SSRF、RCE、path traversal、反序列化、SSTI、XXE | | 6 | Business / logic flaws | 竞态条件、资金/数量、绕过 workflow、幂等性 | | 7 | Database layer | 查询安全性、最小权限、PII、加密、数据库迁移 | | 8 | Data egress / outputs | 邮件、Webhook、3rd-party/LLM、作为泄漏渠道的日志、数据导出 | | 9 | Rate limiting & DoS | 哪里需要限制、防止资源耗尽、高负载下的稳定性 | | 10 | Crypto & secrets mgmt | Hash、加密、随机数、密钥管理 | | 11 | Files & storage | 上传、内容验证、object storage、zip-slip | | 12 | Client / frontend | XSS、CSP、CSRF、token 存储、bundle 中的机密 | | 13 | Infra / CI-CD / IaC | Container、pipeline、Terraform/K8s、云权限、网络 | | 14 | Observability & IR | 安全日志、监控、audit trail、应急响应准备 | | 15 | AI / LLM / agentic *(可选)* | Prompt injection、RAG/vector、过度代理、system prompt 泄漏、cost-DoS — **OWASP LLM Top 10 (2025)** | | 16 | Mobile *(可选)* | OWASP MASVS：存储、网络、平台、弹性、隐私 | | 17 | Privacy & compliance | PII 数据流图、retention/删除、GDPR / PCI DSS / HIPAA / SOC 2 映射 | **可选阶段 15 和 16** 仅在项目包含 AI/LLM/Agent 或移动客户端时触发。 每个阶段都有目标、具体操作和 **exit gate**。最终步骤是 **production-readiness gate**：清晰的结论：go / go-with-conditions / no-go。 此外，playbook 还深化了供应链安全（SBOM CycloneDX/SPDX、SLSA-provenance、通过 Sigstore/cosign 签名制品、依赖固定以及通过 SHA 固定 GitHub Actions），并包含了 **OSS 工具矩阵**（Semgrep、CodeQL、Trivy、Grype、Gitleaks、TruffleHog、ZAP、Nuclei、Checkov、garak、MobSF）。 ## 📄 输出格式 所有结果都会存放在待检查项目根目录下的一个文件夹 **`yata/`** 中（Agent 不会改动仓库的其余部分）。里面包含根据 [`REPORT_TEMPLATE.md`](./REPORT_TEMPLATE.md) 生成的报告以及应用的补丁： - `README.md` — 索引：go/no-go 结论、按 severity 统计的 findings 计数、“finding → diff”表格、应用方法； - `SECURITY_AUDIT_REPORT.md` — 执行摘要、系统概述 + 诚实的 **coverage**（检查了什么，没检查什么）； - `findings/` — 按 severity 分级的 findings，每一个都包含位置、利用路径、CVSS（针对 High/Critical）以及到 OWASP/CWE 的映射； - `fixes/` — 针对每个问题的 **`.diff` 补丁**（`git apply`），具有统一的 ID（`CRIT-01`、`HIGH-01`、…）； - `route-inventory.md` + `appendix/` — 攻击面图谱和工具的原始输出； - 最终的 production-readiness gate，包含按优先级排列的修复计划（effort × impact）。 ## 🧰 支持的技术栈 该文件**与具体技术栈无关**。针对以下技术提供自动检测和工具提示： Node.js/TS、Python、Go、Java/Kotlin、Ruby/Rails、PHP/Laravel、.NET/C#、Rust 以及 Docker/K8s/Terraform。 会针对每个生态系统推荐相应的 SCA 扫描工具（`npm audit`、`pip-audit`、`govulncheck`、`osv-scanner`、`trivy` 等）。 ## 📚 制定依据 OWASP Top 10 (2021)、OWASP API Security Top 10 (2023)、**OWASP Top 10 for LLM Applications (2025)**、OWASP MASVS (移动端)、OWASP ASVS 5.0、OWASP WSTG、Proactive Controls & Cheat Sheets、CWE Top 25、CIS Benchmarks、NIST SSDF、SLSA (供应链)、MITRE ATT&CK —— 并结合了 2026 年的实践进行了调整。 ## 📜 许可证 [MIT](./LICENSE) — 可自由使用，包括用于商业项目。 _{Yata 是提供给 Agent 的检查清单和导航器，而非绝对保证。审计结果是供人类决策参考的专家意见，而不是对安全性的最终判决。}

标签：AI代理, 防御加固