Swagger Parser

The PermittedUrlsChecker is designed to protect against Server-Side Request Forgery (SSRF) and DNS rebinding attacks by verifying that a URL's hostname does not resolve to a private or restricted IPv4/IPv6 address range.

When you call verify(String url), the library performs these steps:

1. Extracts the hostname from the provided URL.
2. Resolves the hostname to an IP address.
3. Validates the IP against restricted ranges (throwing an exception if it matches a restricted range and is not allowlisted).
4. Returns a ResolvedUrl object containing:
   • url: The original URL, but with the hostname replaced by the resolved IP address.
   • hostHeader: The original hostname, intended to be used as a Host header in subsequent requests.

Customization:

• Allowlist: Entries in the allowlist permit a URL to pass even if its IP resolves to a private/restricted range.
• Denylist: Entries in the denylist will cause a HostDeniedException even if the URL resolves to a public IP address.

// Conceptual usage of the verification flow
ResolvedUrl resolvedUrl = checker.verify("https://github.com/swagger-api/swagger-parser");
// resolvedUrl.getUrl() will contain the IP-based URL
// resolvedUrl.getHostHeader() will contain "github.com"

The ParseOptions class allows you to customize how the parser handles references and schema structures.

Key options include:

• setResolve(boolean): Resolves remote or relative references and adds them to the local components section.
• setResolveFully(boolean): (Requires resolve to be true) Removes all local references by replacing them with the actual content of the referenced element.
• setFlatten(boolean): Moves inline schemas into the components/schemas section and replaces them with references.
• setResolveCombinators(boolean): (Requires resolveFully to be true) Controls how allOf/anyOf/oneOf are processed. If true (default), it merges properties into a single schema. If false, it maintains the composed structure.
• setExplicitObjectSchema(boolean): (Requires resolveFully to be true) If true (default), properties without a defined type are assigned the type object. If false, they remain undefined.

Use the PermittedUrlsChecker to validate URLs against private IP ranges and custom allow/deny lists. This is useful when handling user-submitted URLs that your service needs to fetch.

Key Classes:

• io.swagger.v3.parser.urlresolver.PermittedUrlsChecker: The main engine for verification.
• io.swagger.v3.parser.urlresolver.models.ResolvedUrl: The result object containing the IP-replaced URL and the original host header.
• io.swagger.v3.parser.urlresolver.exceptions.HostDeniedException: The exception thrown when a URL is deemed unsafe.

import io.swagger.v3.parser.urlresolver.PermittedUrlsChecker;
import io.swagger.v3.parser.urlresolver.exceptions.HostDeniedException;
import io.swagger.v3.parser.urlresolver.models.ResolvedUrl;

import java.util.List;

public class Main {
    public static void main(String[] args) {
        List<String> allowlist = List.of("mysite.local");
        List<String> denylist = List.of("*.example.com:443");
        var checker = new PermittedUrlsChecker(allowlist, denylist);

        try {
            // 1. Fails: localhost resolves to local IP and is not in allowlist
            // checker.verify("http://localhost/example");

            // 2. Succeeds: github.com resolves to a public IP
            // checker.verify("https://github.com/swagger-api/swagger-parser");

            // 3. Fails: *.example.com is explicitly deny listed
            // checker.verify("https://subdomain.example.com/somepage");

            // 4. Succeeds: mysite.local is explicitly allowlisted
            ResolvedUrl resolvedUrl = checker.verify("http://mysite.local/example");
            System.out.println(resolvedUrl.getUrl()); // "http://127.0.0.1/example"
            System.out.println(resolvedUrl.getHostHeader()); // "mysite.local"
        } catch (HostDeniedException e) {
            e.printStackTrace();
        }
    }
}

Use OpenAPIParser to read OpenAPI specifications from a URL, a file path, or a string. The parser returns a SwaggerParseResult which contains the parsed OpenAPI POJO and any validation messages (errors or warnings).

Note: If you provide a Swagger/OpenAPI 2.0 document, it will be automatically converted to OpenAPI 3.0.

import io.swagger.parser.OpenAPIParser;
import io.swagger.v3.parser.core.models.SwaggerParseResult;
import io.swagger.v3.oas.models.OpenAPI;

// Parse from a URL or file location
SwaggerParseResult result = new OpenAPIParser().readLocation("https://petstore3.swagger.io/api/v3/openapi.json", null, null);

// Parse from string contents
// SwaggerParseResult result = new OpenAPIParser().readContents("contents", null, null);

OpenAPI openAPI = result.getOpenAPI();

// Handle validation errors and warnings
if (result.getMessages() != null) {
  result.getMessages().forEach(System.err::println);
}

if (openAPI != null) {
  // Use the parsed model
}