Metadata-Version: 2.4
Name: codeguard-pro
Version: 0.3.0
Summary: Inline security gate for AI coding agents: secrets, supply chain, OWASP, and MiniMax-assisted deep analysis.
Home-page: https://github.com/Miles0sage/codeguard-mcp
Author: Miles
Classifier: Development Status :: 4 - Beta
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp[cli]>=1.0.0
Requires-Dist: requests>=2.31.0
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)
![MCP Compatible](https://img.shields.io/badge/MCP-compatible-green)
![Tools: 23](https://img.shields.io/badge/tools-23-orange)
![Tests: 112](https://img.shields.io/badge/tests-112-brightgreen)
![License: MIT](https://img.shields.io/badge/license-MIT-lightgrey)
![pip installable](https://img.shields.io/badge/pip-installable-blue)

# CodeGuard Pro

> Stop secrets from reaching git. The inline security gate for AI coding agents.

AI coding agents (Claude Code, Cursor, Copilot) write code fast. Too fast to catch the AWS key they just hardcoded. CodeGuard sits **inline** -- agents call `security_gate` before every commit. Secrets get blocked, not just flagged.

```
$ git commit -m "add payment integration"

CodeGuard Pro — scanning for secrets...

  BLOCKED — 2 critical secret(s) found.

  [CRITICAL] Stripe Secret Key (line 14, col 12)
    Found:  sk_l****************************eJ7z
    Fix:    Use environment variable: os.environ["STRIPE_SECRET_KEY"]

  [CRITICAL] AWS Access Key (line 22, col 8)
    Found:  AKIA****************************3Q9R
    Fix:    Use AWS credentials file (~/.aws/credentials) or IAM roles

  Commit blocked. Fix the issues above and try again.
```

## Quick Start

```bash
pip install mcp[cli]
git clone https://github.com/Miles0sage/codeguard-mcp && cd codeguard-mcp
codeguard install   # hooks into your repo's pre-commit
```

That's it. Every `git commit` now scans for secrets automatically.

## Features

| Feature | What it does |
|---|---|
| **Inline Security Gate** | MCP tool agents call before committing -- returns APPROVED / BLOCKED |
| **25+ Secret Patterns** | OpenAI, AWS, Stripe, GitHub, Slack, GCP, Supabase, private keys, JWTs... |
| **Auto-Fix Patches** | Returns a diff replacing secrets with `os.environ[]` lookups |
| **Pre-Commit Hook** | Blocks commits containing secrets at the git level |
| **OWASP Top 10 Scanner** | SQL injection, XSS, command injection, SSRF, path traversal, weak crypto |
| **Code Review Engine** | Duplicate functions, deep nesting, long functions, naming, unused imports |
| **MCP Server Audit** | Checks input validation, error handling, shell execution, rate limiting |
| **Full Audit** | Combined secrets + code review + security scan in one call |
| **Supply Chain Scanner** | Known-compromised package DB, typosquatting, unpinned deps, GitHub Actions SHA audit, OSV lookups |
| **MiniMax Beta** | Behavioral malware analysis for setup hooks, exfiltration, and exploit explanations |
| **Learning Loop** | Stores missed samples, generates issue-ready markdown, and keeps reviewable detection backlog |
| **False Positive Filtering** | Skips comments, placeholders, examples, test keys |
| **Directory Scanning** | Recursive scan with smart skipping (node_modules, .git, binaries) |

## Positioning

CodeGuard Pro is strongest as an **inline security gate for AI coding agents**.

What it does well now:
- blocks hardcoded secrets before commit
- scans code for OWASP-style issues and common injection patterns
- audits supply-chain risk before install or release
- uses MiniMax as a beta sidecar for behavioral malware and exploit explanation
- saves suspicious misses into a reviewable learning corpus instead of silently rewriting rules

What it is not yet:
- a fully autonomous self-improving security platform
- proof that the AI layer catches every crypto-indirection edge case
- an enterprise policy/observability suite with mature dashboards, SSO, audit trails, and fleet management

## MCP Integration

Add to your Claude Code config (`~/.claude.json`):

```json
{
  "mcpServers": {
    "codeguard": {
      "command": "python3",
      "args": ["/path/to/codeguard-mcp/server.py"]
    }
  }
}
```

### 23 MCP Tools

| Tool | Purpose |
|---|---|
| `security_gate` | **The gate.** Pass a diff, get APPROVED or BLOCKED with fix patches |
| `scan_secrets_in_file` | Scan a single file for hardcoded secrets |
| `scan_secrets_in_directory` | Recursive secret scan across a project |
| `smart_review` | Code review: duplicates, nesting, naming, debug statements |
| `review_file` | Review a file from disk (auto-detects language) |
| `security_scan` | OWASP Top 10 vulnerability scan on code |
| `security_scan_file` | Security scan a file from disk |
| `security_scan_directory` | Scan all files in a directory for vulns |
| `audit_mcp_server` | Security audit for MCP servers specifically |
| `scan_package` | Check a package before install for typosquatting and compromise history |
| `scan_requirements_file` | Audit a requirements file package-by-package |
| `scan_pth_files` | Detect malicious `.pth` startup hooks in site-packages |
| `scan_requirements_unpinned` | Find loose or missing dependency pins |
| `scan_github_actions` | Audit workflow actions for unpinned mutable refs |
| `query_osv` | Query OSV.dev for a package+version |
| `query_osv_batch` | Batch query OSV.dev across packages |
| `full_audit` | Secrets + code review + security scan combined |
| `deep_analyze` | MiniMax beta taint and behavioral analysis |
| `smart_analyze` | Recommended layered entry point: fast path first, MiniMax escalation only when justified |
| `analyze_setup_py` | MiniMax beta setup.py malware verdict |
| `explain_vulnerability` | MiniMax beta exploit explanation |
| `record_learning_candidate` | Save suspicious samples for later review |
| `generate_learning_issue` | Generate issue-ready markdown from a saved sample |
| `learning_summary` | Summarize the local learning corpus and issue queue |

### How Agents Use It

```
Agent writes code
       |
       v
Agent runs: security_gate(diff)
       |
  +----+----+
  |         |
APPROVED  BLOCKED
  |         |
commit    apply fix_patch
          re-run gate
          then commit
```

The agent gets structured JSON back:

```json
{
  "status": "BLOCKED",
  "critical": 1,
  "total": 1,
  "report": "...",
  "fix_patch": "--- line 14\n-  api_key = \"sk_live_abc123...\"\n+  api_key = os.environ[\"STRIPE_SECRET_KEY\"]",
  "action": "Apply the fix patch, then re-run security_gate."
}
```

## CLI Usage

```bash
codeguard install           # Install pre-commit hook
codeguard scan ./src        # Scan a directory
codeguard scan app.py       # Scan a single file
codeguard scan-diff         # Scan staged changes
codeguard learn-add sample.py --title "obfuscated setup hook"
codeguard learn-summary
codeguard uninstall         # Remove hook (restores backup)
```

## Recommended Flow

Use `smart_analyze` as the default code-analysis entry point:

1. deterministic fast path runs first
2. MiniMax escalation runs only when the result is high-risk but incomplete, behavior looks suspicious, or a deeper explanation is requested
3. optional learning-corpus capture stores suspicious misses for review

That keeps cost and latency low while still giving you deeper analysis when regex alone is not enough.

## AI Beta

MiniMax is wired directly to the official MiniMax API using `MINIMAX_API_KEY`.

Recommended usage:
- call `smart_analyze` first for code-level analysis
- let `smart_analyze` decide whether deterministic findings are enough or whether MiniMax escalation is justified
- use `deep_analyze` directly only when you explicitly want forced AI taint/behavior review

## Why Now

The timing is unusually good for launch:

- TeamPCP-class supply-chain attacks are active and visible
- AI coding agents are causing more developers to install and generate code faster than they review it
- most competing tools still run after code is written, not inline in the agent loop

CodeGuard is strongest when positioned as the security gate that sits *inside* the AI workflow:
- before install
- before commit
- before shipping

Current verified beta capabilities:
- setup-hook malware verdicts for obfuscated `exec(base64.b64decode(...))` patterns
- behavioral credential exfiltration detection
- exploit explanation generation
- graceful degradation to deterministic scanners when no key is configured

Current limits:
- latency is materially higher than regex/supply-chain scans
- crypto-indirection edge cases are not yet proven comprehensively
- AI output should be treated as reviewable evidence, not self-modifying truth

## Learning Loop

New threats should become review artifacts, not silent rule mutations.

Recommended flow:
1. Save a suspicious sample with `codeguard learn-add`.
2. Generate an issue draft with `codeguard learn-report`.
3. Review the issue and decide whether it needs a regex rule, AST rule, AI prompt update, or documentation-only limitation.
4. Add a regression test before promoting any new detector.

This keeps the product getting smarter without turning it into an opaque self-editing scanner.

## Secret Patterns (25+)

| Provider | Pattern | Severity |
|---|---|---|
| OpenAI | `sk-proj-...` | CRITICAL |
| Anthropic | `sk-ant-...` | CRITICAL |
| AWS Access Key | `AKIA...` | CRITICAL |
| AWS Secret Key | `aws_secret_access_key=...` | CRITICAL |
| GitHub Token | `ghp_...` | CRITICAL |
| GitHub OAuth | `gho_...` | CRITICAL |
| GitHub App | `ghu_/ghs_/ghr_...` | CRITICAL |
| Google API Key | `AIza...` | CRITICAL |
| Google OAuth | `GOCSPX-...` | CRITICAL |
| Stripe Secret | `sk_live_/sk_test_...` | CRITICAL |
| Stripe Publishable | `pk_live_/pk_test_...` | HIGH |
| Slack Token | `xox[bpors]-...` | CRITICAL |
| Slack Webhook | `hooks.slack.com/services/...` | HIGH |
| Twilio | `SK...` | CRITICAL |
| Discord | Bot token format | CRITICAL |
| Database URL | `postgres://user:pass@...` | CRITICAL |
| JWT | `eyJ...` | HIGH |
| Supabase Key | Supabase JWT format | HIGH |
| SendGrid | `SG....` | CRITICAL |
| Cloudflare | Context-aware token match | HIGH |
| MiniMax | `sk-cp-...` | CRITICAL |
| Vercel | `vercel_...` | CRITICAL |
| Private Keys | `-----BEGIN PRIVATE KEY-----` | CRITICAL |
| Hardcoded Passwords | `password = "..."` | CRITICAL |
| Generic API Keys | `api_key = "..."` | HIGH |

## OWASP Security Checks

- **A01** Broken Access Control -- CORS wildcards, debug mode
- **A02** Cryptographic Failures -- MD5, SHA-1, DES, RC4, ECB, hardcoded keys
- **A03** Injection -- SQL (f-strings, concatenation, % formatting), command injection (os.system, eval, exec), XSS (innerHTML, document.write, dangerouslySetInnerHTML)
- **A05** Security Misconfiguration -- SSL verification disabled, binding 0.0.0.0
- **A07** Auth Failures -- JWT verification disabled, timing-unsafe comparisons
- **A09** Logging Failures -- Sensitive data in logs
- **A10** SSRF -- Unvalidated URLs in requests/httpx/fetch
- **Bonus** Path traversal, insecure deserialization (pickle, yaml.load)

## CodeGuard vs. Others

| | CodeGuard Pro | GitGuardian | Semgrep | TruffleHog |
|---|---|---|---|---|
| **Inline agent gate** | Yes -- agents call it before commit | No | No | No |
| **Pre-commit hook** | Yes | Yes | Yes | Yes |
| **Auto-fix patches** | Yes -- returns env var replacements | No | Some | No |
| **OWASP scanner** | Yes (built-in) | No | Yes | No |
| **Code review** | Yes (built-in) | No | Partial | No |
| **MCP server audit** | Yes | No | No | No |
| **Runs locally** | Yes -- zero API calls | Cloud | Both | Both |
| **Cost** | Free | Freemium | Freemium | Free |
| **Setup** | 3 lines | Dashboard + token | Config files | Config files |

**The difference:** Other tools scan *after* code is written. CodeGuard gates the commit *inline* -- the AI agent can't proceed until secrets are removed. No secrets reach git history. Ever.

## Supply Chain Scanner

Audit your dependencies for known vulnerabilities before they ship:

```bash
codeguard check requests flask
```

```
Checking requests==2.31.0...
  [CRITICAL] CVE-2024-35195 — Session headers leak on redirect (fixed in 2.32.0)

Checking flask==3.0.0...
  No known vulnerabilities.

1 package(s) with issues. Run `codeguard check --fix` to update.
```

Works with `pip freeze` output too:

```bash
pip freeze | codeguard check --stdin
```

## `codeguard init`

Bootstrap a security policy for your repo in one command:

```bash
codeguard init              # Interactive — asks questions
codeguard init --minimal    # Pre-commit hook only, zero config
codeguard init --standard   # Hook + .codeguardrc with sane defaults
codeguard init --full       # Hook + strict policy + CI template + supply chain audit
```

| Level | Pre-commit hook | `.codeguardrc` | CI template | Supply chain scan | OWASP scan |
|---|---|---|---|---|---|
| `--minimal` | Yes | No | No | No | No |
| `--standard` | Yes | Yes | No | No | Yes |
| `--full` | Yes | Yes | Yes | Yes | Yes |

## GitHub Action

Add CodeGuard to your CI pipeline:

```yaml
# .github/workflows/codeguard.yml
name: CodeGuard Security Gate
on: [push, pull_request]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Miles0sage/codeguard-mcp@main
        with:
          scan-mode: full        # minimal | standard | full
          fail-on: critical      # critical | high | medium
          supply-chain: true     # audit dependencies
```

Blocks the PR if secrets or critical vulnerabilities are found. Results appear as inline annotations on the diff.

## Roadmap

These are the right next steps if you want to push toward the bigger vision:

- **Self-improving suggestions**: auto-cluster missed samples and propose rule/test patches for review
- **Crypto edge coverage**: stronger AST handling for `getattr`, f-string assembled alg names, and simple constant folding
- **Enterprise stability**: structured logs, request IDs, provider error reporting, policy bundles, and CI-grade observability
- **Enterprise policy**: allowlists, suppressions with expiry, approval workflows, and org-wide baseline management
- **Fleet operations**: dashboards, issue sync, audit trail, multi-repo rollups, and ticketing integrations

The product can grow into those areas, but it should not claim them as finished today.

## vs Semgrep / GitGuardian

| Capability | CodeGuard Pro | Semgrep | GitGuardian |
|---|---|---|---|
| **Inline agent gate** | Yes -- blocks before commit | No | No |
| **MCP integration** | Native (14 tools) | No | No |
| **Auto-fix patches** | Yes -- env var replacements | Partial (autofix rules) | No |
| **Supply chain scan** | Yes -- CVE lookup per package | Via Supply Chain product | No |
| **OWASP scanner** | Built-in (8 categories) | Extensive rule library | No |
| **Secret detection** | 25+ patterns, inline block | Community rules | 350+ detectors |
| **Code review** | Built-in (duplicates, nesting, naming) | Custom rules only | No |
| **Runs 100% local** | Yes -- zero API calls | Both (local + cloud) | Cloud only |
| **Setup time** | `codeguard init` (10 seconds) | Config files + rules | Dashboard + token |
| **Pricing** | Free | Free tier + paid | Free tier + paid |
| **Best for** | AI agent workflows, solo devs | Large teams, custom rules | Enterprise secret mgmt |

**CodeGuard's edge:** It is the only tool designed to sit *inside* the AI agent loop. Semgrep and GitGuardian scan after code is written. CodeGuard gates the agent -- secrets never reach git history because the agent cannot proceed until they are removed.

## Supported Languages

Python, JavaScript, TypeScript, Go, Rust, Java, Ruby -- with language-aware review rules for naming conventions, import analysis, and debug statement detection.

## License

MIT
