Skip to content

SECURITY.md

Latest commit

 

History

History
275 lines (189 loc) · 8.23 KB

SECURITY.md

File metadata and controls

275 lines (189 loc) · 8.23 KB
Raw

Security Policy

Supported Versions

We release patches for security vulnerabilities in the following versions:

Version Supported
1.5.x ✅
1.4.x ✅
< 1.4 ❌

Reporting a Vulnerability

Please do not report security vulnerabilities through public GitHub issues.

Instead, please report them through one of these channels:

Option 1: GitHub Security Advisories (Preferred)

  1. Go to the Security tab of this repository
  2. Click "Report a vulnerability"
  3. Fill out the form with details

Option 2: Email

Send an email to the maintainers with:

  • A description of the vulnerability
  • Steps to reproduce the issue
  • Affected versions
  • Any potential impact assessment

What to Include

When reporting a vulnerability, please include:

  1. Type of vulnerability (e.g., XSS, injection, privilege escalation)
  2. Location of the affected source code (file, line number, function)
  3. Proof of concept or exploit code (if available)
  4. Impact assessment - what an attacker could accomplish
  5. Suggested remediation (if you have recommendations)

Response Timeline

  • Initial Response: Within 48 hours of receipt
  • Triage Completed: Within 7 days
  • Fix Development: Depends on severity (critical: 7 days, high: 14 days, medium: 30 days)
  • Public Disclosure: After fix is released (coordinated with reporter)

Security Update Process

  1. Security issue received and acknowledged
  2. Issue triaged and severity assessed
  3. Fix developed and tested
  4. Security advisory drafted
  5. Fix released with advisory
  6. CVE requested (if applicable)

Vulnerability Disclosure Policy

We follow a coordinated disclosure policy:

  • We will work with you to understand and validate the issue
  • We will develop and test a fix
  • We will publicly disclose the vulnerability after a fix is available
  • We will credit the reporter (unless anonymity is requested)

Disclosure Timeline

  • 90 days maximum from report to public disclosure
  • Earlier disclosure if a fix is released
  • Extensions possible for complex issues (with mutual agreement)

Security Best Practices for Users

When using Guvnr:

1. Keep Updated

npm update guvnr

2. Use Pre-commit Hooks

pip install pre-commit
pre-commit install

The hooks include:

  • detect-secrets for credential scanning
  • Dependency vulnerability checking
  • AI-specific pattern detection

3. Validate AI-Generated Code

Always run /security-review on AI-generated code, especially:

  • Authentication and authorization code
  • Input handling and validation
  • Database queries
  • External API integrations
  • File system operations

4. Check Dependencies

The framework includes slopsquatting prevention:

# Verify dependencies before installing
./scripts/hooks/verify-deps.sh

5. Use the Doctor Command

npx guvnr doctor

This checks for:

  • Outdated dependencies
  • Missing security configurations
  • Known vulnerability patterns

Security Features

The framework includes security features to help protect your codebase:

Feature Purpose
/security-review command OWASP-aligned security audit
Pre-commit hooks Automated security scanning
verify-deps.sh Slopsquatting detection
MCP server security Rate limiting, input validation
Template security No hardcoded credentials in templates

Security Architecture

Threat Model

Assets Protected:

  • Secrets and credentials in project files
  • Project configuration (CLAUDE.md, guvnr.yaml)
  • MCP memory database (decisions, patterns, context)
  • User input (command arguments, file paths, configuration)

Mitigations by Threat:

Threat Mitigations Components
Secret Exposure Content scanning with 100+ patterns, gitignore management CLI, Pre-commit hooks
Injection Attacks Input validation, sanitization, parameterized queries CLI, MCP Server
Denial of Service Rate limiting, timeout controls, bounded input CLI, MCP Server
Path Traversal Path normalization, base path validation, null byte detection CLI, Init Command
Prototype Pollution Object.create(null), Object.hasOwn() checks CLI, Commands
Log Injection Control character stripping, ANSI escape removal CLI, Error handling
ReDoS Bounded quantifiers in all regex patterns Secret detection
Memory Exhaustion Size limits on imports, connection pooling MCP Server

CLI Security

Input Validation Chain:

User Input → Length Check → Type Normalization → Sanitization → Command Handler
  • Maximum argument length: 1000 chars (configurable via GUVNR_MAX_ARG_LENGTH)
  • Command timeout: 5 minutes (configurable via GUVNR_TIMEOUT)
  • Signal handling for graceful abort (SIGINT, SIGTERM)
  • All violations collected before reporting

Secret Detection

100+ patterns across 10 categories with ReDoS-protected regex:

  • AI/ML Keys (OpenAI, Anthropic, Google AI, etc.)
  • Cloud Providers (AWS, Azure, GCP)
  • VCS Tokens (GitHub, GitLab, Bitbucket)
  • Communication (Slack, Discord, Twilio)
  • Payment (Stripe, PayPal)
  • Databases (MongoDB, PostgreSQL, MySQL, Redis)
  • Package Registries (npm, PyPI)
  • Email Services (SendGrid, Mailchimp)
  • Cryptographic Material (Private keys, JWTs)

ReDoS Protection: All patterns use bounded quantifiers (e.g., {1,100} instead of +). Patterns are tested in tests/security.test.js.

MCP Server Security

Rate Limiting:

  • Default: 100 ops/minute (PROJECT_MEMORY_RATE_LIMIT)
  • Token bucket algorithm with sliding window
  • Metrics exposed via health endpoint

Connection Pooling:

  • Pool size: 5 (PROJECT_MEMORY_POOL_SIZE)
  • Temp connection limit: 10
  • Wait queue: 50 requests max
  • WAL mode for SQLite concurrency

Import Security:

JSON Size Check (before parsing) → JSON Parse → Schema Validation → Checksum Verification → Import

Limits:

  • JSON size: 10MB
  • Decisions: 10,000
  • Patterns: 1,000
  • Context keys: 500

Purge Protection: Two-step confirmation with 128-bit token and 60-second TTL.

Error Handling

Error contexts are sanitized to prevent information leakage:

  • Path redaction for home directories
  • Circular reference handling
  • Sensitive env var filtering (*KEY*, *SECRET*, *TOKEN*, *PASSWORD*, etc.)
  • Stack trace sanitization

Running Security Tests

# All security tests
node --test tests/security.test.js

# ReDoS resistance tests
node --test tests/security.test.js --test-name-pattern "ReDoS"

Known Security Considerations

AI-Specific Risks

The framework is designed to mitigate AI-specific security risks:

Risk Prevalence Mitigation
XSS in AI code 86% /security-review command
Log injection 88% Pattern detection in hooks
Hallucinated packages 20% verify-deps.sh hook
Privilege escalation 322% higher Access control reviews

MCP Server

The MCP server includes security measures:

  • Input validation: All inputs sanitized
  • Rate limiting: Prevents abuse
  • No code execution: Read-only memory operations
  • Local-only: No network exposure by default

Security Acknowledgments

We thank the following for their contributions to the security of this project:

  • [Contributors listed here]

Additional Resources