ward-scanner 0.2.2__tar.gz

ward_scanner-0.2.2/.gitattributes

@@ -0,0 +1,20 @@
+# Force LF endings cross-platform. Without this, files authored on Windows
+# arrive at Linux CI runners with CRLF, which breaks the `#!/usr/bin/env bash`
+# shebang in action/entrypoint.sh and trips a few Python tools.
+* text=auto eol=lf
+
+# Binary types we never want munged.
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+
+# Shell scripts must be LF, full stop.
+*.sh   text eol=lf
+*.bash text eol=lf
+
+# Windows-specific scripts stay CRLF.
+*.bat text eol=crlf
+*.cmd text eol=crlf
+*.ps1 text eol=crlf

ward_scanner-0.2.2/.github/dependabot.yml

@@ -0,0 +1,44 @@
+# Dependabot configuration.
+#
+# Bumps pip + GitHub Actions dependencies weekly, opens a PR per ecosystem,
+# rebases automatically. Security advisories trigger updates regardless of
+# the schedule. Keeps the supply chain fresh without flooding the PR queue.
+
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: "deps"
+      include: "scope"
+    groups:
+      python-dev-deps:
+        dependency-type: "development"
+        update-types: ["minor", "patch"]
+      python-runtime-deps:
+        dependency-type: "production"
+        update-types: ["patch"]
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 3
+    commit-message:
+      prefix: "ci"
+      include: "scope"
+
+  - package-ecosystem: "github-actions"
+    directory: "/action"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 3
+    commit-message:
+      prefix: "action"
+      include: "scope"

ward_scanner-0.2.2/.github/workflows/bench.yml

@@ -0,0 +1,70 @@
+name: Bench
+
+on:
+  pull_request:
+
+# Comment on the PR with the detection-rate diff vs the base branch.
+# Makes silent regressions on Ward's benchmark numbers impossible to merge
+# without a human noticing.
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  bench-diff:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out PR HEAD
+        uses: actions/checkout@v4
+        with:
+          path: pr
+
+      - name: Check out base ref
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.base.ref }}
+          path: base
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Bench the base branch
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install ./base
+          ward bench --no-cache --format json --output "${{ runner.temp }}/base.json"
+          python -m pip uninstall -y ward-scanner
+
+      - name: Bench the PR branch
+        run: |
+          python -m pip install ./pr
+          ward bench --no-cache --format json --output "${{ runner.temp }}/pr.json"
+
+      - name: Compute diff
+        run: |
+          ward bench-diff \
+            "${{ runner.temp }}/base.json" \
+            "${{ runner.temp }}/pr.json" \
+            --output "${{ runner.temp }}/diff.md"
+          cat "${{ runner.temp }}/diff.md"
+
+      - name: Post / update sticky PR comment
+        uses: marocchino/sticky-pull-request-comment@v2
+        # Skip on forks: they do not have write permission to comment on the PR.
+        if: ${{ github.event.pull_request.head.repo.fork == false }}
+        with:
+          header: ward-bench-diff
+          path: ${{ runner.temp }}/diff.md
+
+      - name: Upload bench artefacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: bench-diff
+          path: |
+            ${{ runner.temp }}/base.json
+            ${{ runner.temp }}/pr.json
+            ${{ runner.temp }}/diff.md

ward_scanner-0.2.2/.github/workflows/ci.yml

