---
openproject: 362
base-branch: dev
---
# Task: Security Hardening - Address ReDoS, Path Traversal, and SSRF Vulnerabilities

## Related Documents
- OpenProject: [#362](https://pm.hyperlocalplatform.com/work_packages/362)
- Branch: `feature/362-security-hardening` (from `dev`)

## Priority
HIGH

## Objective
Address pre-existing security vulnerabilities identified in the security audit: ReDoS in pathPattern regex, path traversal in file system access, and SSRF in unrestricted URL fetching. These issues pose risks to users of the MCP server.

## Definition of Done
- [x] ReDoS vulnerability mitigated with regex timeout/complexity limits
- [x] Path traversal prevented with path validation
- [x] SSRF mitigated with URL allowlist/blocklist support
- [x] TypeScript compilation CLEAN
- [x] Lint checks PASSED (no lint script configured)
- [x] ALL tests passing (33 security tests)
- [x] Manual verification completed
- [x] PROOF PROVIDED (security test cases)

## Scope
### IN SCOPE
- ReDoS mitigation in `src/tools/query.ts` pathPattern handling
- Path traversal prevention in `src/lib/parser.ts` file access
- SSRF mitigation in URL fetching (remote spec loading)
- Input validation utilities
- Security-focused test cases

### OUT OF SCOPE
- Authentication/authorization (MCP server runs locally)
- Encryption at rest
- Rate limiting (single-user CLI tool)
- Audit logging

## Sub-Tasks

### Phase 1: ReDoS Mitigation
#### 1.1 Add Regex Complexity Limits
- **Details**: Implement regex validation before creating RegExp from user input. Either use a safe-regex library or implement timeout-based execution.
- **Files**: `src/tools/query.ts`
- **Testing**: Test with known ReDoS patterns (e.g., `(a+)+$` against `aaaaaaaaaaaaaaaaaaaaaaaaaaaa!`)

#### 1.2 Create Input Validation Utilities
- **Details**: Create `src/lib/input-validation.ts` with reusable validation functions for regex patterns, file paths, and URLs.
- **Files**: `src/lib/input-validation.ts` (new)
- **Testing**: Unit tests for validation functions

### Phase 2: Path Traversal Prevention
#### 2.1 Implement Path Validation
- **Details**: Validate file paths to prevent directory traversal attacks (e.g., `../../../etc/passwd`). Resolve paths and ensure they don't escape intended directories.
- **Files**: `src/lib/parser.ts`, `src/lib/input-validation.ts`
- **Testing**: Test with path traversal payloads

#### 2.2 Add Configurable Base Directory (Optional)
- **Details**: Allow configuration of allowed directories for spec file access. Default to current working directory.
- **Files**: `src/lib/parser.ts`, `src/lib/input-validation.ts`
- **Testing**: Test directory restrictions

### Phase 3: SSRF Mitigation
#### 3.1 Implement URL Validation
- **Details**: Validate URLs before fetching. Block internal/private IP ranges (10.x, 172.16-31.x, 192.168.x, localhost, 127.x). Consider allowlist for known spec hosts.
- **Files**: `src/lib/parser.ts`, `src/lib/input-validation.ts`
- **Testing**: Test with internal IP addresses and localhost URLs

#### 3.2 Add URL Protocol Restrictions
- **Details**: Only allow `http://` and `https://` protocols. Block `file://`, `ftp://`, `data:`, etc.
- **Files**: `src/lib/input-validation.ts`
- **Testing**: Test with various URL protocols

## Files to Modify
- `src/tools/query.ts`: Add regex validation before `new RegExp()`
- `src/lib/parser.ts`: Add path and URL validation before spec loading
- `src/lib/input-validation.ts` (new): Centralized input validation utilities
- `src/lib/types.ts`: Add configuration types if needed

## Risks & Mitigations
| Risk | Impact | Mitigation |
|------|--------|------------|
| Breaking legitimate regex patterns | MEDIUM | Test common valid patterns, provide clear error messages |
| Blocking valid internal specs | MEDIUM | Make SSRF protection configurable, document bypass options |
| Performance impact from validation | LOW | Keep validation lightweight, cache validation results |
| Incomplete protection | HIGH | Follow OWASP guidelines, test with known attack payloads |

## Testing Strategy
- Build: `npm run build` - must pass
- Lint: `npm run lint` - must pass
- Manual testing with attack payloads:
  - ReDoS: `(a+)+$`, `([a-zA-Z]+)*$` against long strings
  - Path traversal: `../../../etc/passwd`, `....//....//etc/passwd`
  - SSRF: `http://127.0.0.1/`, `http://localhost/`, `http://10.0.0.1/`
- Verify legitimate use cases still work:
  - Local spec files (relative and absolute paths)
  - Remote HTTPS specs (public APIs)
  - Common regex patterns for path filtering

## Implementation Notes

### ReDoS Approach Options
1. **safe-regex library**: Detect dangerous patterns before execution
2. **Regex timeout**: Use `vm.runInNewContext` with timeout (complex)
3. **Pattern restrictions**: Limit regex features (simpler but restrictive)

Recommended: Start with pattern validation + timeout fallback.

### Path Traversal Approach
Use `path.resolve()` and verify the resolved path starts with the allowed base directory:
```typescript
const resolved = path.resolve(basePath, userPath);
if (!resolved.startsWith(basePath)) {
  throw new Error('Path traversal detected');
}
```

### SSRF Approach
1. Parse URL with `new URL()`
2. Check protocol (allow only http/https)
3. Resolve hostname to IP
4. Check IP against private ranges blocklist
5. Consider DNS rebinding protection (optional, advanced)

## References
- OWASP ReDoS: https://owasp.org/www-community/attacks/Regular_expression_Denial_of_Service_-_ReDoS
- OWASP Path Traversal: https://owasp.org/www-community/attacks/Path_Traversal
- OWASP SSRF: https://owasp.org/www-community/attacks/Server_Side_Request_Forgery