Skip to main content

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)

Source distribution for uv-scrollguard 0.1.0
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)

Table of built distributions (wheels) for uv-scrollguard 0.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page