ghostrules 0.2.1__tar.gz → 0.4.0__tar.gz

{ghostrules-0.2.1 → ghostrules-0.4.0}/.ghostrules.lock

@@ -3,22 +3,22 @@
     "claude-code": [
       {
         "conditions": [],
-        "lines": "2a3d3f1fb26381e9 e3b0c44298fc1c14 ddabff43c0a4efe5 6aa552cc1598dcb7 be186e6b970ab643 fb78540ec32b52f9 e3b0c44298fc1c14 d393a517d5cbec9f e3b0c44298fc1c14 85b7ae55df076ab0 2f6995b0ecd75c8d e3b0c44298fc1c14 5f2235a1b010f82c 56a4406ad70b7f0a ba2cd86d7e76eff5 a7b723b74ee03fc8 e3b0c44298fc1c14 782729a560418c17 36a8e590ff4c085c e3b0c44298fc1c14 9f4e3cc48918efc0 efeeec23855e4659 2f23b1dcff8841e8 c3abd357eb574eb6 76881ea91e0040bd e3b0c44298fc1c14 36cd3f2bb454f575 ad332335cfaa348c a58865feac87f52b 052081156966d443 5654f9fffd4a2a7a bd0710fd0315ecbb e4d8cec4158bb770 f1b901847390b0ed e3b0c44298fc1c14 966a8946115b377a 5b59b2f749ffabac 9bf96d3c4c385073 43d8bbb16372109c 5226bbb3f5f9e13d add6d744d3ac0c02 3dafca094d79548b 21a3cd5236dfd642 79e12b3b50117933 9cb81024d1184666 f1e7b346d65f35c5 e3b0c44298fc1c14 60ab6be4219694a0 3a1c5dcc5281208a e256f3fb8239bf8c 10d8918d097bebb5 ff85c33a894fab39 10f274c7d25257d2 6216cf539fa87bd8 e3b0c44298fc1c14 7136000e494604c0 aa8d4cf82644ac63 f75f6ee8f0d942eb 1f59b655e6071114 da29957f3e8be475",
+        "lines": "2a3d3f1fb26381e9 e3b0c44298fc1c14 ddabff43c0a4efe5 6aa552cc1598dcb7 be186e6b970ab643 fb78540ec32b52f9 e3b0c44298fc1c14 662c42577f74cece e3b0c44298fc1c14 85b7ae55df076ab0 2f6995b0ecd75c8d e3b0c44298fc1c14 5f2235a1b010f82c 56a4406ad70b7f0a ba2cd86d7e76eff5 a7b723b74ee03fc8 e3b0c44298fc1c14 782729a560418c17 36a8e590ff4c085c e3b0c44298fc1c14 9f4e3cc48918efc0 efeeec23855e4659 2f23b1dcff8841e8 c3abd357eb574eb6 76881ea91e0040bd e3b0c44298fc1c14 36cd3f2bb454f575 ad332335cfaa348c a58865feac87f52b 052081156966d443 5654f9fffd4a2a7a bd0710fd0315ecbb e4d8cec4158bb770 f1b901847390b0ed e3b0c44298fc1c14 966a8946115b377a 5b59b2f749ffabac 9bf96d3c4c385073 43d8bbb16372109c 5226bbb3f5f9e13d add6d744d3ac0c02 3dafca094d79548b 21a3cd5236dfd642 79e12b3b50117933 9cb81024d1184666 f1e7b346d65f35c5 e3b0c44298fc1c14 60ab6be4219694a0 3a1c5dcc5281208a e256f3fb8239bf8c 10d8918d097bebb5 ff85c33a894fab39 10f274c7d25257d2 6216cf539fa87bd8 e3b0c44298fc1c14 7136000e494604c0 aa8d4cf82644ac63 f75f6ee8f0d942eb 1f59b655e6071114 da29957f3e8be475",
         "load": "always",
         "path": "CLAUDE.md",
-        "raw_sha256": "c21de91b03da043818a3d8a83418a2e4ce449e58e1e6a5906e7d7c2212ddfca5",
-        "seen_sha256": "c21de91b03da043818a3d8a83418a2e4ce449e58e1e6a5906e7d7c2212ddfca5",
+        "raw_sha256": "d989296d3afb40ba35cdf955a9dcc549df351fa4a5b0ee4585475e94e86e774c",
+        "seen_sha256": "d989296d3afb40ba35cdf955a9dcc549df351fa4a5b0ee4585475e94e86e774c",
         "via": []
       }
     ],
     "copilot-cli": [
       {
         "conditions": [],
-        "lines": "2a3d3f1fb26381e9 e3b0c44298fc1c14 ddabff43c0a4efe5 6aa552cc1598dcb7 be186e6b970ab643 fb78540ec32b52f9 e3b0c44298fc1c14 d393a517d5cbec9f e3b0c44298fc1c14 85b7ae55df076ab0 2f6995b0ecd75c8d e3b0c44298fc1c14 5f2235a1b010f82c 56a4406ad70b7f0a ba2cd86d7e76eff5 a7b723b74ee03fc8 e3b0c44298fc1c14 782729a560418c17 36a8e590ff4c085c e3b0c44298fc1c14 9f4e3cc48918efc0 efeeec23855e4659 2f23b1dcff8841e8 c3abd357eb574eb6 76881ea91e0040bd e3b0c44298fc1c14 36cd3f2bb454f575 ad332335cfaa348c a58865feac87f52b 052081156966d443 5654f9fffd4a2a7a bd0710fd0315ecbb e4d8cec4158bb770 f1b901847390b0ed e3b0c44298fc1c14 966a8946115b377a 5b59b2f749ffabac 9bf96d3c4c385073 43d8bbb16372109c 5226bbb3f5f9e13d add6d744d3ac0c02 3dafca094d79548b 21a3cd5236dfd642 79e12b3b50117933 9cb81024d1184666 f1e7b346d65f35c5 e3b0c44298fc1c14 60ab6be4219694a0 3a1c5dcc5281208a e256f3fb8239bf8c 10d8918d097bebb5 ff85c33a894fab39 10f274c7d25257d2 6216cf539fa87bd8 e3b0c44298fc1c14 7136000e494604c0 aa8d4cf82644ac63 f75f6ee8f0d942eb 1f59b655e6071114 da29957f3e8be475",
+        "lines": "2a3d3f1fb26381e9 e3b0c44298fc1c14 ddabff43c0a4efe5 6aa552cc1598dcb7 be186e6b970ab643 fb78540ec32b52f9 e3b0c44298fc1c14 662c42577f74cece e3b0c44298fc1c14 85b7ae55df076ab0 2f6995b0ecd75c8d e3b0c44298fc1c14 5f2235a1b010f82c 56a4406ad70b7f0a ba2cd86d7e76eff5 a7b723b74ee03fc8 e3b0c44298fc1c14 782729a560418c17 36a8e590ff4c085c e3b0c44298fc1c14 9f4e3cc48918efc0 efeeec23855e4659 2f23b1dcff8841e8 c3abd357eb574eb6 76881ea91e0040bd e3b0c44298fc1c14 36cd3f2bb454f575 ad332335cfaa348c a58865feac87f52b 052081156966d443 5654f9fffd4a2a7a bd0710fd0315ecbb e4d8cec4158bb770 f1b901847390b0ed e3b0c44298fc1c14 966a8946115b377a 5b59b2f749ffabac 9bf96d3c4c385073 43d8bbb16372109c 5226bbb3f5f9e13d add6d744d3ac0c02 3dafca094d79548b 21a3cd5236dfd642 79e12b3b50117933 9cb81024d1184666 f1e7b346d65f35c5 e3b0c44298fc1c14 60ab6be4219694a0 3a1c5dcc5281208a e256f3fb8239bf8c 10d8918d097bebb5 ff85c33a894fab39 10f274c7d25257d2 6216cf539fa87bd8 e3b0c44298fc1c14 7136000e494604c0 aa8d4cf82644ac63 f75f6ee8f0d942eb 1f59b655e6071114 da29957f3e8be475",
         "load": "always",
         "path": "CLAUDE.md",
-        "raw_sha256": "c21de91b03da043818a3d8a83418a2e4ce449e58e1e6a5906e7d7c2212ddfca5",
-        "seen_sha256": "c21de91b03da043818a3d8a83418a2e4ce449e58e1e6a5906e7d7c2212ddfca5",
+        "raw_sha256": "d989296d3afb40ba35cdf955a9dcc549df351fa4a5b0ee4585475e94e86e774c",
+        "seen_sha256": "d989296d3afb40ba35cdf955a9dcc549df351fa4a5b0ee4585475e94e86e774c",
         "via": []
       }
     ],
