ghostrules 0.1.0__tar.gz → 0.2.0__tar.gz

ghostrules-0.2.0/.ghostrules.lock

@@ -0,0 +1,31 @@
+{
+  "agents": {
+    "claude-code": [
+      {
+        "conditions": [],
+        "lines": "2a3d3f1fb26381e9 e3b0c44298fc1c14 ddabff43c0a4efe5 6aa552cc1598dcb7 be186e6b970ab643 fb78540ec32b52f9 e3b0c44298fc1c14 d393a517d5cbec9f e3b0c44298fc1c14 85b7ae55df076ab0 2f6995b0ecd75c8d e3b0c44298fc1c14 5f2235a1b010f82c 030e09c253572539 ba2cd86d7e76eff5 3b81b7bc3295aca9 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 8e5a481cbb86370a f75f6ee8f0d942eb 1f59b655e6071114 da29957f3e8be475",
+        "load": "always",
+        "path": "CLAUDE.md",
+        "raw_sha256": "dc7776630751bba0d3c39e83e96b3b6dae1de7cd5630b49e3b0f7853bbbf1f3f",
+        "seen_sha256": "dc7776630751bba0d3c39e83e96b3b6dae1de7cd5630b49e3b0f7853bbbf1f3f",
+        "via": []
+      }
+    ],
+    "copilot-cli": [
+      {
+        "conditions": [],
+        "lines": "2a3d3f1fb26381e9 e3b0c44298fc1c14 ddabff43c0a4efe5 6aa552cc1598dcb7 be186e6b970ab643 fb78540ec32b52f9 e3b0c44298fc1c14 d393a517d5cbec9f e3b0c44298fc1c14 85b7ae55df076ab0 2f6995b0ecd75c8d e3b0c44298fc1c14 5f2235a1b010f82c 030e09c253572539 ba2cd86d7e76eff5 3b81b7bc3295aca9 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 8e5a481cbb86370a f75f6ee8f0d942eb 1f59b655e6071114 da29957f3e8be475",
+        "load": "always",
+        "path": "CLAUDE.md",
+        "raw_sha256": "dc7776630751bba0d3c39e83e96b3b6dae1de7cd5630b49e3b0f7853bbbf1f3f",
+        "seen_sha256": "dc7776630751bba0d3c39e83e96b3b6dae1de7cd5630b49e3b0f7853bbbf1f3f",
+        "via": []
+      }
+    ],
+    "cursor": [],
+    "generic": []
+  },
+  "configs": [],
+  "generator": "ghostrules 0.2.0",
+  "lock_version": 1
+}

{ghostrules-0.1.0 → ghostrules-0.2.0}/.github/workflows/ci.yml

@@ -38,3 +38,4 @@ jobs:
         run: |
           ghostrules scan . --no-color
           ghostrules scan . --all-files --no-color
+          ghostrules lock --check --no-color

ghostrules-0.2.0/.github/workflows/self-test.yml

