amarjaleelbanbhan/CortexWard
GitHub: amarjaleelbanbhan/CortexWard
CortexWard 是一个自主 AI 软件安全工程师，通过多层证据验证阶梯对代码漏洞进行理解、验证、修复并导出标准化安全报告。
Stars: 2 | Forks: 0
# 🛡️ CortexWard
**一个自主的 AI 软件安全工程师，能够理解、验证、修复并保护软件安全。**
[](.github/workflows/ci.yml)
[](LICENSE)
[](pyproject.toml)
[](ROADMAP.md)
[](pyproject.toml)
## 为什么选择 CortexWard
AI 编写了世界上大量且比例不断增长的代码，而研究反复发现 **30-40% 的 AI 生成代码都带有安全漏洞**。现有的工具都只能看到问题的一部分：
- **静态分析器**（Semgrep、CodeQL、Bandit）只能匹配模式，但无法判断匹配项是否真正可达或可利用——因此会让团队陷入误报的泥潭。
- **LLM 审查器**能够推理意图，但会产生幻觉，并且无法*证明*任何东西。
- **几乎没有工具**能够通过生成修复程序并证明该修复程序有效来形成闭环。
CortexWard 并不是另一个 LLM 封装器。它是一个**自主安全工程师**：它能建立对代码库的真正理解，收集关于每个潜在漏洞的*证据*，并且只上报或修复它能够证实的问题。
## 核心理念：验证阶梯
CortexWard 不仅仅给出“漏洞利用是否运行成功”的二进制结果，而是为每个发现分配**最强的可行证据**，并据此校准其置信度：
| 阶梯 | 证据 | 含义 |
|------|----------|---------|
| 0 · `NONE` | 模式匹配 | 触发了检测器 |
| 1 · `STATIC_REACHABILITY` | 可达性证明 | sink 可达 |
| 2 · `TAINT_CONFIRMED` | 数据流追踪 | 攻击者控制的数据到达了 sink |
| 3 · `DYNAMIC_POC` | 沙箱漏洞利用 | 概念验证实际运行成功 |
| 4 · `DIFFERENTIAL_TEST` | 差异化测试 | 在存在漏洞的代码与已修复代码上表现不同 |
两条安全规则是结构性的，而非理想化的：
1. **仅靠 LLM 永远是不够的**——模型的判断是有限的，无法攀登阶梯；只有具体的分析才能做到。
2. **证伪是一等公民**——证明某个发现*不可*利用的证据会被捕获，并推动其得出 `NOT_AFFECTED` 的结论。
结果以 **SARIF**（发现）、**VEX**（可利用性）和 **CycloneDX**（SBOM）格式导出——这些是对“在当前上下文中这真的是一个问题吗？”的标准对齐回答。
## 架构一览
CortexWard 采用六边形（端口和适配器）设计，带有一个进程内、可检查的 agent 编排器。所有与外部世界交互的组件都是可插拔的适配器。
```
Interfaces: CLI · REST API · GitHub App · VS Code extension (packages/cortexward-{cli,server,sdk})
Application: Orchestrator → Planner · Scanner · Verifier · Repair · Reviewer · Memory
Domain core: Finding · Evidence · Verification Ladder · Patch · Provenance ← pure, no I/O
Ports: CodeGraph · LanguageProvider · Scanner · LLM · Sandbox · VCS
· Storage · Telemetry · Orchestrator · Reporter (cortexward.ports, typing.Protocol)
Plugins: entry-point discovery — a new adapter needs zero core changes (cortexward.plugins)
Adapters: tree-sitter CPG · Semgrep/Bandit/CodeQL · Anthropic/OpenAI/Ollama · Docker …
```
`cortexward-core` 提供了领域模型、完整的端口目录以及插件注册表。
`cortexward-cpg`（依赖于 `cortexward-core`）提供了参考的 Code Property Graph 引擎——这是一种与语言无关的节点/边 schema，以及一个带有防循环的可达性/污点/切片查询的内存 `CodeGraph` 实现；正在开发基于 tree-sitter 的解析功能。
其他每一行都是 [`packages/`](packages/) 下独立维护版本的包，随着其阶段的完成而添加——详情请参阅 [ARCHITECTURE.md](ARCHITECTURE.md) 和 [ADR-0005](docs/adr/0005-uv-workspace-monorepo.md)。
## 快速开始（开发）
需要 Python 3.11+ 和 [uv](https://docs.astral.sh/uv/)。这是一个 **uv 工作区**（ADR-0005）：根目录的 `pyproject.toml` 是一个虚拟清单，因此必须使用 `--all-packages` 显式同步工作区成员。
```
git clone https://github.com/amarjaleelbanbhan/CortexWard
cd CortexWard
uv sync --all-packages --extra dev
# 完全按照 CI 的方式运行 quality gate
uv run ruff check packages
uv run ruff format --check packages
for pkg in packages/*/; do uv run mypy "${pkg}src" "${pkg}tests"; done # per-package, see CONTRIBUTING.md
uv run lint-imports # hexagonal dependency-direction check
uv run pytest --cov=cortexward --cov-fail-under=100
```
领域核心如今即可使用：
```
from cortexward.domain import (
Finding, Evidence, EvidenceKind, Provenance,
SourceLocation, VerificationRung, assess,
)
finding = Finding(
rule_id="py.sql-injection",
title="Possible SQL injection",
message="User input flows into a raw SQL query.",
cwe=89,
locations=(SourceLocation(path="app/db.py", start_line=42),),
provenance=Provenance(producer="semgrep", producer_version="1.90"),
).with_evidence(
Evidence(kind=EvidenceKind.STATIC_MATCH, summary="semgrep rule matched",
provenance=Provenance(producer="semgrep")),
Evidence(kind=EvidenceKind.TAINT_TRACE, rung=VerificationRung.TAINT_CONFIRMED,
summary="request.args → cursor.execute", provenance=Provenance(producer="cpg")),
)
report = assess(finding)
print(report.recommended_state, report.vex_status, round(report.confidence, 2))
# 已验证 under_investigation 0.86
# 已证实存在 taint rung → VERIFIED，但尚不是可运行的 PoC，因此
# VEX 结论保持为 "under_investigation" 而非 "affected"。
```
## 路线图
CortexWard 分为严格的、可交付的阶段进行构建。阶段 1 交付了基础和经过测试的领域核心；阶段 1.5（当前里程碑）交付了工作区重构、端口目录、插件注册表以及强化的 CI。有关每个阶段的详情，请参阅 [ROADMAP.md](ROADMAP.md)。
## 贡献
欢迎您的贡献。请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)、我们的[行为准则](CODE_OF_CONDUCT.md)以及 [SECURITY.md](SECURITY.md)。研究想法和悬而未决的问题位于 [`research/`](research/) 中。
## 许可证
[Apache License 2.0](LICENSE)。标签：AI安全工程师, AI风险缓解, LLM防护, Maven, 云安全监控, 基础设施安全, 漏洞验证, 自动化漏洞修复, 请求拦截, 逆向工具, 静态分析