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
