ghostrules 0.1.0__tar.gz

ghostrules-0.1.0/.ghostrules.toml

@@ -0,0 +1,10 @@
+# ghostrules scanning its own repository: the demos and fixtures are poisoned on purpose.
+exclude = [
+  "examples/**",
+  "tests/fixtures/**",
+  "dist/**",
+  "build/**",
+  ".mypy_cache/**",
+  ".ruff_cache/**",
+  ".pytest_cache/**",
+]

ghostrules-0.1.0/.gitattributes

@@ -0,0 +1,5 @@
+# Keep line endings stable: the demo repositories and fixtures are byte-exact (they contain
+# invisible characters and tests compare them with what the generators write).
+* text=auto eol=lf
+examples/** -text
+tests/fixtures/** -text

ghostrules-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Report a security vulnerability
+    url: https://github.com/BardLaudian/ghostrules/security/advisories/new
+    about: Please report vulnerabilities in ghostrules itself privately, not in a public issue.

ghostrules-0.1.0/.github/ISSUE_TEMPLATE/false-positive.yml

@@ -0,0 +1,49 @@
+name: False positive
+description: ghostrules reported something that is not a problem.
+title: "[false positive] GRxxx: "
+labels: ["false-positive"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting it. **Do not paste real secrets or private files.** Reduce the content to
+        a small, defanged example (use `example.com`, fake tokens). If the finding involves invisible
+        characters, say which ones (for example the output of `ghostrules reveal FILE`).
+  - type: input
+    id: version
+    attributes:
+      label: ghostrules version
+      description: Output of `ghostrules version`.
+    validations:
+      required: true
+  - type: input
+    id: rule
+    attributes:
+      label: Rule
+      description: The rule that fired, for example GR013.
+      placeholder: GR013
+    validations:
+      required: true
+  - type: textarea
+    id: input
+    attributes:
+      label: Minimal file that triggers it
+      description: The smallest defanged snippet that reproduces the finding, and its file name.
+      render: text
+    validations:
+      required: true
+  - type: textarea
+    id: output
+    attributes:
+      label: What ghostrules printed
+      description: The finding (`ghostrules scan --no-color FILE`).
+      render: text
+    validations:
+      required: true
+  - type: textarea
+    id: why
+    attributes:
+      label: Why it is legitimate
+      description: What the text is for, and how a rule could tell it apart from a real problem.
+    validations:
+      required: true

ghostrules-0.1.0/.github/ISSUE_TEMPLATE/new-rule.yml

@@ -0,0 +1,52 @@
+name: New rule proposal
+description: Suggest a new detection, or a missed one (false negative).
+title: "[rule] "
+labels: ["new-rule"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Good rules are precise: they say what to look for, why it is dangerous in a file an agent
+        obeys, and what must **not** match. **Use defanged examples only** (`example.com`, fake
+        tokens), never working payloads.
+  - type: textarea
+    id: threat
+    attributes:
+      label: The risk
+      description: What can an attacker do with it, and which agent or file does it affect? Link a primary source if there is one.
+    validations:
+      required: true
+  - type: textarea
+    id: positive
+    attributes:
+      label: Should be reported
+      description: One or more defanged examples that the rule must flag, with the file name.
+      render: text
+    validations:
+      required: true
+  - type: textarea
+    id: negative
+    attributes:
+      label: Must not be reported
+      description: Legitimate examples that look similar and must stay quiet.
+      render: text
+    validations:
+      required: true
+  - type: dropdown
+    id: severity
+    attributes:
+      label: Suggested severity
+      options: [critical, high, medium, low, info]
+    validations:
+      required: true
+  - type: textarea
+    id: detection
+    attributes:
+      label: Detection idea
+      description: A pattern, a heuristic or a config check. Optional but helpful.
+  - type: checkboxes
+    id: contribute
+    attributes:
+      label: Contribution
+      options:
+        - label: I can send a pull request (see CONTRIBUTING.md).

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

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        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
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check .
+      - name: Format check
+        run: ruff format --check .
+      - name: Test
+        run: pytest -q
+      - name: Smoke test the demos
+        shell: bash
+        run: |
+          ghostrules scan examples/clean-repo
+          code=0
+          ghostrules scan examples/poisoned-repo --no-color > /dev/null || code=$?
+          test "$code" = "1"
+      - name: ghostrules scans its own repository
+        shell: bash
+        run: |
+          ghostrules scan . --no-color
+          ghostrules scan . --all-files --no-color

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

@@ -0,0 +1,77 @@
+name: Release
+
+# Push a tag like v0.1.0 to publish. PyPI uses Trusted Publishing (OIDC): there is no API token
+# in this repository. One-time setup on PyPI: add a "pending publisher" for this repository,
+# workflow "release.yml" and environment "pypi".
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: The tag must match the package version
+        env:
+          TAG: ${{ github.ref_name }}
+        run: |
+          python - <<'PY'
+          import os, re
+          version = re.search(r'__version__ = "([^"]+)"', open("src/ghostrules/__init__.py").read()).group(1)
+          tag = os.environ["TAG"].removeprefix("v")
+          assert version == tag, f"tag {tag} does not match __version__ {version}"
+          PY
+
+      - name: The changelog must have release notes for this tag
+        env:
+          TAG: ${{ github.ref_name }}
+        run: python scripts/changelog_section.py "$TAG" > release-notes.md
+
+      - name: Build
+        run: |
+          python -m pip install --disable-pip-version-check --quiet build
+          python -m build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: |
+            dist/
+            release-notes.md
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+      - name: Create the GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ github.ref_name }}
+          REPO: ${{ github.repository }}
+        run: gh release create "$TAG" dist/* --repo "$REPO" --title "$TAG" --notes-file release-notes.md

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

@@ -0,0 +1,73 @@
+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

ghostrules-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+*.ghostrules.bak
+ghostrules.sarif

ghostrules-0.1.0/.pre-commit-hooks.yaml

@@ -0,0 +1,9 @@
+- id: ghostrules
+  name: ghostrules (hidden instructions in AI agent files)
+  description: >-
+    Scan the repository for hidden Unicode, malicious instructions and risky MCP/agent
+    configuration in AGENTS.md, CLAUDE.md, .cursorrules, skills, MCP configs and similar files.
+  entry: ghostrules scan
+  language: python
+  pass_filenames: false
+  minimum_pre_commit_version: "3.0.0"

ghostrules-0.1.0/CHANGELOG.md

@@ -0,0 +1,41 @@
+# 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.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/CLAUDE.md

@@ -0,0 +1,60 @@
+# ghostrules — project memory for Claude Code
+
+## What this project is
+`ghostrules` is a Python CLI + GitHub Action that scans a repository (and optionally the user's
+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."*
+
+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.
+
+## Source-of-truth documents (read before coding)
+- `docs/SPEC.md` — features, CLI, file targets, output formats, config. **The contract.**
+- `docs/RULES.md` — every detection rule: ID, severity, logic, true/false positive examples.
+- `docs/PLAN.md` — build order, phase by phase, with acceptance criteria.
+
+If something in the code disagrees with these docs, the docs win unless the user says otherwise.
+If a doc is ambiguous, pick the simplest reasonable option and note it in `docs/DECISIONS.md`.
+
+## Tech stack
+- Python **3.10+**, packaged with `pyproject.toml` (hatchling), src layout: `src/ghostrules/`.
+- CLI: **typer**; terminal output: **rich**. TOML config: `tomllib` (3.11+) / `tomli` fallback.
+- No other runtime dependencies unless clearly justified. **No network libraries at runtime.**
+- Dev: `pytest`, `pytest-cov`, `ruff` (lint + format), `mypy` (lenient is fine).
+
+## Commands
+```bash
+pip install -e ".[dev]"          # install for development
+pytest -q                        # run tests
+ruff check . && ruff format .    # lint + format
+ghostrules scan examples/poisoned-repo   # manual smoke test (must find issues)
+ghostrules scan examples/clean-repo      # must report zero findings
+```
+
+## Code conventions
+- Each rule is a small class/function in `src/ghostrules/rules/` registered in one registry.
+  Rules receive a parsed `ScanTarget` (path, kind, text, lines, parsed JSON/TOML if any) and
+  yield `Finding` objects. Rules must be pure: no I/O, no global state.
+- `Finding` fields: `rule_id, severity, title, message, path, line, column, end_column, snippet,
+  decoded (optional str), fix_hint`.
+- Severities: `critical > high > medium > low > info`.
+- Snippets must render invisible characters visibly, e.g. `⟦U+200B ZERO WIDTH SPACE⟧`.
+- **Secrets must always be masked** in every output format (`ghp_****…a1b2`).
+- Type hints everywhere; small functions; docstrings on public functions.
+- Every rule needs at least one positive and one negative test.
+
+## Safety rules for this repo (important)
+- Test fixtures and demo files must be **defanged**: use `attacker.example`, `example.com`,
+  `exfil.example`, fake tokens like `ghp_EXAMPLEEXAMPLEEXAMPLEEXAMPLE0000` — never real
+  domains, real webhooks or working payloads.
+- Fixtures containing invisible characters are **generated by `scripts/make_fixtures.py`**,
+  not hand-typed, so they are reproducible and reviewable.
+- Never add code that executes, downloads or evaluates scanned content.
+
+## Workflow
+- Work phase by phase following `docs/PLAN.md`. After each phase: run tests + ruff, then
+  stop and summarize what was done and what is next.
+- Commit after each phase with a conventional commit message (`feat:`, `test:`, `docs:`…).
+- Keep the README in English and keep it updated when CLI flags change.

ghostrules-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,80 @@
+# Contributing to ghostrules
+
+Thanks for helping. A noisy scanner gets uninstalled, so **precision matters as much as
+coverage**: every change to a detection comes with a positive and a negative test.
+
+## Set up
+
+```bash
+git clone https://github.com/BardLaudian/ghostrules && cd ghostrules
+python -m venv .venv && . .venv/bin/activate      # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+
+pytest -q                         # tests
+ruff check . && ruff format .     # lint and format
+mypy src                          # types (lenient is fine)
+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
+them in the same pull request.
+
+## Add a rule in three steps
+
+1. **Write the rule.** Add a function to the module that fits (`src/ghostrules/rules/unicode.py`,
+   `injection.py`, `mcp.py` or `agent_settings.py`) and register it with the decorator:
+
+   ```python
+   @rule(
+       "GR017",                       # next free id: GR0xx = instruction files, GR1xx = config
+       Severity.HIGH,                 # typical severity
+       "Short title",
+       "One sentence on what it finds and why it matters.",
+       ("instructions",),             # file kinds it applies to
+       scans_decoded=True,            # also run on hidden text decoded by other rules?
+   )
+   def gr017_something(target: ScanTarget) -> Iterator[Finding]:
+       ...
+       yield build_finding(target=target, rule_id="GR017", ...)
+   ```
+
+   Rules are **pure**: they receive a `ScanTarget` and yield `Finding`s, with no I/O and no global
+   state. Use `build_finding` so line, column, snippet and secret masking come out right. Put
+   shared regular expressions in `rules/patterns.py`.
+
+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.
+   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
+   positive examples), note any judgement call in `docs/DECISIONS.md`, add a line to
+   `CHANGELOG.md`, then refresh the README table:
+
+   ```bash
+   python scripts/make_demo.py
+   python scripts/gen_rules_table.py --write
+   ```
+
+## Rules of the repository
+
+- **Defanged only.** Fixtures, demos and tests use `attacker.example`, `exfil.example`,
+  `example.com` and obviously fake tokens such as `ghp_` + `EXAMPLE` repeated. Never real
+  domains, real webhooks or working payloads.
+- **Invisible characters are generated, never typed.** Write them as escapes or with `chr()` in
+  the generators. A test fails if a literal invisible character ends up in the sources.
+- **Never execute, download or evaluate scanned content**, and no network libraries at runtime.
+- **Secrets are always masked.** Anything that prints text from a scanned file goes through
+  `ghostrules.secrets.mask_secrets` (findings do it for you).
+- Type hints everywhere, small functions, docstrings on public functions, English README.
+- Conventional commits (`feat:`, `fix:`, `test:`, `docs:`...).
+
+## Pull request checklist
+
+- [ ] `pytest -q`, `ruff check .`, `ruff format --check .` and `mypy src` pass
+- [ ] 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
+- [ ] nothing real in the fixtures: no secrets, domains or payloads that work

ghostrules-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pablo Seoane Temprano
+
+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.