trustline-cli 0.1.0__tar.gz

trustline_cli-0.1.0/LICENSE

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

trustline_cli-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: trustline-cli
+Version: 0.1.0
+Summary: Trusted baseline + auto-rollback for AI agent configuration files (.claude/, AGENTS.md, .mcp.json, ...). Detects prompt-injection / supply-chain tampering of agent rules and rolls back to a trusted snapshot.
+Author-email: Terence Cai <cys2193736202@163.com>
+License: MIT
+Keywords: security,ai-agents,claude-code,supply-chain,prompt-injection,baseline
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12
+Requires-Dist: rich>=13.7
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+Dynamic: license-file
+
+# Trustline
+
+**Trusted baseline + auto-rollback for AI agent configuration files.**
+
+[![CI](https://github.com/LuckTerence/trustline/actions/workflows/ci.yml/badge.svg)](https://github.com/LuckTerence/trustline/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/trustline-cli)](https://pypi.org/project/trustline-cli/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+AI coding agents (Claude Code, Cursor, Codex, ...) load rules from files such as
+`.claude/`, `AGENTS.md`, `.cursorrules` and `.mcp.json`. Those files are now a
+supply-chain attack surface: cloning a repository or installing a third-party
+MCP can silently inject instructions that tell your agent to exfiltrate
+secrets, tamper with your shell, or hide its own actions.
+
+Existing scanners (medusa, Snyk agent-scan, Cisco mcp-scanner, ...) **detect**
+such tampering. Trustline is the missing **recovery layer**: it keeps a
+trusted baseline of your agent configuration files and can roll them back —
+and, through Claude Code hooks, block suspicious loads *before* they reach the
+model.
+
+## Why Trustline?
+
+Detection is table stakes. Every scanner in this space answers one question:
+*"has this rules file been poisoned?"* — and then leaves you to fix it by hand.
+Trustline answers the two questions that come after:
+
+1. **Did my agent config drift from a state I explicitly trusted?**
+   `status` diffs the working tree against a SHA-256 baseline *you* approved,
+   so a poisoned `.claude/settings.json` cloned from an untrusted repo shows up
+   as a concrete `modified`/`added` change — not a vague alert.
+2. **How do I get back to the trusted state?**
+   `rollback` restores from git HEAD or from content snapshots taken at
+   baseline time, and preserves the tampered copy for forensics — no manual
+   surgery, no guessing which file was the original.
+
+And because PreToolUse fires *before* a write lands, Trustline can refuse to
+let an agent write a poisoned rules file into your tree in the first place —
+the layer none of the scanners provide. This is deliberately defense-in-depth:
+the model's own safety training is the first line, the hook is the second, and
+the baseline + audit log is the third.
+
+## What it does
+
+- `trustline init` — establish a trusted baseline (SHA-256 snapshot) of managed agent files.
+- `trustline status` — diff the working tree against the baseline (added / modified / deleted).
+- `trustline scan` — static heuristic scan for prompt-injection / exfiltration / privilege-tampering signals (15 rules in v0.1).
+- `trustline rollback [files...]` — restore files to the baseline (git HEAD first, then local snapshots; soft rollback keeps `.bak`).
+- `trustline export-sarif` — emit scan findings as SARIF for CI / DefectDojo.
+- `trustline hook install` — wire Claude Code hooks (SessionStart / file-load / PreToolUse) to verify before the agent trusts a rules file.
+
+## Install
+
+```bash
+pip install trustline-cli     # or: uv tool install trustline-cli
+```
+
+## Quick start
+
+```bash
+cd ~/some-repo-you-cloned
+trustline init                 # review listed files, press enter -> baseline saved
+trustline status               # nothing changed yet
+trustline scan --sarif         # heuristic scan of managed files
+# ... after a suspicious change ...
+trustline status               # shows: MODIFIED .claude/settings.json
+trustline scan .claude/settings.json
+trustline rollback .claude/settings.json   # back to trusted state
+```
+
+## Claude Code hooks
+
+```bash
+trustline hook install         # writes .claude/settings.local.json (gitignored)
+```
+
+Hooks are executed with the project directory as cwd (no project-dir
+placeholder is needed). What fires:
+
+- **SessionStart** — warns on any managed file that differs from the trusted
+  baseline (verified in real Claude Code sessions).
+- **PreToolUse** on `Write`/`Edit`/`NotebookEdit` of a managed file — inspects
+  the *incoming* content and blocks with `exit 2` when a high-severity tamper
+  signal is present (so the agent cannot write a poisoned rules file).
+- **InstructionsLoaded** — best-effort block when a loaded rules file drifted
+  out of baseline; the event is not emitted in all Claude Code versions /
+  headless mode, so treat it as defense-in-depth, not the primary gate.
+
+Every hook decision is appended to a per-project audit log under
+`~/.config/trustline/projects/<root>/audit.jsonl`, so behaviour is observable
+without trusting stderr alone.
+
+## Real-world smoke scan
+
+`trustline scan` run over three public repositories (2026-09-02, shallow clone,
+default rules). Findings are static signals that require human review — the
+point of the table is to show the tool runs cleanly on real trees and that
+false-positive volume is low.
+
+| Repository | Managed files scanned | Findings | Signal rules hit | Notes |
+|---|---|---|---|---|
+| [affaan-m/ECC](https://github.com/affaan-m/ECC) (ruleset, 245k★) | 65 | 3 | T010 · T007 · T012 | low hit-rate on a very large rules corpus |
+| [yamadashy/repomix](https://github.com/yamadashy/repomix) (tool, 28k★) | 11 | 1 | T010 | unpinned `npx` MCP package (common, low-risk) |
+| [Pantheon-Security/medusa](https://github.com/Pantheon-Security/medusa) (security scanner) | 3 | 2 | T013 · T004 | both hits are inside its own `tests/fixtures/malicious_repo/` samples — Trustline flags the same fixtures medusa ships |
+
+Reproduce: `pip install trustline-cli && trustline scan --root <clone-dir> --sarif`.
+
+## Managed files (default)
+
+`.claude/**`, `CLAUDE.md`, `**/AGENTS.md`, `**/.cursorrules`, `**/.mcp.json`,
+`**/.codex/**`, `**/.github/copilot-instructions.md` — override with
+`trustline init --patterns ...` or a `trustline.toml`.
+
+## Development
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

trustline_cli-0.1.0/README.md

@@ -0,0 +1,123 @@
+# Trustline
+
+**Trusted baseline + auto-rollback for AI agent configuration files.**
+
+[![CI](https://github.com/LuckTerence/trustline/actions/workflows/ci.yml/badge.svg)](https://github.com/LuckTerence/trustline/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/trustline-cli)](https://pypi.org/project/trustline-cli/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+AI coding agents (Claude Code, Cursor, Codex, ...) load rules from files such as
+`.claude/`, `AGENTS.md`, `.cursorrules` and `.mcp.json`. Those files are now a
+supply-chain attack surface: cloning a repository or installing a third-party
+MCP can silently inject instructions that tell your agent to exfiltrate
+secrets, tamper with your shell, or hide its own actions.
+
+Existing scanners (medusa, Snyk agent-scan, Cisco mcp-scanner, ...) **detect**
+such tampering. Trustline is the missing **recovery layer**: it keeps a
+trusted baseline of your agent configuration files and can roll them back —
+and, through Claude Code hooks, block suspicious loads *before* they reach the
+model.
+
+## Why Trustline?
+
+Detection is table stakes. Every scanner in this space answers one question:
+*"has this rules file been poisoned?"* — and then leaves you to fix it by hand.
+Trustline answers the two questions that come after:
+
+1. **Did my agent config drift from a state I explicitly trusted?**
+   `status` diffs the working tree against a SHA-256 baseline *you* approved,
+   so a poisoned `.claude/settings.json` cloned from an untrusted repo shows up
+   as a concrete `modified`/`added` change — not a vague alert.
+2. **How do I get back to the trusted state?**
+   `rollback` restores from git HEAD or from content snapshots taken at
+   baseline time, and preserves the tampered copy for forensics — no manual
+   surgery, no guessing which file was the original.
+
+And because PreToolUse fires *before* a write lands, Trustline can refuse to
+let an agent write a poisoned rules file into your tree in the first place —
+the layer none of the scanners provide. This is deliberately defense-in-depth:
+the model's own safety training is the first line, the hook is the second, and
+the baseline + audit log is the third.
+
+## What it does
+
+- `trustline init` — establish a trusted baseline (SHA-256 snapshot) of managed agent files.
+- `trustline status` — diff the working tree against the baseline (added / modified / deleted).
+- `trustline scan` — static heuristic scan for prompt-injection / exfiltration / privilege-tampering signals (15 rules in v0.1).
+- `trustline rollback [files...]` — restore files to the baseline (git HEAD first, then local snapshots; soft rollback keeps `.bak`).
+- `trustline export-sarif` — emit scan findings as SARIF for CI / DefectDojo.
+- `trustline hook install` — wire Claude Code hooks (SessionStart / file-load / PreToolUse) to verify before the agent trusts a rules file.
+
+## Install
+
+```bash
+pip install trustline-cli     # or: uv tool install trustline-cli
+```
+
+## Quick start
+
+```bash
+cd ~/some-repo-you-cloned
+trustline init                 # review listed files, press enter -> baseline saved
+trustline status               # nothing changed yet
+trustline scan --sarif         # heuristic scan of managed files
+# ... after a suspicious change ...
+trustline status               # shows: MODIFIED .claude/settings.json
+trustline scan .claude/settings.json
+trustline rollback .claude/settings.json   # back to trusted state
+```
+
+## Claude Code hooks
+
+```bash
+trustline hook install         # writes .claude/settings.local.json (gitignored)
+```
+
+Hooks are executed with the project directory as cwd (no project-dir
+placeholder is needed). What fires:
+
+- **SessionStart** — warns on any managed file that differs from the trusted
+  baseline (verified in real Claude Code sessions).
+- **PreToolUse** on `Write`/`Edit`/`NotebookEdit` of a managed file — inspects
+  the *incoming* content and blocks with `exit 2` when a high-severity tamper
+  signal is present (so the agent cannot write a poisoned rules file).
+- **InstructionsLoaded** — best-effort block when a loaded rules file drifted
+  out of baseline; the event is not emitted in all Claude Code versions /
+  headless mode, so treat it as defense-in-depth, not the primary gate.
+
+Every hook decision is appended to a per-project audit log under
+`~/.config/trustline/projects/<root>/audit.jsonl`, so behaviour is observable
+without trusting stderr alone.
+
+## Real-world smoke scan
+
+`trustline scan` run over three public repositories (2026-09-02, shallow clone,
+default rules). Findings are static signals that require human review — the
+point of the table is to show the tool runs cleanly on real trees and that
+false-positive volume is low.
+
+| Repository | Managed files scanned | Findings | Signal rules hit | Notes |
+|---|---|---|---|---|
+| [affaan-m/ECC](https://github.com/affaan-m/ECC) (ruleset, 245k★) | 65 | 3 | T010 · T007 · T012 | low hit-rate on a very large rules corpus |
+| [yamadashy/repomix](https://github.com/yamadashy/repomix) (tool, 28k★) | 11 | 1 | T010 | unpinned `npx` MCP package (common, low-risk) |
+| [Pantheon-Security/medusa](https://github.com/Pantheon-Security/medusa) (security scanner) | 3 | 2 | T013 · T004 | both hits are inside its own `tests/fixtures/malicious_repo/` samples — Trustline flags the same fixtures medusa ships |
+
+Reproduce: `pip install trustline-cli && trustline scan --root <clone-dir> --sarif`.
+
+## Managed files (default)
+
+`.claude/**`, `CLAUDE.md`, `**/AGENTS.md`, `**/.cursorrules`, `**/.mcp.json`,
+`**/.codex/**`, `**/.github/copilot-instructions.md` — override with
+`trustline init --patterns ...` or a `trustline.toml`.
+
+## Development
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

trustline_cli-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "trustline-cli"
+version = "0.1.0"
+description = "Trusted baseline + auto-rollback for AI agent configuration files (.claude/, AGENTS.md, .mcp.json, ...). Detects prompt-injection / supply-chain tampering of agent rules and rolls back to a trusted snapshot."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Terence Cai", email = "cys2193736202@163.com" }]
+keywords = ["security", "ai-agents", "claude-code", "supply-chain", "prompt-injection", "baseline"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Security",
+]
+dependencies = [
+    "typer>=0.12",
+    "rich>=13.7",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-cov>=5",
+]
+
+[project.scripts]
+trustline = "trustline.cli:app"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

trustline_cli-0.1.0/setup.cfg

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

trustline_cli-0.1.0/src/trustline/__init__.py

@@ -0,0 +1,3 @@
+"""Trustline: trusted baseline + auto-rollback for AI agent configuration files."""
+
+__version__ = "0.1.0"

trustline_cli-0.1.0/src/trustline/baseline.py

@@ -0,0 +1,126 @@
+"""Trusted baseline: SHA-256 snapshot of managed files + content copies."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import shutil
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .config import Config, normalize_relpath
+
+BASELINE_VERSION = 1
+
+
+def sha256_file(path: Path) -> str:
+    h = hashlib.sha256()
+    with path.open("rb") as f:
+        for chunk in iter(lambda: f.read(65536), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def sha256_bytes(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+@dataclass
+class FileEntry:
+    sha256: str
+    copied: bool = False  # a content snapshot exists under copies/<sha>/
+    size: int = 0
+
+
+@dataclass
+class Change:
+    relpath: str
+    change_type: str  # "added" | "modified" | "deleted"
+    old_sha: str = ""
+    new_sha: str = ""
+
+
+@dataclass
+class Baseline:
+    version: int = BASELINE_VERSION
+    created_at: str = ""
+    files: dict[str, FileEntry] = field(default_factory=dict)
+
+    def to_json(self) -> dict:
+        return {
+            "version": self.version,
+            "created_at": self.created_at,
+            "files": {k: {"sha256": v.sha256, "copied": v.copied, "size": v.size} for k, v in self.files.items()},
+        }
+
+    @classmethod
+    def from_json(cls, data: dict) -> "Baseline":
+        b = cls(version=data.get("version", BASELINE_VERSION), created_at=data.get("created_at", ""))
+        for k, v in (data.get("files") or {}).items():
+            b.files[k] = FileEntry(sha256=v.get("sha256", ""), copied=bool(v.get("copied")), size=int(v.get("size", 0)))
+        return b
+
+
+def load(config: Config) -> Baseline | None:
+    p = config.baseline_path
+    if not p.exists():
+        return None
+    try:
+        return Baseline.from_json(json.loads(p.read_text(encoding="utf-8")))
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
+def save(config: Config, baseline: Baseline) -> Path:
+    config.ensure_dirs()
+    p = config.baseline_path
+    p.write_text(json.dumps(baseline.to_json(), indent=2, ensure_ascii=False), encoding="utf-8")
+    return p
+
+
+def snapshot(config: Config) -> Baseline:
+    """Hash every managed file; store content copies under copies/<sha> when
+    config.with_copies is set so rollback works even outside a git repo."""
+    from .discovery import discover
+
+    baseline = Baseline(created_at=time.strftime("%Y-%m-%dT%H:%M:%S%z"))
+    for path in discover(config):
+        rel = normalize_relpath(config.root, path)
+        digest = sha256_file(path)
+        entry = FileEntry(sha256=digest, size=path.stat().st_size)
+        if config.with_copies:
+            dest = config.copies_dir / digest
+            if not dest.exists():
+                dest.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copy2(path, dest)
+            entry.copied = True
+        baseline.files[rel] = entry
+    return baseline
+
+
+def compare(config: Config, baseline: Baseline) -> list[Change]:
+    """Diff current managed files against the baseline."""
+    from .discovery import discover
+
+    changes: list[Change] = []
+    current: dict[str, Path] = {}
+    for path in discover(config):
+        rel = normalize_relpath(config.root, path)
+        current[rel] = path
+
+    for rel, path in current.items():
+        entry = baseline.files.get(rel)
+        if entry is None:
+            changes.append(Change(relpath=rel, change_type="added", new_sha=sha256_file(path)))
+        else:
+            digest = sha256_file(path)
+            if digest != entry.sha256:
+                changes.append(Change(relpath=rel, change_type="modified", old_sha=entry.sha256, new_sha=digest))
+
+    for rel in baseline.files:
+        if rel not in current:
+            changes.append(Change(relpath=rel, change_type="deleted", old_sha=baseline.files[rel].sha256))
+
+    changes.sort(key=lambda c: (c.change_type, c.relpath))
+    return changes