Skip to content

Getting started

Installation

Policyglass currently targets Python 3.13+.

python -m pip install \
  'https://code.mehalter.com/api/packages/clawlter/pypi/files/policyglass/0.1.1/policyglass-0.1.1-py3-none-any.whl'

This exact wheel URL was verified against the published Forgejo package registry release. Do not rely on pip install policyglass alone: public PyPI already has an unrelated package with that name.

For local development:

uv venv .venv
uv pip install --python .venv/bin/python -e '.[dev]'

Generate a starter policy

policyglass init policyglass.yml

This writes a conservative example you can trim down for your repository.

Create a minimal policy by hand

version: 1
required_paths:
  - README.md
forbidden_globs:
  - '*.pem'

Run a scan

policyglass check . --policy policyglass.yml

If the policy file lives inside the target directory, it is scanned like any other file unless you explicitly ignore it.

Example failure output:

FAIL /path/to/repo
Scanned files: 42
Findings:
- forbidden_glob: secrets.pem — Path matches forbidden glob: *.pem

JSON output

policyglass check . --policy policyglass.yml --format json

Example automation pattern:

policyglass check dist --policy examples/release-artifact-policy.yml --format json > report.json

Typical use cases

Repository hygiene

Require key files and block obvious secret material:

version: 1
required_paths:
  - README.md
  - src/
forbidden_globs:
  - '*.pem'
  - '.env'
ignore_globs:
  - '.git/'
  - '.venv/'

Release bundle validation

Apply limits to built artifacts and forbid private-key content:

version: 1
required_paths:
  - dist/
size_limits:
  - glob: 'dist/*.whl'
    max_bytes: 12000000
forbidden_content_patterns:
  - pattern: 'BEGIN (RSA|OPENSSH|EC) PRIVATE KEY'
    message: 'Private key material should not be present in release artifacts'

Exit codes

  • 0: no violations
  • 1: one or more violations found

Limitations

  • content scanning currently reads files as text with UTF-8 decoding and errors="ignore"
  • regex patterns are user-supplied and should be chosen responsibly; invalid regexes are rejected when the policy is loaded
  • the scan root is enforced strictly; Policyglass skips symlinked files whose resolved targets fall outside the requested root
  • the first release is focused on deterministic directory scans, not streaming or watch mode