yui-agent-guard 0.1.0__tar.gz

yui_agent_guard-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,65 @@
+# Where: .github/workflows/ci.yml
+# What: run workflow linting, tests, and packaging checks on every push to master and every PR.
+# Why: keep the extracted guard package safe while the API surface is still moving.
+
+name: ci
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+jobs:
+  actionlint:
+    name: actionlint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: devops-actions/actionlint@v0.1.11
+
+  test:
+    name: pytest (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.11', '3.12']
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package + dev deps
+        run: pip install -e ".[dev]"
+      - name: Run tests
+        run: pytest -q
+      - name: Run CLI smoke tests
+        run: |
+          python -m agent_guard.cli content check --repo-root . --policy examples/content_security_policy.yaml --mode registered --scan-dir . --json
+          python -m agent_guard.cli path check --root . --policy examples/ai_resilience_path_policy.yaml --json
+          mkdir -p /tmp/agent-guard-digest-smoke
+          printf 'pinned\n' > /tmp/agent-guard-digest-smoke/pinned.txt
+          python - <<'PY'
+          import hashlib
+          from pathlib import Path
+
+          root = Path("/tmp/agent-guard-digest-smoke")
+          digest = hashlib.sha256((root / "pinned.txt").read_bytes()).hexdigest()
+          (root / "policy.yaml").write_text(
+              "checks:\n"
+              "  - id: pinned_text\n"
+              "    path: pinned.txt\n"
+              f"    sha256: '{digest}'\n",
+              encoding="utf-8",
+          )
+          PY
+          python -m agent_guard.cli digest check --root /tmp/agent-guard-digest-smoke --policy /tmp/agent-guard-digest-smoke/policy.yaml --json
+      - name: Build sdist + wheel
+        if: matrix.python-version == '3.12'
+        run: python -m build
+      - name: Verify metadata (twine check)
+        if: matrix.python-version == '3.12'
+        run: python -m twine check dist/*

yui_agent_guard-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,84 @@
+# Where: .github/workflows/release.yml
+# What: build sdist+wheel and publish to PyPI on tag push, via Trusted Publishing.
+# Why: make agent-guard consumable from downstream CI without long-lived PyPI tokens.
+
+name: release
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
+on:
+  workflow_dispatch:
+    inputs:
+      publish:
+        description: 'Publish to PyPI instead of build-only dry run'
+        required: true
+        type: boolean
+        default: false
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: read
+
+jobs:
+  validate-release-request:
+    name: validate release request
+    runs-on: ubuntu-latest
+    steps:
+      - name: Validate manual publish ref
+        run: |
+          set -euo pipefail
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ] \
+             && [ "${{ inputs.publish }}" = "true" ] \
+             && [[ "${GITHUB_REF}" != refs/tags/v* ]]; then
+            echo "::error::manual publish=true must be run against a v* tag ref, not ${GITHUB_REF}"
+            exit 1
+          fi
+          echo "release request accepted for ${GITHUB_REF}"
+
+  build:
+    name: build sdist + wheel
+    needs: validate-release-request
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+      - name: Assert tag matches package version
+        if: github.event_name == 'push' || startsWith(github.ref, 'refs/tags/v')
+        env:
+          TAG_NAME: ${{ github.ref_name }}
+        run: python scripts/check_release_version.py "$TAG_NAME"
+      - name: Check PyPI release state
+        if: github.event_name == 'push' || startsWith(github.ref, 'refs/tags/v')
+        run: python scripts/check_pypi_release_state.py
+      - name: Install build + twine
+        run: python -m pip install --upgrade build twine
+      - name: Build distributions
+        run: python -m build
+      - name: Verify metadata (twine check)
+        run: python -m twine check dist/*
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: publish to PyPI (OIDC)
+    needs: build
+    if: github.event_name == 'push' || (inputs.publish && startsWith(github.ref, 'refs/tags/v'))
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/yui-agent-guard
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

yui_agent_guard-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+.pytest_cache/
+build/
+dist/
+*.egg-info/
+.venv312/
+.venv-py312/

yui_agent_guard-0.1.0/PKG-INFO

@@ -0,0 +1,277 @@
+Metadata-Version: 2.4
+Name: yui-agent-guard
+Version: 0.1.0
+Summary: Static repository guardrails for agent-touched codebases.
+Project-URL: Repository, https://github.com/yui-stingray/agent-guard
+Project-URL: Issues, https://github.com/yui-stingray/agent-guard/issues
+Author: yui-stingray
+License-Expression: MIT
+Keywords: agent,ai-agents,guardrails,policy,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pyyaml<7,>=6
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == 'dev'
+Requires-Dist: pytest-cov<7,>=5; extra == 'dev'
+Requires-Dist: pytest<9,>=8; extra == 'dev'
+Requires-Dist: twine<7,>=6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# agent-guard
+
+> Static repository guardrails for agent-touched codebases.
+>
+> `agent-policy` decides whether an agent should do something.
+> `agent-guard` checks whether the repository content still obeys the rules.
+
+**Status**: `0.1.0` alpha. The current MVP ships four scanners: `api`, `content`, `path`, and `digest`.
+
+## Why
+
+`agent-guard` exists to enforce fail-closed static checks around agent-operated repositories without pulling in a full control plane.
+
+The current extracted scanners are intentionally narrow:
+- `api`: scan repository text files for URLs, allow approved API patterns, fail on forbidden API patterns
+- `content`: scan Markdown or other configured text files for dangerous instruction patterns
+- `path`: scan repository path names for private artifacts, env files, and other publish-time leaks
+- `digest`: verify SHA-256 pins for governance docs and safety-critical scripts
+- return stable JSON or text output for local hooks and CI
+
+It does **not** manage approvals, logs, state, or UI. Those belong in higher layers.
+
+## Install
+
+```bash
+pip install -e .
+```
+
+Requires Python 3.11+. The only runtime dependency is `PyYAML`.
+
+## Quick start
+
+API surface guard:
+
+```bash
+agent-guard api check --root . --policy examples/architecture_policy.yaml
+```
+
+Content security guard:
+
+```bash
+agent-guard content check --repo-root . --policy examples/content_security_policy.yaml --mode registered --scan-dir skills
+```
+
+Path-name guard:
+
+```bash
+agent-guard path check --root . --policy examples/ai_resilience_path_policy.yaml
+```
+
+Digest guard:
+
+```bash
+agent-guard digest check --root . --policy digest_policy.yaml
+```
+
+JSON mode is stable and intended for CI/wrappers:
+
+```bash
+agent-guard api check --root . --policy examples/architecture_policy.yaml --json
+agent-guard content check --repo-root . --policy examples/content_security_policy.yaml --mode registered --scan-dir skills --json
+agent-guard path check --root . --policy examples/ai_resilience_path_policy.yaml --json
+agent-guard digest check --root . --policy digest_policy.yaml --json
+```
+
+## Current scanners
+
+### API guard
+
+The API guard scans configured paths for URLs and compares them against allow/deny regex lists.
+
+Typical use case:
+- keep a CLI-first repository from silently drifting into direct inference API calls
+
+It returns:
+- exit `0` on clean
+- exit `1` on violation
+- exit `2` on configuration/runtime error
+
+### Content guard
+
+The content guard scans configured text content for forbidden regex patterns.
+
+Supported modes:
+- `registered`: scan a configured directory under the repo
+- `preregister`: scan explicit file or directory targets
+- `new`: scan changed files from git diff, optionally including untracked files
+
+`new` mode uses two behaviors: with `--since-ref`, it scans files changed between that ref and `HEAD`; without `--since-ref`, it scans the current working tree diff and can optionally include untracked files.
+
+Typical use cases:
+- keep dangerous install instructions out of skills docs
+- block hardcoded credential-like strings in agent-authored Markdown
+- catch destructive command suggestions before they spread
+
+It returns:
+- exit `0` on clean
+- exit `1` on violation
+- exit `2` on configuration/runtime error
+
+### Path guard
+
+The path guard scans file and directory names under configured roots. It uses
+allowlist-first matching so narrow exceptions such as `.env.example` can be
+allowed while broader deny patterns still block `.env`, `.env.local`, and
+`.env.evil`.
+
+Typical use cases:
+- keep `artifacts/private/` out of publishable repository paths
+- block bypass corpus files and red-team session logs by name
+- catch env-file leaks even when contents are ignored or unreadable
+
+It returns:
+- exit `0` on clean
+- exit `1` on violation
+- exit `2` on configuration/runtime error
+
+### Digest guard
+
+The digest guard verifies pinned SHA-256 values for files that should not
+drift silently. Each check names a repository-relative path, an expected
+digest, and an optional `start_line` when only the content body should be
+hashed.
+
+Typical use cases:
+- detect unreviewed edits to governance documents
+- pin verifier scripts that protect publication or release gates
+- preserve B9-style constitution integrity checks without shell-specific logic
+
+It returns:
+- exit `0` on clean
+- exit `1` on violation
+- exit `2` on configuration/runtime error
+
+## Example policies
+
+### API guard policy
+
+```yaml
+scan:
+  include:
+    - src
+    - scripts
+  exclude:
+    - scripts/build_instructions.sh
+
+policy:
+  allowed_api_patterns:
+    - "^https://ntfy\.sh/"
+  forbidden_api_patterns:
+    - "^https://api\.openai\.com/"
+    - "^https://api\.anthropic\.com/"
+```
+
+A ready-to-run copy lives in [`examples/architecture_policy.yaml`](examples/architecture_policy.yaml).
+
+### Content guard policy
+
+```yaml
+file_globs:
+  - "**/*.md"
+exclude_globs:
+  - "archive/**"
+forbidden_patterns:
+  - id: pipe_to_shell
+    severity: high
+    pattern: '(?i)curl\s+[^\n|]+\|\s*(bash|sh)\b'
+    message: "pipe-to-shell pattern is forbidden"
+    exclude_globs:
+      - "fixtures/red-team/**"
+```
+
+A ready-to-run copy lives in [`examples/content_security_policy.yaml`](examples/content_security_policy.yaml).
+
+Content rules may define per-rule `include_globs` / `exclude_globs`. Use this
+when a repository contains intentional adversarial fixtures that should stay
+scannable for secrets but should not fail dangerous-command rules. For narrow
+documented examples, append an inline suppression such as
+`# agent-guard: allow pipe_to_shell` or `# agent-guard: allow all` on the same
+line.
+
+### Path guard policy
+
+```yaml
+scan:
+  include:
+    - "."
+  exclude:
+    - ".git"
+    - ".venv"
+    - "node_modules"
+
+policy:
+  allowed_path_patterns:
+    - "(^|/)\\.env\\.example$"
+  forbidden_path_patterns:
+    - id: private_artifacts
+      severity: high
+      pattern: "(^|/)artifacts/private(/|$)"
+      message: "private artifact directory must stay outside published/tracked paths"
+```
+
+A ready-to-run ai-resilience-style copy lives in
+[`examples/ai_resilience_path_policy.yaml`](examples/ai_resilience_path_policy.yaml).
+
+### Digest guard policy
+
+```yaml
+checks:
+  - id: constitution_full
+    path: agent-constitution-v0.md
+    sha256: "<64-char lowercase sha256>"
+  - id: constitution_content
+    path: agent-constitution-v0.md
+    sha256: "<64-char lowercase sha256>"
+    start_line: 15
+```
+
+## CLI
+
+```bash
+agent-guard api check --root <repo> --policy <yaml> [--json]
+agent-guard content check --repo-root <repo> --policy <yaml> --mode <registered|preregister|new> [--scan-dir <dir>] [--targets <paths...>] [--since-ref <ref>] [--no-untracked] [--json]
+agent-guard path check --root <repo> --policy <yaml> [--json]
+agent-guard digest check --root <repo> --policy <yaml> [--json]
+```
+
+## Roadmap
+
+Planned next steps:
+- shared result envelope helpers across scanners
+- optional pre-commit examples
+
+## Releases
+
+Tag-driven. Pushing a `vX.Y.Z` annotated tag triggers
+[`.github/workflows/release.yml`](.github/workflows/release.yml), which first
+verifies that the tag matches `[project].version` in `pyproject.toml`, checks
+that the version is not already present on PyPI, then builds the sdist + wheel
+and publishes to PyPI via Trusted Publishing (OIDC). No maintainer-side PyPI
+token is required once the PyPI project environment is configured. Manual
+`workflow_dispatch` with `publish=false` is a build-only dry run; it skips the
+publish job. Manual `publish=true` must be run against a `v*` tag ref; running
+it from a branch fails before build.
+
+## License
+
+MIT.

yui_agent_guard-0.1.0/README.md

@@ -0,0 +1,248 @@
+# agent-guard
+
+> Static repository guardrails for agent-touched codebases.
+>
+> `agent-policy` decides whether an agent should do something.
+> `agent-guard` checks whether the repository content still obeys the rules.
+
+**Status**: `0.1.0` alpha. The current MVP ships four scanners: `api`, `content`, `path`, and `digest`.
+
+## Why
+
+`agent-guard` exists to enforce fail-closed static checks around agent-operated repositories without pulling in a full control plane.
+
+The current extracted scanners are intentionally narrow:
+- `api`: scan repository text files for URLs, allow approved API patterns, fail on forbidden API patterns
+- `content`: scan Markdown or other configured text files for dangerous instruction patterns
+- `path`: scan repository path names for private artifacts, env files, and other publish-time leaks
+- `digest`: verify SHA-256 pins for governance docs and safety-critical scripts
+- return stable JSON or text output for local hooks and CI
+
+It does **not** manage approvals, logs, state, or UI. Those belong in higher layers.
+
+## Install
+
+```bash
+pip install -e .
+```
+
+Requires Python 3.11+. The only runtime dependency is `PyYAML`.
+
+## Quick start
+
+API surface guard:
+
+```bash
+agent-guard api check --root . --policy examples/architecture_policy.yaml
+```
+
+Content security guard:
+
+```bash
+agent-guard content check --repo-root . --policy examples/content_security_policy.yaml --mode registered --scan-dir skills
+```
+
+Path-name guard:
+
+```bash
+agent-guard path check --root . --policy examples/ai_resilience_path_policy.yaml
+```
+
+Digest guard:
+
+```bash
+agent-guard digest check --root . --policy digest_policy.yaml
+```
+
+JSON mode is stable and intended for CI/wrappers:
+
+```bash
+agent-guard api check --root . --policy examples/architecture_policy.yaml --json
+agent-guard content check --repo-root . --policy examples/content_security_policy.yaml --mode registered --scan-dir skills --json
+agent-guard path check --root . --policy examples/ai_resilience_path_policy.yaml --json
+agent-guard digest check --root . --policy digest_policy.yaml --json
+```
+
+## Current scanners
+
+### API guard
+
+The API guard scans configured paths for URLs and compares them against allow/deny regex lists.
+
+Typical use case:
+- keep a CLI-first repository from silently drifting into direct inference API calls
+
+It returns:
+- exit `0` on clean
+- exit `1` on violation
+- exit `2` on configuration/runtime error
+
+### Content guard
+
+The content guard scans configured text content for forbidden regex patterns.
+
+Supported modes:
+- `registered`: scan a configured directory under the repo
+- `preregister`: scan explicit file or directory targets
+- `new`: scan changed files from git diff, optionally including untracked files
+
+`new` mode uses two behaviors: with `--since-ref`, it scans files changed between that ref and `HEAD`; without `--since-ref`, it scans the current working tree diff and can optionally include untracked files.
+
+Typical use cases:
+- keep dangerous install instructions out of skills docs
+- block hardcoded credential-like strings in agent-authored Markdown
+- catch destructive command suggestions before they spread
+
+It returns:
+- exit `0` on clean
+- exit `1` on violation
+- exit `2` on configuration/runtime error
+
+### Path guard
+
+The path guard scans file and directory names under configured roots. It uses
+allowlist-first matching so narrow exceptions such as `.env.example` can be
+allowed while broader deny patterns still block `.env`, `.env.local`, and
+`.env.evil`.
+
+Typical use cases:
+- keep `artifacts/private/` out of publishable repository paths
+- block bypass corpus files and red-team session logs by name
+- catch env-file leaks even when contents are ignored or unreadable
+
+It returns:
+- exit `0` on clean
+- exit `1` on violation
+- exit `2` on configuration/runtime error
+
+### Digest guard
+
+The digest guard verifies pinned SHA-256 values for files that should not
+drift silently. Each check names a repository-relative path, an expected
+digest, and an optional `start_line` when only the content body should be
+hashed.
+
+Typical use cases:
+- detect unreviewed edits to governance documents
+- pin verifier scripts that protect publication or release gates
+- preserve B9-style constitution integrity checks without shell-specific logic
+
+It returns:
+- exit `0` on clean
+- exit `1` on violation
+- exit `2` on configuration/runtime error
+
+## Example policies
+
+### API guard policy
+
+```yaml
+scan:
+  include:
+    - src
+    - scripts
+  exclude:
+    - scripts/build_instructions.sh
+
+policy:
+  allowed_api_patterns:
+    - "^https://ntfy\.sh/"
+  forbidden_api_patterns:
+    - "^https://api\.openai\.com/"
+    - "^https://api\.anthropic\.com/"
+```
+
+A ready-to-run copy lives in [`examples/architecture_policy.yaml`](examples/architecture_policy.yaml).
+
+### Content guard policy
+
+```yaml
+file_globs:
+  - "**/*.md"
+exclude_globs:
+  - "archive/**"
+forbidden_patterns:
+  - id: pipe_to_shell
+    severity: high
+    pattern: '(?i)curl\s+[^\n|]+\|\s*(bash|sh)\b'
+    message: "pipe-to-shell pattern is forbidden"
+    exclude_globs:
+      - "fixtures/red-team/**"
+```
+
+A ready-to-run copy lives in [`examples/content_security_policy.yaml`](examples/content_security_policy.yaml).
+
+Content rules may define per-rule `include_globs` / `exclude_globs`. Use this
+when a repository contains intentional adversarial fixtures that should stay
+scannable for secrets but should not fail dangerous-command rules. For narrow
+documented examples, append an inline suppression such as
+`# agent-guard: allow pipe_to_shell` or `# agent-guard: allow all` on the same
+line.
+
+### Path guard policy
+
+```yaml
+scan:
+  include:
+    - "."
+  exclude:
+    - ".git"
+    - ".venv"
+    - "node_modules"
+
+policy:
+  allowed_path_patterns:
+    - "(^|/)\\.env\\.example$"
+  forbidden_path_patterns:
+    - id: private_artifacts
+      severity: high
+      pattern: "(^|/)artifacts/private(/|$)"
+      message: "private artifact directory must stay outside published/tracked paths"
+```
+
+A ready-to-run ai-resilience-style copy lives in
+[`examples/ai_resilience_path_policy.yaml`](examples/ai_resilience_path_policy.yaml).
+
+### Digest guard policy
+
+```yaml
+checks:
+  - id: constitution_full
+    path: agent-constitution-v0.md
+    sha256: "<64-char lowercase sha256>"
+  - id: constitution_content
+    path: agent-constitution-v0.md
+    sha256: "<64-char lowercase sha256>"
+    start_line: 15
+```
+
+## CLI
+
+```bash
+agent-guard api check --root <repo> --policy <yaml> [--json]
+agent-guard content check --repo-root <repo> --policy <yaml> --mode <registered|preregister|new> [--scan-dir <dir>] [--targets <paths...>] [--since-ref <ref>] [--no-untracked] [--json]
+agent-guard path check --root <repo> --policy <yaml> [--json]
+agent-guard digest check --root <repo> --policy <yaml> [--json]
+```
+
+## Roadmap
+
+Planned next steps:
+- shared result envelope helpers across scanners
+- optional pre-commit examples
+
+## Releases
+
+Tag-driven. Pushing a `vX.Y.Z` annotated tag triggers
+[`.github/workflows/release.yml`](.github/workflows/release.yml), which first
+verifies that the tag matches `[project].version` in `pyproject.toml`, checks
+that the version is not already present on PyPI, then builds the sdist + wheel
+and publishes to PyPI via Trusted Publishing (OIDC). No maintainer-side PyPI
+token is required once the PyPI project environment is configured. Manual
+`workflow_dispatch` with `publish=false` is a build-only dry run; it skips the
+publish job. Manual `publish=true` must be run against a `v*` tag ref; running
+it from a branch fails before build.
+
+## License
+
+MIT.