codeguard-pro 0.3.3

Inline security gate for AI coding agents: secrets, supply chain, OWASP, and MiniMax-assisted deep analysis.

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

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:

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

If you want a quick product demo:

codeguard demo

If you want the MCP server locally:

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

codeguard-mcp

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

codeguard-mcp --stdio

Print a ready-to-paste config snippet:

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

Generic MCP config:

{
  "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:

{
  "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

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 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 for the benchmark definition and what the numbers mean.

You can also run the local demo directly:

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:

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:

pip freeze | codeguard check --stdin

codeguard init

Bootstrap a security policy for your repo in one command:

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:

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