Content
# JavaSinkTracer_MCP
JavaSinkTracer is a Java source code vulnerability auditing tool based on function-level taint analysis, providing security analysis capabilities for AI assistants through the Model Context Protocol (MCP) Server.
## Quick Start
### 1. Install Dependencies
```bash
pip install -r requirements.txt
```
### 2. Configure Claude Desktop
Edit the configuration file and add the MCP server configuration:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"javasinktracer": {
"command": "python",
"args": [
"/path/to/JavaSinkTracer/mcp_server.py"
],
"description": "Java source code vulnerability auditing tool - based on function-level taint analysis"
}
}
}
```
**Note**: Replace `/path/to/JavaSinkTracer` with the actual project path.
### 3. Restart Claude Desktop
After configuration, restart Claude Desktop, and the MCP tool will be loaded automatically.
## Video Demonstration
https://www.bilibili.com/video/BV1XrxDz1EvF
## Core Features
### Vulnerability Scanning
Track back from dangerous functions (Sink) to external entry points (Source), automatically discovering potential security vulnerability chains.
### Call Graph Analysis
Build a complete Java project function call relationship graph, supporting cross-file and cross-class call tracking.
### Intelligent Analysis
Based on function-level taint analysis, effectively avoid variable-level tracking breakage in complex scenarios (threads, reflections, callbacks).
### Code Extraction
Automatically extract the complete source code of each function on the vulnerability chain for in-depth analysis by humans or AI.
## Available Tools
| Tool Name | Function Description |
|---------|---------|
| `build_callgraph` | Build project call relationship graph |
| `find_vulnerabilities` | Scan security vulnerabilities |
| `analyze_vulnerability_chain` | Analyze vulnerability call chain source code |
| `extract_method_code` | Extract specified method source code |
| `list_sink_rules` | View vulnerability rule configuration |
| `get_project_statistics` | Get project statistics |
## Usage Examples
### Example 1: Comprehensive Vulnerability Scanning
```
Please help me scan the /path/to/java-project project for security vulnerabilities.
```
AI will automatically:
1. Build the call relationship graph
2. Scan all types of vulnerabilities
3. Analyze and report found issues
### Example 2: Targeted Detection
```
Check if there are SQL injection and command execution vulnerabilities in the project.
```
AI will scan specific types of vulnerabilities (SQLI, RCE).
### Example 3: In-Depth Analysis
```
Is this vulnerability chain real? Please analyze the call chain's source code.
```
AI will extract the complete call chain code and analyze it.
## Supported Vulnerability Types
- **RCE** - Remote Code Execution (CWE-78)
- **SQLI** - SQL Injection (CWE-89)
- **XXE** - XML External Entity Injection (CWE-611)
- **SSRF** - Server-Side Request Forgery (CWE-918)
- **PATH_TRAVERSAL** - Path Traversal (CWE-22)
- **DESERIALIZE** - Deserialization Vulnerability (CWE-502)
- **XPATH_INJECTION** - XPath Injection (CWE-643)
- **TEMPLATE_INJECTION** - Template Injection (CWE-94)
- **JNDI_INJECTION** - JNDI Injection (CWE-74)
- **REFLECTION_INJECTION** - Reflection Injection (CWE-470)
- **LOG_INJECTION** - Log Injection (CWE-117)
- **CRYPTO_WEAKNESS** - Cryptographic Weakness (CWE-327)
## Supported Frameworks
- Spring Boot / Spring MVC
- MyBatis / Hibernate / JPA
- Fastjson / Jackson / Gson
- OkHttp / Apache HttpClient
- Freemarker / Velocity / Thymeleaf
- Log4j / SLF4J
## Working Principle
### Function-Level Taint Analysis
Unlike traditional SAST tools' "variable-level" taint analysis, this tool adopts "function-level" taint analysis:
- **Advantages**: Effectively avoid breakage in complex scenarios (threads, reflections, callbacks)
- **Trade-offs**: May produce false positives, requiring further analysis and confirmation by AI or humans
### Analysis Process
1. Parse Java source code, build AST
2. Extract all class and method information
3. Build function call relationship graph
4. Track back from Sink points (dangerous functions)
5. Identify call chains reaching Source points (external entry points)
6. Filter functions without parameters (exclude uncontrollable variables)
7. Extract source code of all functions on the call chain
## Configuration Description
### Rule Files
Rule configuration files are located in `Rules/rules.json`, including:
- **sink_rules**: Dangerous function rules (e.g., `Runtime.exec`)
- **source_rules**: External input source rules (e.g., `HttpServletRequest.getParameter`)
- **sanitizer_rules**: Sanitization function rules (e.g., `StringEscapeUtils.escapeHtml`)
### Custom Rules
You can edit `rules.json` to add new Sink, Source, or Sanitizer rules:
```json
{
"sink_rules": [
{
"sink_name": "CUSTOM_VULN",
"sink_desc": "Custom vulnerability type",
"severity_level": "High",
"cwe": "CWE-XXX",
"sinks": [
"com.example.DangerousClass:dangerousMethod"
]
}
]
}
```
## Performance Optimization
### Cache Mechanism
- Build AST and call graph during the first project analysis
- Reuse cache for subsequent calls, significantly improving speed
- Cache key: `project_path:rules_path`
### Lightweight Mode
`find_vulnerabilities` tool uses lightweight mode by default:
- Only returns vulnerability chain information
- Does not extract source code immediately
- Use `analyze_vulnerability_chain` to get detailed code when needed
## Frequently Asked Questions
### Tool Not Loaded?
1. Check if the configuration file path is correct
2. Confirm all Python dependencies are installed
3. View Claude Desktop developer tool logs
### Analysis Speed Slow?
- Large projects require time to build AST during the first analysis
- Speed significantly improves after cache is used
- You can call `build_callgraph` to preheat the cache
### False Positives?
- Function-level taint analysis may produce false positives
- Use `analyze_vulnerability_chain` to view source code
- Combine AI analysis or human confirmation for vulnerability authenticity
## Extension Development
### Add New MCP Tools
Edit `mcp_server.py`:
```python
@app.list_tools()
async def list_tools() -> list[Tool]:
return [
Tool(
name="your_tool",
description="Tool description",
inputSchema={...}
)
]
@app.call_tool()
async def call_tool(name: str, arguments: Any):
if name == "your_tool":
# Implement your tool logic
pass
```
## Related Resources
- **Detailed Usage Guide**: View `MCP_GUIDE.md`
- **Principle Description**: View `README.md`
- **Upgrade Log**: View `UPGRADE_SUMMARY.md`
## Acknowledgements
JavaSinkTracer developer [Tr0e](https://github.com/Tr0e)
## Statement
This project is for learning and research purposes only. Please do not use it for commercial or illegal purposes. Any consequences arising from the use of this project are borne by the user.
