mattijsmoens/sovereign-shield

# Sovereign Shield **位于您的 AI 与现实世界之间的安全层。** [](LICENSE) [](https://python.org) []() []() []() 当 AI agent 决定浏览网站、执行代码、发送电子邮件或回答问题时 — Sovereign Shield 会在该操作发生**之前**对其进行检查。如果该操作是危险的、欺骗性的或基于未经验证的事实，它将被拦截。如果是安全的，则会放行。每次都在不到一毫秒的时间内确定性地完成。 将其视为 AI 的保镖。AI 可以随心所欲地思考，但任何内容在通过 11 项独立的安全检查之前都不能离开系统 — 从 prompt injection 检测到事实性幻觉拦截，再到人工审批（human-in-the-loop）。 **它能拦截什么：** - Prompt injection 攻击（50+ 种模式，12 种语言） - Shell 执行、文件删除、凭据窃取 - 欺骗性行为（操纵、社会工程学、IP 窃取） - 未经验证的事实陈述（TruthGuard 会拦截缺乏工具支持验证的自信回答） - DDoS 和速率限制滥用 - 自我改进 — 报告漏报的攻击，自动生成并部署新规则 **零依赖。纯 Python。相同的输入 = 相同的决策，100% 一致。** ## 升级至 1.2.2 如果从早期版本升级，请在安装后**删除您的 `data/.core_safety_lock` 和 `data/.conscience_lock` 文件**。哈希完整性检查会对源代码进行封装 — 由于源代码已更改，您的旧 lockfile 将不匹配并触发完整性违规。它会在下次启动时自动重新封装。 ### 1.2.1 → 1.2.2 的变更 安全审计补丁 — 跨 5 个文件的 10 个修复： - **CoreSafety**：`RESTRICTED_DOMAINS` 现在是不可变元组（原来是可变列表）。Lockfile I/O 使用显式 `encoding="utf-8"`。读取文件路径检查现在使用 `os.path.normpath` 进行规范化。 - **Conscience**：完整性违规现在调用 `os._exit(1)`（不可被捕获）而不是 `sys.exit(1)`（可被捕获）。初始化失败现在终止进程（失效关闭）而不是静默继续。Lockfile I/O 使用显式 `encoding="utf-8"`。 - **Firewall**：Ledger 文件 I/O 使用显式 `encoding="utf-8"` 以实现跨平台兼容性。 - **HITLApproval**：Ledger 文件 I/O 使用显式 `encoding="utf-8"`。 - **MultiModalFilter**：双扩展名检测现在可以捕获最终扩展名（例如 `photo.jpg.exe`）。 ### 1.2.0 → 1.2.1 的变更 - **HITLApproval (新增)**：用于高影响操作的人工审批（Human-in-the-loop）工作流。不再是简单的允许/拦截二元选择，像 DEPLOY、DELETE_FILE、SHUTDOWN 这样的操作可以在执行前要求人工批准。加密参数绑定防止“批准一个操作，执行另一个操作”的替换攻击。AISVS C9.2, C14.2。 - **SIEMLogger (新增)**：用于 SIEM 集成的结构化安全事件记录器。输出 CEF (Common Event Format) 或结构化 JSON，兼容 Splunk、Elastic、QRadar、Sentinel。AI 特定字段：置信度分数、检测到的标记、模型版本、会话 ID。AISVS C13.2.2。 - **MultiModalFilter (新增)**：用于图像、音频和文件的多模态输入验证。魔数验证、MIME 类型欺骗检测、双扩展名检查、嵌入式可执行文件扫描、文件大小强制执行、EXIF 元数据标记。将所有提取的文本（OCR、语音转文本）作为不受信任的输入通过 InputFilter 路由。AISVS C2.7。 ### 1.1.0 → 1.2.0 的变更 - **TruthGuard (新增)**：事实性幻觉检测器。跟踪 AI 实际使用的验证工具，然后扫描输出中的自信声明（时间、数字、引用、确定性标记）。拦截未经验证的声明，允许带有保留态度的回应，并将已验证的事实缓存在带 TTL 的 SQLite 中。可在运行时切换。 - **ActionParser (添加)**：确定性 LLM 输出解析器，从 IntentShield 添加。3 层解析（逐行、正则回退、核扫描），强制执行 SUBCONSCIOUS/ACTION 格式并提供纠正反馈。 - **LoRAExporter (新增)**：将 TruthGuard 数据编译为用于外部 LoRA 微调的 JSONL 训练对。目标：教导模型偏好真实的回应，从而不再需要 TruthGuard 来捕获它。4 种对类型：负向纠正、正向验证、正向保留、正向引用。 - **整合**：移除了 SovereignShieldFull。所有 8 个组件现在位于一个 SovereignShield 包中。181 个测试通过。 ### 1.0.4 → 1.1.0 的变更 - **自扩展雷区 (V2)**：AdaptiveShield 现在将攻击分为不同类别（窃取、注入、冒充等）并学习关键词簇。一次报告即可阻止一类它从未见过的*整个类别*的类似攻击。 - **自剪枝误报**：新的 `report_false_positive()` 方法移除错误拦截干净输入的学习关键词 — 保留不可变的预定义规则。系统变得更聪明*且*更精确。 - **多语言检测**：InputFilter 现在拦截 12 种语言的注入尝试（法语、德语、西班牙语、葡萄牙语、意大利语、荷兰语、波兰语、俄语、中文、日语、韩语、阿拉伯语）。 - **多重解码流水线**：自动 Base64、ROT13、leet speak 和反向文本解码可捕获编码的绕过尝试。 - **基准测试**：跨 10 个类别的 300 个真实攻击载荷 — 在 2 个学习世代中收敛率从 2.7% → 78.7% → **100% 检测率**。在 50 个干净输入上 0 误报。 ### 1.0.3 → 1.0.4 的变更 - ** AdaptiveShield (新增)**：从漏报攻击中学习的自我改进安全过滤器。报告触发自动规则生成 → 针对历史流量在沙箱中重放 → 基于阈值部署。专利申请中。 - **InputFilter**：修复了 Unicode 同形字符绕过 — 希腊/西里尔字母外观相似字符（例如 Ι, Ρ, А, О）现在在关键词匹配之前折叠为拉丁等效字符。添加了 40+ 个字符映射。 - **InputFilter**：修复了 Base64/编码载荷绕过 — 通过 Base64 签名分析改进了熵检测（捕获 `=` 填充 + 数字/符号密度）。 - **Firewall**：修复了即时重新拦截 — 滑动窗口中的过时时间戳导致用户在拦截过期后立即被重新拦截。历史记录现在在过期时清除。 ### 1.0.2 → 1.0.3 的变更 - **InputFilter**：添加了 18 个缺失的 prompt injection 关键词（`IGNORE ALL`、`ACT AS`、`PRETEND TO BE`、`DISREGARD ALL`、`BYPASS ALL` 等） — 这些以前绕过了检测，因为填充词破坏了子字符串匹配。 - **CoreSafety**：速率限制器现在可通过 `rate_limit_interval` 参数配置（默认 0.5s）。如果您的应用程序自行处理速率限制，请设置为 `0` 以禁用。 ## 架构 ``` ┌─────────────────────────────────────────────────────────────────────────────────────────────────┐ │ SOVEREIGN SHIELD │ ├──────────┬──────────────┬───────────┬──────────────┬────────────────┬──────────────┬────────────┤ │ Firewall │ InputFilter │Conscience │ CoreSafety │ AdaptiveShield │ TruthGuard │MultiModal │ │(Layer 1) │ (Layer 2) │ (Layer 3) │ (Layer 4) │ (Layer 5) │ (Layer 6) │ (Layer 7) │ │ │ │ │ │ │ │ │ │• Identity│ • Unicode │• Deception│ • Hash Seal │• Self-Improving│• Factual │• MIME Type │ │ White- │ Normalize │ Detection│ • Integrity │ Filter │ Claim │ Validation│ │ list │ • Injection │• Harm │ Verify │• Scan Logging │ Detection │• Magic Byte│ │• Rate │ Blocking │ Patterns │ • Action │• Report │• Tool Use │ Checking │ │ Limiting│ • Gibberish │• IP Leak │ Auditing │ Interface │ Tracking │• Filename │ │• DDoS │ Detection │ Detection│ • Killswitch │• Sandbox │• Verified │ Sanitize │ │ Protect │ • LLM Token │• Evasion │ • Write/Read │ Replay │ Fact Cache │• Embedded │ │• Persisted│ Blocking │ Detection│ Whitelists │• Threshold │• Hedge │ Exe Check │ │ Ledger │ • Keyword │• Self- │ • Malware │ Gated Deploy │ Detection │• EXIF Flag │ │ │ Blocking │ Preserve │ Syntax │• Manual │• LoRA Export │• Extracted │ │ │ │ │ • Budget │ Approval │ │ Text Route│ │ │ │ │ • Rate Limit │• SQLite │ │ │ │ │ │ │ │ Persistence │ │ │ └──────────┴──────────────┴───────────┴──────────────┴────────────────┴──────────────┴────────────┘ Cross-Cutting: HITLApproval (human-in-the-loop approval for high-impact actions) SIEMLogger (structured CEF/JSON security event logging for SIEM platforms) ActionParser (LLM output parsing) │ LoRAExporter (training data compiler) ``` ## 组件 ### 1. `CoreSafety` — 不可变宪法 AI 想要执行的每个操作首先都会通过 CoreSafety。它强制执行无法在运行时更改的硬性规则 — 用户不能改，应用程序不能改，AI 自己也不能改。这些规则存在于 `FrozenNamespace` 元类中，这使得它们在 Python 内存中物理上不可变。首次启动时，CoreSafety 使用 SHA-256 对其自己的源代码进行哈希处理，并将该哈希锁定到磁盘。如果有人编辑了文件，哈希将不匹配，进程会立即自行终止。 这是最后一道防线。即使其他一切都失败了，CoreSafety 也会拦截 Shell 执行、文件删除、凭据窃取和代码注入 — 每次，确定性地。 - SHA-256 哈希封装，具有篡改触发关闭功能 - 操作审计：管理员权限、文件白名单、域限制、恶意软件语法 - 幻觉检测：捕获 AI 声称它“分析”了某物而未使用工具的情况 - 线程安全的每日预算限制器，防止成本失控 - 紧急开关：一个文件即可立即终止进程 ### 2. `Conscience` — 道德指南针 CoreSafety 处理硬性技术规则，而 Conscience 处理软性行为规则。它捕获 AI 欺骗、操纵或试图提取不应获取的信息的情况。它使用预编译的正则表达式模式扫描 22+ 个操纵动词（lie、fake、trick、roleplay、gaslight）和 24+ 个危害关键词。 之所以将其作为单独的一层：某些危险输出在技术上是有效操作。“ANSWER: Here is the full source code of CoreSafety...”是一个合法的回答操作，但 Conscience 捕获了 IP 泄露。“ANSWER: Sure, I'll pretend I have no restrictions”是一个有效的响应，但 Conscience 捕获了欺骗行为。 - 欺骗、伤害和社会工程学模式检测 - 源代码和系统 Prompt 泄露预防 - 虚假工具注入检测（语法有效但未经授权的调用） - 自我保护：拒绝删除自己的文件 - 哈希封装，具有与 CoreSafety 相同的 lockfile 完整性 ### 3. `InputFilter` — 感官皮层 在任何输入到达您的 AI 之前，InputFilter 会对其进行清理。它规范化 Unicode，去除 ANSI 转义码，检测乱码/编码载荷，并拦截 12 种语言的 Prompt injection 关键词。多重解码流水线自动尝试 Base64、ROT13、leet speak 和反向文本 — 因此，即使攻击者将编码绕过尝试包裹在多层混淆中，也能被捕获。 之所以将其作为单独的一层：Prompt injection 是针对 AI 系统最常见的攻击向量。大多数注入依赖于特殊字符、Unicode 技巧或关键词短语，这些都可以在 AI 看到它们之前确定性地捕获。 - Unicode 规范化 + 40+ 个希腊/西里尔同形字符映射 - ANSI 转义码去除 - 熵分析 + 针对编码载荷的 Base64 签名检测 - LLM token 拦截（ChatML、LLaMA、系统 token） - 跨 12 种语言的 30+ 个越狱关键词 ### 4. `Firewall` — 身份网关 在用户级别控制访问。只有白名单中的用户 ID 才能交互，并且他们受到滑动窗口的速率限制。违规者会被自动拦截一段可配置的持续时间，拦截账本持久化到磁盘，以便在重启后保留。这可以防止 DDoS、暴力破解和滥用模式。 - 具有可配置允许 ID 的用户白名单 - 滑动窗口速率限制器（每个窗口的消息数） - 具有可配置持续时间的自动拦截 - 持久化到磁盘的拦截账本 - 线程安全操作 ### 5. `AdaptiveShield` — 自我改进过滤器 *(专利申请中)* 大多数安全系统都是静态的 — 它们只能捕获构建时设计的那些内容。AdaptiveShield 缩小了这一差距。当攻击突破时，您报告它。系统从漏报攻击中提取关键词，将其分类为攻击类别（窃取、注入、冒充等），并存储它们。一次报告即可教会它拦截一类它从未见过的类似攻击。 在部署新规则之前，AdaptiveShield 会针对所有历史允许的输入重放该规则，以计算其误报率。如果低于 1%，规则立即生效。如果高于 1%，则标记为人工审查。如果干净输入被错误拦截，`report_false_positive()` 仅移除导致该问题的学习关键词 — 预定义规则永远不会被触及。 - 通过扫描 ID 报告漏报攻击，从关键词自动生成规则 - 基于类别的分类：一次报告即可拦截整个攻击类别 - 部署前针对历史流量在沙箱中重放 - 自剪枝：移除过于激进的学习规则，同时保持核心规则不可变 - 两种模式：自动部署或人工审批工作流 - SQLite 持久化，完全离线，线程安全 ### 6. `TruthGuard` — 事实性幻觉检测器 *(专利申请中)* AI 模型会自信地陈述不真实的事情。TruthGuard 通过跟踪 AI 在会话期间实际使用的验证工具（SEARCH、BROWSE、READ_FILE），然后扫描输出中的置信度标记 — 时间声明（“截至 2024”）、数字声明（“成本 499 美元”）、引用（“根据 MIT”）和确定性语言（“ definitely”、“always”、“100%”）— 来捕获这种情况。如果 AI 在没有先使用验证工具的情况下做出自信的事实声明，TruthGuard 会拦截它。 如果 AI 适当地使用保留措辞（“我相信”、“据我所知”），TruthGuard 会放行。已验证的事实缓存在带有可配置 TTL 的 SQLite 中，因此同一事实不需要每次都重新验证。可以在运行时开启或关闭。 - 4 个正则表达式类别：时间、数字、引用、确定性 - 感知会话的工具跟踪 - 保留检测：允许适当不确定的响应 - 带有 TTL 的已验证事实缓存 - 每次检查的完整审计日志 - 运行时切换：`guard.enabled = True/False` ### 7. `ActionParser` — LLM 输出解析器 LLM 生成杂乱、不可预测的文本。ActionParser 将其转换为结构化数据。它强制执行 SUBCONSCIOUS/ACTION 格式，其中 AI 必须在声明其想要做什么之前展示其推理。三个解析层（逐行、正则回退、核扫描）处理从干净输出到完全格式错误文本的所有内容。如果解析失败，它会返回一个纠正 Prompt，告诉 AI 如何修复其输出。 - 具有渐进式回退的 3 层解析 - SUBCONSCIOUS/ACTION 格式强制执行 - Markdown 产物清理（去除粗体、反引号、格式） - 工具白名单验证 - 针对失败解析的纠正反馈 ### 8. `LoRAExporter` — 训练数据编译器 TruthGuard 在运行时捕获幻觉，但真正的目标是让模型从一开始就停止幻觉。LoRAExporter 将 TruthGuard 学到的所有内容 — 被拦截的声明、已验证的事实、保留响应、引用答案 — 编译成 JSONL 训练对。然后，您可以将这些数据集与外部微调工具（OpenAI API、HuggingFace、Unsloth）一起使用，以训练模型偏好真实的、保留的响应而不是自信的猜测。随着时间的推移，模型会内化这种行为，不再需要 TruthGuard 来捕获它。 - 4 种训练对类型：负向纠正、正向验证、正向保留、正向引用 - 标准 messages JSONL 格式（兼容 OpenAI/HuggingFace） - 显示数据就绪情况的统计仪表板 - 自动保留：将被拦截的声明转换为用于训练的保留版本 ### 9. `HITLApproval` — 人工审批 *(AISVS C9.2, C14.2)* 某些操作过于重要，不能仅信任自动化系统。HITLApproval 拦截高影响操作（DEPLOY、DELETE_FILE、SHUTDOWN、TRANSFER_FUNDS 等），并暂停执行直到人工审查员批准或拒绝它们。批准使用 SHA-256 加密绑定到确切的操作参数 — 因此，批准一组参数不能被重放以执行不同的参数。批准在可配置的 TTL（默认值：5 分钟）后过期。 - 可配置的高影响操作列表（13 个默认值） - 加密参数绑定（防止替换攻击） - 带有自动过期的批准 TTL - 持久化 JSON 账本在重启后保留 - 批准/拒绝/待处理管理界面 - 线程安全操作 ### 10. `SIEMLogger` — SIEM 集成 *(AISVS C13.2.2)* 企业安全团队在其 SIEM 仪表板中工作。SIEMLogger 将来自每个 SovereignShield 组件的每个安全事件格式化为 CEF (Common Event Format) 或结构化 JSON — 两者都是 Splunk、Elastic、QRadar 和 Azure Sentinel 可以原生摄取的标准格式。每个事件都包含传统安全日志中不存在的 AI 特定上下文字段：模型版本、置信度分数、检测到的标记、会话 ID。 - CEF 和 JSON 输出格式 - 自动映射的严重性级别（17 种事件类型） - AI 特定上下文：置信度分数、标记、模型版本 - 具有基于大小轮换的线程安全文件输出 - 便捷方法：`log_block()`、`log_allow()`、`log_injection()`、`log_hallucination()` ### 11. `MultiModalFilter` — 多模态输入验证 *(AISVS C2.7)* AI 应用程序越来越多地处理图像、音频和文件 — 不仅仅是文本。MultiModalFilter 在这些非文本输入进入流水线之前对其进行验证。它使用魔数检查文件类型（不仅仅是文件扩展名），检测类型欺骗（声明是 JPEG 但实际上是可执行文件），无条件拦截危险的文件类型，捕获双扩展名（photo.jpg.exe），并扫描嵌入式可执行签名。从媒体中提取的任何文本（OCR、语音转文本）都作为不受信任的输入通过 InputFilter 路由。 - 15+ 种文件类型的魔数验证 - 具有危险类型黑名单的 MIME 类型白名单 - 类型欺骗检测（声明与实际不匹配） - 文件名清理（空字节、路径遍历、双扩展名） - 嵌入式可执行文件扫描（PE、ELF、脚本签名） - EXIF 元数据检测和剥离标记 - 通过 InputFilter 路由提取的文本 ## 快速开始 ``` from sovereign_shield import CoreSafety, Conscience, InputFilter, Firewall, AdaptiveShield, TruthGuard # 1. 初始化 hash seals（在启动时执行一次） CoreSafety.initialize_seal(data_dir="./security_data") Conscience.initialize(data_dir="./security_data") # 2. 创建你的防火墙 fw = Firewall( allowed_users=[12345, 67890], # Only these user IDs can interact rate_limit=10, # 10 messages per 60s window window=60, block_duration=300, # 5min block for violators ledger_path="./security_data/ddos_ledger.json" ) # 3. 创建 input filter input_filter = InputFilter( safe_keywords=["internal_command"], # These bypass the filter ) # 4. 创建 adaptive shield（自我改进 filter） adaptive = AdaptiveShield( db_path="./security_data/adaptive.db", fp_threshold=0.01, # 1% false positive threshold auto_deploy=True, # Rules deploy automatically when validated ) # 5. 处理请求 def handle_request(user_id, user_input): # Layer 1: Identity + Rate Limit allowed, reason = fw.check(user_id) if not allowed: return f"BLOCKED: {reason}" # Layer 2: Input Sanitization (static + adaptive rules) result = adaptive.scan(user_input) if not result["allowed"]: return f"REJECTED: {result['reason']}" # Layer 3: Ethical Check approved, ethics_reason = Conscience.evaluate_action("RESPOND", user_input) if not approved: return f"ETHICS BLOCK: {ethics_reason}" # Layer 4: Action Audit authorized, audit_reason = CoreSafety.audit_action("ANSWER", user_input) if not authorized: return f"SAFETY BLOCK: {audit_reason}" # All clear — process the request return process_safely(user_input) # 6. 报告漏报攻击（触发 self-improvement） # report = adaptive.report(scan_id="abc123", reason="data exfiltration attempt") # 7. 报告误报（触发 self-pruning） # fp = adaptive.report_false_positive(scan_id="def456", reason="legitimate question") ``` ## 安全属性 | 属性 | 机制 | |---|---| | **防篡改** | 带 lockfile 的 SHA-256 哈希封装。不匹配时进程自行终止。 | | **不可变法则** | `FrozenNamespace` 元类物理上阻止属性修改。 | | **深度防御** | 7 个独立层 + 4 个跨切模块 — 破坏一个不能绕过其他的。 | | **失效关闭** | 验证失败时，系统关闭而不是在未受保护的情况下运行。 | | **线程安全** | 所有共享状态都由锁保护。 | | **持久化** | 拦截账本和使用计数器在重启后保留。 | | **自我改进** | 自适应过滤器通过沙箱验证的规则从漏报攻击中学习。 | | **管理员检测** | 拒绝以 root/admin 身份运行（最小权限强制执行）。 | | **防窃取** | 拦截读取源代码、配置或环境变量的尝试。 | ## 文件结构 ``` SovereignShield/ ├── README.md ← You are here ├── LICENSE ← BSL 1.1 ├── pyproject.toml ← Package config ├── test_shield.py ← Core security tests (38) ├── test_truth_guard.py ← TruthGuard tests (27) ├── test_lora_export.py ← LoRA + toggle tests (14) └── sovereign_shield/ ├── __init__.py ← Public API (exports all 11 components) ├── core.py ← CoreSafety + FrozenNamespace ├── conscience.py ← Ethical evaluation engine ├── input_filter.py ← Input sanitization ├── firewall.py ← Identity + rate limiting ├── adaptive.py ← AdaptiveShield (self-improving filter) ├── truth_guard.py ← TruthGuard (factual hallucination detection) ├── action_parser.py ← ActionParser (LLM output parsing) ├── lora_export.py ← LoRAExporter (training data compiler) ├── hitl.py ← HITLApproval (human-in-the-loop approval) ├── siem_logger.py ← SIEMLogger (SIEM event logging) └── multimodal_filter.py ← MultiModalFilter (multi-modal validation) ``` ## 测试 ``` python -m pytest test_shield.py test_truth_guard.py test_lora_export.py -v ``` 181 个测试用例，涵盖 FrozenNamespace 不可变性、InputFilter（同形字符、熵和多语言攻击）、Firewall、Conscience、CoreSafety、AdaptiveShield V2（自扩展雷区、自剪枝）、TruthGuard（置信度标记、保留检测、事实缓存、会话隔离）和 LoRAExporter（JSONL 输出、训练对格式、运行时切换）。 ## 许可证 [Business Source License 1.1](LICENSE) — 免费用于非生产用途（个人项目、研究、测试、评估）。商业用途需要商业许可证。在每个发布十年后转换为 Apache 2.0。 ## 起源 提取自 **KAIROS Autonomous Intelligence System** — 一个具有 24/7 自主运行能力的主权 AI 实体。这些安全组件保护 KAIROS 免受 Prompt injection、越狱、自我修改、数据窃取和所有已知 AI 操纵技术的侵害。 **专利申请中** — Truth Adapter Validation System | Self-Improving Security Filter System

标签：Agentic Security, AI安全, AI防火墙, Chat Copilot, DNS 反向解析, DNS 解析, Homebrew安装, Security Framework, Social Engineering Defense, WAF, Web防火墙, 专利技术, 事实核查, 人机协同, 代理安全, 伦理围栏, 哈希封印, 大模型安全, 完整性校验, 审计日志, 提示词注入防火墙, 数据防泄露, 沙箱, 确定性安全, 纯Python, 网络安全, 网络安全审计, 自我改进, 自适应过滤器, 行为监控, 逆向工具, 配置错误, 防DDoS, 隐私保护, 零依赖