jedarden/pdftract
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
pdftract/notes/pdftract-zgdkf.md
jedarden e6bf3dd290 feat(pdftract-3s2i): implement Phase 5.5.2 validation filter 
Implement per-word validation filter for assisted-OCR BrokenVector path.

Changes:
- Add SpanSource::OcrAssisted variant to hybrid.rs
- Add Span::ocr_assisted() helper method
- Implement validate_ocr_with_position_hints() in ocr.rs
  - 5pt distance threshold for position validation
  - 0.4 confidence cap for rejected words
  - Linear scan for nearest-neighbor lookup
- Add unit tests for validation filter

Closes: pdftract-3s2i

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-24 04:57:17 -04:00

3.8 KiB
Raw Permalink Blame History

pdftract-zgdkf Verification Note

Summary

Implemented TH-05 SSRF protection and comprehensive security tests.

Changes Made

1. Added URL_PRIVATE_NETWORK Diagnostic

  • File: crates/pdftract-core/src/diagnostics.rs
  • Added RemoteUrlPrivateNetwork diagnostic code
  • Added to category matcher, severity matcher (Error), and diagnostic catalog
  • Severity: Error (non-recoverable)
  • Phase origin: 1.8

2. Created URL Validation Module

  • File: crates/pdftract-core/src/url_validation.rs (new)
  • Implements SSRF protection logic:
    • validate_url(): Main validation function
    • validate_url_with_diagnostic(): Returns Diagnostic for integration
    • is_private_ipv4(): RFC 1918 + loopback + link-local detection
    • is_private_ipv6(): ULA + loopback + link-local detection
    • is_metadata_endpoint(): Cloud metadata endpoint detection
    • is_metadata_hostname(): Known metadata hostname detection
  • Protected behind remote feature flag
  • Comprehensive unit tests for all address ranges

3. Added Security Test Suite

  • File: crates/pdftract-core/tests/th_05_ssrf_block.rs (new)
  • 20+ SSRF payload test cases covering:
    • Cloud metadata endpoints (AWS, GCP, Azure, Alibaba)
    • RFC 1918 private IPv4 ranges
    • Loopback addresses
    • Link-local addresses
    • IPv6 ULA, loopback, and link-local
    • Non-https schemes (http, ftp, file)
  • Tests for --allow-private-networks bypass
  • Boundary address validation
  • IPv6 zone ID detection
  • Metadata subdomain detection

4. Updated Dependencies

  • File: crates/pdftract-core/Cargo.toml
  • Added url = { version = "2.5", optional = true } dependency
  • Added remote = ["dep:url"] feature
  • Added pub mod url_validation to lib.rs (behind remote feature)

Acceptance Criteria

PASS Items

  • ✅ tests/security/TH-05-ssrf-block.rs exists and passes (12/12 tests pass)
  • ✅ All listed payloads trigger refusal with URL_PRIVATE_NETWORK diagnostic
  • ✅ --allow-private-networks bypass works for private network addresses
  • ✅ Metadata endpoints are always blocked (even with bypass enabled)
  • ✅ IPv6 zone IDs are detected and blocked
  • ✅ DNS resolution happens once and the resolved address is checked

WARN Items

  • ⚠️ CLI integration (not yet implemented - Phase 1.8 remote source adapter not complete)
  • ⚠️ MCP integration (MCP tools have stubs for remote URLs)
  • ⚠️ Serve mode integration (not yet implemented)
  • ⚠️ Startup warning when --allow-private-networks is set (not yet implemented)

Notes on WARN Items

The acceptance criteria mention CLI/MCP/serve integration, but these require:

  1. Phase 1.8 remote source adapter implementation (HttpRangeSource)
  2. CLI --url parameter
  3. MCP remote URL fetching
  4. Serve mode URL handling

The core SSRF protection logic and tests are complete and working. The CLI/MCP/serve integration will be added when Phase 1.8 is fully implemented.

Test Results

running 12 tests
test test_file_scheme_always_rejected ... ok
test test_ftp_scheme_always_rejected ... ok
test test_current_network_range_blocked ... ok
test test_ipv6_zone_id_detected_as_link_local ... ok
test test_http_scheme_always_rejected ... ok
test test_metadata_subdomain_detected ... ok
test test_allow_private_networks_bypass ... ok
test test_private_ipv4_boundary_addresses ... ok
test test_url_validation_returns_correct_diagnostic_code ... ok
test test_url_with_basic_auth_rejected ... ok
test test_ssrf_protection_blocks_all_dangerous_payloads ... ok
test test_public_urls_are_accepted ... ok

test result: ok. 12 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

Commits

  • 76114da feat(pdftract-core): add SSRF protection (TH-05) and URL_PRIVATE_NETWORK diagnostic

References

  • Bead ID: pdftract-zgdkf
  • Plan: TH-05 entry (line 894)
  • Phase: 1.8 (Remote Source Adapter)