secrets versus random

## Two generators, two jobs Python ships two sources of randomness with almost identical-looking APIs, and the entire security question is which one a value came from. `random` exists for simulation and statistics. The module-level callables — `random.random`, `random.randint`, `random.choice`, `random.shuffle`, `random.getrandbits` — are bound methods of a single hidden `random.Random` instance created when the module is first imported. That instance runs the Mersenne Twister MT19937 algorithm. MT19937 is fast, has an enormous period and excellent statistical properties, and is *entirely deterministic*: its whole future is a pure function of 19937 bits of state, held as 624 32-bit words plus a position index. `secrets` exists for keys and tokens. Every draw goes through the operating system's cryptographic random source — the same source `os.urandom` exposes — which is designed so that observing output tells you nothing usable about what comes next. ## Why "it looks random" is not the test The failure with `random` is not that its output looks patterned; it passes statistical tests comfortably. The failure is *state recovery*. Because the tempering step MT19937 applies to each output word is invertible, an attacker who collects around 624 consecutive 32-bit outputs can undo the tempering, reassemble the internal state, and then generate the same stream the victim's process will generate — backwards as well as forwards. Values produced through `random.random()` discard some bits per draw, which costs the attacker more samples, not the attack itself. Now look at what a token *is*. A password-reset token is mailed to whoever asks for one. An attacker can request thousands for accounts they control, harvesting a long run of the generator's output, then predict the token that will be issued for an account they do not control. Session identifiers, invitation codes, "unguessable" upload URLs, CSRF values and API keys all share that shape: the attacker sees many outputs and needs to guess one more. This class of bug has shipped repeatedly in real products. Seeding does not save it. `random.seed(some_secret)` keeps the seed private, but the outputs still leak the state, and state recovery never needed the seed. Nor does length: a 64-character token built from `random.choice` over an alphabet is 64 characters of a predictable stream. ## The `secrets` API you actually use ```python import secrets candidates = ["alpha", "beta", "gamma"] secrets.token_urlsafe(32) # str, URL- and cookie-safe, 43 characters secrets.token_hex(32) # str, 64 hexadecimal characters secrets.token_bytes(32) # bytes, for keys and binary protocols secrets.choice(candidates) # unpredictable selection from a sequence secrets.randbelow(1_000_000) # unbiased integer in range(1_000_000) ``` Note the `str` versus `bytes` split: `token_bytes` returns `bytes` and is what you want for a key you will feed to a keyed hash; `token_hex` and `token_urlsafe` return `str` and are what you want in a URL, a header or a database column. All three take a byte count and default to 32 bytes when called with no argument. ## Where `random` is still the right import Keep `random` for retry jitter, load shaping, Monte Carlo work, picking a sample of records for a report, shuffling fixture data in tests, and anything else where the only requirement is variety. `random` is much faster than reading OS entropy on every draw, and reproducibility from a seed is a feature there rather than a flaw. The rule that survives an interview is a rule about consequence, not about the module names: if guessing the value gains an attacker anything — access, identity, a bypass, a leaked resource — it comes from `secrets`. Otherwise `random` is fine and cheaper. ## The anti-patterns to name out loud Two are worth being able to spot. The first is a fallback: code that tries `secrets`, catches a broad `Exception`, swallows it, and quietly falls back to `random` — a silent downgrade from secure to guessable that no test will ever notice. The second is post-processing: hashing or base64-ing a `random` value to "strengthen" it. Encoding adds no entropy; a predictable input hashed with a public algorithm produces a predictable output.