codeguard-pro 0.3.0__tar.gz

codeguard_pro-0.3.0/PKG-INFO

@@ -0,0 +1,398 @@
+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