@@ -26,6 +26,6 @@
     "generic": []
   },
   "configs": [],
-  "generator": "ghostrules 0.2.1",
+  "generator": "ghostrules 0.4.0",
   "lock_version": 1
 }

{ghostrules-0.2.1 → ghostrules-0.4.0}/.ghostrules.toml

@@ -7,4 +7,6 @@ exclude = [
   ".mypy_cache/**",
   ".ruff_cache/**",
   ".pytest_cache/**",
+  "corpus/.cache/**",  # API responses and clones are other people's text
+  "corpus/results/**",
 ]

ghostrules-0.4.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+# Keeps the commit-pinned actions in .github/workflows and action.yml up to date: each update is a
+# pull request that changes the SHA and its version comment.
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: "chore"

{ghostrules-0.2.1 → ghostrules-0.4.0}/.github/workflows/ci.yml

@@ -14,8 +14,8 @@ jobs:
         os: [ubuntu-latest, windows-latest, macos-latest]
         python-version: ["3.10", "3.11", "3.12", "3.13"]
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install

ghostrules-0.4.0/.github/workflows/corpus.yml

@@ -0,0 +1,80 @@
+name: Corpus
+
+# Runs ghostrules against the public repositories listed in corpus/repos.toml (the only networked
+# part of the project). Never on pull requests.
+on:
+  schedule:
+    - cron: "17 4 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: corpus
+  cancel-in-progress: false
+
+jobs:
+  corpus:
+    runs-on: ubuntu-latest
+    timeout-minutes: 120
+    env:
+      GH_TOKEN: ${{ github.token }}
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: "3.12"
+      - name: Install ghostrules from this checkout
+        run: pip install -e ".[dev]"
+      - name: Scan the regression tier
+        run: python corpus/run.py --tier regression
+      - name: Gate against labels.toml
+        run: python corpus/check.py
+      - name: Aggregate files (badge and summary, counts only)
+        if: always() && hashFiles('corpus/results/latest-summary.json') != ''
+        run: python corpus/badge.py --out corpus-public
+      - name: Upload results
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: corpus-results
+          path: |
+            corpus/results
+            corpus-public
+          retention-days: 30
+          if-no-files-found: ignore
+
+  publish:
+    # Only the default branch publishes; the badge reads corpus/badge.json from the orphan
+    # branch "badges" (gh-pages is not served: Pages is deployed from Actions by pages.yml).
+    needs: corpus
+    if: always() && needs.corpus.result != 'skipped' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: corpus-results
+          path: artifact
+      - name: Publish to the badges branch
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+        run: |
+          set -euo pipefail
+          test -f artifact/corpus-public/badge.json
+          git clone --quiet --depth 1 --branch badges \
+            "https://x-access-token:${GH_TOKEN}@github.com/${REPO}.git" site \
+            || { mkdir site && git -C site init --quiet -b badges \
+              && git -C site remote add origin \
+              "https://x-access-token:${GH_TOKEN}@github.com/${REPO}.git"; }
+          mkdir -p site/corpus
+          cp artifact/corpus-public/badge.json artifact/corpus-public/summary.json site/corpus/
+          cd site
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add corpus
+          git diff --cached --quiet || git commit --quiet -m "corpus: weekly summary"
+          git push origin badges

