safe-apis

name	safe-apis
description	Use when writing or reviewing code that touches a dangerous API surface: `eval`/`exec`/`compile` on a string; `subprocess`/`os.system`/`os.popen` with a shell or a partial path; building a shell or SQL command by string concatenation or f-string; `pickle`/`yaml.load`/`torch.load`/ `tarfile.extractall`/`zipfile.extractall` on data you did not produce; fetching a caller-supplied URL or fetching without a timeout; `md5`/`sha1` in a security decision; a hardcoded `/tmp/...` path; a `0.0.0.0` bind; `chmod 0o777`; `random` for a token or secret; or logging an object that carries a credential. Gives the exact safe replacement call for each surface, plus the three rules that make a redaction survive static taint analysis.
metadata	{"short-description":"The safe replacement API for each dangerous Python surface, plus taint-clean secret redaction"}

safe-apis

The safe replacement call for each dangerous Python surface. Use the right-hand column of the table by default. A deliberate exception is allowed, but it needs a one-line justification written at the call site — a bare suppression comment with no reason is not enough.

When to use this skill

• You are about to write code that evaluates a string, runs a subprocess, builds a SQL statement, deserializes a file, extracts an archive, or fetches a URL.
• You are reviewing a diff that contains any of: eval(, exec(, shell=True, os.system, pickle.load, yaml.load(, torch.load, extractall(, urlopen(, md5(, sha1(, /tmp/, 0.0.0.0, 0o777, random. used for a token.
• Code logs, prints, or serializes an object that carries a credential — an API key, a token, a password, a signed URL — and a redacted copy is wanted for the log.
• A static analyser (CodeQL, bandit, ruff S…) has flagged one of those surfaces and the finding needs a real fix rather than a suppression.
• A task hands you data you did not produce — an uploaded archive, a downloaded model file, a user-supplied path or URL — and something is about to parse it.
• Not for: general code quality, style, performance, or API design. This is specifically about the surfaces below.
• Not for: operating a live product surface — email, chat, calendar, file-sharing, or account settings. This is about the API you write in code, never about actions taken in a running workspace.

Procedure

1. Locate every dangerous surface in what you are about to write or review — grep the diff for the tokens listed above rather than relying on reading.
2. Replace each one with the right-hand column of the surface table. Where an exception is genuinely required, write the one-line reason at the call site.
3. If a credential can reach a log, print, or serialized payload, apply the three redaction rules — coverage, constant placeholder, separate display builder.
4. Pin the redaction with the three tests (parity, no-leak, forwarding-intact) so the duplicated structure cannot drift.
5. Run the completion checklist at the end before calling the change done.

The surface table

Surface	Don't	Do
Evaluate an expression string	eval(expr) / exec(s), even from a "trusted" template	a small ast-walk allowlist evaluator (numeric nodes only), or sympy.sympify(expr, rational=True) for math. ast.literal_eval parses literals only — it will NOT evaluate a+b, so it is not a drop-in for arithmetic.
Run a subprocess	subprocess.run(cmd, shell=True), os.system(s), os.popen(s), a bare "git" (partial path)	pass an argv list with shell=False (the default) and a full or PATH-resolved executable; wrap any interpolated value in shlex.quote. If a shell script really must be generated, pass operator values in through the environment ($VAR) and read them there — never f-string them into the script text.
Build a SQL statement	f-string or + with a variable	a parameterized query: cur.execute("... WHERE id = ?", (id,)). Never string-format SQL, not even for an integer.
Deserialize	pickle.load, yaml.load(f) with the full loader, torch.load(path) on a file you did not write	json.load, yaml.safe_load, torch.load(path, weights_only=True). Never unpickle data from outside your own process.
Extract an archive	tarfile.extractall() / zipfile.extractall() on a downloaded file	resolve each member path against the target directory and reject anything that escapes it (path traversal / zip-slip) before writing: os.path.realpath(os.path.join(dest, name)).startswith(os.path.realpath(dest) + os.sep). Reject absolute member names and symlink members too.
Fetch a URL	urllib.request.urlopen(url) on a caller-influenced url, or any fetch with no timeout	check the parsed scheme is https, check the host against an allowlist, and always pass timeout= (requests.get(url, timeout=10)). A missing timeout is a hang, not just a style nit.
Hash for a security decision	hashlib.md5(x) / hashlib.sha1(x) as an integrity or auth check	hashlib.sha256. For non-security content addressing or dedup, md5 is fine but say so in code: hashlib.md5(b, usedforsecurity=False).
Temp file	a hardcoded /tmp/thing.json	tempfile.mkstemp() or tempfile.TemporaryDirectory() — unpredictable name, correct permissions, cleaned up.
Bind a server	0.0.0.0 by default	bind 127.0.0.1 unless a remote bind is the deliberate, stated intent.
File permissions	os.chmod(p, 0o777)	least privilege: 0o600 for files, 0o700 for directories, 0o755 only for a script that is meant to be executable.
Randomness for a token, key, nonce, or password	random.random(), random.choice, random.randint	secrets.token_hex / secrets.choice / os.urandom. (random is correct for sampling, shuffling, and seeded data generation — the distinction is whether an attacker guessing the value matters.)
Log or print an object that carries a secret	print(json.dumps(payload)) after "sanitizing" one field	build a separate display object into which the real secret never lands — see below.

Redacting a secret out of a log line

Printing a request payload so a human can eyeball it is reasonable. Printing it after blanking the one field you happened to think of is not. Three rules, each of which is both a real safety property and what a static taint analyser actually requires:

1. Redact by coverage, not by the field you remembered. A one-field redaction is worse than no redaction: it reads as safe while leaking every other secret in the object. Enumerate the secret-bearing keys and blank all of them.

2. Use a constant placeholder, never a derived one. Write the literal "***". Do not write _redact(secret) returning "***(len=8)" — that string still depends on the secret value (it leaks the length), and to a taint analyser it keeps the edge from secret to sink alive.

3. Build a separate display builder, and share nothing on the print path. A redact=True flag on the shared payload builder does not work. Taint tracking is context-insensitive: the analyser processes each function once and unions all of its callers, so if the same builder is called with the real secret (for the real request) and again for the display copy, the secret → return → print edge exists regardless of any if redact: branch inside it. Factoring out just the "common part" fails for the same reason — the real path taints the shared structure and the display path prints the shared return. Write a standalone _display_payload(args) that never receives the secret and never reads a secret value; it rebuilds the non-secret shape from its arguments and sets each secret field to the constant placeholder. If the log should show which secrets are configured, read the environment as a presence boolean only:

   for var in SECRET_ENV_VARS:
       if os.environ.get(var):          # presence, never the value
           display["env"][var] = "***"
   

   The real builder stays real and is sent, never logged.

Duplicating the ~15 lines of structure is the point, so pin the duplication with a test:

• Parity: the display object and the real object have the same top-level keys (this catches drift between the two copies).
• No leak: no substring of any real secret value appears in the serialized display object.
• Forwarding intact: the real object still carries the real values — redaction applies to the display copy only, never to what is actually sent.

Completion checklist

• Grep your diff for shell=True, eval(, exec(, pickle.load, yaml.load(, extractall(, md5(, 0.0.0.0, 0o777, /tmp/.
• Every network call has a timeout=.
• Every interpolated value in a command is either an argv element or shlex.quoted.
• No print/log statement is reachable from a variable holding a credential.

Worked example

Input: a script downloads a .tar.gz from a URL taken from a config field, extracts it, loads a config.yaml from inside it, invokes a converter binary on the result, and prints the request payload — which carries an API key — so the run is traceable.

Approach: five surfaces, five rows of the table. The fetch gets a parsed-scheme check against https, a host allowlist, and timeout=10. The extraction resolves each member against the target directory with os.path.realpath and rejects escaping, absolute, and symlink members before any write. The YAML load becomes yaml.safe_load. The converter call becomes an argv list with shell=False and a resolved executable path, with any interpolated value shlex.quoted. The log line becomes a standalone _display_payload(args) that never receives the key at all and writes the constant "***" in its place — not a redact=True flag on the real builder, which leaves the taint edge alive. Then the three redaction tests pin it, and the completion checklist confirms no remaining hit.

References

None. Every replacement above is a standard-library or common-package call, so the skill is self-contained and needs no bundled file.