uv-scrollguard
uv-scrollguard finds Python scripts with
PEP 723 inline metadata,
requires an adjacent uv lockfile for each one, and verifies that every lockfile
is current.
uv 0.5.17 or newer must be installed and available
on PATH. Use uv-scrollguard as a GitHub Action or prek/pre-commit hook to
catch missing, stale, and invalid script locks in CI. CI is pinned to uv 0.11.28.
The project delegates lock validation to uv lock --script ... --check and may
be archived if uv provides an equivalent repository-wide check natively.
Disclaimer: This project was built by AI coding agents under human supervision, for personal use. Use your own judgment before relying on it.
Policy
The default policy is strict: every discovered PEP 723 script must have a
current adjacent lockfile, including scripts with dependencies = []. Missing,
stale, and invalid locks fail without modifying the repository.
An opt-in existing-only policy validates sidecars that already exist without requiring new ones:
| Policy | CLI and hook | GitHub Action | Behavior |
|---|---|---|---|
| Strict (default) | No option | existing-only: "false" |
Require and validate every discovered script lock |
| Existing only | --existing-only |
existing-only: "true" |
Validate existing script locks and ignore missing ones |
GitHub Action
Install uv before running the Action. The Action may be referenced by a release
tag or a commit SHA. The examples use full-length commit SHAs because
GitHub recommends them when an immutable reference is desired.
After release, replace <commit-sha> with the SHA tagged v0.1.0.
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
- uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
- uses: shaanmajid/uv-scrollguard@<commit-sha> # v0.1.0
Use existing-only mode when a repository wants to validate committed locks without requiring every PEP 723 script to adopt one:
- uses: shaanmajid/uv-scrollguard@<commit-sha> # v0.1.0
with:
existing-only: "true"
The optional paths input accepts newline-delimited files and directories:
- uses: shaanmajid/uv-scrollguard@<commit-sha> # v0.1.0
with:
paths: |
scripts
tools/release.py
prek and pre-commit
Set the hook revision to the release tag or its commit SHA. The example uses the SHA for reproducibility:
repos:
- repo: https://github.com/shaanmajid/uv-scrollguard
rev: <commit-sha> # v0.1.0
hooks:
- id: uv-scrollguard
For existing-only mode:
- id: uv-scrollguard
args: [--existing-only]
The hook performs a repository-wide check rather than receiving staged filenames.
CLI
The CLI is useful for local audits and CI systems that do not use the packaged
integrations. Run it from PyPI with uvx:
uvx uv-scrollguard
With no paths, the command scans downward from the current directory and respects Git ignore rules. Explicit paths replace default discovery and are combined and deduplicated:
uv-scrollguard scripts/ tools/release.py
uv-scrollguard --existing-only scripts/
Explicit directories include ignored contents because they were requested
directly. Explicit files may use any extension. --paths-from-env NAME adds
newline-delimited scopes from an environment variable and is primarily used by
the GitHub Action.
Ordinary discovery considers .py, .pyw, and extensionless shebang files.
Files without PEP 723 metadata are ignored. The checker deliberately does not
guess whether an ordinary Python module, test, or utility was intended to be a
standalone script.
To repair a reported script, run:
uv lock --script path/to/script.py
Exit statuses are 0 for success, 1 for failed lock checks, 2 for invalid
usage or paths, and 3 when uv cannot be executed.
License
MIT
Metadata
Release files for uv-scrollguard 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| uv_scrollguard-0.1.0.tar.gz | 7.3 kB | With provenance | Details for uv_scrollguard-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| uv_scrollguard-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for uv_scrollguard-0.1.0-py3-none-any.whl |
Total release size: 16.5 kB
Release files / uv_scrollguard-0.1.0.tar.gz
| Download URL | uv_scrollguard-0.1.0.tar.gz |
|---|---|
| Size | 7.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
318fadf329a41f8cd5dc0a0500593913600081c3b50b0dec9a32295bea31dea4
|
|
BLAKE2b-256 checksum How to use checksums |
2acb202a6eaf865f30f944e7dcf328368b1f654c4670afc6f7849109d344b2c3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 17, 2026.
Transparency logRelease files / uv_scrollguard-0.1.0-py3-none-any.whl
| Download URL | uv_scrollguard-0.1.0-py3-none-any.whl |
|---|---|
| Size | 9.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6fb4cff8e1076a687e021b96e8ee05146cb290eb58ac874502d74b89028dddcc
|
|
BLAKE2b-256 checksum How to use checksums |
94a6dab72a2b1d1de477c0df0b5bcc24705457e0ac9be77c939d4fe832fd0e09
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 17, 2026.
Transparency logSecurity for uv-scrollguard 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for uv_scrollguard-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 17, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.