java-file-upload-audit

Java File Upload Vulnerability Audit Tool

Inspect Java Web project source code, identify file upload implementations, and detect upload-related vulnerabilities (arbitrary file upload, path traversal, file overwrite, executable in web root, etc.).

Core Requirements

This skill must fully analyze all upload-related code; omissions are not allowed.

• ✅ Identify all upload entry points (ServletFileUpload / MultipartFile / transferTo / FileItem)
• ✅ Annotate the save path, filename source, and validation strategy of each upload point
• ✅ Detect all potential upload vulnerability patterns (missing type validation, path traversal, web root write, file overwrite)
• ✅ When source code is unavailable, decompilation is mandatory, and output a decompiled file list (filename + location)
• ❌ Omitting any upload entry point is prohibited
• ❌ Skipping the decompilation step is prohibited

---

Vulnerability Severity Classification Standard

See SEVERITY_RATING.md

• Vulnerability ID format: {C/H/M/L}-UPLOAD-{序号}
• Severity level = f(reachability R, impact scope I, exploitation complexity C)
• Score = R × 0.40 + I × 0.35 + C × 0.25, mapped to CVSS 3.1

Prefix	CVSS 3.1	Meaning
🔴 C	9.0-10.0	Can directly lead to system compromise
🟠 H	7.0-8.9	Can cause major damage
🟡 M	4.0-6.9	Can cause certain damage
🔵 L	0.1-3.9	Security hardening item

---

Skill Collaboration Workflow (CRITICAL)

java-file-upload-audit must be executed after java-route-mapper, conducting the audit based on the already-organized route information.

┌─────────────────────────────────────────────────────────────────┐
│                    完整审计流程                                  │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  [步骤1] java-route-mapper                                      │
│     │                                                           │
│     │ 输出：                                                    │
│     │ ├─ 所有 HTTP 路由列表                                     │
│     │ ├─ 每个路由的参数定义                                     │
│     │ │   ├─ 参数名、类型                                       │
│     │ │   └─ JSON 内部字段                                      │
│     │ └─ Burp Suite 请求模板                                    │
│     │                                                           │
│     ↓                                                           │
│  [步骤2] java-file-upload-audit（本技能）                       │
│     │                                                           │
│     │ 输入：java-route-mapper 的输出                            │
│     │                                                           │
│     │ 执行：                                                    │
│     │ ├─ 快速扫描上传实现                                       │
│     │ ├─ 参数-上传映射分析                                      │
│     │ ├─ 校验逻辑与保存路径分析                                 │
│     │ └─ 执行条件分析                                           │
│     │                                                           │
│     ├─── 需要深入追踪 ───→ java-route-tracer                    │
│     │                           │                               │
│     │    ←── 返回调用链信息 ────┘                               │
│     │                                                           │
│     ↓                                                           │
│  [步骤3] 输出综合审计报告                                       │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Input Dependencies (from java-route-mapper)

Before starting the audit, you must first check whether the output file of java-route-mapper already exists:

{project_name}_audit/
├── route_mapper/
│   ├── {project_name}_route_mapper_{timestamp}.md    ← 主索引（先读此文件定位模块详情）
│   ├── {module_name}/
│   │   └── {project_name}_module_{module_name}_{timestamp}.md  ← 模块详情
│   └── webservice/
│       └── {project_name}_ws_{service_name}_{timestamp}.md
└── file_upload_audit/
    └── {project_name}_file_upload_audit_{timestamp}.md  ← 本技能输出

If the route_mapper output does not exist, it is recommended to run first:

Skill(skill="java-route-mapper", args="--project {project_path}")

Key Information Obtained from route_mapper

Information	Purpose
Route path	Locate upload Controller/Servlet entry points
Parameter name + type	Identify MultipartFile / FileItem / fileName parameters
JSON internal fields	Identify nested upload parameters
Parameter purpose description	Determine whether it is used for filename or save path

---

Workflow (Three Phases)

Phase 1: Quick Scan (Execute First)

Goal: Quickly locate upload-related code without missing key points.

# 1.1 Servlet/Commons FileUpload
rg -n "ServletFileUpload|DiskFileItemFactory|FileItem|isMultipartContent" --glob="*.java"

# 1.2 Spring Boot MultipartFile
rg -n "MultipartFile|@RequestParam\\(\"file\"\\)|transferTo\\(" --glob="*.java"

# 1.3 文件名/路径相关
rg -n "getOriginalFilename|getName\\(\\)|getRealPath\\(\"/uploads\"\\)|uploadDir" --glob="*.java"
rg -n "new File\\(|Paths\\.get\\(|Path\\.of\\(|File\\.separator" --glob="*.java"

# 1.4 上传接口路由
rg -n "@PostMapping\\(|@RequestMapping\\(.*upload|/upload" --glob="*.java"

Output: High-risk file list (sorted by priority)

Priority	File Type	Audit Focus
P0	*Controller.java / *Servlet.java contains upload logic	MultipartFile/FileItem
P1	*Service.java, *ServiceImpl.java	File save path/rename
P2	*Util.java, *Storage.java, *File*.java	General storage encapsulation
P3	*Config.java, application.yml	File size/directory configuration

Phase 2: Parameter-Upload Mapping Analysis

Based on route_mapper output, check whether each upload parameter affects the filename or save path.

2.1 High-Risk Parameter Identification

Parameter Source	Parameter Name	Type	Vulnerability Severity
@RequestParam	file	MultipartFile	High - Direct upload
FileItem	item	FileItem	High - fileName controllable
@RequestParam	fileName	String	High - Filename concatenation
JSON	upload.path	String	High - Directory concatenation