ghostrules-0.4.0/.github/workflows/pages.yml

@@ -0,0 +1,48 @@
+name: Playground
+
+# Builds the browser playground (web/ plus the wheel of this checkout) and deploys it to GitHub Pages.
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: pip install -e ".[dev,web-test]"
+      - name: Build the site
+        run: python scripts/build_site.py _site
+      - name: Playwright smoke test on the built site
+        run: |
+          playwright install --with-deps chromium
+          pytest -q tests/web
+      - uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5
+      - uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3
+        with:
+          path: _site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4

{ghostrules-0.2.1 → ghostrules-0.4.0}/.github/workflows/release.yml

@@ -14,9 +14,9 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
         with:
           python-version: "3.12"
 
@@ -41,7 +41,7 @@ jobs:
           python -m pip install --disable-pip-version-check --quiet build
           python -m build
 
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
         with:
           name: dist
           path: |
@@ -55,10 +55,10 @@ jobs:
     permissions:
       id-token: write # Trusted Publishing
     steps:
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
         with:
           name: dist
-      - uses: pypa/gh-action-pypi-publish@release/v1
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # release/v1
 
   github-release:
     needs: publish-pypi
@@ -66,7 +66,7 @@ jobs:
     permissions:
       contents: write
     steps:
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
         with:
           name: dist
       - name: Create the GitHub release
