api-key-guard 1.0.2 → 1.0.5

package/README.md

@@ -1,84 +1,450 @@
-# 🔐 api-key-guard
+# 🔐 API Key Guard
 
 [![npm version](https://badge.fury.io/js/api-key-guard.svg)](https://www.npmjs.com/package/api-key-guard)
 [![npm downloads](https://img.shields.io/npm/dm/api-key-guard.svg)](https://www.npmjs.com/package/api-key-guard)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## Project Title & Description
+A comprehensive CLI tool for detecting, preventing, and managing API key leaks in your codebase with AI-powered documentation generation.
 
-**api-key-guard** is a comprehensive Node.js CLI tool designed to help developers and teams detect, prevent, and manage API key leaks within their codebases. It provides powerful scanning capabilities, integrates seamlessly with Git hooks, and even offers AI-powered assistance for project documentation, ensuring your secrets stay secret.
+## ⚡ Quick Start
 
-## ⚠️ Problem Statement: The Silent Threat of API Key Leaks
+```bash
+# Install globally
+npm install -g api-key-guard
 
-Accidentally committing API keys, private tokens, or sensitive credentials to a public or even private repository is a widespread and critical security vulnerability. A single leaked key can lead to:
+# Scan for API key leaks
+api-key-guard scan
 
-*   **Data Breaches:** Unauthorized access to sensitive user data.
-*   **Financial Loss:** Misuse of cloud resources, payment gateways, or premium services.
-*   **Reputational Damage:** Erosion of trust from customers and partners.
-*   **Service Interruptions:** Malicious actors disabling or disrupting your services.
+# Setup git hooks for automatic scanning
+api-key-guard setup-hooks
 
-Traditional methods often rely on manual reviews or simplistic grep commands, which are prone to error and can't keep pace with rapid development cycles. **api-key-guard** provides an automated, intelligent solution to proactively safeguard your repositories against this silent, yet devastating, threat.
+# Generate AI-powered README (requires GEMINI_API_KEY)
+export GEMINI_API_KEY=your_api_key_here
+api-key-guard readme
+```
 
-## ✨ Features List
+## 🚨 The Problem
 
-**api-key-guard** comes packed with features to make API key management robust and effortless:
+API key leaks in code repositories are a critical security vulnerability that can lead to:
 
-*   🔍 **Advanced API Key Detection:**
-    *   Utilizes a combination of regex patterns and entropy analysis to identify a wide range of common API keys (AWS, Google Cloud, Stripe, GitHub, etc.) and high-entropy strings that might be custom secrets.
-    *   Scans various file types including JavaScript, TypeScript, Python, Ruby, JSON, YAML, Markdown, and more.
-*   🎣 **Seamless Git Hooks Integration:**
-    *   Set up pre-commit hooks to automatically scan staged files before every commit, preventing secrets from ever reaching your repository.
-    *   Provides clear feedback and blocks commits if a leak is detected.
-*   🚀 **Powerful CLI Commands:**
-    *   `scan`: On-demand scanning of entire directories or specific files.
-    *   `setup-hooks`: Automates the installation of Git pre-commit hooks.
-    *   `readme`: Leverages AI to generate comprehensive `README.md` files based on your project's structure and existing documentation.
-*   🤖 **AI-Powered README Generation:**
-    *   A unique feature that helps you quickly generate professional and informative `README.md` files, improving project documentation and onboarding.
-*   📁 **Multiple File Format Support:**
-    *   Intelligently parses and scans a broad spectrum of text-based file formats, ensuring no stone is left unturned.
-*   ⚙️ **Configurable Ignore Patterns:**
-    *   Define custom ignore rules in configuration files or via CLI flags to exclude specific files, directories (e.g., `node_modules`, `dist`), or even patterns of "false positive" keys, reducing noise.
-*   🌈 **Colorful and Clear Output:**
-    *   Leverages `chalk` to provide easy-to-read, color-coded output in the terminal, highlighting detected keys and scan results.
+- **Data breaches** and unauthorized access
+- **Financial losses** from misused cloud resources  
+- **Service disruptions** and security incidents
+- **Reputational damage** from exposed credentials
 
-## 🛠️ Installation
+## ✨ Features
 
-**Prerequisites:**
+- 🔍 **Smart Detection**: Advanced regex patterns detect AWS keys, GitHub tokens, Google API keys, and more
+- 🔒 **Git Hooks Integration**: Automatic pre-commit scanning to prevent leaks
+- 🤖 **AI-Powered README**: Generate professional documentation using Google's Gemini API
+- ⚡ **Fast Scanning**: Efficient file parsing with configurable ignore patterns
+- 🌈 **Clear Output**: Color-coded results with detailed reporting
+- 📋 **Multiple Formats**: Support for JS, TS, Python, JSON, YAML, ENV files, and more
 
-*   Node.js (v14 or higher)
-*   npm (v6 or higher)
+## 📋 CLI Commands
 
-Install `api-key-guard` globally using npm:
+### Scan for API Keys
+```bash
+# Scan current directory
+api-key-guard scan
 
+# Scan specific path
+api-key-guard scan --path ./src
+
+# Verbose output with pattern details
+api-key-guard scan --verbose
+```
+
+### Git Hooks Setup
 ```bash
-npm install -g api-key-guard
+# Install pre-commit hook
+api-key-guard setup-hooks
 ```
 
-Verify the installation by checking the version:
+### AI README Generation
+```bash
+# Generate README.md
+api-key-guard readme
+
+# Force overwrite existing file
+api-key-guard readme --force
+
+# Custom output file
+api-key-guard readme --output DOCUMENTATION.md
+```
+
+## 🛠️ Installation
+
+**Prerequisites:** Node.js 14+ and npm
+
+```bash
+# Global installation (recommended)
+npm install -g api-key-guard
 
+# Local project installation
+npm install --save-dev api-key-guard
+```
+
+**Verify installation:**
 ```bash
 api-key-guard --version
 ```
 
+## 🔑 API Key Types Detected
+
+- **AWS Access Keys**: `AKIA...`
+- **GitHub Tokens**: `ghp_...`, `github_pat_...`
+- **Google API Keys**: `AIza...`
+- **Generic Patterns**: `api_key`, `secret_key`, `access_token`
+- **Bearer Tokens**: `Bearer ...`
+- **Custom Patterns**: High-entropy strings
+
+## 🤖 AI README Generation
+
+The `readme` command uses Google's Gemini API to generate comprehensive documentation:
+
+### Setup
+1. Get API key from [Google AI Studio](https://makersuite.google.com/app/apikey)
+2. Set environment variable:
+   ```bash
+   export GEMINI_API_KEY=your_api_key_here
+   ```
+
+### Generated Content
+- Project overview and description
+- Installation instructions
+- Usage examples and CLI documentation
+- Security best practices
+- Contributing guidelines
+
+## ⚙️ Configuration
+
+Create `.api-key-guard.json` in your project root:
+
+```json
+{
+  "ignorePatterns": [
+    "node_modules/**",
+    "dist/**",
+    "*.min.js",
+    "test/**/*.fixture.js"
+  ],
+  "customPatterns": [
+    {
+      "name": "Custom API Key",
+      "pattern": "custom_key_[0-9a-f]{32}"
+    }
+  ]
+}
+```
+
+## 🔐 Git Hooks
+
+The `setup-hooks` command creates a pre-commit hook that:
+
+1. Scans staged files for API keys
+2. Blocks commits if leaks are detected  
+3. Provides clear feedback on detected patterns
+4. Allows bypass with `--no-verify` if needed
+
+## 🛡️ Security Features
+
+- **Zero Storage**: API keys are never stored or logged
+- **Environment Variables**: Secure handling of authentication tokens
+- **Pattern Matching**: Regular expressions detect common key formats
+- **Entropy Analysis**: Identifies high-entropy strings that may be secrets
+- **Configurable Scanning**: Customize patterns and ignore rules
+
+## 📊 Usage Examples
+
+**Basic Scanning:**
+```bash
+api-key-guard scan
+# ✅ No potential API key leaks detected!
+```
+
+**With API Key Detection:**
+```bash
+api-key-guard scan --verbose
+# 🚨 Found 2 potential API key leak(s):
+#   📄 src/config.js:15
+#      Pattern: AKIA1234567890ABCDEF
+#   📄 .env.example:3  
+#      Pattern: sk-1234567890abcdef...
+```
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/amazing-feature`
+3. Commit changes: `git commit -m 'Add amazing feature'`
+4. Push to branch: `git push origin feature/amazing-feature`
+5. Open a Pull Request
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙋‍♂️ Support
+
+- 📖 [Documentation](https://www.npmjs.com/package/api-key-guard)
+- 🐛 [Report Issues](https://github.com/yourusername/api-key-guard/issues)
+- 💬 [Discussions](https://github.com/yourusername/api-key-guard/discussions)
+
+---
+
+**Made with ❤️ for developer security**
+npm install --save-dev api-key-guard
+```
+
 ## 🚀 CLI Usage Examples
 
-`api-key-guard` provides a simple yet powerful command-line interface.
+`api-key-guard` provides several commands for different use cases.
 
-### 1. `api-key-guard scan` - Scan your codebase for API keys
+### 🔍 `api-key-guard scan` - Detect API Keys
 
-Scan a directory or specific files for potential API key leaks.
+Scans your project for potential API key leaks.
 
-#### Basic Scan of Current Directory:
+**Basic Scan (current directory):**
 
 ```bash
 api-key-guard scan .
 ```
 
-#### Scan a Specific File:
+**Scan a specific directory:**
+
+```bash
+api-key-guard scan src/
+```
+
+**Scan a specific file:**
+
+```bash
+api-key-guard scan config/secrets.js
+```
+
+**Verbose output (shows more details about detection):**
+
+```bash
+api-key-guard scan . --verbose
+```
+
+**Fail on leak (exit with a non-zero code if leaks are found, useful for CI/CD):**
+
+```bash
+api-key-guard scan . --fail-on-leak
+```
+
+**Include specific file types (comma-separated):**
 
 ```bash
-api-key-guard scan src/utils/api.js
+api-key-guard scan . --include "*.js,*.ts,*.env"
 ```
 
-#### Scan a Specific Directory with
+**Exclude specific file types (comma-separated):**
+
+```bash
+api-key-guard scan . --exclude "*.min.js,*.lock"
+```
+
+**Ignore files or directories using patterns (shell-like glob patterns):**
+
+```bash
+api-key-guard scan . --ignore-pattern "node_modules/**" --ignore-pattern "dist/*"
+```
+
+**Use a `.gitignore` file for ignore patterns:**
+
+```bash
+api-key-guard scan . --ignore-file .gitignore
+```
+
+**Combine options:**
+
+```bash
+api-key-guard scan src/ --fail-on-leak --verbose --ignore-file .gitignore --include "*.js,*.ts"
+```
+
+### 🎣 `api-key-guard setup-hooks` - Integrate Git Hooks
+
+Sets up Git pre-commit and/or pre-push hooks to automatically scan for keys before commits or pushes.
+
+**Set up pre-commit hook (default):**
+
+```bash
+api-key-guard setup-hooks
+```
+
+This will configure your local `.git/hooks/pre-commit` script to run `api-key-guard scan --fail-on-leak` on staged files.
+
+**Set up pre-push hook:**
+
+```bash
+api-key-guard setup-hooks --hook pre-push
+```
+
+This will configure your local `.git/hooks/pre-push` script to run `api-key-guard scan --fail-on-leak` on all changes being pushed.
+
+**Remove existing hooks (if you need to clean up):**
+
+```bash
+api-key-guard setup-hooks --remove
+```
+
+### 📝 `api-key-guard readme` - Generate READMEs with AI
+
+Leverages AI to help you generate a professional README.md for your project. (Requires an active internet connection and potentially an API key for the AI service, configured via environment variables).
+
+**Generate a README with a prompt:**
+
+```bash
+api-key-guard readme "Generate a README for a Node.js CLI tool that detects API keys, focusing on its security benefits and ease of use."
+```
+
+**Generate and save to a specific file:**
+
+```bash
+api-key-guard readme --output docs/PROJECT_README.md "Generate a simple README for a web application using React and Node.js."
+```
+
+## 🎣 Git Hooks Usage
+
+Once you've set up Git hooks using `api-key-guard setup-hooks`, the tool will automatically run during your `git commit` or `git push` operations.
+
+**Example of a pre-commit hook in action:**
+
+1.  You have `api-key-guard` pre-commit hook enabled.
+2.  You accidentally add a file containing a hardcoded API key:
+    ```javascript
+    // src/config.js
+    const API_KEY = "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"; // BAD PRACTICE!
+    ```
+3.  You stage the file:
+    ```bash
+    git add src/config.js
+    ```
+4.  You try to commit:
+    ```bash
+    git commit -m "Add new config"
+    ```
+5.  `api-key-guard` will detect the leak, prevent the commit, and display a warning:
+    ```
+    🚨 api-key-guard: Potential API key leak detected in staged files! 🚨
+    Path: src/config.js
+    Line 2: const API_KEY = "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
+    
+    Commit aborted. Please remove or secure the sensitive information.
+    If you need to bypass, use 'git commit --no-verify'.
+    ```
+
+To bypass the hook for a single commit (use with extreme caution!):
+
+```bash
+git commit -m "Temporary commit, will fix secrets later" --no-verify
+```
+
+## ⚙️ Configuration
+
+`api-key-guard` can be configured using a `api-key-guard.config.json` file at the root of your project. This allows you to define custom rules, ignore patterns, and scanner settings.
+
+**Example `api-key-guard.config.json`:**
+
+```json
+{
+  "scanPaths": [
+    "src/",
+    "config/",
+    "server/"
+  ],
+  "ignorePatterns": [
+    "node_modules/**",
+    "dist/**",
+    "*.min.js",
+    "*.log",
+    "testdata/**"
+  ],
+  "ignoreFiles": [
+    ".gitignore",
+    ".dockerignore"
+  ],
+  "includeFileTypes": [
+    "*.js",
+    "*.ts",
+    "*.env",
+    "*.json",
+    "*.yaml",
+    "*.yml"
+  ],
+  "excludeFileTypes": [
+    "*.lock",
+    "package-lock.json"
+  ],
+  "customRules": [
+    {
+      "name": "Custom-API-Key",
+      "regex": "MY_CUSTOM_API_KEY_[a-zA-Z0-9]{32,64}",
+      "description": "Detects specific internal API keys."
+    }
+  ],
+  "failOnLeak": true,
+  "verbose": false
+}
+```
+
+*   **`scanPaths`**: An array of glob patterns for directories or files to explicitly scan. If empty, the current directory (`.`) is scanned.
+*   **`ignorePatterns`**: An array of glob patterns for files or directories to ignore during scanning.
+*   **`ignoreFiles`**: An array of filenames (e.g., `.gitignore`) whose contents will be used as additional ignore patterns.
+*   **`includeFileTypes`**: An array of glob patterns for file types to explicitly include. If specified, only these types will be scanned.
+*   **`excludeFileTypes`**: An array of glob patterns for file types to explicitly exclude.
+*   **`customRules`**: An array of custom regex rules for detecting specific patterns. Each rule should have a `name`, `regex`, and `description`.
+*   **`failOnLeak`**: Boolean. If `true`, the CLI will exit with a non-zero code if any leaks are found.
+*   **`verbose`**: Boolean. If `true`, more detailed output will be provided.
+
+## 🔒 Security Best Practices
+
+While `api-key-guard` is a powerful tool, it's part of a broader security strategy. Always adhere to these best practices:
+
+*   **🚫 Never Hardcode Secrets:** The golden rule. Avoid placing API keys, passwords, or sensitive tokens directly in your code.
+*   **🌳 Use Environment Variables:** For development and deployment, load secrets from environment variables (e.g., using `.env` files locally and proper environment variable injection in production).
+*   **🔐 Employ Secret Management Services:** For production environments, utilize dedicated secret management services like AWS Secrets Manager, Azure Key Vault, Google Secret Manager, HashiCorp Vault, or similar.
+*   **🔑 Implement Least Privilege:** Grant API keys only the minimum necessary permissions required for their function.
+*   **🔄 Rotate Keys Regularly:** Periodically change your API keys, especially if they are long-lived.
+*   **📚 Educate Your Team:** Ensure all developers understand the risks of secret exposure and the proper procedures for handling sensitive information.
+*   **⚙️ Integrate into CI/CD:** Incorporate `api-key-guard` scans into your Continuous Integration/Continuous Deployment pipelines to catch leaks before deployment.
+
+`api-key-guard` helps you catch mistakes, but proactive secure coding practices are paramount.
+
+## 🛣️ Future Roadmap
+
+We are continuously working to enhance `api-key-guard`. Here are some planned features:
+
+*   **Advanced Entropy Analysis:** Improve detection of generic high-entropy strings that might indicate secrets without specific patterns.
+*   **Machine Learning-Based Detection:** Explore ML models for more intelligent and adaptive secret detection.
+*   **Cloud Provider Integrations:** Direct integrations with AWS, Azure, GCP for scanning cloud-specific credential formats.
+*   **Reporting & Alerting:** Generate detailed reports and integrate with alerting systems (e.g., Slack, email) when leaks are detected in CI/CD.
+*   **Support for More Secret Types:** Expand detection to include private keys, database connection strings, access tokens, etc.
+*   **IDE Extensions:** Develop extensions for popular IDEs (VS Code, IntelliJ) for real-time feedback.
+*   **Web UI for Centralized Management:** A future goal for larger teams to manage configurations and view scan results centrally.
+
+## 🤝 Contributing
+
+We welcome contributions to `api-key-guard`! Whether it's bug reports, feature requests, or code contributions, your help is valuable.
+
+1.  **Report Bugs:** If you find a bug, please open an issue on GitHub, providing detailed steps to reproduce, expected behavior, and actual behavior.
+2.  **Suggest Features:** Have an idea for a new feature or improvement? Open an issue to discuss it.
+3.  **Code Contributions:**
+    *   Fork the repository.
+    *   Create a new branch (`git checkout -b feature/your-feature-name` or `fix/bug-fix-description`).
+    *   Make your changes.
+    *   Write tests for your changes.
+    *   Ensure your code adheres to the project's coding style.
+    *   Commit your changes (`git commit -m "feat: Add new feature"`) using conventional commits.
+    *   Push to your fork (`git push origin feature/your-feature-name`).
+    *   Open a Pull Request to the `main` branch of the original repository.
+
+Please adhere to our Code of Conduct.
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "api-key-guard",
-  "version": "1.0.2",
+  "version": "1.0.5",
   "description": "A comprehensive tool to detect, prevent, and manage API key leaks in your codebase with AI-powered README generation",
   "main": "src/index.js",
   "bin": {

package/src/readmeGenerator.js

@@ -108,7 +108,7 @@ async function generateWithGemini(apiKey, projectContext) {
           temperature: 0.7,
           topK: 40,
           topP: 0.95,
-          maxOutputTokens: 2048,
+          maxOutputTokens: 8192,
         },
         safetySettings: [
           {