# Sentron

**Ask a security expert before you adopt open source.**  
Your AI assistant should have to ask too.

Sentron is an MCP security gateway. It sits between Claude, Cursor, and the messy reality of GitHub: Scorecard for repo health, Trivy for licenses and vulns, Syft for SBOMs. When an assistant is about to trust a dependency, Sentron makes it run the checks a careful human would.

> Status: **v0.1.0** — usable locally, opinionated, still early. See [docs/roadmap.md](docs/roadmap.md).

---

## Why this exists

AI coding tools install packages, clone repos, and recommend binaries at machine speed. Humans used to pause and ask:

- Is this project maintained, or abandoned with a shiny README?
- Are there known HIGH/CRITICAL CVEs in what I'm about to pull?
- What's actually in the box (SBOM), and under which licenses?

That pause is disappearing. Sentron puts it back — as tools your assistant can call before it says "looks fine."

It does **not** replace judgment. It replaces the blank stare when nobody ran Scorecard.

---

## What you get (v0.1)

| Tool | Under the hood | Answers |
| --- | --- | --- |
| `audit_repo_health` | [OpenSSF Scorecard](https://github.com/ossf/scorecard) | Overall score, weak checks, process smell |
| `scan_licenses_and_vulns` | [Trivy](https://trivy.dev/) | License hits + HIGH/CRITICAL vulns |
| `generate_sbom` | [Syft](https://github.com/anchore/syft) | Package inventory / ecosystem counts |
| `get_job_status` | Sentron job runner | Poll long scans (Claude Desktop ~60s cap) |

Long scans start in the background and return a `job_id`. Poll until `completed`. That keeps Claude Desktop from timing out mid-Scorecard.

---

## Quick start

### 1. Install scanners (on your `$PATH`)

```bash
brew install scorecard trivy syft   # or your package manager of choice
```

### 2. Install Sentron

```bash
git clone https://github.com/grootynix/sentron.git
cd sentron
uv sync
```

### 3. Secrets stay in `.env` (never in `mcp.json`)

```bash
cp .env.example .env
# GITHUB_AUTH_TOKEN=...   # Scorecard rate limits / private repos
```

### 4. Wire Claude Desktop or Cursor

**Claude Desktop** — `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "sentron": {
      "command": "/Users/YOU/.local/bin/uv",
      "args": ["run", "--directory", "/ABS/PATH/TO/sentron", "sentron"]
    }
  }
}
```

**Cursor** — see [`.cursor/mcp.json`](.cursor/mcp.json). Same idea: launch via `uv`, no tokens in the JSON.

Quit and reopen the client. Ask it to audit a repo and **poll `get_job_status`**.

### Smoke test without an AI client

```bash
uv run python - <<'PY'
import asyncio, json
from sentron.tools.syft import run_syft

async def main():
    print(json.loads(await run_syft("."))["summary"]["total_packages"])

asyncio.run(main())
PY
```

---

## Architecture (short version)

```text
Claude / Cursor
      │  stdio MCP
      ▼
 sentron.server (FastMCP)
      │  start job → job_id
      ▼
 sentron.jobs  ──poll──► get_job_status
      │
      ├── tools/scorecard.py  → scorecard CLI
      ├── tools/trivy.py      → trivy CLI
      └── tools/syft.py       → git clone (if URL) + syft CLI
```

CLI binaries are executed with `asyncio.create_subprocess_exec`, timeouts, and PATH preflight. Missing tools return a JSON error with install hints — not a stack trace.

Full write-up: [docs/architecture.md](docs/architecture.md).

---

## Documentation

| Doc | Contents |
| --- | --- |
| [Getting started](docs/getting-started.md) | Install, tokens, client config |
| [Tools](docs/tools.md) | Arguments, response shapes, polling |
| [Configuration](docs/configuration.md) | Env vars, `.env`, timeouts |
| [Architecture](docs/architecture.md) | Modules, data flow, design choices |
| [Roadmap](docs/roadmap.md) | v0.1 → v1.0 and beyond |
| [Security](SECURITY.md) | How to report issues |
| [Contributing](CONTRIBUTING.md) | Dev setup, PRs |

---

## Project status & versioning

- **Current release:** `0.1.0` (see [CHANGELOG.md](CHANGELOG.md))
- **Python:** 3.11+
- **License:** [Apache-2.0](LICENSE)
- **Stability:** APIs may shift before 1.0. Pin a tag if you automate on this.

---

## Roadmap (headline)

- **v0.1** — Scorecard + Trivy + Syft over MCP, async jobs, local secrets — *shipped*
- **v0.2** — Policy profiles ("block CRITICAL", license allowlists), better summaries for agents
- **v0.3** — CI / GitHub Action mode; SARIF / CycloneDX export
- **v1.0** — Stable tool schema, signed releases, documented threat model

Details: [docs/roadmap.md](docs/roadmap.md).

---

## What Sentron is not

- Not a magic "safe / unsafe" oracle
- Not a hosted SaaS (v0.1 runs on your machine)
- Not a replacement for Scorecard, Trivy, or Syft — it orchestrates them

If a check fails because your fine-grained PAT can't read branch protection, Sentron skips that check and says so. Bring a classic `repo`-scoped PAT if you need the full set.

---

## Contributing

Bugs, sharp edges, and small PRs welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md).

---

## License

Copyright 2026 Sentron contributors.  
Licensed under the [Apache License, Version 2.0](LICENSE).

Third-party CLIs (Scorecard, Trivy, Syft) keep their own licenses; you install them separately. See [NOTICE](NOTICE).

---

## Acknowledgments

Built on the shoulders of [OpenSSF Scorecard](https://github.com/ossf/scorecard), [Aquasecurity Trivy](https://github.com/aquasecurity/trivy), [Anchore Syft](https://github.com/anchore/syft), and the [Model Context Protocol](https://modelcontextprotocol.io/).