{"id":7898,"library":"advocate","title":"Advocate HTTP Client","description":"Advocate is a Python library providing a safe wrapper around the popular `requests` library for making HTTP requests on behalf of a third party. It helps prevent common security pitfalls like SSRF by allowing developers to define strict URL validation patterns, limit redirects, set timeouts, and control request options. The current version is 1.0.0, and it maintains a stable release cadence focused on security and reliability.","status":"active","version":"1.0.0","language":"en","source_language":"en","source_url":"https://github.com/JordanMilne/Advocate","tags":["http","requests","security","ssrf","validation"],"install":[{"cmd":"pip install advocate","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Advocate is a wrapper around the requests library, using it for underlying HTTP communication.","package":"requests","optional":false}],"imports":[{"symbol":"Advocate","correct":"from advocate import Advocate"}],"quickstart":{"code":"from advocate import Advocate\n\n# Configure Advocate for safe third-party requests\n# This example allows requests only to google.com/search\nadvocate = Advocate(\n    url_regex_pattern=\"^https://www\\.google\\.com/search\",\n    max_redirects=0, # Disallow redirects for this sensitive operation\n    raise_on_redirect=True,\n    timeout=5, # Set a timeout to prevent hanging requests\n    requests_options={\n        \"headers\": {\"User-Agent\": \"MySafeClient/1.0\"},\n        \"verify\": True # Ensure SSL verification is on\n    }\n)\n\ntry:\n    # Make a safe GET request\n    response = advocate.get(\"https://www.google.com/search?q=python+advocate\")\n    response.raise_for_status() # Raise an exception for HTTP errors (4xx or 5xx)\n    print(f\"Request successful! Status: {response.status_code}\")\n    print(\"First 200 characters of response:\")\n    print(response.text[:200])\nexcept advocate.exceptions.InvalidURLError as e:\n    print(f\"Invalid URL error: {e}\")\nexcept advocate.exceptions.RedirectError as e:\n    print(f\"Redirect error: {e}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\n\n# Example of a disallowed URL (will raise InvalidURLError)\ntry:\n    advocate.get(\"http://internal-api.example.com/sensitive-data\")\nexcept advocate.exceptions.InvalidURLError as e:\n    print(f\"Successfully blocked disallowed URL: {e}\")\nexcept Exception as e:\n    print(f\"Unexpected error for disallowed URL: {e}\")","lang":"python","description":"This quickstart demonstrates how to initialize `Advocate` with a strict URL regex pattern, disable redirects, set a timeout, and make a safe GET request. It also shows how the library prevents requests to URLs that don't match the configured pattern, raising `InvalidURLError`."},"warnings":[{"fix":"Thoroughly test your `url_regex_pattern` to ensure it only permits intended URLs. Use online regex testers and consider edge cases. It's often safer to define a whitelist of allowed domains/paths rather than trying to blacklist.","message":"The `url_regex_pattern` is critical for security. If it's too broad or incorrectly specified, it can negate Advocate's safety features, potentially exposing your application to Server-Side Request Forgery (SSRF) vulnerabilities.","severity":"gotcha","affected_versions":"1.0.0+"},{"fix":"For sensitive third-party requests, it's generally recommended to set `max_redirects=0` and `raise_on_redirect=True` to explicitly control and prevent redirects. Only allow redirects if you fully trust the redirect chain.","message":"Misconfiguring `max_redirects` and `raise_on_redirect` can lead to unexpected behavior or security issues. For third-party requests, unsolicited redirects might point to malicious or unintended destinations.","severity":"gotcha","affected_versions":"1.0.0+"},{"fix":"Only use `Advocate` when making HTTP requests on behalf of an untrusted third party or when strict URL validation and request control are required for security. For internal or trusted requests, use `requests` directly.","message":"Advocate adds overhead due to URL validation and other safety checks. Using it for requests where there is no third-party involvement or trust concern can introduce unnecessary performance penalties.","severity":"gotcha","affected_versions":"1.0.0+"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Review your `Advocate` instance's `url_regex_pattern` to ensure it correctly allows the URLs you intend to access. If the URL is genuinely invalid, do not attempt to access it. If it should be allowed, adjust the regex pattern carefully.","cause":"The URL provided to an Advocate request method (e.g., `get`, `post`) does not match the regular expression pattern defined in the `url_regex_pattern` parameter during `Advocate` initialization.","error":"advocate.exceptions.InvalidURLError: URL 'http://evil.com' does not match configured regex pattern."},{"fix":"If you intend to follow redirects, set `raise_on_redirect=False` during `Advocate` initialization. If redirects are a security concern (as often recommended for third-party requests), investigate why the target URL is redirecting.","cause":"The requested URL returned an HTTP redirect, but the `Advocate` instance was configured with `raise_on_redirect=True`, which explicitly forbids following redirects.","error":"advocate.exceptions.RedirectError: Request resulted in a redirect to 'https://new-location.com' but raise_on_redirect is True."},{"fix":"Store the result of `advocate.get()` (or `post`, etc.) in a variable, then call response methods on that variable. Example: `response = advocate.get(url); data = response.json()`.","cause":"You are attempting to call a response method like `.json()`, `.text`, or `.status_code` directly on the `Advocate` instance itself, instead of on the `response` object returned by its request methods.","error":"AttributeError: 'Advocate' object has no attribute 'json'"}]}