Metadata-Version: 2.4
Name: codeguard-pro
Version: 0.3.3
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

> The inline security gate for AI coding agents.

AI coding agents (Claude Code, Cursor, Copilot, IDE extensions, MCP-enabled tools) write and install fast. Too fast to reliably catch a hardcoded key, a malicious package, or an obfuscated setup hook. CodeGuard sits **inside that loop**: before install, before commit, and before shipping.

```
$ 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
pipx install codeguard-pro
codeguard install   # hooks into your repo's pre-commit
```

That's the simple path. Every `git commit` now scans for secrets automatically.

If you prefer a virtualenv:

```bash
python3 -m venv .venv
. .venv/bin/activate
pip install codeguard-pro
```

If you want a quick product demo:

```bash
codeguard demo
```

If you want the MCP server locally:

```bash
codeguard-mcp
```

## Why People Will Use It

- **Simple install**: `pipx install codeguard-pro` or install inside a `venv`
- **PEP 668 friendly**: works cleanly with `pipx` or inside a `venv`
- **Agent-focused**: built for Claude/Codex/Cursor-style workflows, not just CI
- **Real demos**: see [`DEMO.md`](DEMO.md) for outputs captured from the current codebase
- **Current attack relevance**: `.pth` startup hooks, mutable GitHub Action refs, compromised packages, behavioral setup hooks
- **Fast feedback loop**: suspicious misses can become saved samples, issue drafts, and regression tests

## 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

The packaged MCP command is:

```bash
codeguard-mcp
```

If you run it directly in a terminal, it will print a short hint instead of failing silently. For explicit server mode:

```bash
codeguard-mcp --stdio
```

Print a ready-to-paste config snippet:

```bash
codeguard mcp-config
codeguard mcp-config --client claude
codeguard mcp-config --client vscode
codeguard mcp-config --client codex
```

Generic MCP config:

```json
{
  "mcpServers": {
    "codeguard": {
      "command": "codeguard-mcp",
      "args": []
    }
  }
}
```

Client-specific UIs and file locations vary. The important part is the command: point the MCP client at `codeguard-mcp`.

### 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 / wants to install a package
       |
       v
Agent runs:
  - scan_package() before install
  - security_gate(diff) before commit
  - smart_analyze(code) for risky code
       |
  +----+----+
  |         |
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 init              # Install hook, config, and print next steps
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 check litellm     # Check a package before install
codeguard mcp-config        # Print MCP config snippet
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.

## Real Demo

See [`DEMO.md`](DEMO.md) for:
- deterministic email-injection detection
- MiniMax setup.py malware verdict
- MiniMax credential-exfiltration detection
- verified test totals used in the current release

## Benchmarks

Current verified benchmark:

- `pytest -q test_*.py` -> `112 passed, 6 skipped`
- fresh virtualenv install works
- `codeguard init` works in a new git repo
- `codeguard demo` works from the installed package
- clean code stays clean on the fast path
- adversarial install/injection samples are caught or escalated

See [`TESTING.md`](TESTING.md) for the benchmark definition and what the numbers mean.

You can also run the local demo directly:

```bash
codeguard demo
```

## 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

Visible current-attack angle:
- TeamPCP-style package compromise
- `.pth` startup-hook abuse
- GitHub Actions mutable ref poisoning
- faster package installs driven by AI agents

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.

## Feedback Loop From Misses To Tests

This is the intended improvement loop:

1. detect a miss or suspicious sample in the real world
2. save it with `codeguard learn-add`
3. generate an issue draft with `codeguard learn-report`
4. decide whether it needs:
   - a deterministic rule
   - an AI prompt change
   - a documented limitation
5. add a regression test before promoting the change

That is how CodeGuard gets better without becoming untrustworthy.

## 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
