When working within the requests library, developers must assume responsibility for securing outbound HTTP interactions, dynamic boundaries, and sensitive data flows. The framework provides underlying capabilities for connection pooling, header management, and authentication, but does not inherently protect against untrusted URLs, unmanaged resource exhaustion, or misconfigured environment settings. Security-sensitive surfaces include URL parsing, proxy configurations, credential forwarding, and response payload handling, all of which must fail closed when invalid states or ambiguous protocol responses occur.
Essential implementation rules
Verify Response Status Codes Before Payload Parsing
Always call r.raise_for_status() or explicitly verify response status codes before parsing payloads with methods like r.json(). Successful method execution only indicates formatting validity, not business success, preventing applications from ingesting error responses as valid data.
Implement Custom Authentication via AuthBase and Manage Redirects
Implement custom authentication mechanisms by subclassing requests.auth.AuthBase to encapsulate token injection safely. When using HTTPDigestAuth, set allow_redirects=False if redirected requests must not retain credentials.
Validate Target URL Schemes and Domain Boundaries
Perform strict validation on dynamic or user-supplied URLs to ensure explicit and safe URI schemes like https or http and valid network locations before passing them to execution functions.
Disable Environment and .netrc Loading in Untrusted Contexts
Set trust_env = False on requests Session objects in multi-tenant, serverless, or untrusted execution environments to prevent implicit configuration overrides from local environment variables and .netrc files.
Use Atomic File Opening for Secure Disk Writes
Use atomic_open() when creating or updating files on disk to safely write data to a temporary location before atomically replacing the final destination path, avoiding race conditions and partially written data exposure.
Restrict Non-Standard JSON Numeric Formats
Avoid passing out-of-spec numeric values such as float('nan') or float('inf') into JSON request payloads via the json parameter to prevent parser desynchronization or InvalidJSONError exceptions.
Handle Conflicting Content-Length Headers
Wrap request execution blocks in try and except requests.exceptions.InvalidHeader: to properly handle malformed or ambiguous protocol responses containing conflicting Content-Length headers.
Configure Explicit Proxy Schemes and Scope no_proxy Entries
Include explicit schemes in proxy URLs and scope no_proxy entries strictly to intended bypass destinations, keeping in mind that IPv4 entries, CIDR ranges, and hostname boundaries match according to standard library rules.
Enforce Explicit Timeouts and Streaming Context Managers
Specify explicit connection and read timeouts on all request calls to prevent thread exhaustion, and wrap streaming requests made with stream=True inside with statement blocks to ensure connections close properly.
Protect Credentials and Provide Explicit Types
Disable automatic netrc authentication via trust_env when unintended, and pass username and password arguments as explicit string or byte types compatible with latin1 encoding to basic authentication handlers.
Merge Environment Settings for Manually Prepared Requests
Call Session.merge_environment_settings when sending manually prepared requests with Session.send() to ensure system trust stores, custom CA bundles, and environment configurations are consistently applied.
Configure Secure and Domain-Restricted Session Cookies
Explicitly define the domain, path, and set secure=True when creating session cookies via requests.cookies.create_cookie() or when adding them to a RequestsCookieJar to prevent supercookie behavior and unencrypted transmission.
requests: All Security Cards
Approximately 2,599 tokens
On this card
Category: api contract misuse
Validate HTTP Response Status Codes Before Parsing Payloads
Use when
Processing response data or parsing payloads returned from HTTP requests.
Secure rules
Rule 1: Always verify the response status code or call raise_for_status() before parsing response payloads.
Successful execution of r.json() only indicates valid JSON formatting, not HTTP success. Error responses such as HTTP 500 or 400 may still contain valid JSON payloads, so calling r.raise_for_status() ensures that applications do not ingest error details as successful business data.
import requestsr = requests.get('https://api.github.com/events', timeout=5)# Check response status before parsing payloadr.raise_for_status()data = r.json()
Category: authentication
Authenticate Requests Securely Using Supported Mechanisms
Use when
Establishing and verifying identity using credentials, tokens, or digest authentication when sending HTTP requests.
Secure rules
Rule 1: Implement custom authentication mechanisms by subclassing AuthBase
When standard HTTP Basic or Digest authentication is insufficient, implement custom authentication logic by subclassing requests.auth.AuthBase and modifying the Request object inside __call__ to encapsulate header injection and token signing safely.
Rule 2: Disable automatic redirects when Digest credentials must not be forwarded
Use HTTPDigestAuth when a server requires HTTP Digest authentication, but do not assume it removes credentials from every redirect. Its 401 handler limits authenticated resends, while its redirect hook only resets that retry state. Authorization stripping is handled separately and conditionally, so some same-host redirects retain the header. When no redirected request may carry the credentials, set allow_redirects=False.
Validate URL Scheme and Domain Boundaries Before Request Execution
Use when
When accepting dynamic or user-supplied target URL strings before passing them to requests functions.
Secure rules
Rule 1: Validate target URL schemes and host structures before passing dynamic URLs to requests.
Check that the URL has an explicit and safe URI scheme and a valid network location prior to making network calls. This prevents requests from failing at runtime or encountering unexpected protocol parsing behaviors when processing untrusted input.
import requestsfrom urllib.parse import urlparsedef fetch_url(target_url: str): parsed = urlparse(target_url) if parsed.scheme not in ("https", "http") or not parsed.netloc: raise ValueError(f"Untrusted or invalid target URL: {target_url}") return requests.get(target_url)
Category: configuration source integrity
Disable environment variable and .netrc credential loading in untrusted execution contexts
Use when
Configuring HTTP sessions in multi-tenant, serverless, or untrusted environments where local environment variables or .netrc files could be manipulated by external actors.
Secure rules
Rule 1: Set trust_env to False on the requests Session to prevent automatic configuration overrides from local environment variables and .netrc files.
When running applications in environments where local configuration sources like environment variables or .netrc files may be untrusted or ambiguous, instantiate a requests Session and set trust_env to False. This ensures that proxy settings and authentication credentials are not implicitly loaded from the local environment, protecting against configuration tampering or unauthorized traffic redirection.
import requestss = requests.Session()# Disable reading proxies and auth from environment and .netrcs.trust_env = Falseresp = s.get("https://internal.example.com/api")
Category: file handling
Use atomic file opening for safe file creation and updates
Use when
Writing or updating files on disk to prevent race conditions or partially written data exposure.
Secure rules
Rule 1: Use atomic_open() when creating or updating files on disk to safely write data to a secure temporary file before atomically replacing the destination path.
Always use atomic_open() when writing files to disk so that data is written to a secure temporary location first and only replaces the final destination upon successful completion. This prevents race conditions and exposure of partially written files during concurrent operations or application crashes.
from requests.utils import atomic_openwith atomic_open('/path/to/target_file.txt') as handle: handle.write(b'sensitive data content')
Category: input interpretation safety
Prevent Parser Desynchronization by Restricting Non-Standard JSON Numeric Formats
Use when
Serializing data structures to JSON payloads via the json parameter in requests.
Secure rules
Rule 1: Avoid passing out-of-spec numeric values like float('nan') or float('inf') into JSON request payloads.
Ensure all dictionary and sequence data passed to the json parameter contain valid standard JSON data types and do not include values that trigger an InvalidJSONError or break strict backend API parsers.
Configure Explicit Proxy Bypass Rules and Complete URI Schemes
Use when
Configuring trusted proxy environments and destination bypass rules for outbound requests.
Secure rules
Rule 1: Specify proxy URL schemes explicitly
Include an explicit scheme in every proxy URL, as shown in the documented proxy configuration. In Requests v2.34.2, omitting the scheme does not raise MissingSchema; Requests automatically prepends http. Specify the scheme explicitly instead of relying on that default.
Rule 2: Scope no_proxy entries to intended bypass destinations
Configure no_proxy with only the destinations that should bypass configured proxies. Requests matches plain IPv4 entries exactly and supports IPv4 CIDR ranges. A hostname entry matches both that hostname and its subdomains on a domain-label boundary; it is not an exact-host-only rule. A hostname combined with a port limits the match to that port.
Configure Explicit Timeouts and Manage Streaming Connections to Prevent Resource Exhaustion
Use when
Making HTTP requests using the requests library where unmanaged streams or missing timeouts can lead to connection exhaustion and thread blocking.
Secure rules
Rule 1: Always specify explicit connection and read timeouts on request calls.
Pass an explicit timeout parameter to prevent requests from blocking indefinitely and causing thread exhaustion when dealing with unresponsive servers.
Rule 2: Use context managers with streaming requests to ensure connections are closed.
Wrap requests made with stream=True inside a with statement block to ensure underlying network connections are properly closed and returned to the connection pool.
import requestswith requests.get('https://example.com/stream', stream=True) as response: response.raise_for_status() for chunk in response.iter_content(chunk_size=8192): pass
Category: secret handling
Protect Sensitive Credentials and Tokens During Storage and Transport
Use when
Configuring requests with client certificates, basic authentication, netrc files, or handling ephemeral tokens.
Secure rules
Rule 1: Disable automatic netrc authentication when it is not intended
When a session must not use credentials from the user’s netrc file, set trust_env to False before sending requests. Otherwise, Requests attempts to obtain netrc credentials when no auth argument is supplied, and those credentials override a raw authentication header supplied through headers.
Rule 2: Provide credentials as explicit string or byte types for basic authentication.
Pass username and password arguments as explicit str or bytes objects compatible with latin1 encoding to authentication handlers to avoid unexpected encoding exceptions.
Merge environment settings explicitly for manually prepared requests
Use when
Building requests manually using PreparedRequest and sending them with Session.send() where system trust stores and environment configurations must be applied.
Secure rules
Rule 1: Call Session.merge_environment_settings when sending manually prepared requests to ensure environment configurations and trust stores are consistently applied.
PreparedRequest instances bypass environment evaluation by default. Omitting environment merging ignores custom CA bundles like REQUESTS_CA_BUNDLE, causing certificate validation failures or unexpected security setting bypasses. Always retrieve and pass the merged settings dictionary when executing Session.send().
Configure Secure and Domain-Restricted Session Cookies
Use when
Creating custom cookies programmatically or adding them to a RequestsCookieJar for session management.
Secure rules
Rule 1: Explicitly define the domain, path, and secure flag when creating session cookies.
When creating cookies programmatically via requests.cookies.create_cookie() or adding them to a RequestsCookieJar, you must explicitly specify the domain, path, and set secure=True. Omitting the domain defaults to an empty string, turning the cookie into a supercookie that attaches to requests across all external domains. Leaving secure=False permits session cookies to be transmitted over unencrypted HTTP connections.
Validate HTTP Response Status Codes Before Parsing Payloads
Approximately 188 tokens
Use when
Processing response data or parsing payloads returned from HTTP requests.
Secure rules
Rule 1: Always verify the response status code or call raise_for_status() before parsing response payloads.
Successful execution of r.json() only indicates valid JSON formatting, not HTTP success. Error responses such as HTTP 500 or 400 may still contain valid JSON payloads, so calling r.raise_for_status() ensures that applications do not ingest error details as successful business data.
import requestsr = requests.get('https://api.github.com/events', timeout=5)# Check response status before parsing payloadr.raise_for_status()data = r.json()
Authenticate Requests Securely Using Supported Mechanisms
Approximately 364 tokens
Use when
Establishing and verifying identity using credentials, tokens, or digest authentication when sending HTTP requests.
Secure rules
Rule 1: Implement custom authentication mechanisms by subclassing AuthBase
When standard HTTP Basic or Digest authentication is insufficient, implement custom authentication logic by subclassing requests.auth.AuthBase and modifying the Request object inside __call__ to encapsulate header injection and token signing safely.
Rule 2: Disable automatic redirects when Digest credentials must not be forwarded
Use HTTPDigestAuth when a server requires HTTP Digest authentication, but do not assume it removes credentials from every redirect. Its 401 handler limits authenticated resends, while its redirect hook only resets that retry state. Authorization stripping is handled separately and conditionally, so some same-host redirects retain the header. When no redirected request may carry the credentials, set allow_redirects=False.
Validate URL Scheme and Domain Boundaries Before Request Execution
Approximately 206 tokens
Use when
When accepting dynamic or user-supplied target URL strings before passing them to requests functions.
Secure rules
Rule 1: Validate target URL schemes and host structures before passing dynamic URLs to requests.
Check that the URL has an explicit and safe URI scheme and a valid network location prior to making network calls. This prevents requests from failing at runtime or encountering unexpected protocol parsing behaviors when processing untrusted input.
import requestsfrom urllib.parse import urlparsedef fetch_url(target_url: str): parsed = urlparse(target_url) if parsed.scheme not in ("https", "http") or not parsed.netloc: raise ValueError(f"Untrusted or invalid target URL: {target_url}") return requests.get(target_url)
Disable environment variable and .netrc credential loading in untrusted execution contexts
Approximately 234 tokens
Use when
Configuring HTTP sessions in multi-tenant, serverless, or untrusted environments where local environment variables or .netrc files could be manipulated by external actors.
Secure rules
Rule 1: Set trust_env to False on the requests Session to prevent automatic configuration overrides from local environment variables and .netrc files.
When running applications in environments where local configuration sources like environment variables or .netrc files may be untrusted or ambiguous, instantiate a requests Session and set trust_env to False. This ensures that proxy settings and authentication credentials are not implicitly loaded from the local environment, protecting against configuration tampering or unauthorized traffic redirection.
import requestss = requests.Session()# Disable reading proxies and auth from environment and .netrcs.trust_env = Falseresp = s.get("https://internal.example.com/api")
Use atomic file opening for safe file creation and updates
Approximately 187 tokens
Use when
Writing or updating files on disk to prevent race conditions or partially written data exposure.
Secure rules
Rule 1: Use atomic_open() when creating or updating files on disk to safely write data to a secure temporary file before atomically replacing the destination path.
Always use atomic_open() when writing files to disk so that data is written to a secure temporary location first and only replaces the final destination upon successful completion. This prevents race conditions and exposure of partially written files during concurrent operations or application crashes.
from requests.utils import atomic_openwith atomic_open('/path/to/target_file.txt') as handle: handle.write(b'sensitive data content')
Prevent Parser Desynchronization by Restricting Non-Standard JSON Numeric Formats
Approximately 191 tokens
Use when
Serializing data structures to JSON payloads via the json parameter in requests.
Secure rules
Rule 1: Avoid passing out-of-spec numeric values like float('nan') or float('inf') into JSON request payloads.
Ensure all dictionary and sequence data passed to the json parameter contain valid standard JSON data types and do not include values that trigger an InvalidJSONError or break strict backend API parsers.
Configure Explicit Proxy Bypass Rules and Complete URI Schemes
Approximately 351 tokens
Use when
Configuring trusted proxy environments and destination bypass rules for outbound requests.
Secure rules
Rule 1: Specify proxy URL schemes explicitly
Include an explicit scheme in every proxy URL, as shown in the documented proxy configuration. In Requests v2.34.2, omitting the scheme does not raise MissingSchema; Requests automatically prepends http. Specify the scheme explicitly instead of relying on that default.
Rule 2: Scope no_proxy entries to intended bypass destinations
Configure no_proxy with only the destinations that should bypass configured proxies. Requests matches plain IPv4 entries exactly and supports IPv4 CIDR ranges. A hostname entry matches both that hostname and its subdomains on a domain-label boundary; it is not an exact-host-only rule. A hostname combined with a port limits the match to that port.
Configure Explicit Timeouts and Manage Streaming Connections to Prevent Resource Exhaustion
Approximately 262 tokens
Use when
Making HTTP requests using the requests library where unmanaged streams or missing timeouts can lead to connection exhaustion and thread blocking.
Secure rules
Rule 1: Always specify explicit connection and read timeouts on request calls.
Pass an explicit timeout parameter to prevent requests from blocking indefinitely and causing thread exhaustion when dealing with unresponsive servers.
Rule 2: Use context managers with streaming requests to ensure connections are closed.
Wrap requests made with stream=True inside a with statement block to ensure underlying network connections are properly closed and returned to the connection pool.
import requestswith requests.get('https://example.com/stream', stream=True) as response: response.raise_for_status() for chunk in response.iter_content(chunk_size=8192): pass
Protect Sensitive Credentials and Tokens During Storage and Transport
Approximately 283 tokens
Use when
Configuring requests with client certificates, basic authentication, netrc files, or handling ephemeral tokens.
Secure rules
Rule 1: Disable automatic netrc authentication when it is not intended
When a session must not use credentials from the user’s netrc file, set trust_env to False before sending requests. Otherwise, Requests attempts to obtain netrc credentials when no auth argument is supplied, and those credentials override a raw authentication header supplied through headers.
Rule 2: Provide credentials as explicit string or byte types for basic authentication.
Pass username and password arguments as explicit str or bytes objects compatible with latin1 encoding to authentication handlers to avoid unexpected encoding exceptions.
Merge environment settings explicitly for manually prepared requests
Approximately 223 tokens
Use when
Building requests manually using PreparedRequest and sending them with Session.send() where system trust stores and environment configurations must be applied.
Secure rules
Rule 1: Call Session.merge_environment_settings when sending manually prepared requests to ensure environment configurations and trust stores are consistently applied.
PreparedRequest instances bypass environment evaluation by default. Omitting environment merging ignores custom CA bundles like REQUESTS_CA_BUNDLE, causing certificate validation failures or unexpected security setting bypasses. Always retrieve and pass the merged settings dictionary when executing Session.send().
Configure Secure and Domain-Restricted Session Cookies
Approximately 233 tokens
Use when
Creating custom cookies programmatically or adding them to a RequestsCookieJar for session management.
Secure rules
Rule 1: Explicitly define the domain, path, and secure flag when creating session cookies.
When creating cookies programmatically via requests.cookies.create_cookie() or adding them to a RequestsCookieJar, you must explicitly specify the domain, path, and set secure=True. Omitting the domain defaults to an empty string, turning the cookie into a supercookie that attaches to requests across all external domains. Leaving secure=False permits session cookies to be transmitted over unencrypted HTTP connections.
