pury/README.md

🛡️ AI-powered security scanner with advanced threat detection, dual reporting system (detailed & summary), and comprehensive code analysis

# PuryAI - AI-Powered Code Security Scanner 🛡️

[![npm version](https://badge.fury.io/js/pury.svg)](https://badge.fury.io/js/pury)
[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

PuryAI is a powerful, AI-powered command-line tool and library that ensures the
"purity" and security of your codebase. It combines traditional static analysis
with cutting-edge AI technology to detect malware, vulnerabilities, secrets, and
code quality issues.

## 🌟 Features

### 🔍 AI-Powered Analysis

- **Malware Detection**: Advanced pattern recognition to identify malicious
  code, obfuscation, and suspicious behaviors
- **Secret Scanning**: Detects API keys, passwords, tokens, and other sensitive
  information
- **Vulnerability Assessment**: Identifies security weaknesses and dependency
  vulnerabilities
- **Code Quality**: Analyzes code smells, performance issues, and
  maintainability problems

### 🤖 Gemini AI Integration

- Powered by Google's Gemini AI for intelligent code analysis
- Context-aware scanning that understands code intent
- Real-time streaming analysis for large codebases
- Low false-positive rates through AI reasoning

### 🛠️ Practical Tools

- **Console Cleaner**: Remove debug statements before production
- **Localization Helper**: Convert non-English text to English for international
  collaboration
- **Environment Formatter**: Organize and validate .env files
- **Multiple Output Formats**: Console, JSON, HTML, and SARIF reports

## 🚀 Quick Start

### Installation

```bash
# Install globally
npm install -g pury

# Or use with npx
npx pury --help
```

### Setup

1. Get your Gemini API key from [Google AI Studio](https://aistudio.google.com/)
2. Set the environment variable:

   ```bash
   export GEMINI_API_KEY="your-api-key-here"
   ```

3. Initialize configuration:
   ```bash
   pury init
   ```

### Basic Usage

```bash
# Scan current directory
pury scan .

# Scan specific directory with JSON output
pury scan ./src --format json

# Clean console.log statements
pury clean-logs ./src --apply

# Convert non-English text to English
pury localize ./src --apply

# Format environment files
pury env-format .env --apply
```

## 📖 Detailed Usage

### Scanning for Security Issues

```bash
# Basic security scan
pury scan ./project

# Scan with specific analyzers
pury scan ./src --analyzers malware secrets vulnerabilities

# High sensitivity scan
pury scan ./src --sensitivity high

# Output to file
pury scan ./src --format json --output security-report.json
```

### Configuration

Create a `puryai.config.yaml` file:

```yaml
scanner:
  exclude:
    - node_modules/**
    - dist/**
    - '*.min.js'
  maxFileSize: 1048576 # 1MB

analyzers:
  malware:
    enabled: true
    sensitivity: medium
  secrets:
    enabled: true
    sensitivity: high
  vulnerabilities:
    enabled: true
    sensitivity: medium

ai:
  provider: gemini
  gemini:
    model: gemini-2.5-flash
    temperature: 0.1
    maxTokens: 2048
```

### Command Reference

#### `pury scan [path]`

Scan files for security threats and code quality issues.

**Options:**

- `--config <file>`: Configuration file path
- `--exclude <patterns...>`: Patterns to exclude
- `--include <patterns...>`: Patterns to include
- `--format <type>`: Output format (console, json, html, sarif)
- `--no-ai`: Disable AI analysis
- `--analyzers <types...>`: Specific analyzers to run
- `--sensitivity <level>`: Analysis sensitivity (low, medium, high)

#### `pury clean-logs [path]`

Remove console.log and debug statements.

**Options:**

- `--apply`: Actually apply changes (default is dry-run)
- `--backup`: Create backup files
- `--exclude <patterns...>`: Patterns to exclude

#### `pury localize [path]`

Convert non-English text to English.

**Options:**

- `--apply`: Apply changes
- `--backup`: Create backup files
- `--target-lang <lang>`: Target language (default: en)

#### `pury env-format [path]`

Format and organize environment files.

**Options:**

- `--apply`: Apply formatting
- `--backup`: Create backup files
- `--sort`: Sort variables alphabetically
- `--group`: Group related variables

#### `pury init`

Initialize configuration file.

**Options:**

- `--force`: Overwrite existing config
- `--global`: Create global config
- `--template <type>`: Config template (default, strict, minimal)

## 🔧 Library Usage

PuryAI can also be used as a library in your Node.js applications:

```typescript
import { PuryAI } from 'pury';

const pury = new PuryAI();
await pury.loadConfig();

const report = await pury.scan(
  {
    path: './src',
    recursive: true
  },
  {
    analyzers: ['malware', 'secrets'],
    useAI: true,
    sensitivity: 'medium'
  }
);

console.log(`Found ${report.summary.threatsFound} issues`);
```

## 🎯 Detection Capabilities

### Malware Patterns

- Obfuscated JavaScript/TypeScript code
- Base64 encoded payloads
- Suspicious function calls (eval, exec, Function constructor)
- Dynamic code generation
- Command injection patterns
- Network exfiltration attempts

### Secret Detection

- API keys (AWS, Google, GitHub, etc.)
- Database credentials and connection strings
- JWT tokens and OAuth secrets
- Private keys and certificates
- Hardcoded passwords
- Webhook URLs

### Vulnerability Types

- SQL injection opportunities
- Cross-site scripting (XSS) risks
- Command injection vulnerabilities
- Path traversal issues
- Insecure cryptographic usage
- Authentication bypasses

### Code Quality Issues

- Debug statements (console.log, debugger)
- Dead code and unreachable blocks
- Performance anti-patterns
- Complexity violations
- Non-English text in code

## 🔒 Security & Privacy

- **No Code Upload**: All analysis happens locally on your machine
- **API Privacy**: Only code patterns are sent to AI services, not full source
  code
- **Configurable**: Disable AI analysis entirely if needed
- **Open Source**: Full transparency in security analysis methods

## 📊 Output Formats

### Console Output

Clean, color-coded terminal output with severity indicators and actionable
suggestions.

### JSON Report

```json
{
  "summary": {
    "filesScanned": 42,
    "threatsFound": 3,
    "severityCount": { "high": 1, "medium": 2, "low": 0 }
  },
  "findings": [
    {
      "type": "secret",
      "severity": "high",
      "title": "API Key Detected",
      "file": "config.js",
      "line": 15,
      "suggestion": "Move to environment variables"
    }
  ]
}
```

### HTML Report

Interactive HTML report with filtering and detailed findings.

### SARIF

Industry-standard format compatible with GitHub, VS Code, and other tools.

## 🛣️ Roadmap

- **VS Code Extension**: Real-time scanning in your editor
- **CI/CD Integration**: GitHub Actions, Jenkins, GitLab pipelines
- **Custom Rules**: Define your own detection patterns
- **Team Collaboration**: Shared configurations and reporting
- **More AI Providers**: OpenAI, Claude, and local models
- **Additional Languages**: Python, Java, Go, Rust support

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md)
for details.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- **Google Gemini AI**: For powering our intelligent analysis
- **Open Source Community**: For security patterns and vulnerability data
- **Security Researchers**: For continuous improvement of detection methods

## 📞 Support

- 📚 [Documentation](https://docs.puryai.com)
- 🐛 [Issue Tracker](https://github.com/puryai/pury/issues)
- 💬 [Discord Community](https://discord.gg/puryai)
- 📧 [Email Support](mailto:support@puryai.com)

---

**Made with ❤️ by the PuryAI Team**

_Keep your code pure, secure, and ready for production!_