mirror of
https://github.com/trailofbits/skills.git
synced 2026-09-14 14:28:48 +08:00
Dan Guido
c199e0cc7d
* Narrow the modern-python shims to the commands uv run replaces Closes #207. The shims sit on PATH, so they intercept every subprocess any tool spawns, not just what Claude types. Two of the intercepted invocations were not package management at all, and blocking them broke real tooling. `uv pip` now passes through when it carries --project, --directory or --target. Those say a tool is building an environment it owns, where `uv add` is not the available advice: prek installs every hook with `uv pip install --project / --directory <cache>`, so the refusal made `git commit` fail in any repo whose hooks need a Python environment. A bare `uv pip install requests` is still refused. `python -c`, `python -m <module>` and `python -` now reach the real interpreter. None of them resolves a script against a project's dependencies, which is what `uv run` exists to do, and `uv run python3 -` is not a drop-in replacement inside a pipeline. `python -m pip` stays intercepted, as do bare `python` and `python script.py`. Passing anything through is new for the python shim, which previously ended every branch in exit 1, so it gains the same skip-my-own-dir PATH walk the uv shim already had. That walk now uses parameter expansion rather than basename, because the one case where it must report failure is a PATH holding nothing but the shim, where shelling out to coreutils fails first with a confusing error. Verified by A/B on the two symptoms #207 reports, running each suite against the old shim and the new one: - zeroize-audit's rust-regression smoke test: FAILED at line 72 before, "Rust regression smoke checks passed." after. - prek hook installation from a cold cache: refused before, "check json Passed" after. bats goes from 19 cases to 38. Five python cases inverted rather than being deleted: the ones asserting that -c and -m are refused now assert they run. AGENTS.md's note on `make shell-suites` is corrected rather than removed — the #207 interceptions are gone, but the target still fails because variant-analysis invokes `python3 <script>.py`, which the shim intercepts by design. That one belongs to variant-analysis. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * Decide on the mode selector, not on argument position Two gaps in the narrowing, both from review. `uv pip install --help` documents `-t, --target <TARGET>`, so the short form has to be exempt alongside the long one. Without it the same tool-managed install was allowed or refused depending on spelling. The python shim read only $1 to find the mode selector, so `python -u -c 'code'` was refused while `python -c 'code'` ran, even though they are the same invocation. It now steps over interpreter flags to find the selector, giving `-W`, `-X` and `--check-hash-based-pycs` the two slots they take. `-u -m pip` is still refused, and so is `-u script.py`: a script path is what `uv run` replaces regardless of what precedes it. bats 38 -> 43. Both #207 regressions re-verified after the restructure: zeroize-audit's smoke test passes and prek installs hooks from a cold cache. Not fixed here, deliberately: `uv --no-progress pip install requests` still slips past the refusal, because the subcommand check reads $1 as well. Parsing that correctly means knowing which uv global flags take a value, and getting it wrong would refuse a command that works today. The failure mode is a missed nudge rather than a breakage — the real uv runs and behaves correctly — so it does not belong in a change whose purpose is to refuse less. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Modern Python
Modern Python tooling and best practices using uv, ruff, ty, and pytest. Based on patterns from trailofbits/cookiecutter-python.
Author: William Tan
When to Use
- Setting up a new Python project with modern, fast tooling
- Replacing pip/virtualenv with uv for faster dependency management
- Replacing flake8/black/isort with ruff for unified linting and formatting
- Replacing mypy with ty for faster type checking
- Adding pre-commit hooks and security scanning to an existing project
What It Covers
Core Tools:
- uv - Package/dependency management (replaces pip, virtualenv, pip-tools, pipx, pyenv)
- ruff - Linting and formatting (replaces flake8, black, isort, pyupgrade)
- ty - Type checking (replaces mypy, pyright)
- pytest - Testing with coverage enforcement
- prek - Pre-commit hooks (replaces pre-commit)
Security Tools:
- shellcheck - Shell script linting
- detect-secrets - Secret detection in commits
- actionlint - GitHub Actions syntax validation
- zizmor - GitHub Actions security audit
- pip-audit - Dependency vulnerability scanning
- Dependabot - Automated dependency updates with supply chain protection
Standards:
- pyproject.toml - Single configuration file with dependency groups (PEP 735)
- PEP 723 - Inline script metadata for single-file scripts
- src/ layout - Standard package structure
- Python 3.11+ - Minimum version requirement
Hook: Legacy Command Interception
This plugin includes a SessionStart hook that prepends PATH shims for python, pip, pipx, and uv. When Claude runs a bare python, pip, or pipx command, the shell resolves to the shim, which prints an error with the correct uv alternative and exits non-zero. The suggested alternative always uses the exact command name python (never python3) so it also works outside a project; see the header comment in hooks/shims/python for the full rationale.
The shims sit on PATH, so they see every subprocess a tool spawns, not only what Claude types. That is why the intercepted set is narrow: it covers the invocations uv run and uv add genuinely replace, and passes the rest through to the real binary. python -c, python -m <module> and python - read a program from the command line, an installed module, or stdin, so none of them resolves a script against a project's dependencies; uv pip carrying --project, --directory or --target is a tool building an environment it owns. Redirecting those broke real tooling, including prek hook installation and any script piping into python3 - (#207).
| Intercepted Command | Suggested Alternative |
|---|---|
python ... |
uv run python ... |
python -m pip |
uv add/uv remove |
pip install pkg |
uv add pkg or uv run --with pkg |
pip uninstall pkg |
uv remove pkg |
pip freeze |
uv export |
uv pip ... |
uv add/uv remove/uv sync |
| (passed through) | python -c, python -m <module>, python -, and uv pip with --project, --directory or --target |
pipx install <pkg> |
uv tool install <pkg> |
pipx run <pkg> |
uvx <pkg> |
pipx uninstall <pkg> |
uv tool uninstall <pkg> |
pipx upgrade <pkg> |
uv tool upgrade <pkg> |
pipx upgrade-all |
uv tool upgrade --all |
pipx ensurepath |
uv tool update-shell |
pipx inject <pkg> <dep> |
uv tool install --with <dep> <pkg> |
pipx list |
uv tool list |
Commands like grep python, which python, and cat python.txt work normally because python is a shell argument, not the command being invoked.
Installation
/plugin install trailofbits/skills/plugins/modern-python