@@ -0,0 +1,153 @@
+name: Self-test
+
+# Runs the action from this very checkout against the demo repositories.
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  action:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Poisoned demo with fail-on none (must pass, must report findings)
+        id: poisoned
+        uses: ./
+        with:
+          path: examples/poisoned-repo
+          fail-on: none
+          upload-sarif: "false"
+
+      - name: SARIF must contain results, led by the hidden instruction
+        run: |
+          python - <<'PY'
+          import json
+          run = json.load(open("ghostrules.sarif"))["runs"][0]
+          results = run["results"]
+          assert len(results) > 10, f"expected many results, got {len(results)}"
+          ids = {r["ruleId"] for r in results}
+          assert {"GR001", "GR012", "GR101"} <= ids, ids
+          assert results[0]["ruleId"] == "GR001", results[0]["ruleId"]
+          assert run["tool"]["driver"]["rules"], "rules missing"
+          print(f"ok: {len(results)} results")
+          PY
+
+      - name: The exit-code output is 0
+        env:
+          EXIT_CODE: ${{ steps.poisoned.outputs.exit-code }}
+        run: test "$EXIT_CODE" = "0"
+
+      - name: Poisoned demo with the default fail-on (must fail the step)
+        id: gate
+        uses: ./
+        continue-on-error: true
+        with:
+          path: examples/poisoned-repo
+          upload-sarif: "false"
+
+      - name: The gate must have failed
+        env:
+          OUTCOME: ${{ steps.gate.outcome }}
+          EXIT_CODE: ${{ steps.gate.outputs.exit-code }}
+        run: |
+          test "$OUTCOME" = "failure"
+          test "$EXIT_CODE" = "1"
+
+      - name: Clean demo (must pass with no results)
+        uses: ./
+        with:
+          path: examples/clean-repo
+          upload-sarif: "false"
+
+      - name: SARIF must be empty
+        run: |
+          python - <<'PY'
+          import json
+          results = json.load(open("ghostrules.sarif"))["runs"][0]["results"]
+          assert results == [], results
+          PY
+
+  import-chain:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Import-chain demo, following imports (default)
+        uses: ./
+        with:
+          path: examples/import-chain-repo
+          fail-on: none
+          upload-sarif: "false"
+
+      - name: SARIF must carry the hidden payload with the import chain that reaches it
+        run: |
+          python - <<'PY'
+          import json
+          results = json.load(open("ghostrules.sarif"))["runs"][0]["results"]
+          ids = {r["ruleId"] for r in results}
+          assert {"GR001", "GR020", "GR021"} <= ids, ids
+          hidden = next(r for r in results if r["ruleId"] == "GR001")
+          chain = [l["physicalLocation"]["artifactLocation"]["uri"] for l in hidden["relatedLocations"]]
+          assert chain == ["CLAUDE.md", "docs/style.md"], chain
+          assert hidden["locations"][0]["physicalLocation"]["artifactLocation"]["uri"] == "shared/team-rules.md"
+          assert "reached-via-import" in hidden["properties"]["tags"]
+          print(f"ok: {len(results)} results")
+          PY
+
+      - name: Import-chain demo with follow-imports off (a 0.1-style scan finds nothing)
+        uses: ./
+        with:
+          path: examples/import-chain-repo
+          follow-imports: "false"
+          upload-sarif: "false"
+
+      - name: SARIF must be empty
+        run: |
+          python - <<'PY'
+          import json
+          results = json.load(open("ghostrules.sarif"))["runs"][0]["results"]
+          assert results == [], results
+          PY
+
+      - name: Lock a copy of the demo, then make a pull-request-like change to another copy
+        run: |
+          python scripts/make_demo.py --lock-scenario "$RUNNER_TEMP/acme"
+          ghostrules lock --root "$RUNNER_TEMP/acme/base"
+          cp "$RUNNER_TEMP/acme/base/.ghostrules.lock" "$RUNNER_TEMP/acme/pr/"
+
+      - name: Lock check on the unchanged repository (must pass)
+        id: unchanged
+        uses: ./
+        with:
+          path: ${{ runner.temp }}/acme/base
+          fail-on: none
+          lock-check: "true"
+          upload-sarif: "false"
+
+      - name: The unchanged lock exit code is 0
+        env:
+          LOCK_EXIT_CODE: ${{ steps.unchanged.outputs.lock-exit-code }}
+        run: test "$LOCK_EXIT_CODE" = "0"
+
+      - name: Lock check after the pull request (must fail the step)
+        id: changed
+        uses: ./
+        continue-on-error: true
+        with:
+          path: ${{ runner.temp }}/acme/pr
+          fail-on: none
+          lock-check: "true"
+          upload-sarif: "false"
+
+      - name: The changed lock must have failed with exit code 1
+        env:
+          OUTCOME: ${{ steps.changed.outcome }}
+          LOCK_EXIT_CODE: ${{ steps.changed.outputs.lock-exit-code }}
+        run: |
+          test "$OUTCOME" = "failure"
+          test "$LOCK_EXIT_CODE" = "1"

ghostrules-0.2.0/CHANGELOG.md

@@ -0,0 +1,104 @@
+# 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.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.1.0 → ghostrules-0.2.0}/CONTRIBUTING.md