@@ -0,0 +1,77 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: test (${{ matrix.os }} / py${{ matrix.python }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+
+      - name: Install dev deps
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+
+      - name: Lint
+        run: |
+          python -m ruff check src tests
+          python -m ruff format --check src tests
+
+      - name: Type-check
+        run: python -m mypy src/ward
+
+      - name: Tests + coverage
+        run: python -m pytest --cov=src/ward --cov-report=term --cov-report=xml
+
+  self-scan:
+    name: ward scans its own repo
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install
+        run: pip install -e .
+
+      - name: scan-local
+        # Self-scan is informational. A security tool that describes the
+        # attacks it catches will inevitably trigger its own rules; the
+        # ward-allow-file directive handles most of it, but `continue-on-error`
+        # keeps any remaining hit informational rather than gating.
+        continue-on-error: true
+        run: ward scan-local --format sarif > ward-self.sarif
+
+      - name: Upload SARIF
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: ward-self-sarif
+          path: ward-self.sarif
+
+      - name: selftest (scripted scenarios, gating)
+        run: ward selftest

ward_scanner-0.2.2/.github/workflows/release.yml

@@ -0,0 +1,68 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build distribution
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    # Only runs once you've set the repo variable PYPI_READY=true AND
+    # configured a trusted publisher at https://pypi.org for this repo.
+    # Until then this job is skipped so tag pushes don't fail the workflow.
+    if: vars.PYPI_READY == 'true'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/ward-scanner
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist
+
+  github-release:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true

ward_scanner-0.2.2/.gitignore

@@ -0,0 +1,35 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+.eggs/
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Virtual environments
+.venv/
+venv/
+env/
+.uv/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Ward output
+*.sarif
+ward-report.json

ward_scanner-0.2.2/.pre-commit-hooks.yaml

@@ -0,0 +1,39 @@
+# Pre-commit framework hooks for Ward.
+# Consumers add a block like this to their own .pre-commit-config.yaml:
+#
+#   - repo: https://github.com/sonofg0tham/ward
+#     rev: v0.1.0
+#     hooks:
+#       - id: ward-scan-local
+#         args: [--fail-on, high]
+
+- id: ward-scan-local
+  name: Ward scan-local
+  description: |
+    Scan the current branch name, the most recent commit messages, tag
+    names, every tracked file path, and the top of every Markdown / text
+    / source file for prompt-injection patterns.
+  entry: ward scan-local
+  language: python
+  pass_filenames: false
+  always_run: true
+  stages: [pre-commit, pre-push]
+
+- id: ward-scan-stdin
+  name: Ward scan-stdin (commit message)
+  description: |
+    Pipe the commit message under composition through Ward. Designed for
+    use with `stages: [commit-msg]`.
+  entry: bash -c 'cat "$1" | ward scan-stdin --surface commit_message --fail-on high'
+  language: python
+  pass_filenames: true
+  stages: [commit-msg]
+
+- id: ward-selftest
+  name: Ward selftest
+  description: Run the built-in adversarial scenarios. Useful as a CI gate.
+  entry: ward selftest
+  language: python
+  pass_filenames: false
+  always_run: true
+  stages: [manual]

ward_scanner-0.2.2/.wardignore

@@ -0,0 +1,25 @@
+# .wardignore - paths whose content scan-local should skip.
+#
+# Filenames are still scanned (a malicious filename in an ignored directory
+# is still suspicious). Only file_content / code_comment scanning is
+# suppressed.
+#
+# A security tool that documents and tests the attacks it catches will
+# inevitably trigger its own rules. The ward-allow-file directive handles
+# documentation files (README, SECURITY.md). The .wardignore here covers
+# Ward's own source tree and the deliberately-adversarial test fixtures.
+
+# Ward's own source tree. Source files contain docstrings describing the
+# attack patterns; rule YAMLs describe the rules; selftest and demo
+# modules embed example attacks.
+src/ward/*
+src/ward/**/*
+
+# Test fixtures are intentionally adversarial. Test modules contain attack
+# strings as parametrised inputs.
+tests/fixtures/*
+tests/fixtures/**/*
+tests/test_*.py
+
+# The bundled GitHub Action wrapper mentions the surfaces it scans.
+action/*

ward_scanner-0.2.2/CLAUDE.md

@@ -0,0 +1,32 @@
+# Ward
+
+Pre-agent metadata scanner. Catches prompt injection in branch names, commits, PR titles/bodies and filenames before they reach an AI code reviewer. Python 3.11+ Typer CLI (`ward`) plus a composite GitHub Action.
+
+## Key files
+
+- `src/ward/cli.py` - CLI entry. Commands: scan-stdin, scan-branch, scan-commit, scan-local, scan-pr, explain, selftest, attack-demo, update-rules, lab, bench, bench-diff, judge.
+- `src/ward/core/` - engine, rules loader, normalise (homoglyph/unicode/TAG-block/evasion), verdict, github_api, wardignore.
+- `src/ward/detectors/` - one module per attack category (instruction_override, obfuscation, exfiltration, etc.).
+- `src/ward/rules/*.yaml` - bundled rule packs.
+- `src/ward/reporters/` - pretty, json, sarif output.
+- `src/ward/bench/` - benchmark harness (corpora, runner, report, compare, download) + bundled samples.
+- `src/ward/judge/` - optional LLM judge tier (base, mock, anthropic_judge, prompt). Off by default; needs the [judge] extra.
+- `src/ward/lab.py` + `src/ward/lab_reviewer.py` - lab harnesses. `lab attack` (metadata-flow demo, mock) and `lab review` (real reviewer agent: NaiveReviewer offline / AnthropicReviewer via [judge]).
+- `action.yml` - the GitHub Action at repo root (inputs: pr, fail-on, format, upload-sarif...). entrypoint under `action/`.
+- `tests/fixtures/` - numbered YAML attack fixtures; `tests/fixtures/clean/` - false-positive fixtures that must NOT trigger.
+
+## Run / test
+
+```
+pip install -e ".[dev]"
+pytest                  # coverage must stay >= 75%
+ruff check . && ruff format .
+mypy                    # strict mode, covers src/ward
+```
+
+## Conventions
+
+- Ruff: line-length 100, py311 target. Mypy strict.
+- RUF001-003 are deliberately ignored in homoglyph-handling files (normalise, obfuscation, demo, selftest and their tests). Never "fix" Cyrillic or ambiguous unicode there - it is the test payload.
+- `class Foo(str, Enum)` is intentional; do not convert to StrEnum (changes str() output).
+- New detection rules need both an attack fixture and, where relevant, a clean fixture proving no false positive.

ward_scanner-0.2.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Craig McCart
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.