siftscan 0.1.0__tar.gz

siftscan-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Baran Ayaztaş
+
+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.

siftscan-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: siftscan
+Version: 0.1.0
+Summary: Scan AI agent instruction files (CLAUDE.md, .cursorrules, AGENTS.md, mcp.json) for hidden or planted instructions.
+Author: Baran Ayaztas
+License: MIT
+Project-URL: Homepage, https://github.com/ReazGan/sift
+Project-URL: Issues, https://github.com/ReazGan/sift/issues
+Keywords: security,prompt-injection,supply-chain,llm,ai-agents,cursor,claude,copilot,mcp,static-analysis,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: rich>=13.7
+Dynamic: license-file
+
+# sift
+
+[![CI](https://github.com/ReazGan/sift/actions/workflows/ci.yml/badge.svg)](https://github.com/ReazGan/sift/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/siftscan)](https://pypi.org/project/siftscan/)
+
+Scan AI agent instruction files for hidden or planted instructions.
+
+Your repo now ships files that tell an assistant what to do: `CLAUDE.md`,
+`.cursorrules`, `AGENTS.md`, Copilot instructions, `mcp.json`. A human skims
+them in a diff; the model obeys every byte. That gap is where an attacker hides
+a command, pulled in through a cloned starter, a dependency, or a pull request.
+sift reads those files the way the model does and flags what a reviewer can't
+see: invisible characters, instructions buried in comments, "ignore previous
+instructions" payloads, data-exfiltration steps, and risky MCP configs.
+
+Runs offline. No network calls, nothing leaves your machine.
+
+![sift flagging invisible smuggled text, a hidden comment and a risky MCP config](https://raw.githubusercontent.com/ReazGan/sift/main/docs/screenshot.svg)
+
+## Install
+
+```
+pip install siftscan
+```
+
+or, to keep it isolated:
+
+```
+pipx install siftscan
+```
+
+The command is `sift`.
+
+## Usage
+
+```
+sift                      scan the current directory
+sift path/to/repo         scan a directory or a single file
+sift --min high           only show high and critical findings
+sift --json               machine-readable output
+sift --quiet              no output, just the exit code (for hooks/CI)
+```
+
+Exit status is `0` when clean, `1` when there is a finding at or above the fail
+level (`--fail-on`, default `high`), and `2` on error, so it drops straight
+into a hook or a pipeline.
+
+### pre-commit
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: https://github.com/ReazGan/sift
+    rev: v0.1.0
+    hooks:
+      - id: sift
+```
+
+### GitHub Action
+
+```yaml
+- uses: actions/checkout@v4
+- uses: ReazGan/sift@v0.1.0
+  with:
+    fail-on: high
+```
+
+## What it checks
+
+| Check | Severity | What it finds |
+|-------|----------|---------------|
+| `invisible-chars` | critical / high | Unicode tag characters (ASCII smuggling), variation-selector stego, zero-width and other invisible characters. Decodes and shows the hidden text. |
+| `bidi-override` | critical | Bidirectional control characters (Trojan Source) that reorder how a line is displayed. |
+| `unusual-encoding` | medium | An instruction file that is not plain UTF-8 (e.g. UTF-16), a way to hide a payload from UTF-8 tools. |
+| `hidden-comment` | high | Instruction-like text inside an HTML comment, invisible in rendered Markdown. |
+| `padded-line` | medium | Text pushed off-screen by a long run of spaces. |
+| `invisible-html` | high | Text colored to blend into the background. |
+| `instruction-override` | high | "Ignore previous instructions", re-role attempts, "don't tell the user" (English and Turkish). Also runs on MCP tool descriptions (tool poisoning). |
+| `data-exfiltration` | critical / high | A webhook endpoint, or a secret file (`.env`, `id_rsa`, ...) named next to a "send ... to" step. |
+| `mcp-auto-approve` | high | An MCP server set to approve its own tool calls. |
+| `mcp-secret` | high | A credential hard-coded in an MCP config. |
+| `mcp-remote` | medium / low | An MCP server reached over the network, including `npx mcp-remote <url>` bridges. |
+
+Files scanned: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.cursorrules` and
+`.cursor/rules/*`, `.github/copilot-instructions.md`, `.windsurfrules`,
+`.clinerules`, Qwen/Roo/Aider/IDX instruction files, and MCP configs
+(`.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`). `node_modules`, `.git`
+and build folders are skipped.
+
+## False positives
+
+sift is tuned to stay quiet on real instruction files. The checks are narrow on
+purpose: ordinary advice like "never commit secrets" or "always run the tests"
+is not flagged, only wording that overrides, hides, or exfiltrates. If sift
+flags something you wrote on purpose, it is pointing at a line worth a second
+look, but you are the judge. Found a false positive? Open an issue with the
+line.
+
+## License
+
+MIT

siftscan-0.1.0/README.md

@@ -0,0 +1,101 @@
+# sift
+
+[![CI](https://github.com/ReazGan/sift/actions/workflows/ci.yml/badge.svg)](https://github.com/ReazGan/sift/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/siftscan)](https://pypi.org/project/siftscan/)
+
+Scan AI agent instruction files for hidden or planted instructions.
+
+Your repo now ships files that tell an assistant what to do: `CLAUDE.md`,
+`.cursorrules`, `AGENTS.md`, Copilot instructions, `mcp.json`. A human skims
+them in a diff; the model obeys every byte. That gap is where an attacker hides
+a command, pulled in through a cloned starter, a dependency, or a pull request.
+sift reads those files the way the model does and flags what a reviewer can't
+see: invisible characters, instructions buried in comments, "ignore previous
+instructions" payloads, data-exfiltration steps, and risky MCP configs.
+
+Runs offline. No network calls, nothing leaves your machine.
+
+![sift flagging invisible smuggled text, a hidden comment and a risky MCP config](https://raw.githubusercontent.com/ReazGan/sift/main/docs/screenshot.svg)
+
+## Install
+
+```
+pip install siftscan
+```
+
+or, to keep it isolated:
+
+```
+pipx install siftscan
+```
+
+The command is `sift`.
+
+## Usage
+
+```
+sift                      scan the current directory
+sift path/to/repo         scan a directory or a single file
+sift --min high           only show high and critical findings
+sift --json               machine-readable output
+sift --quiet              no output, just the exit code (for hooks/CI)
+```
+
+Exit status is `0` when clean, `1` when there is a finding at or above the fail
+level (`--fail-on`, default `high`), and `2` on error, so it drops straight
+into a hook or a pipeline.
+
+### pre-commit
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: https://github.com/ReazGan/sift
+    rev: v0.1.0
+    hooks:
+      - id: sift
+```
+
+### GitHub Action
+
+```yaml
+- uses: actions/checkout@v4
+- uses: ReazGan/sift@v0.1.0
+  with:
+    fail-on: high
+```
+
+## What it checks
+
+| Check | Severity | What it finds |
+|-------|----------|---------------|
+| `invisible-chars` | critical / high | Unicode tag characters (ASCII smuggling), variation-selector stego, zero-width and other invisible characters. Decodes and shows the hidden text. |
+| `bidi-override` | critical | Bidirectional control characters (Trojan Source) that reorder how a line is displayed. |
+| `unusual-encoding` | medium | An instruction file that is not plain UTF-8 (e.g. UTF-16), a way to hide a payload from UTF-8 tools. |
+| `hidden-comment` | high | Instruction-like text inside an HTML comment, invisible in rendered Markdown. |
+| `padded-line` | medium | Text pushed off-screen by a long run of spaces. |
+| `invisible-html` | high | Text colored to blend into the background. |
+| `instruction-override` | high | "Ignore previous instructions", re-role attempts, "don't tell the user" (English and Turkish). Also runs on MCP tool descriptions (tool poisoning). |
+| `data-exfiltration` | critical / high | A webhook endpoint, or a secret file (`.env`, `id_rsa`, ...) named next to a "send ... to" step. |
+| `mcp-auto-approve` | high | An MCP server set to approve its own tool calls. |
+| `mcp-secret` | high | A credential hard-coded in an MCP config. |
+| `mcp-remote` | medium / low | An MCP server reached over the network, including `npx mcp-remote <url>` bridges. |
+
+Files scanned: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.cursorrules` and
+`.cursor/rules/*`, `.github/copilot-instructions.md`, `.windsurfrules`,
+`.clinerules`, Qwen/Roo/Aider/IDX instruction files, and MCP configs
+(`.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`). `node_modules`, `.git`
+and build folders are skipped.
+
+## False positives
+
+sift is tuned to stay quiet on real instruction files. The checks are narrow on
+purpose: ordinary advice like "never commit secrets" or "always run the tests"
+is not flagged, only wording that overrides, hides, or exfiltrates. If sift
+flags something you wrote on purpose, it is pointing at a line worth a second
+look, but you are the judge. Found a false positive? Open an issue with the
+line.
+
+## License
+
+MIT

siftscan-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "siftscan"
+version = "0.1.0"
+description = "Scan AI agent instruction files (CLAUDE.md, .cursorrules, AGENTS.md, mcp.json) for hidden or planted instructions."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Baran Ayaztas" }]
+keywords = [
+    "security", "prompt-injection", "supply-chain", "llm", "ai-agents",
+    "cursor", "claude", "copilot", "mcp", "static-analysis", "cli",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Security",
+]
+dependencies = [
+    "click>=8.1",
+    "rich>=13.7",
+]
+
+[project.urls]
+Homepage = "https://github.com/ReazGan/sift"
+Issues = "https://github.com/ReazGan/sift/issues"
+
+[project.scripts]
+sift = "sift.cli:main"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["sift*"]

siftscan-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

siftscan-0.1.0/sift/__init__.py

@@ -0,0 +1,23 @@
+"""sift: find hidden instructions in AI agent instruction files."""
+
+from __future__ import annotations
+
+__all__ = ["scan", "__version__"]
+
+try:  # populated from package metadata once installed
+    from importlib.metadata import version as _version
+
+    __version__ = _version("siftscan")
+except Exception:  # running from a source checkout
+    __version__ = "0.0.0+dev"
+
+
+def scan(root: str):
+    """Scan a path and return a list of Finding objects. Library entry point."""
+    from sift.checks import run_all
+    from sift.discover import discover
+
+    findings = []
+    for target in discover(root):
+        findings.extend(run_all(target))
+    return findings

siftscan-0.1.0/sift/checks/__init__.py

@@ -0,0 +1,20 @@
+"""Check registry.
+
+Every module exposes `check(ctx: ScanTarget) -> list[Finding]`. run_all runs
+them over one target and returns the findings, worst severity first.
+"""
+
+from __future__ import annotations
+
+from sift.checks import encoding, exfil, hidden, injection, invisible, mcp
+from sift.checks.base import SEVERITY_ORDER, Finding, ScanTarget
+
+_CHECKS = (invisible, encoding, hidden, injection, exfil, mcp)
+
+
+def run_all(ctx: ScanTarget) -> list[Finding]:
+    findings: list[Finding] = []
+    for module in _CHECKS:
+        findings.extend(module.check(ctx))
+    findings.sort(key=lambda f: (SEVERITY_ORDER[f.severity], f.line or 0))
+    return findings

siftscan-0.1.0/sift/checks/base.py

@@ -0,0 +1,56 @@
+"""Shared types for sift checks.
+
+Each check module exposes `check(ctx) -> list[Finding]`, where ctx is a
+ScanTarget (one AI-agent instruction or config file). Findings are later
+serialized with `Finding.to_dict()`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+Severity = Literal["low", "medium", "high", "critical"]
+
+SEVERITY_ORDER: dict[str, int] = {"critical": 0, "high": 1, "medium": 2, "low": 3}
+
+
+@dataclass
+class ScanTarget:
+    """One file sift looks at."""
+
+    path: str  # path as shown to the user, forward-slash separated
+    kind: str  # which agent it belongs to, e.g. "claude", "cursor", "mcp"
+    text: str  # decoded file contents
+    is_config: bool = False  # True for JSON configs (mcp.json etc.)
+    encoding: str = "utf-8"  # how the bytes were decoded
+
+
+@dataclass
+class Finding:
+    check: str
+    title: str
+    description: str
+    severity: Severity
+    path: str
+    line: int | None = None
+    evidence: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        out: dict[str, Any] = {
+            "check": self.check,
+            "title": self.title,
+            "severity": self.severity,
+            "path": self.path,
+        }
+        if self.line is not None:
+            out["line"] = self.line
+        out["description"] = self.description
+        if self.evidence:
+            out["evidence"] = self.evidence
+        return out
+
+
+def line_of(text: str, index: int) -> int:
+    """1-based line number of the character at `index`."""
+    return text.count("\n", 0, index) + 1

siftscan-0.1.0/sift/checks/encoding.py

@@ -0,0 +1,38 @@
+"""Unusual file encoding.
+
+Instruction files are plain UTF-8 text. One saved as UTF-16, or that only
+decodes with byte replacement, is a cheap way to hide a payload from a scanner
+that assumes UTF-8 while the editor/agent still reads it. sift decodes it anyway
+and flags the anomaly itself.
+"""
+
+from __future__ import annotations
+
+from sift.checks.base import Finding, ScanTarget
+
+CHECK = "unusual-encoding"
+
+_OK = {"utf-8", "ascii"}
+
+
+def check(ctx: ScanTarget) -> list[Finding]:
+    if ctx.encoding in _OK:
+        return []
+    if ctx.encoding == "utf-8-sig":
+        # A BOM is common on Windows; not worth a finding on its own.
+        return []
+    return [
+        Finding(
+            check=CHECK,
+            title=f"Instruction file is not plain UTF-8 ({ctx.encoding})",
+            description=(
+                "This file is not plain UTF-8. Instruction files normally are, and "
+                "a non-UTF-8 encoding can hide text from tools that assume UTF-8 "
+                "while the assistant still reads it. sift decoded and scanned it "
+                "anyway; re-save it as UTF-8 and review the contents."
+            ),
+            severity="medium",
+            path=ctx.path,
+            evidence={"encoding": ctx.encoding},
+        )
+    ]

siftscan-0.1.0/sift/checks/exfil.py

@@ -0,0 +1,104 @@
+"""Data-theft instructions planted in an instruction file.
+
+The payoff of a backdoored instruction file is usually to make the assistant
+read something secret and send it somewhere. That reads as a plausible "setup
+step" to a skimming reviewer, so it is worth calling out.
+
+- SIFT030 data-exfiltration: a webhook/collector endpoint, or a concrete secret
+  file (.env, id_rsa, ...) named next to an outward send verb.
+
+Note: a bare "curl ... | bash" is NOT flagged - it is the exact shape of nearly
+every legitimate installer, and flagging it would fire on most setup docs. A
+hidden fetch-and-run is still caught, because to hide it an attacker has to use
+the invisible-character, comment, or override tricks the other checks cover.
+"""
+
+from __future__ import annotations
+
+import re
+
+from sift.checks.base import Finding, ScanTarget, line_of
+
+CHECK_EXFIL = "data-exfiltration"
+
+# Concrete secret-bearing artifacts. Deliberately NOT the generic words
+# "credentials/secrets/password/api keys/environment variables" - real
+# instruction files mention those constantly as advice.
+_SECRET_RE = re.compile(
+    r"\.env(?:\.\w+)?\b|\bid_rsa\b|\.ssh/|\.aws/credentials\b|\.npmrc\b|"
+    r"\.git-credentials\b|\.pem\b|\.p12\b|\bprivate\s+key\b|"
+    r"\bSECRET_ACCESS_KEY\b|\bprivate[_\s-]?key\b",
+    re.IGNORECASE,
+)
+
+# An outward send verb followed (within a short span) by "to" - "send/upload/
+# post X to ...". Requiring "to" keeps ordinary "load the .env" / "fetch config"
+# from matching.
+_SEND_TO_RE = re.compile(
+    r"\b(?:send|upload|post|exfiltrat\w*|leak|ship|transmit|beacon|email)\b"
+    r"[^\n]{0,40}\bto\b",
+    re.IGNORECASE,
+)
+
+_URL_RE = re.compile(r"https?://[^\s'\"<>)\]]+", re.IGNORECASE)
+
+_WEBHOOK_RE = re.compile(
+    r"https?://(?:[\w-]+\.)?(?:discord(?:app)?\.com/api/webhooks|hooks\.slack\.com|"
+    r"webhook\.site|requestbin|pipedream\.net|ngrok\.io|interact\.sh|oast\.\w+|"
+    r"burpcollaborator\.net)/?\S*",
+    re.IGNORECASE,
+)
+
+
+def _window(text: str, index: int, radius: int = 200) -> str:
+    return text[max(0, index - radius): index + radius]
+
+
+def check(ctx: ScanTarget) -> list[Finding]:
+    findings: list[Finding] = []
+    text = ctx.text
+
+    wm = _WEBHOOK_RE.search(text)
+    if wm:
+        findings.append(
+            Finding(
+                check=CHECK_EXFIL,
+                title="Webhook endpoint in an instruction file",
+                description=(
+                    "This file points at a webhook / request-collector URL. "
+                    "Instruction files rarely need one; combined with any 'read X "
+                    "and send it here' wording it is a data-theft channel. Confirm "
+                    "why it is here."
+                ),
+                severity="critical",
+                path=ctx.path,
+                line=line_of(text, wm.start()),
+                evidence={"url": wm.group(0)[:160]},
+            )
+        )
+
+    secret = _SECRET_RE.search(text)
+    if secret and not (wm and secret.start() == wm.start()):
+        window = _window(text, secret.start())
+        if _SEND_TO_RE.search(window):
+            findings.append(
+                Finding(
+                    check=CHECK_EXFIL,
+                    title="Instruction to read a secret and send it out",
+                    description=(
+                        "A secret file is named next to an outward 'send ... to' "
+                        "step. That is the shape of a data-theft instruction. A "
+                        "normal instruction file does not tell the assistant to "
+                        "ship secret files anywhere."
+                    ),
+                    severity="high",
+                    path=ctx.path,
+                    line=line_of(text, secret.start()),
+                    evidence={
+                        "secret": secret.group(0),
+                        "has_external_url": bool(_URL_RE.search(window)),
+                    },
+                )
+            )
+
+    return findings