# Trust - AI-Native Security Scanner

[![Smithery](https://smithery.ai/badge/trust-security/scanner)](https://smithery.ai/servers/trust-security/scanner)

Scan websites and GitHub repositories for security vulnerabilities. AI analyzes root causes, generates fix code with before/after diffs, and creates one-click Fix PRs.

**Live**: [https://www.trust-scan.me](https://www.trust-scan.me)

> [Korean / 한국어 문서](docs/README.ko.md)

---

## Features

### URL Security Scan
- DAST vulnerability detection with 5,000+ Nuclei templates
- Runtime checks for HTTP headers, SSL, CORS, cookie settings, and more
- Scan completes in under 30 seconds

### GitHub Repo Scan
- **SAST**: Code-level vulnerability detection with Semgrep (XSS, SQL Injection, hardcoded secrets, etc.)
- **Secrets**: API key, token, and password exposure detection with Gitleaks
- **SCA**: Dependency CVE detection with npm audit
- Weighted scoring system (A+ to F grade)

### AI Analysis (Pro)
- Root cause analysis for each vulnerability using Claude Sonnet
- **Before/After code**: Actual fix code diff generation
- Step-by-step remediation guide

### Auto-Fix PR (Pro)
- One-click GitHub PR creation from AI-analyzed vulnerabilities
- Automatic branch creation + file modification + PR opening
- package.json version update support

### Fix with AI (Pro)
- Fix prompt generation for all vulnerabilities
- Directly applicable in Cursor, Claude Code, and other IDEs

### Additional Features
- **Trust Badge**: Security score-based README badge
- **Benchmark**: Compare security scores with other sites
- **Shared Reports**: Share scan result URLs (viewable without login)
- **MCP Server**: In-IDE security scanning for Claude Code and Cursor (8 tools + 3 resources)
- **GitHub Action**: Automated security scanning in CI/CD pipelines + PR comments
- **Scheduled Scans**: Hourly / Daily / Weekly automatic security scans + email/Slack alerts
- **Weekly Digest**: Weekly security report email (score trends, vulnerability summary)
- **Push Notifications**: Web Push notifications on scan completion

### Plans

| | Free | Pro ($9.9/mo) |
|---|---|---|
| URL Scans | 5/month | Unlimited |
| Repo Scans | 3/month | Unlimited |
| AI Analysis | 2 per scan | Unlimited |
| Auto-Fix PR | - | Yes |
| Scheduled Scans | - | Yes |
| PDF/CSV Export | - | Yes |

---

## MCP Server (Model Context Protocol)

Install with a single command in Claude Code, Cursor IDE, and other MCP clients to get real-time security feedback while coding.

### Install (Claude Code)

```bash
claude mcp add --transport http trust-security "https://trust-mcp-144011703035.asia-northeast3.run.app/mcp"
```

### Install (Claude Desktop / Cursor)

Add to your config file:

```json
{
  "mcpServers": {
    "trust-security": {
      "type": "http",
      "url": "https://trust-mcp-144011703035.asia-northeast3.run.app/mcp"
    }
  }
}
```

### Available Tools (8 tools)

| Tool | Description | Example |
|------|-------------|---------|
| `scan_and_wait` | Scan website + wait for results (recommended) | "Scan https://my-app.com" |
| `scan_url` | Start website scan (async) | "Start a scan" |
| `get_scan_result` | Get URL scan results | "Show scan results" |
| `scan_repo_and_wait` | Scan GitHub repo + wait for results (recommended) | "Security scan this repo" |
| `scan_repo` | Start repo scan (async) | "Start repo scan" |
| `get_repo_scan_result` | Get repo scan results | "Show repo scan results" |
| `analyze_code_security` | Analyze code vulnerabilities + secrets (37+ patterns) | "Check this code for security issues" |
| `check_secrets` | Detect API keys/passwords (20+ patterns) | "Any exposed keys in this code?" |

### MCP Resources (3 resources)

Context resources automatically read by AI agents.

| Resource URI | Description |
|-------------|-------------|
| `trust://scans/latest` | Most recent scan result (score, grade, vulnerability count) |
| `trust://scans/history` | Last 10 scan history |
| `trust://security/posture` | Security posture summary (average score, trends, grade distribution) |

---

## Tech Stack

| Area | Technology |
|------|-----------|
| **Frontend** | Next.js 16, React 19, TailwindCSS 4, Framer Motion |
| **Backend** | FastAPI, Python 3.11+, Nuclei, Semgrep, Gitleaks |
| **Database** | Supabase (PostgreSQL + Auth + RLS) |
| **AI** | Claude API (Anthropic) — Sonnet for analysis |
| **Payment** | Paddle (Pro subscription) |
| **Deployment** | Vercel (Frontend), Cloud Run (Backend + MCP) |

---

## Project Structure

```
.
├── app/                        # Next.js App Router
│   ├── page.tsx                # Landing (URL / Repo scan)
│   ├── report/[scanId]/        # Scan report page
│   ├── history/                # Scan history
│   ├── pricing/                # Pricing
│   ├── why-trust/              # Why Trust marketing
│   ├── auth/                   # OAuth callbacks (Supabase, GitHub)
│   ├── mcp/                    # MCP setup guide
│   ├── error.tsx               # Error boundary
│   └── not-found.tsx           # 404 page
├── components/
│   ├── trust/                  # Main view components
│   │   ├── client-app.tsx      # Main app state management
│   │   ├── dashboard-view.tsx  # Scan result dashboard
│   │   ├── landing-view.tsx    # Landing view
│   │   ├── scanning-view.tsx   # Scan progress view
│   │   ├── UpgradeModal.tsx    # Go Pro modal
│   │   ├── NotificationToggle.tsx  # Push notification toggle
│   │   ├── OnboardingTour.tsx  # Onboarding tour
│   │   └── dashboard/
│   │       ├── CreateFixPRModal.tsx   # Fix PR modal
│   │       ├── FixPromptModal.tsx     # Fix Prompt modal
│   │       ├── ScheduleSection.tsx    # Scheduled scan management
│   │       ├── DigestSection.tsx      # Weekly digest settings
│   │       ├── BadgeSection.tsx       # Trust Badge
│   │       ├── VulnerabilityList.tsx  # Vulnerability list
│   │       └── ExportPanel.tsx        # PDF/CSV export
│   └── ui/                     # Shared UI (shadcn/ui)
├── lib/
│   ├── api.ts                  # Backend API client
│   ├── types.ts                # TypeScript type definitions
│   ├── supabase.ts             # Supabase client
│   └── subscription.ts         # Pro subscription state management
│
├── backend/                    # FastAPI Backend
│   ├── app/
│   │   ├── main.py             # FastAPI entrypoint
│   │   ├── config.py           # Configuration
│   │   ├── limiter.py          # Rate limiting
│   │   ├── api/routes/
│   │   │   ├── scan.py              # URL scan API
│   │   │   ├── repo_scan.py         # GitHub repo scan API
│   │   │   ├── analyze.py           # AI analysis API
│   │   │   ├── github.py            # GitHub integration + Fix PR API
│   │   │   ├── github_webhook.py    # GitHub webhook handler
│   │   │   ├── badge.py             # Trust Badge API
│   │   │   ├── billing_webhook.py   # Paddle billing webhook
│   │   │   ├── notifications.py     # Notification settings API
│   │   │   └── scheduled_scans.py   # Scheduled scan API
│   │   └── services/
│   │       ├── nuclei_scanner.py
│   │       ├── semgrep_scanner.py
│   │       ├── gitleaks_scanner.py
│   │       ├── repo_scanner.py       # Unified repo scanner
│   │       ├── claude_analyzer.py    # AI analysis (Claude)
│   │       ├── github_service.py     # GitHub API service
│   │       ├── supabase_client.py    # DB service
│   │       ├── scheduler.py          # Scheduled scan scheduler
│   │       └── notifier.py           # Email/Slack/digest notifications
│   ├── Dockerfile
│   └── requirements.txt
│
├── mcp-server/                 # MCP Server (standalone service)
│   ├── server.py
│   ├── Dockerfile
│   └── requirements.txt
│
├── public/
│   └── sw.js                   # Push Notification Service Worker
│
└── docs/                       # Documentation
    ├── README.ko.md            # Korean documentation
    ├── ROADMAP.md
    ├── HANDOVER_CONTEXT_AWARE_FIX.md
    └── REQUIREMENTS_UNIVERSAL_AUTO_FIX.md
```

---

## API Endpoints

### URL Scan

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/api/scan` | Start URL scan |
| `GET` | `/api/scan/{scan_id}` | Get scan status/results |
| `GET` | `/api/scan/{scan_id}/export` | Export PDF/CSV |

### Repo Scan

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/api/repo-scan` | Start GitHub repo scan |
| `GET` | `/api/repo-scan/{scan_id}` | Get repo scan status/results |
| `POST` | `/api/repo-scan/{scan_id}/analyze` | Run AI analysis |
| `POST` | `/api/repo-scan/{scan_id}/fix-prompt` | Generate fix prompt |

### GitHub Integration

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/github/connection` | Check GitHub connection status |
| `POST` | `/api/github/connect` | Connect GitHub OAuth |
| `POST` | `/api/github/create-fix-pr` | Create fix PR |
| `POST` | `/api/github/fix-feedback` | Submit fix quality feedback |
| `DELETE` | `/api/github/connection` | Disconnect GitHub |

### AI Analysis

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/api/analyze/{scan_id}` | Start AI analysis |
| `GET` | `/api/analyze/{vuln_id}` | Get analysis results |

### Badge

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/api/badge/{scan_id}` | Issue badge |
| `GET` | `/api/badge/{badge_id}` | Get badge SVG |

### Scheduled Scans

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/api/scheduled-scans` | Create scheduled scan |
| `GET` | `/api/scheduled-scans` | List scheduled scans |
| `DELETE` | `/api/scheduled-scans/{id}` | Delete scheduled scan |
| `POST` | `/api/cron/run-schedules` | Execute schedules (Cloud Scheduler) |

### History / Notifications

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/scans/history` | Get scan history |
| `GET` | `/api/notifications/settings` | Get notification settings |
| `PUT` | `/api/notifications/settings` | Update notification settings |

### Webhooks

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/api/billing/webhook` | Paddle billing webhook |
| `POST` | `/webhooks/github` | GitHub PR event webhook |

---

## Getting Started

### Prerequisites

- Node.js 20+
- Python 3.11+
- Nuclei, Semgrep, Gitleaks (security scanners)
- Supabase account
- Anthropic API key

### 1. Clone Repository

```bash
git clone --recurse-submodules https://github.com/Jaden-JJH/trust-security-scanner.git
cd trust-security-scanner
```

### 2. Frontend Setup

```bash
npm install
cp .env.example .env.local
npm run dev
```

**Environment Variables (.env.local)**
```env
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_GITHUB_APP_CLIENT_ID=your-github-app-client-id
```

### 3. Backend Setup

```bash
cd backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
uvicorn app.main:app --reload --port 8000
```

---

## Deployment

### Frontend (Vercel)

Auto-deploys on push to `main` branch via GitHub integration.

### Backend (Cloud Run)

```bash
cd backend
gcloud builds submit --tag gcr.io/[PROJECT_ID]/trust-backend
gcloud run deploy trust-backend \
  --image gcr.io/[PROJECT_ID]/trust-backend \
  --platform managed --region asia-northeast3 \
  --allow-unauthenticated
```

---

## License

MIT License