@@ -75,3 +75,24 @@ jobs:
           TAG: ${{ github.ref_name }}
           REPO: ${{ github.repository }}
         run: gh release create "$TAG" dist/* --repo "$REPO" --title "$TAG" --notes-file release-notes.md
+
+  move-major-tag:
+    # Users pin BardLaudian/ghostrules@v0 (or an exact tag). Only a stable x.y.z release moves it.
+    needs: github-release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - name: Move the v0 tag to this release
+        env:
+          TAG: ${{ github.ref_name }}
+        run: |
+          set -euo pipefail
+          if ! [[ "$TAG" =~ ^v0\.[0-9]+\.[0-9]+$ ]]; then
+            echo "$TAG is not a stable v0.x.y release: the v0 tag stays where it is"
+            exit 0
+          fi
+          git tag -f v0 "$TAG"
+          git push --force origin v0
+

{ghostrules-0.2.1 → ghostrules-0.4.0}/.github/workflows/self-test.yml

@@ -13,7 +13,7 @@ jobs:
   action:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
 
       - name: Poisoned demo with fail-on none (must pass, must report findings)
         id: poisoned
@@ -75,7 +75,7 @@ jobs:
   import-chain:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
 
       - name: Import-chain demo, following imports (default)
         uses: ./
@@ -125,6 +125,9 @@ jobs:
         uses: ./
         with:
           path: ${{ runner.temp }}/acme/base
+          # not a git repository: scanned with its own settings
+          trust-repo-config: "true"
+          inline-suppressions: all
           fail-on: none
           lock-check: "true"
           upload-sarif: "false"
@@ -140,6 +143,9 @@ jobs:
         continue-on-error: true
         with:
           path: ${{ runner.temp }}/acme/pr
+          # not a git repository: scanned with its own settings
+          trust-repo-config: "true"
+          inline-suppressions: all
           fail-on: none
           lock-check: "true"
           upload-sarif: "false"

ghostrules-0.4.0/.gitignore

@@ -0,0 +1,23 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+*.ghostrules.bak
+ghostrules.sarif
+
+# corpus tooling
+corpus/.cache/
+corpus/results/*
+!corpus/results/latest-summary.json
+_site/
+
+# benchmark: findings of third-party repositories
+bench/.cache/

ghostrules-0.4.0/CHANGELOG.md

@@ -0,0 +1,314 @@
+# Changelog
+
+All notable changes to this project are documented here.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [0.4.0] - 2026-10-29
+
+Remediation release, from an independent review of 0.3.0 ([plan](docs/design/v0.4/REMEDIATION.md)).
+The scanned change can no longer switch the scanner off, the lock cannot be re-blessed by a pull
+request, visible prose no longer drowns the check, claims are corrected and measured, and the scanner
+reads more of what agents run. On a new benchmark (101 attack cases and a 100-repository held-out
+set, `bench/`): 87 of 101 attacks reported, 50 fail the default check; precision for a user on the
+held-out set is 19% (4 of 21 findings, labels provisional). Both numbers come with their misses.
+
+**Upgrading: breaking changes.** (1) On pull requests the Action reads the config, the ignore comments,
+the baseline and the lock from the base commit; a path outside a git repository needs
+`trust-repo-config: "true"` and `inline-suppressions: all`. (2) Plain visible prose is `low` or `info`
+by default, so a visible `curl | sh` no longer fails `--fail-on high`; `--strict` (config
+`profile = "strict"`, Action `profile: strict`) restores the 0.3 severities. (3) The label `wontfix` is
+now `benign-context` in the corpus tools. (4) The Action installs from a hash-pinned requirements file.
+
+### Added
+
+- **Scripts that hooks and skills run** (W5.1, W5.2): hook commands of Claude Code, Gemini, Cursor and
+  Codex and scripts named in `SKILL.md` are scanned as code, with the chain that reaches them: GR110
+  (sends the environment or a secret), GR111 (reads credential files), GR112 (downloads and runs code),
+  GR113 (hides what it runs).
+- **The context engine as a library** (W8): `ghostrules.context.resolve()` and `schema()`, a JSON
+  schema for the result validated in the tests, and a README section on alternatives.
+- **Settings a pull request cannot rewrite** (W2 of docs/design/v0.4/REMEDIATION.md): `scan
+  --config-from-ref REF`, `--trusted-config FILE`, `--no-inline-suppressions` and
+  `--suppressions-from-ref REF`. They close two ways a change could silence the scanner for its own
+  payload: a `ghostrules-ignore` comment on the malicious line and `exclude` in `.ghostrules.toml`.
+- **Codex and Gemini CLI** (W5.3): `context` models for both (`--agent codex`, `--agent gemini-cli`;
+  opt-in through `agents`, so existing lockfiles do not change); `AGENTS.override.md`,
+  `.codex/config.toml` and `.codex/hooks.json` are scanned; GR107 reports Codex
+  `sandbox_mode = "danger-full-access"` and `approval_policy = "never"` and Gemini's bare
+  `run_shell_command` allow and `enablePermanentToolApproval`.
+- **Files that prose points to** (W5.4): `Read X and follow every step` and `Run scripts/x.sh` make the
+  file part of the scan, with the chain and the tag `reached-via-reference` (GR026, a tag, not a
+  detector). The `context` tree does not show a `referenced` state yet.
+- **Instructions split across two sentences** (W5.5): GR013 reports a secret in one sentence and a send
+  to a URL in the next, with a new `confidence: medium` field on the finding.
+- **A benchmark you can check** (W6): `bench/` has 81 defanged attack cases written from public
+  sources (recall per technique and per rule, misses listed, four cases from the independent review as
+  known misses) and the 100-repository held-out set run once, with precision for a user per rule. The
+  README now shows these numbers instead of the corpus claims. Labels `wontfix` are now
+  `benign-context`.
+- **Supply-chain hygiene** (W7): every `uses:` in the Action and the workflows is pinned to a full
+  commit SHA (Dependabot keeps them current); the Action installs its dependencies and the build
+  backend from `action-requirements.txt`, hash-pinned, with `--require-hashes --no-deps
+  --no-build-isolation`; the release workflow moves a `v0` tag to each stable `v0.x.y` release.
+- **Fewer false positives from the independent review** (W4): installers of the project's own
+  GitHub organisation and homepage are known installers (read from the base ref when the scan has
+  one); Azure CLI, Flox, golangci-lint, Foundry, Flux and Linkerd are known installers; "do not tell
+  the user they …" is not concealment.
+- **`ghostrules baseline` and `scan --baseline / --no-baseline / --baseline-from-ref`**: record
+  today's findings as fingerprints (no line numbers, no snippets) and fail only on new ones. Hidden
+  text is never baselined. The Action reads the baseline at the base commit on pull requests, and
+  editing it is reported by GR030.
+- **Breaking: severity by visibility.** Plain visible prose in an agent file is now `low` (an
+  instruction) or `info` (a description or quotation) for GR010 to GR014 and GR016; text in an HTML
+  comment, decoded hidden text, files reached only through an import, GR015 and every configuration
+  rule keep their severity. A visible `curl | sh` or "send `.env` to a URL" no longer fails the
+  default check (`--fail-on high`). `--strict`, `profile = "strict"` in the config and the Action's
+  `profile: strict` restore the 0.3 behaviour.
+- **`lock --check --base REF`** (W3): compares with the lock and the config at `REF`, so a pull
+  request that edits what the agents read and regenerates `.ghostrules.lock` still fails. Exit 2 when
+  the ref or its lock does not exist. The idea is cairnlock's `verify --base`.
+- **Breaking: the Action's lock check uses the lock at the base on pull requests**, and a new
+  `approve-label` input lets a maintainer approve a legitimate change by applying a label; only the
+  event that applies it approves (new commits void it), and the summary names who and when. Output
+  `lock-approved`. `trust-repo-config: "true"` restores the working-tree lock.
+- **Inline ignores no longer hide text a reviewer cannot see** (W2): a finding inside an HTML
+  comment is never suppressed, and no ignore counts inside a file that an agent reaches only
+  through an import (the report says how many were not honoured). Decoded hidden text, GR001 and
+  GR002 were already never suppressed. An ignore on a visible line works as before.
+- **GR030, scanner configuration changed** (high): with a base ref, the change adds or edits
+  `.ghostrules.toml`, `[tool.ghostrules]`, the lockfile or a `ghostrules-ignore` comment. Reported
+  even when legitimate, never suppressible inline, and the change cannot disable it. A new `change`
+  scope of rules compares the scanned tree with the base.
+- **Breaking: the Action reads settings from the base commit on pull requests.** On
+  `pull_request` and `pull_request_target` events it passes `--config-from-ref` and
+  `--suppressions-from-ref` with the base SHA, fetching that commit if the checkout is shallow, and
+  fails with exit code 2 when it cannot read it. New inputs: `config`, `trust-repo-config` (default
+  `false`) and `inline-suppressions` (`base`, `off` or `all`; default `base`). Workflows that scan a
+  path outside a git repository on a pull request need `trust-repo-config: "true"` and
+  `inline-suppressions: all`. Other events behave as before.
+
+### Changed
+
+- **Corrected claims** (W1 of [docs/design/v0.4/REMEDIATION.md](docs/design/v0.4/REMEDIATION.md)).
+  The 0.2 statement that no other tool follows `@path` imports was wrong (cfgaudit does, since
+  2026-10-24): the prior-art notes are corrected and dated, and ghostrules no longer claims to be
+  the first or the only one. The README says "scheduled weekly; last run" instead of "every week".
+  The study report is now "A snapshot (2026-10-28)", puts hygiene statistics apart from security
+  indicators, shows a numerator and denominator next to each percentage, explains the MCP
+  denominator (a lower bound, so the share is an upper bound), counts benign-context matches as noise
+  in a per-rule precision table, and has a "Threats to validity" section. The 0.3.0 notes below are
+  left as published.
+- README restructured as a landing page; option tables, configuration, supported files, FAQ and limits
+  moved to `docs/USAGE.md`, and the rules table to `docs/RULES.md`.
+- SARIF `helpUri` points to `docs/RULES.md#grNNN` (the rules table moved there).
+
+### Known limits
+
+- Paraphrases, languages other than English and Spanish (GR013 has no Spanish patterns), a few read
+  verbs (`Open ~/.npmrc`), `exec(urlopen())`, endpoint overrides in settings and the descriptions an MCP
+  server serves are not caught: 14 of the 101 attack cases (`bench/RESULTS.md`).
+- Only 4 of the review's 18 evasion cases are in the attack set; the rest were not available.
+- The held-out labels are provisional (given by the assistant that ran the benchmark, not reviewed by a
+  person) and 21 findings are too few for a per-rule precision estimate.
+- The `context` tree does not show files reached by a prose reference, and the lock does not record
+  them; Codex and Gemini CLI models are opt-in.
+- The MCP share in the study is an upper bound (its denominator is a lower bound).
+
+## [0.3.0] - 2026-10-28
+
+Measurement release. ghostrules now runs against real repositories every week, a browser playground
+runs the real scanner without installing anything, and the first full study of popular repositories
+drove a round of precision fixes. On the 300-repository regression tier 0.2.1 reported 323 findings
+(84 critical, 156 high); 0.3.0 reports 212 (0 critical, 53 high), every critical and high finding
+reviewed. On the 1,283-repository study tier the first run reported 1,072 findings (13 critical, 296
+high); after the fixes 945 (12 critical, 252 high), all of medium and above triaged.
+
+### Added
+- **Playground** (`web/`, `.github/workflows/pages.yml`): a static page that runs the real scanner in
+  the browser with Pyodide. Paste a file, drop a folder (agent files and what they import, up to
+  5 MB) or name a public GitHub repo (the only tab that uses the network). Shows what you see versus
+  what the agent reads, the context tree per agent and downloadable JSON, Markdown and SARIF reports.
+  Playwright smoke test; deployed to GitHub Pages on release tags.
+- **Corpus tooling** (`corpus/`, outside the package and the wheel): `discover.py`, `run.py`,
+  `check.py`, `triage.py`, `badge.py`, `filestats.py`, a weekly `corpus.yml` workflow and an endpoint
+  badge in the README. Findings are labelled by fingerprint in `corpus/labels.toml`; labels never
+  name a repository for a reported finding.
+- **Study tooling** (`study/`): per-repository features, aggregate CSVs, SVG charts in light and dark,
+  the triage classes and `study/report.md`, generated from the CSVs.
+- `ghostrules.playground`, `ghostrules.reveal_data` and `ghostrules.reporters.context_data`: the core
+  (scanner, rules, context engine, JSON, SARIF and Markdown reporters) now imports without `typer`
+  and `rich`; the terminal output is unchanged.
+- `action.yml` is named `ghostrules scan` and its description fits the Marketplace limit (125
+  characters).
+
+### Fixed
+- GR003: a lone U+200B between two letters of Khmer, Thai, Lao or Myanmar text is that script's word
+  separator and is ignored.
+- GR005: a hidden comment is `medium` when it carries an instruction cue, `low` when it only mentions
+  agents, `high` unchanged for injection matches.
+- GR010: `override system|safety` needs a following noun, and defensive text that quotes the phrase
+  is `low`.
+- GR011: `without asking the user` is no longer concealment; a prohibition earlier in the clause, a
+  safety claim ("does not silently install"), a description in the third person ("silently runs") and
+  a modal before it are not reported.
+- GR012: naming the `curl | sh` pattern without a target is `low`; a `curl` in prose no longer joins
+  the next code block; `| bash script.sh` is not a data pipe into the shell.
+- GR013: needs a verb, a secret and a URL in the same clause; prohibitions, loopback URLs, `POST`
+  and `.post(`, "send the user to" and "send X only to the fixed origin" are not exfiltration.
+- GR014: the verb must govern the path across no paragraph break, clause connector (`before`,
+  `after`, `when`), passive or noun use; `### Output` is a heading; `.env.default` and copying a
+  dotenv file are not reads.
+- GR015: runs inside URLs, Subresource Integrity digests and low-entropy hex (`AAAA…`) are skipped.
+- GR016: a prohibition ("Avoid `--yolo`"), a table row and a list item that documents a flag are not
+  an instruction.
+- A bare `@/`, `@~/`, `@./` or `@../` is a path prefix, not an import.
+
+### Known limits
+- Splitting an exfiltration instruction across two sentences avoids the GR013 prose match, and a
+  concealment right after an unrelated prohibition in the same clause is not reported.
+
+## [0.2.1] - 2026-10-28
+
+Precision release. A scan of 12 popular public repositories with 0.2.0 found no critical issue,
+but every `high` finding was a false positive, and `context` was wrong for the most common real
+setup. On those repositories 0.2.0 reported 9 high, 18 medium and 8 low findings; 0.2.1 reports
+2 medium and 2 low, with no high, no critical and no GR025.
+
+### Added
+- `ghostrules context --format json` entries carry `alias_of` (and `link_problem`) when a symlink is
+  involved; lock entries carry `link` for an alias. Both keys are omitted otherwise.
+- `ghostrules.rules.directive.classify`: the helper that tells directive, descriptive and example
+  text apart (used by GR011, GR014 and GR016).
+
+### Fixed
+- A symbolic link whose final target is a regular file inside the repository is now an **alias**:
+  `CLAUDE.md -> AGENTS.md` (the setup Claude Code documents) is loaded under the link's name,
+  `context` shows `CLAUDE.md → AGENTS.md (symlink)` and the `AGENTS.md` entry as already read, the
+  content is scanned once (findings say `via CLAUDE.md (symlink)`), and `lock` records the link and
+  its target. Chains of up to 8 links and in-repository directory links work the same way. Nothing
+  is opened before the resolved path is known to be inside the repository.
+  GR025 now fires only for links that leave the repository (`high`) or are broken, cyclic or too
+  long (`low`), instead of one `medium` per link, and adds an `info` note for a link checked out as
+  a text file (Windows with `core.symlinks=false`).
+- GR022 no longer reports npm scopes and mentions (`@n8n/design-system`, `@cline/llms`, `@types/node`)
+  as imports that do not load. It reports a token only if it has a file extension, starts with `./`,
+  `../`, `~/` or `/`, or its first directory exists next to the importing file.
+- GR011, GR014 and GR016 tell instructions from descriptions and examples. A match in prose that
+  describes something ("The scripts read `~/.npmrc`", "The harness runs Claude with
+  `bypassPermissions`") is at most `medium`; in a fenced block, in quotes or after "e.g.", "such
+  as", "a skill that ..." it is at most `low`; imperative text and decoded hidden text keep their
+  severity. A lowered finding says why.
+  - GR011: "do not tell the user to/which/what/how ..." is no longer concealment.
+  - GR014: the verb must govern the path (same clause, six words at most) and template files
+    (`.env.example`, `*.example`, `.env.ai-surfaces.example`) never fire.
+- GR012: `curl ... | python -c`, `| python -m`, `| python script.py`, `| sh -c '...'` use stdin as
+  data and are no longer reported; `| python`, `| python -` and `| sh` still are. The Claude Code
+  installer (`https://claude.ai/install.sh`) is a known installer. GR105 and GR107 share these
+  patterns and follow.
+
+### Changed
+- README: the new tagline is the only one (the old one opens the first paragraph), the import-chain
+  GIF comes first and the hidden-Unicode GIF sits further down, both by absolute URL.
+- The original `SPEC.md`, `PLAN.md` and the per-version design documents moved to `docs/design/`
+  (design history, not kept up to date). `RULES.md`, `AGENT_MODELS.md` and `DECISIONS.md` stay in
+  `docs/`.
+
+## [0.2.0] - 2026-10-28
+
+Know exactly what your agent reads: `ghostrules` now models how each agent loads its instructions,
+scans exactly that, shows it, and pins it.
+
+### Added
+- GitHub Action inputs `follow-imports` (default `true`) and `lock-check` (default `false`). With
+  `lock-check` the action runs `ghostrules lock --check`, puts the differences in the job summary
+  under "What your agents read changed in this PR" and fails the job if there are any; new output
+  `lock-exit-code`.
+- Config keys `follow_imports`, `agents` and `lockfile`.
+- `python scripts/make_demo.py --lock-scenario DEST` and the tapes `demo/imports.tape` and
+  `demo/lock.tape` for the 0.2 GIFs.
+- `ghostrules lock`: writes `.ghostrules.lock`, a deterministic record (sorted keys, no timestamps,
+  CRLF-normalised hashes) of every file in each modelled agent's context, how it is reached, and
+  the text the agent actually receives, plus a hash of every MCP and agent settings file.
+  `lock --check` recomputes it and shows what changed (added, changed, removed, and changes that
+  only touch text an agent strips), with invisible characters revealed; exit 0 up to date, 1
+  changed, 2 error. `--format text|markdown|json`, `--update`, `--lockfile`; config key `lockfile`.
+- `ghostrules context [TARGET]`: shows what an agent reads when it works on a file (the files it
+  loads at session start, the rules its `paths`/`globs` select, the directories that load on
+  demand, the imports it follows and the files it skips, with the reason) and scans exactly that.
+  Output as a tree, JSON or Markdown; `--agent`, `--cwd`, `--root`, `--show-text`, `--no-scan`,
+  `--home`, `--fail-on`.
+- `examples/import-chain-repo`: a CLAUDE.md that looks clean and reaches a hidden payload through two
+  imports, plus a `.env` import and one outside the repository.
+- `scan` follows `@path` imports by default: files an instruction file imports are scanned as
+  instructions, and their findings carry the import chain (`via`), the agents that load them and the
+  tag `reached-via-import`. `--no-follow-imports` (or `follow_imports = false`) turns it off.
+- Rules GR020 (external import), GR021 (sensitive file imported), GR022 (import that silently does
+  not load), GR023 (import cycle), GR024 (tag for payloads reached through an import) and GR025
+  (symlinked instruction source).
+- The files each modelled agent loads (including `.claude/rules/**`) are scanned even when the
+  discovery globs do not list them. New config keys `follow_imports` and `agents`.
+- JSON findings gain optional `via`, `agents` and `tags`; SARIF results gain `relatedLocations` for
+  the chain and `properties.agents`/`tags`; the table and Markdown reports show the chain.
+
+- `docs/AGENT_MODELS.md`: how each agent loads its instructions, with the documentation it is based on
+  and what is still unverified; `CONTRIBUTING.md` explains how to add a model.
+- `ghostrules` locks its own `CLAUDE.md` (`.ghostrules.lock`), checked in CI.
+
+### Changed
+- GR005 is agent-aware: it says which agents see a hidden comment. Claude Code strips block-level
+  comments from CLAUDE.md files, so the finding is info when no configured agent sees the comment.
+
+## [0.1.1] - 2026-10-27
+
+### Changed
+- GR012 (remote code execution pattern) now sets its severity from context instead of reporting
+  every `curl ... | sh` as critical. A well-known installer in a code block is low, in prose
+  medium; an unknown domain is high in a code block and critical in prose. Plain `http://`, IP
+  literals, non-default ports, collector domains, opaque payloads (`base64 -d | sh`,
+  `powershell -enc`) and text hidden by invisible characters stay critical. This stops the default
+  `--fail-on high` from failing on real repositories that document `uv` or `rustup`.
+  GR105 and GR107 (MCP server commands and hooks) are unchanged.
+
+### Added
+- Built-in list of well-known installers (uv/ruff, rustup, Bun, Deno, pnpm, Poetry, Homebrew, nvm,
+  SDKMAN, Docker, Ollama, Volta), matched on the exact host and optional path prefix, and
+  `ghostrules rules --installers` to print it.
+- `trust_known_installers` option (default `true`); `false` restores the 0.1.0 behaviour.
+- Inline code span awareness for GR012 (`ScanTarget.code_span_at`).
+
+## [0.1.0] - 2026-10-27
+
+First release.
+
+### Added
+- Scanner for the files AI coding agents read and obey (`AGENTS.md`, `CLAUDE.md`, `.cursorrules`,
+  Copilot instructions, skills, MCP configs, agent settings and more), with `--home` for
+  user-level configs and `--all-files` for hidden Unicode anywhere in a tree.
+- 21 rules. Hidden content: Unicode tag characters (GR001), bidirectional controls (GR002),
+  zero-width characters (GR003), variation-selector steganography (GR004), hidden HTML comments
+  (GR005), mixed-script homoglyphs (GR006). Malicious instructions, English and Spanish: instruction
+  override (GR010), concealment (GR011), remote code execution (GR012), data exfiltration (GR013),
+  sensitive file access (GR014), encoded payloads (GR015), safety bypass (GR016). Configuration:
+  hardcoded secrets (GR101), unpinned packages (GR102), insecure transport (GR103), broad
+  filesystem scope (GR104), shell wrappers (GR105), dangerous Docker options (GR106),
+  over-permissive agent settings (GR107), auto-trusted MCP servers (GR108).
+- Hidden text decoded by GR001, GR004 and GR015 is re-scanned by GR010-GR016 and reported with
+  one more level of severity.
+- CLI: `scan` (the default command), `reveal`, `clean`, `rules`, `version`. Reports as a table
+  grouped by file with the decoded hidden text highlighted, JSON, SARIF 2.1.0 (validated against the
+  official schema) and Markdown. Exit codes: 0 clean, 1 findings at or above `--fail-on`, 2 error.
+- Configuration through `.ghostrules.toml` or `[tool.ghostrules]`, and inline `ghostrules-ignore`
+  suppressions (never for GR001, GR002 or text found inside hidden characters).
+- GitHub Action (SARIF upload to code scanning, job summary, `fail-on` gate), pre-commit hook, CI
+  with a smoke test and a self-scan, and a tag-triggered release workflow using PyPI Trusted
+  Publishing.
+- Demo repositories `examples/poisoned-repo` (every rule fires) and `examples/clean-repo` (no
+  findings), and `demo/demo.tape` to record the README GIF.
+
+### Security
+- Read-only: nothing found in a scanned file is executed, imported, downloaded or sent anywhere,
+  and the tool makes no network requests. Symbolic links are not followed.
+- Secrets are never printed: every finding, warning and error passes through one masking step
+  (`ghp_****…a1b2`), and a test fails if a secret appears in any report format.

{ghostrules-0.2.1 → ghostrules-0.4.0}/CLAUDE.md

@@ -5,7 +5,7 @@
 machine) for **hidden instructions and risky configuration in the files AI coding agents read and
 obey**: `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, Copilot instructions, skills, MCP configs, etc.
 
-Tagline: *"Find the instructions your AI agent sees but you don't."*
+Tagline: *"Know exactly what your AI agent reads — and approve every change to it."*
 
 It is a **defensive** security tool. It only reads files and reports findings. It never executes
 anything it finds, never makes network requests, and never phones home.