# GitHub Security Analyzer — MCP

An AI-powered GitHub security scanner. Log in with your GitHub account, give it a repo name, and the AI scans every file for exposed secrets like API keys, passwords, and tokens — then gives you a full report with what to fix.

---

## How It Works

```
1. Login with GitHub (OAuth)
        ↓
   .github_token saved locally
        ↓
2. Run the agent
        ↓
   You type a repo name
        ↓
3. AI calls deep_security_scan tool
        ↓
   Fetches every file from the repo via GitHub API
        ↓
   Scans each file with 16 secret patterns (regex)
        ↓
4. AI reads the results and writes a report
        ↓
   Tells you what was found, which file, which line, and how to fix it
```

---

## Project Structure

```
├── login.py          # GitHub OAuth login — saves token to .github_token
├── github_client.py  # Wrapper around GitHub API calls
├── server.py         # MCP tools (list repos, scan files, read code, etc.)
├── agent.py          # AI agent loop — uses OpenRouter to run the scanner
├── requirements.txt  # Python dependencies
└── .env              # Your credentials (never commit this)
```

---

## Setup

**1. Create a `.env` file:**
```
GITHUB_CLIENT_ID=your_github_app_client_id
GITHUB_CLIENT_SECRET=your_github_app_client_secret
FLASK_SECRET_KEY=any_random_string
OPENROUTER_API_KEY=your_openrouter_key
```

**2. Install dependencies:**
```bash
pip install -r requirements.txt
```

**3. Login with GitHub:**
```bash
python login.py
```
Open `http://127.0.0.1:5000` → click "Login with Github" → authorize → done.
This saves your token to `.github_token`. You only need to do this once.

---

## Running

**Option A — AI Agent (terminal)**
```bash
python agent.py
```
Enter a repo name when prompted. The AI scans it and prints a full security report.

**Option B — MCP Server (for Claude Desktop or any MCP client)**
```bash
mcp dev server.py
```

---

## What It Scans For

| Secret Type | Example Pattern |
|---|---|
| AWS Access Key | `AKIA...` |
| GitHub Token | `ghp_...` |
| Google API Key | `AIza...` |
| Stripe Keys | `sk_live_...` |
| Database URLs | `postgres://user:pass@host` |
| Generic Passwords | `password = "..."` |
| Private Keys | `-----BEGIN RSA PRIVATE KEY-----` |
| Bearer Tokens | `Authorization: Bearer ...` |
| Slack / Twilio / SendGrid tokens | various patterns |

---

## Available MCP Tools

| Tool | What it does |
|---|---|
| `list_repositories` | Lists all your GitHub repos |
| `repository_details` | Gets details about a specific repo |
| `read_file` | Reads source code from a file |
| `issues` | Lists open GitHub issues |
| `code_change_summary` | Gets recent commit messages |
| `security_scan` | Quick scan of file names for sensitive words |
| `deep_security_scan` | Full content scan of all files for secrets |

---

## Important

- Never commit `.github_token` or `.env` — both are in `.gitignore`
- If you accidentally push your token, revoke it immediately at `https://github.com/settings/tokens`