trustline-cli 0.1.0__py3-none-any.whl

trustline/sarif.py

@@ -0,0 +1,49 @@
+"""SARIF 2.1.0 output for scan findings (consumable by CI / DefectDojo / etc.)."""
+
+from __future__ import annotations
+
+from .heuristics import Finding
+
+SARIF_VERSION = "2.1.0"
+SARIF_SCHEMA = "https://json.schemastore.org/sarif-2.1.0.json"
+
+
+def build_sarif(findings: list[Finding], tool_name: str = "trustline", tool_version: str = "0.1.0") -> dict:
+    """Map trustline findings onto a SARIF run. Rule metadata is derived from
+    the finding itself; we do not require rule metadata files."""
+    results = []
+    for idx, f in enumerate(findings):
+        loc = None
+        if f.file:
+            region = {"startLine": f.line} if f.line else {}
+            loc = {
+                "physicalLocation": {
+                    "artifactLocation": {"uri": f.file},
+                    **({"region": region} if region else {}),
+                }
+            }
+        results.append(
+            {
+                "ruleId": f.rule_id,
+                "level": "error" if f.severity == "high" else "warning",
+                "message": {"text": f.message},
+                **({"locations": [loc]} if loc else {}),
+            }
+        )
+    return {
+        "$schema": SARIF_SCHEMA,
+        "version": SARIF_VERSION,
+        "runs": [
+            {
+                "tool": {
+                    "driver": {
+                        "name": tool_name,
+                        "version": tool_version,
+                        "informationUri": "https://github.com/terencesai/trustline",
+                        "rules": [],
+                    }
+                },
+                "results": results,
+            }
+        ],
+    }

trustline/scanner.py

@@ -0,0 +1,33 @@
+"""Scanner: run heuristics over a single managed file or the whole tree."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .config import Config, normalize_relpath
+from .discovery import discover
+from .heuristics import Finding, scan_text
+
+_MAX_BYTES = 2 * 1024 * 1024  # do not read huge managed files fully
+
+
+def scan_file(path: Path, config: Config) -> list[Finding]:
+    rel = normalize_relpath(config.root, path)
+    try:
+        if path.stat().st_size > _MAX_BYTES:
+            return []
+        text = path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return []
+    return scan_text(text, file_rel=rel)
+
+
+def scan_root(config: Config) -> list[Finding]:
+    all_findings: list[Finding] = []
+    for path in discover(config):
+        all_findings.extend(scan_file(path, config))
+    return all_findings
+
+
+def severity_rank(f: Finding) -> int:
+    return {"high": 0, "medium": 1, "low": 2}.get(f.severity, 3)

trustline_cli-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,16 @@
+trustline/__init__.py,sha256=fiBaAtS-IzSBLIkzS5YHL_VZCnxozRaW7l3_-TwzDG4,107
+trustline/baseline.py,sha256=oJ52xLTCIWgoI1gmKwHzBeO9SHYPtyeJV7N0CP1LxQ0,3922
+trustline/cli.py,sha256=xCfQjwZ6_ThKQ-6J7_2iuKxGxgiSxiXTeJ4D6ZGyH3w,10326
+trustline/config.py,sha256=4TtvCneBv90BHfClAKb78mgAgy6OD5QObkl4lp1KqYU,3620
+trustline/discovery.py,sha256=7vIYlPhZYm77KkCZblr5pIL6ZFf_NvZctxRraUfTwQo,1291
+trustline/heuristics.py,sha256=Jevjyr_C8v_0HPeG5trHrPYw99uC6R1stmk3wtNchf8,11911
+trustline/hooks.py,sha256=jaitb1XAQ7-J3eSQKMDap5TVF8NBhhzJH8jWGTUGcY0,10223
+trustline/rollback.py,sha256=cWnuEtE4GEIkuMlVYeFUWPfKgU4TGDoQugXc1x9k4gU,4649
+trustline/sarif.py,sha256=XvG6Jo744idIZ8aYQqCg8UuEIt165kskSt0O4-2ZASY,1628
+trustline/scanner.py,sha256=9TKgZEZqbeRB6_getWTaxjkTyNaNq2BuTGNZRnU8Fvk,963
+trustline_cli-0.1.0.dist-info/licenses/LICENSE,sha256=uztXZL-fAv1QulHVgyiF4pMPVmf7I57uaCO_h_-Oe_E,1068
+trustline_cli-0.1.0.dist-info/METADATA,sha256=KTyFyYOHS59SRmpdh-Sgs3HMcE5leriAjngRjiTkFq0,6766
+trustline_cli-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+trustline_cli-0.1.0.dist-info/entry_points.txt,sha256=M9EEJg_0mb_LHJKMw1tRTwIc95YWglqzogWVAVW3Tq0,48
+trustline_cli-0.1.0.dist-info/top_level.txt,sha256=Sh338JRFwELnkN9fWfz2ue0bsxjsQT2A2glMjtb3WBU,10
+trustline_cli-0.1.0.dist-info/RECORD,,

trustline_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

trustline_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+trustline = trustline.cli:app

trustline_cli-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+trustline