@@ -17,8 +17,9 @@ ghostrules scan examples/poisoned-repo   # must find issues, exit code 1
 ghostrules scan examples/clean-repo      # must report nothing, exit code 0
 ```
 
-The documents in `docs/` are the contract: `SPEC.md` (features), `RULES.md` (every rule) and
-`DECISIONS.md` (choices made where they were ambiguous). If code and docs disagree, fix one of
+The documents in `docs/` are the contract: `SPEC.md` (features), `RULES.md` (every rule),
+`AGENT_MODELS.md` (how each agent loads its instructions, with sources) and `DECISIONS.md`
+(choices made where they were ambiguous). `docs/v0.2/` holds the 0.2 design documents. If code and docs disagree, fix one of
 them in the same pull request.
 
 ## Add a rule in three steps
@@ -46,7 +47,8 @@ them in the same pull request.
 
 2. **Test it.** Add at least one positive and one negative test (see `tests/test_rules_*.py`). Add
    a case to `scripts/make_demo.py` so `examples/poisoned-repo` triggers the rule (a test fails
-   if any rule does not fire there) and make sure `examples/clean-repo` still reports nothing.
+   if a `GR00x`, `GR01x` or `GR1xx` rule does not fire there; the import rules `GR02x` are tested
+   in `tests/test_scan_imports.py`) and make sure `examples/clean-repo` still reports nothing.
    Fixtures with invisible characters are generated by `scripts/make_fixtures.py`.
 
 3. **Document it.** Describe the rule in `docs/RULES.md` (ID, severity, logic, true and false
@@ -58,6 +60,32 @@ them in the same pull request.
    python scripts/gen_rules_table.py --write
    ```
 
+## Add an agent model
+
+`ghostrules context` and `ghostrules lock` need to know how an agent loads its instructions. A
+model is one module, one section of `docs/AGENT_MODELS.md` and its tests:
+
+1. **Write down what the agent's documentation says** in a new section of `docs/AGENT_MODELS.md`:
+   which files it reads and in what order, which are conditional or loaded on demand, whether it
+   follows `@` imports (relative to what, how deep), what it strips before the model sees the text,
+   and the page and date you checked. Anything the documentation does not state is marked
+   **UNVERIFIED** and modelled conservatively (a file the agent might read is included). Model only
+   what is written there.
+2. **Implement it** in `src/ghostrules/agents/<name>.py` with a `build(repo, *, cwd, target, home)`
+   method that returns a `ContextGraph`. Use the `Builder` in `agents/base.py`: it reads files
+   safely (never through a symlink), applies your text transforms (`render_*`), follows imports
+   with the `ImportPolicy` you pass, hashes the result and records the edges. Register the model in
+   `agents/__init__.py` (`AGENT_NAMES`, `get_model`) and in `config.AGENT_NAMES`. Use
+   `globs.matches_any` for `paths`/`globs`/`applyTo` and `markdown_utils.parse_frontmatter` for
+   front matter.
+3. **Test it with a fake repository** built in `tmp_path` (see `tests/test_agents_claude.py`):
+   given the tree, the working directory and the target, the ordered entries, their `load`
+   states, `matches` and `unverified` flags must be what the documentation implies. Add the
+   precedence and depth cases that apply to the agent.
+4. **Say what you could not model** (user-level or organisation settings, environment variables)
+   in `ContextGraph.notes`, and add a line to `CHANGELOG.md` and a decision to
+   `docs/DECISIONS.md` for every judgement call.
+
 ## Rules of the repository
 
 - **Defanged only.** Fixtures, demos and tests use `attacker.example`, `exfil.example`,
@@ -77,4 +105,6 @@ them in the same pull request.
 - [ ] positive and negative tests for every new or changed detection
 - [ ] `examples/poisoned-repo` still triggers every rule; `examples/clean-repo` is still clean
 - [ ] `docs/RULES.md`, `docs/DECISIONS.md`, `CHANGELOG.md` and the README table are updated
+- [ ] for an agent model: `docs/AGENT_MODELS.md` cites the documentation and the date, and the
+      unverified parts are marked
 - [ ] nothing real in the fixtures: no secrets, domains or payloads that work