2.2 Parameter Tracing (Example)

HTTP 参数: file (MultipartFile)
    ↓
Controller.handleFileUpload(file)
    ↓
file.getOriginalFilename()  ← 文件名来源
    ↓
Paths.get(uploadDir).resolve(fileName)
    ↓
file.transferTo(filePath)   ← 上传写入点

2.3 Upload Point Inspection

For each upload write point, check:

1. Is the filename source controllable?

   • getOriginalFilename() / item.getName() → High
   • Server generates random name → Low

2. Is there path normalization and directory restriction?

   • getCanonicalPath() + Fixed upload directory → Relatively safe
   • Direct path concatenation → High

3. Is type/content validation performed?

   • Whitelist extension/Content-Type/magic number validation → Safe
   • Only checks non-empty or no validation → High

4. Is the upload directory in the Web root directory?

   • getRealPath("/uploads") / /uploads/ → High
   • Non-Web accessible directory → Relatively safe

Phase 3: In-depth Inspection and Reporting

When the upload logic is complex or parameters are passed through multiple layers, call java-route-tracer to obtain the complete call chain and supplement the validation path analysis.

---

Upload Implementation Identification (Key Points from Notion Materials)

1) Servlet/Commons FileUpload

Identification features:

• ServletFileUpload.isMultipartContent(request)
• DiskFileItemFactory / ServletFileUpload
• upload.parseRequest(request) → List<FileItem>
• item.getName() as filename
• item.write(storeFile) write file
• getServletContext().getRealPath("/uploads") as save directory

Notion record key points:

• The example does not validate the form field name,name="file" will not be validated。
• Only a size upper limit is set (e.g., upload.setSizeMax(5MB)), no extension/type/path validation is seen.

2) Spring Boot MultipartFile

Identification features:

• @RequestParam("file") MultipartFile file
• file.getOriginalFilename()
• file.transferTo(filePath)
• Fixed upload directory uploadDir = "/uploads/"

Notion record key points:

• @RequestParam("file") will validate the form field name, requires name="file"。
• The example shows no filename sanitization, type whitelist, or directory isolation.

For detailed detection rules, see UPLOAD_RULES.md

---

Decompilation Phase (CRITICAL)

When source code is unavailable, CFR decompiler must be used to decompile upload-related classes (see java-shared/DECOMPILE_STRATEGY.md）。

Decompilation Tool Invocation

# 反编译单个上传相关类
java -jar {CFR_JAR} /path/to/UploadController.class --outputdir {output_path}/decompiled

# 反编译上传相关目录
find /path/to/WEB-INF/classes/com/example/upload -name "*.class" | xargs java -jar {CFR_JAR} --outputdir {output_path}/decompiled

# 反编译多个指定文件
java -jar {CFR_JAR} /path/to/UploadController.class /path/to/FileStorageService.class /path/to/UploadUtil.class --outputdir {output_path}/decompiled

Classes that must be decompiled

Type	Match Pattern	Purpose
Controller/Servlet	*Upload*Controller.class, *Servlet.class	Extract upload entry point
Service/Storage	*Storage*.class, *FileService*.class	Trace save path
Utility class	*UploadUtil*.class, *FileUtil*.class	Find common validation
Configuration class	*Config*.class	Obtain upload directory/size limit

Decompilation output requirements:

• Output a "decompiled file list", including original filenames and decompiled output paths
• Decompiled file paths must be locatable to specific directories

---

Execution Condition Analysis (CRITICAL - Avoid False Positives)

After discovering upload logic, must check whether the logic will actually be executed!

Check Item	Description	Impact
Permission validation	Only administrators can access	Affects exploitability
Parameter validation	Field name/type/size validation	Reduces vulnerability exploitability
Directory restriction	Fixed upload directory	Reduce path traversal
Accessibility	Whether the upload directory is web-accessible	Determine whether it is executable

Conclusion grading must be annotated: ✅ Confirmed exploitable / ⚠️ To be verified / ❌ Not exploitable / 🔍 Environment-dependent

---

Report generation

Output a single comprehensive audit report file:

{project_name}_audit/file_upload_audit/
└── {route_name}/
    └── {project_name}_file_upload_audit_{timestamp}.md

Route name description:

• The route name is extracted from the route path, removing the leading slash and special characters
• For example:/api/file/upload → api_file_upload

---

Output format

Strictly follow the references/OUTPUT_TEMPLATE.md fill-in template in to generate the output file.

• Filename format: {project_name}_file_upload_audit_{YYYYMMDD_HHMMSS}.md
• Do not modify the template structure, do not add or remove sections, do not adjust the order
• All [Fill in] placeholders must be replaced with actual content
• General specification reference: java-shared/OUTPUT_STANDARD.md
• Vulnerability aggregation rule reference: java-shared/VULNERABILITY_GROUPING.md, multiple entry points with the same root cause are merged into one vulnerability ID and the "affected entry points" are listed, while entry points with different conditions are split.

---

Audit checklist (to prevent omissions)

Code analysis check

• All upload entry points have been analyzed (Servlet/MultipartFile)
• Each upload point is annotated with the filename source and save path
• Directory and access control have been analyzed

Decompilation check

• Decompilation has been performed when source code is unavailable
• The decompiled file list has been output (filename + location)

Report completeness check

• The comprehensive audit report has been generated and passes the self-check list at the end of OUTPUT_TEMPLATE.md

---

Reference materials

• OUTPUT_TEMPLATE.md - Output report fill-in template
• UPLOAD_RULES.md - Upload implementation identification and risk rules