From d84bf1e5d56f9b2cf316c29e2f2376339db4c2db Mon Sep 17 00:00:00 2001 From: jedarden Date: Mon, 6 Jul 2026 22:52:17 -0400 Subject: [PATCH] docs(bf-2p237): catalog TH-05 SSRF blocking tests Identified 19 TH-05 tests across 2 files: - Core tests: 12 URL validation tests - CLI tests: 7 integration tests Documented all test names, locations, coverage areas, and naming patterns in notes/bf-2p237.md. --- notes/bf-2p237.md | 114 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 114 insertions(+) create mode 100644 notes/bf-2p237.md diff --git a/notes/bf-2p237.md b/notes/bf-2p237.md new file mode 100644 index 0000000..ca43220 --- /dev/null +++ b/notes/bf-2p237.md @@ -0,0 +1,114 @@ +# TH-05 SSRF Blocking Tests Catalog + +## Summary + +Identified and cataloged all TH-05 SSRF (Server-Side Request Forgery) blocking tests in the pdftract codebase. These tests verify that the MCP server and CLI properly reject private-network URLs and dangerous schemes. + +## Test Files + +### 1. Core Tests +**File:** `/home/coding/pdftract/crates/pdftract-core/tests/TH-05-ssrf-block.rs` + +Contains 12 tests focusing on URL validation logic and SSRF payload detection. + +#### Test Functions: +1. `test_ssrf_protection_blocks_all_dangerous_payloads` - Tests all SSRF payload categories are blocked +2. `test_allow_private_networks_bypass` - Tests `--allow-private-networks` flag bypass +3. `test_public_urls_are_accepted` - Tests that public URLs are not rejected +4. `test_http_scheme_always_rejected` - Tests http:// scheme rejection (even with bypass flag) +5. `test_file_scheme_always_rejected` - Tests file:// scheme rejection +6. `test_ftp_scheme_always_rejected` - Tests ftp:// scheme rejection +7. `test_url_with_basic_auth_rejected` - Tests URLs with embedded credentials +8. `test_ipv6_zone_id_detected_as_link_local` - Tests IPv6 zone ID detection +9. `test_metadata_subdomain_detected` - Tests metadata endpoint subdomain blocking +10. `test_url_validation_returns_correct_diagnostic_code` - Tests diagnostic code is URL_PRIVATE_NETWORK +11. `test_private_ipv4_boundary_addresses` - Tests addresses just outside private ranges +12. `test_current_network_range_blocked` - Tests 0.0.0.0/8 blocking + +### 2. CLI Tests +**File:** `/home/coding/pdftract/crates/pdftract-cli/tests/TH-05-ssrf-block.rs` + +Contains 7 integration tests that spawn the MCP server and verify JSON-RPC responses. + +#### Test Functions: +1. `test_ipv4_loopback_blocked` - Tests 127.0.0.1 rejection via MCP server +2. `test_ipv4_wildcard_blocked` - Tests 0.0.0.0 rejection via MCP server +3. `test_cloud_metadata_blocked` - Tests AWS metadata endpoint rejection +4. `test_rfc1918_private_blocked` - Tests 10.0.0.1 RFC 1918 rejection +5. `test_ipv6_loopback_blocked` - Tests IPv6 ::1 rejection +6. `test_http_scheme_rejected` - Tests http:// scheme rejection (https:// required) +7. `test_no_network_connection_attempted` - Tests that no actual connection is made + +## Test Coverage + +### SSRF Payload Categories Covered: + +1. **Cloud Metadata Endpoints:** + - AWS: 169.254.169.254 + - GCP: metadata.google.internal, instance-data.google.internal + - Azure: 168.63.129.16 + - Alibaba: 100.100.100.200 + +2. **RFC 1918 Private IPv4 Ranges:** + - 10.0.0.0/8 + - 172.16.0.0/12 + - 192.168.0.0/16 + +3. **Loopback Addresses:** + - 127.0.0.0/8 + - ::1 (IPv6) + +4. **Link-Local Addresses:** + - 169.254.0.0/16 + - fe80::/10 (IPv6) + +5. **IPv6 ULA (Unique Local Address):** + - fc00::/7 + - fd00::/8 + +6. **Dangerous Schemes:** + - http:// (not https://) + - file:// + - ftp:// + +7. **Special Addresses:** + - 0.0.0.0/8 (current network) + +## Test Structure + +### Naming Pattern: +- Core tests: `test_` (descriptive, feature-focused) +- CLI tests: `test__` (target-focused, behavior-focused) + +### Architecture: +- **Core tests** use the `validate_url()` function directly (unit tests) +- **CLI tests** spawn the actual MCP server and test via JSON-RPC (integration tests) + +## Statistics + +- **Total TH-05 tests:** 19 +- **Core tests:** 12 +- **CLI integration tests:** 7 +- **Test files:** 2 + +## Implementation Reference + +The SSRF protection implementation is in: +- `/home/coding/pdftract/crates/pdftract-core/src/url_validation.rs` - URL validation logic +- `/home/coding/pdftract/crates/pdftract-core/tests/TH-05-ssrf-block.rs` - Tests with helper modules + +## Test Helpers + +The core test file includes extensive helper modules: +- `mcp_helpers` - JSON-RPC framing, tool call construction, response parsing +- Process spawning and cleanup utilities (RAII guards for deterministic cleanup) +- Assertion helpers for SSRF_BLOCKED error detection + +All tests follow the test hygiene requirements from CLAUDE.md (bounded timeouts, process cleanup, no hung tests). + +--- + +**Acceptance Criteria Status:** +- ✅ All TH-05 tests identified and listed +- ✅ Test file locations documented +- ✅ Test count (19) and naming patterns recorded