使用说明
支持Maven依赖扫描和修复以及AI RAG
一个基于人工智能的安全分析系统，用于使用Neo4j图形数据库、MCP（模型上下文协议）工具和LLM代理分析OWASP依赖性检查报告。
🎯 概述
该项目为以下方面提供了全面的解决方案：
- 🔍 使用OWASP依赖性检查扫描Java项目的依赖性漏洞
- 📊 将漏洞数据导入Neo4j图形数据库
- 🤖 使用LLM代理和MCP工具进行人工智能分析
- 📈 用于可视化和分析的交互式仪表板
- 🔗 基于可用安全版本的自动修复建议
🏗️ 建筑
┌─────────────────────┐
│ Java Project │
│ (Maven/Gradle) │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ OWASP Dependency │
│ Check Scanner │
│ (Container) │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Import Script │
│ (import_odc_to_ │
│ neo4j.py) │
└──────────┬──────────┘
│
▼
┌─────────────────────┐ ┌─────────────────┐
│ Neo4j Graph │◄────────┤ MCP Tools │
│ Database │ │ (server.py) │
└──────────┬──────────┘ └────────┬────────┘
│ │
▼ ▼
┌─────────────────────┐ ┌─────────────────┐
│ Streamlit │ │ LLM Agent │
│ Dashboard │ │ (agent.py) │
└─────────────────────┘ └─────────────────┘
👤 用户流程
选项1：Web仪表板（建议大多数用户使用）
┌──────────────────────────────────────────────────────────────────┐
│ 1. USER OPENS BROWSER │
│ → streamlit run dashboard.py │
│ → Opens http://localhost:8501 │
└───────────────────────────┬──────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ 2. USER SEES DASHBOARD TABS │
│ [Overview] [Risk Analysis] [Dependency Graph] [CVE] [AI Chat] │
└───────────────────────────┬──────────────────────────────────────┘
│
┌───────────┴──────────┬────────────┬──────────────┐
▼ ▼ ▼ ▼
┌───────────────────┐ ┌──────────────────┐ ┌────────┐ ┌─────────┐
│ Overview Tab │ │ Risk Analysis │ │ Graph │ │ AI Chat │
│ │ │ │ │ │ │ │
│ • Total CVEs │ │ • Top 10 Risky │ │ Visual │ │ Natural │
│ • Severity Chart │ │ Dependencies │ │ Graph │ │ Language│
│ • Module Summary │ │ • Risk Scores │ │ │ │ Queries │
└───────────────────┘ └──────────────────┘ └────────┘ └─────────┘
│
▼
┌────────────────────────┐
│ USER ASKS QUESTIONS: │
│ │
│ "What are the top 10 │
│ riskiest deps?" │
│ │
│ "Show me all CRITICAL │
│ CVEs in log4j" │
│ │
│ "What's the safe │
│ version for X?" │
└───────────┬────────────┘
│
▼
┌───────────────────────────────────┐
│ 3. AI AGENT PROCESSES QUERY │
│ (Behind the scenes) │
│ │
│ THOUGHT: "I need to query Neo4j│
│ for dependencies..." │
│ │
│ ACTION: Calls MCP Tool │
│ read_neo4j_query() │
└───────────────┬───────────────────┘
│
▼
┌───────────────────────────────────┐
│ 4. MCP TOOLS EXECUTE │
│ → Query Neo4j Graph DB │
│ → Fetch CVE data from NVD │
│ → Generate visualizations │
│ → Calculate risk scores │
└───────────────┬───────────────────┘
│
▼
┌───────────────────────────────────┐
│ 5. USER RECEIVES ANSWER │
│ │
│ "Found 5 dependencies with │
│ CRITICAL vulnerabilities: │
│ │
│ 1. log4j-core 2.14.1 │
│ → CVE-2021-44228 (10.0) │
│ → Recommended: 2.17.1 │
│ │
│ 2. jackson-databind 2.9.8 │
│ → CVE-2020-36518 (9.8) │
│ → Recommended: 2.12.6.1" │
└───────────────────────────────────┘
选项2：命令行代理（适用于高级用户）
┌──────────────────────────────────────────────────────────────────┐
│ USER RUNS: python agent.py │
└───────────────────────────┬──────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ INTERACTIVE CHAT SESSION STARTS │
│ │
│ You: What are the top 10 riskiest dependencies? │
└───────────────────────────┬──────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ AGENT SHOWS REASONING (ReAct Pattern) │
│ │
│ 💭 THOUGHT: I should use the analyze_risk_statistics tool... │
│ │
│ 🔧 ACTION: analyze_risk_statistics() │
│ │
│ 📊 OBSERVATION: Retrieved risk data with 47 total deps... │
│ │
│ 💭 THOUGHT: Now I can answer with the top 10 by risk score... │
│ │
│ 🤖 ANSWER: Here are the top 10 riskiest dependencies: │
│ 1. log4j-core 2.14.1 (Risk: 95/100) - 3 CRITICAL CVEs │
│ 2. jackson-databind 2.9.8 (Risk: 87/100) - 2 HIGH CVEs │
│ ... │
└───────────────────────────┬──────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ You: What's the recommended upgrade for log4j-core? │
└───────────────────────────┬──────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ 💭 THOUGHT: I need to query Neo4j for RECOMMENDED_VERSION... │
│ │
│ 🔧 ACTION: read_neo4j_query( │
│ "MATCH (d:Dependency {artifactId: 'log4j-core'}) │
│ -[:RECOMMENDED_VERSION]->(v:ArtifactVersion) │
│ RETURN v.version") │
│ │
│ 📊 OBSERVATION: Found version 2.17.1 │
│ │
│ 🤖 ANSWER: Recommended version for log4j-core: 2.17.1 │
│ This version has no known CVEs and is safe to upgrade to. │
└──────────────────────────────────────────────────────────────────┘
完整的查询过程（幕后）
USER QUESTION AI AGENT MCP TOOLS NEO4J DATABASE
│ │ │ │
│ "Show CVEs in module1" │ │ │
├─────────────────────────────>│ │ │
│ │ │ │
│ │ 💭 Parse question │ │
│ │ 💭 Identify: Need Neo4j │ │
│ │ │ │
│ │ read_neo4j_query() │ │
│ ├─────────────────────────>│ │
│ │ │ │
│ │ │ MATCH (m:Module │
│ │ │ {name:'module1'}) │
│ │ │ -[:USES_DEPENDENCY]-> │
│ │ │ (d)-[:HAS_VULN]->(v) │
│ │ ├────────────────────────>│
│ │ │ │
│ │ │ Execute Cypher │
│ │ │ Return Results │
│ │ │<────────────────────────┤
│ │ │ │
│ │ 📊 Results: 12 CVEs │ │
│ │<─────────────────────────┤ │
│ │ │ │
│ │ 💭 Format answer │ │
│ │ 💭 Add recommendations │ │
│ │ │ │
│ 🤖 "Found 12 CVEs:" │ │ │
│ "1. CVE-2021-44228..." │ │ │
│ "2. CVE-2020-36518..." │ │ │
│<─────────────────────────────┤ │ │
│ │ │ │
📁 项目结构
dependency-remediate-ai-rag/
├── version-scanner-odc/ # OWASP Dependency Check scanner
│ ├── Dockerfile-odc # Scanner container definition
│ ├── version-scanner-odc.py # Main scanner script
│ ├── remediation.py # Version remediation logic
│ ├── get-odc-data.sh # Initialize ODC database
│ ├── build.sh # Build container
│ └── java-project/ # Sample multi-module Java project
│
├── rag_graphdb/ # Neo4j import & tools
│ ├── import_odc_to_neo4j.py # Import ODC reports to Neo4j
│ ├── verify_neo4j.py # Verify Neo4j connection
│ ├── test_tools.py # Test MCP tools
│ ├── requirements.txt # Python dependencies
│ └── .docs/ # Documentation
│ ├── plan1.md # Neo4j schema design
│ └── README.md # Implementation guide
│
├── mcp_agent/ # MCP Server & LLM Agent
│ ├── server.py # MCP tool server (FastMCP)
│ ├── agent.py # LLM agent with MCP client
│ ├── tools.py # Tool implementations
│ ├── dashboard.py # Streamlit web UI
│ ├── streamlit_agent.py # Streamlit chat interface
│ ├── prompt.neo4j.md # Neo4j schema guide for LLM
│ └── requirements.txt # Python dependencies
│
└── README.md # This file
🚀 快速开始
先决条件
- Docker（用于OWASP依赖性检查扫描程序）
- Python 3.9+
- Neo4j 5.0+（本地或远程运行）
- LLM API（OpenAI、Ollama或任何与OpenAI兼容的端点）
1.安装Neo4j
# Using Docker
docker run -d \
--name neo4j \
-p 7474:7474 -p 7687:7687 \
-e NEO4J_AUTH=neo4j/your_password \
neo4j:latest
# Or use Neo4j Desktop, AuraDB, etc.
2.设置环境变量
# Neo4j Configuration
export NEO4J_URI="bolt://localhost:7687"
export NEO4J_USER="neo4j"
export NEO4J_PASSWORD="your_password"
# LLM Configuration (for agent.py)
export LLM_BASE_URL="http://localhost:11434/v1" # Ollama
export LLM_MODEL="qwen3:8b"
# export LLM_API_KEY="sk-xxx" # Only if using OpenAI or similar
3.安装Python依赖项
# Install dependencies for rag_graphdb
cd rag_graphdb
pip install -r requirements.txt
# Install dependencies for mcp_agent
cd ../mcp_agent
pip install -r requirements.txt
4.构建扫描仪容器
cd version-scanner-odc
# Initialize OWASP Dependency Check database
./get-odc-data.sh
# Build container (macOS ARM64)
./build.sh osx
# Or for Linux AMD64
# ./build.sh linux
5.扫描Java项目
cd version-scanner-odc
# Scan the sample project
docker run --rm \
-v "$(pwd):/app" \
-v "$(pwd)/version-scanner-odc.py:/scanner/version-scanner-odc.py" \
-v "$(pwd)/remediation.py:/scanner/remediation.py" \
version-scanner-odc:odc-arm64 \
--target-dir /app/java-project \
--remediation \
--transitive
# This generates:
# - dependency-check-report.json (per module)
# - dependency-graph.dot (dependency tree - includes phantom packages)
# - remediation.json (version upgrade suggestions)
6.将数据导入Neo4j
cd rag_graphdb
# Import all ODC reports from the scanned project
python import_odc_to_neo4j.py \
--target-dir ../version-scanner-odc/java-project \
--project MY_PROJECT
# Verify import
python verify_neo4j.py
7.测试MCP工具
cd rag_graphdb
# Test all tools
python test_tools.py
8.运行LLM代理（交互式聊天）
cd mcp_agent
# Start the agent
python agent.py
# Ask questions like:
# - "What are the top 10 riskiest dependencies?"
# - "Which dependencies have CRITICAL vulnerabilities?"
# - "What is the recommended version for log4j-core?"
9.运行仪表板（Web UI）
cd mcp_agent
# Start Streamlit dashboard
streamlit run dashboard.py
# Open browser at http://localhost:8501
🔧 Neo4j图形模式
该系统基于Plan1.md（方法2）实现了一个全面的图形模式：
节点类型
- 项目：软件项目
- 模块：项目模块（在多模块项目中）
- 依赖：库依赖关系（由SHA256标识）
- 脆弱性：已知CVE
- 工件版本：工件的特定版本
关系
(Project)-[:HAS_MODULE]->(Module)
(Module)-[:USES_DEPENDENCY]->(Dependency)
(Dependency)-[:HAS_VULNERABILITY]->(Vulnerability)
(Dependency)-[:CURRENT_VERSION {project, module}]->(ArtifactVersion)
(Dependency)-[:RECOMMENDED_VERSION {project, module}]->(ArtifactVersion)
(Dependency)-[:AVAILABLE_VERSION {project, module}]->(ArtifactVersion)
(ArtifactVersion)-[:UPGRADES_TO]->(ArtifactVersion)
(Dependency)-[:DEPENDS_ON]->(Dependency)
主要财产
附属国：
sha256：唯一标识符groupId,artifactId,detectedVersion：Maven坐标isDirectDependency：布尔值（来自GraphML分析）hasRemediation：布尔值（可进行安全升级）usedByProjects[]：项目代码数组usedByModules[]：模块名称数组
工件版本：
version：版本字符串（例如“2.17.0”）majorVersion,minorVersion,patchVersion：解析整数hasCVE：布尔值cveCount：CVE数量highSeverityCVECount：高/临界CVE的数量
脆弱性：
name：CVE标识符severity：临界、高、中、低cvssScore：CVSS分数（浮动）description：漏洞描述
🛠️ MCP工具
系统提供以下MCP工具：
1. analyze_risk_statistics()
返回全面的风险分析，包括：
- 项目和模块概述
- 漏洞计数和严重性分布
- 风险评分最高的10个依赖关系
- CVSS统计
2. read_neo4j_query(query: str)
在Neo4j数据库上执行Cypher查询，并自动纠正常见错误。
3. visualize_dependency_graph(limit: int, output_file: str)
生成显示依赖关系及其漏洞的可视化依赖关系图。
4. enrich_cve_data(cve_id: str)
从NVD API获取详细的CVE信息。
5.实用工具
get_current_time(timezone: str)calculate(expression: str)get_weather(city: str)（模拟数据）
📊 查询示例
通过补救措施找到直接依赖关系
MATCH (d:Dependency {isDirectDependency: true, hasRemediation: true})
-[:RECOMMENDED_VERSION]->(rec:ArtifactVersion)
RETURN d.groupId, d.artifactId, d.detectedVersion,
rec.version AS remediationVersion
获取特定依赖项的所有CVE
MATCH (d:Dependency {artifactId: "log4j-core"})
-[:HAS_VULNERABILITY]->(v:Vulnerability)
RETURN v.name, v.severity, v.cvssScore
ORDER BY v.cvssScore DESC
查找升级路径
MATCH path = (cv:ArtifactVersion {version: "2.14.1"})
-[:UPGRADES_TO*]->(rv:ArtifactVersion {version: "2.17.0"})
RETURN path
🤖 LLM代理功能
LLM代理人(agent.py)实施：
- 重演模式：展示推理（思考→ 行动→ 观察）
- 自动校正：修复常见的Cypher语法错误（例如GROUP BY）
- 错误预防：通过强烈警告防止幻觉
- 模式感知：已加载Neo4j模式指南(
prompt.neo4j.md) - 工具链：可以调用多种工具来回答复杂的问题
📈 仪表板功能
Streamlit仪表板(dashboard.py)提供：
- 概述选项卡：漏洞计数和严重性分布
- 风险分析选项卡：完整的风险统计数据和最高风险依赖关系
- 依赖关系图选项卡：可视化图形生成
- CVE查找选项卡：来自NVD的详细CVE信息
- AI聊天选项卡：与LLM客服互动聊天
🧪 测试
# Test Neo4j connection
cd rag_graphdb
python verify_neo4j.py
# Test all MCP tools
python test_tools.py
# Test specific query
python -c "
import sys
sys.path.insert(0, '../mcp_agent')
from tools import read_neo4j_query
print(read_neo4j_query('MATCH (v:Vulnerability) RETURN count(v)'))
"
📚 文档
rag_graphdb/.docs/plan1.md：Neo4j模式设计和原理rag_graphdb/.docs/README.md：实施指南mcp_agent/prompt.neo4j.md：LLM的Neo4j模式指南version-scanner-odc/README.md：扫描仪使用指南
🔐 安全须知
- 安全地存储Neo4j凭据（使用
.env文件） - 不要将API密钥提交到版本控制
- 申请前审查补救建议
- 首先在临时环境中测试升级
🤝 贡献
欢迎投稿！拜托：
- 分叉存储库
- 创建要素分支
- 进行更改
- 如果适用，添加测试
- 提交拉取请求
📝 许可证
有关详细信息，请参阅LICENSE文件。
🙏 致谢
- OWASP依赖性检查项目
- Neo4j图形数据库
- FastMCP框架
- Streamlit框架
- 模型上下文协议（MCP）规范
📞 支持
对于问题和疑问：
- 在GitHub上打开一个问题
- 检查中的现有文档
.docs/文件夹 - 查看中的示例查询
prompt.neo4j.md
备注：这是一个积极的发展项目。功能和API可能会发生变化。
