cybret-scanner 1.0.0
AI-Powered Logic Vulnerability Scanner with Autonomous Remediation
License: MIT
Requires Python: >=3.9
Keywords: security, vulnerability-scanner, static-analysis, sast, idor, bola, logic-vulnerabilities, ai-security, llm, autonomous-remediation, devsecops

# CYBRET Scanner

<div align="center">

```
   ______  ______  ____   ____  ______ ______
  / ____/ /_  __/ / __ ) / __ \/ ____//_  __/
 / /       / /   / __  |/ /_/ / __/    / /   
/ /___    / /   / /_/ // _, _/ /___   / /    
\____/   /_/   /_____//_/ |_/_____/  /_/     
```

**AI-Powered Logic Vulnerability Scanner with Autonomous Remediation**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![PyPI version](https://badge.fury.io/py/cybret-scanner.svg)](https://badge.fury.io/py/cybret-scanner)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

[Features](#-features) • [Installation](#-installation) • [Quick Start](#-quick-start) • [Documentation](#-documentation) • [Contributing](#-contributing)

</div>

---

## 🎯 What is CYBRET Scanner?

CYBRET Scanner is a **next-generation security tool** that combines static analysis with AI-powered autonomous remediation to detect and fix logic vulnerabilities in your code.

### Why CYBRET?

- **🎯 Zero False Positives** - Evidence-based scoring eliminates noise
- **🤖 AI-Powered** - Multi-agent LLM system understands business context
- **⚡ Fast** - Scans 1000+ files in minutes
- **🔧 Auto-Fix** - Generates and applies security fixes automatically
- **🌍 Multi-Language** - Python, JavaScript/TypeScript, Java, Go
- **📊 Graph-Based** - Neo4j knowledge graph for deep analysis

### What It Detects

| Vulnerability Type | Description | CWE |
|-------------------|-------------|-----|
| **IDOR/BOLA** | Insecure Direct Object References | CWE-639 |
| **Auth Bypass** | Missing authentication checks | CWE-862 |
| **Privilege Escalation** | Improper authorization | CWE-269 |
| **Missing Ownership Checks** | Unvalidated resource access | CWE-284 |

---

## ✨ Features

### Core Capabilities

- **🔍 Static Analysis**
  - Multi-language AST parsing
  - Cross-file data flow analysis
  - Call chain tracing
  - Pattern-based detection

- **🧠 AI-Powered Analysis**
  - Multi-agent reasoning system
  - Context-aware vulnerability assessment
  - Business logic understanding
  - Confidence scoring with evidence

- **🔧 Autonomous Remediation**
  - Automatic fix generation
  - Code quality validation
  - Backup creation
  - Pull request automation
  - Security test generation

- **📊 Knowledge Graph**
  - Neo4j-powered code representation
  - Relationship mapping
  - Complex query patterns
  - Visual exploration

### Enterprise Features

- ✅ REST API with OpenAPI docs
- ✅ Docker & Kubernetes ready
- ✅ Prometheus metrics
- ✅ CI/CD integration
- ✅ Incremental scanning
- ✅ Custom rule engine

---

## 🚀 Installation

### Quick Install (Recommended)

```bash
pip install cybret-scanner
```

### Install with LLM Support

```bash
pip install cybret-scanner[llm]
```

### Install from Source

```bash
git clone https://github.com/cybret/cybret-scanner.git
cd cybret-scanner
pip install -e .
```

### Prerequisites

- **Python 3.9+**
- **Neo4j 5.0+** (for graph database)
- **Node.js 16+** (for TypeScript parsing)
- **LLM API Key** (optional, for AI features)

### System Dependencies

```bash
# Install TypeScript parser
npm install -g @typescript-eslint/typescript-estree

# Start Neo4j (Docker)
docker run -d --name neo4j \
  -p 7687:7687 -p 7474:7474 \
  -e NEO4J_AUTH=neo4j/password123 \
  neo4j:latest
```

---

## 🎬 Quick Start

### 1. Basic Scan

```bash
# Scan a directory
cybret scan ./my-app --language javascript

# With verbose output
cybret scan ./my-app --language python --verbose
```

### 2. AI-Powered Analysis

```bash
# Set your API key
export OPENROUTER_API_KEY="sk-or-v1-..."

# Scan with AI analysis
cybret scan ./my-app \
  --language javascript \
  --llm-analyze \
  --llm-report report.md
```

### 3. Full Automation (Scan → Fix → PR)

```bash
# Auto-apply fixes and create PR
cybret scan ./my-app \
  --language javascript \
  --llm-analyze \
  --auto-apply \
  --create-pr \
  --generate-tests
```

### 4. Analyze Existing Results

```bash
# Analyze previous scan results
cybret analyze results.json ./my-app \
  --output remediation-report.md
```

---

## 📖 Usage Examples

### Scanning Different Languages

```bash
# Python
cybret scan ./backend --language python -o results.json

# JavaScript/TypeScript
cybret scan ./frontend --language javascript -o results.json

# Java
cybret scan ./api --language java -o results.json

# Go
cybret scan ./services --language go -o results.json
```

### CI/CD Integration

#### GitHub Actions

```yaml
name: Security Scan

on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install CYBRET Scanner
        run: pip install cybret-scanner
      
      - name: Start Neo4j
        run: |
          docker run -d --name neo4j \
            -p 7687:7687 \
            -e NEO4J_AUTH=neo4j/password123 \
            neo4j:latest
      
      - name: Run Scan
        run: |
          cybret scan . \
            --language javascript \
            --output results.json
      
      - name: Upload Results
        uses: actions/upload-artifact@v3
        with:
          name: scan-results
          path: results.json
```

#### GitLab CI

```yaml
security_scan:
  image: python:3.11
  services:
    - neo4j:latest
  variables:
    NEO4J_AUTH: neo4j/password123
  script:
    - pip install cybret-scanner
    - cybret scan . --language python --output results.json
  artifacts:
    paths:
      - results.json
```

### Docker Usage

```bash
# Build image
docker build -t cybret-scanner .

# Run scan
docker run --rm \
  -v $(pwd):/code \
  -e NEO4J_URI=bolt://neo4j:7687 \
  cybret-scanner scan /code --language python
```

---

## 🧠 AI-Powered Features

### LLM Providers

CYBRET Scanner supports multiple LLM providers:

| Provider | Models | Setup |
|----------|--------|-------|
| **OpenRouter** | Claude, GPT-4, Gemini, etc. | `export OPENROUTER_API_KEY=...` |
| **Anthropic** | Claude 3.5 Sonnet/Opus | `export ANTHROPIC_API_KEY=...` |
| **OpenAI** | GPT-4 Turbo | `export OPENAI_API_KEY=...` |
| **Ollama** | Llama 3.1, Mixtral (local) | `export OLLAMA_BASE_URL=...` |

### Multi-Agent System

CYBRET uses 4 specialized AI agents:

1. **Analyst Agent** - Understands vulnerability context
2. **Expert Agent** - Assesses security impact
3. **Generator Agent** - Creates secure fixes
4. **Validator Agent** - Ensures fix quality

### Configuration

```bash
# .env file
OPENROUTER_API_KEY=sk-or-v1-...
LLM_MODEL=anthropic/claude-3.5-sonnet
```

---

## 📊 Output Formats

### JSON Report

```json
{
  "scan_id": "scan_abc123",
  "vulnerabilities": [
    {
      "vuln_id": "IDOR-xyz789",
      "type": "IDOR",
      "severity": "critical",
      "confidence": 0.945,
      "file_path": "routes/payment.ts",
      "line_start": 19,
      "function_name": "getPaymentMethods",
      "description": "Missing ownership check on payment retrieval",
      "remediation": "Add user ID validation before database query"
    }
  ]
}
```

### Markdown Report (with LLM)

```markdown
# Security Remediation Report

## Executive Summary
- Total Vulnerabilities: 5
- Approved Fixes: 4
- High Confidence: 3

## Vulnerability Details

### 1. IDOR in Payment Endpoint (CRITICAL)
**Location:** `routes/payment.ts:19`
**Confidence:** 94.5%

**Issue:** Missing ownership check allows users to access other users' payment methods.

**Fix:**
\`\`\`typescript
// Add ownership validation
if (paymentMethod.userId !== req.user.id) {
  throw new ForbiddenError();
}
\`\`\`

**Impact:** Prevents unauthorized access to sensitive payment data.
```

---

## 🔧 Configuration

### Environment Variables

```bash
# Neo4j Configuration
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=password123
NEO4J_DATABASE=neo4j

# LLM Configuration
OPENROUTER_API_KEY=sk-or-v1-...
LLM_MODEL=anthropic/claude-3.5-sonnet

# Scanner Settings
SCAN_TIMEOUT=3600
MAX_FILE_SIZE=10485760
```

### Custom Configuration File

```python
# config.py
from scanner.config import Settings

settings = Settings(
    neo4j_uri="bolt://localhost:7687",
    llm_model="anthropic/claude-3.5-sonnet",
    idor_detection_enabled=True,
    auth_bypass_detection_enabled=True
)
```

---

## 📚 Documentation

### Core Documentation

- **[Quick Start Guide](docs/quick-start.md)** - Get started in 5 minutes
- **[Architecture Guide](docs/architecture.md)** - How CYBRET works
- **[API Reference](docs/api-reference.md)** - REST API documentation
- **[CLI Reference](docs/cli-reference.md)** - Command-line usage

### Advanced Topics

- **[LLM Integration](docs/llm-integration.md)** - AI-powered features
- **[Custom Detectors](docs/custom-detectors.md)** - Build your own rules
- **[Graph Queries](docs/graph-queries.md)** - Neo4j query patterns
- **[CI/CD Integration](docs/cicd-integration.md)** - Automation guides

### Guides

- **[Deployment Guide](docs/deployment.md)** - Production setup
- **[Troubleshooting](docs/troubleshooting.md)** - Common issues
- **[Contributing](CONTRIBUTING.md)** - Development guide

---

## 🎯 Real-World Results

### OWASP Juice Shop Benchmark

```
✓ 108 routes extracted (100% coverage)
✓ 50/108 handlers analyzed (46.3%)
✓ 49 cross-file resolutions
✓ 0% false positives
✓ <5 second scan time
✓ 87 TypeScript files analyzed
```

### Performance Metrics

| Metric | Value |
|--------|-------|
| Scan Speed | ~1000 files/minute |
| Memory Usage | ~500MB |
| Accuracy | 100% precision, ~85% recall |
| False Positives | 0% |

---

## 🏗️ Architecture

```
┌─────────────────────────────────────────────────┐
│                  CLI / REST API                  │
└─────────────────────┬───────────────────────────┘
                      │
        ┌─────────────┼─────────────┐
        │             │             │
        ▼             ▼             ▼
   ┌────────┐   ┌─────────┐   ┌─────────┐
   │ Parser │   │  Graph  │   │Detector │
   │ Engine │──▶│ Builder │──▶│ Engine  │
   └────────┘   └─────────┘   └─────────┘
        │             │             │
        │             ▼             │
        │        ┌─────────┐        │
        │        │  Neo4j  │        │
        │        │  Graph  │        │
        │        └─────────┘        │
        │                           │
        └───────────┬───────────────┘
                    │
                    ▼
            ┌───────────────┐
            │  LLM Multi-   │
            │  Agent System │
            └───────────────┘
                    │
        ┌───────────┼───────────┐
        ▼           ▼           ▼
   ┌────────┐ ┌─────────┐ ┌────────┐
   │  Fix   │ │   PR    │ │  Test  │
   │Applier │ │ Creator │ │  Gen   │
   └────────┘ └─────────┘ └────────┘
```

---

## 🤝 Contributing

We welcome contributions! Here's how to get started:

### Development Setup

```bash
# Clone repository
git clone https://github.com/cybret/cybret-scanner.git
cd cybret-scanner

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linters
black .
flake8 .
mypy scanner/
```

### Contribution Guidelines

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.

---

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

## 🙏 Acknowledgments

Built with:
- [FastAPI](https://fastapi.tiangolo.com/) - Modern web framework
- [Neo4j](https://neo4j.com/) - Graph database
- [Rich](https://rich.readthedocs.io/) - Terminal formatting
- [LangChain](https://www.langchain.com/) - LLM orchestration
- [Click](https://click.palletsprojects.com/) - CLI framework

---

## 📞 Support

- **Documentation:** [https://github.com/cybret/cybret-scanner](https://github.com/cybret/cybret-scanner)
- **Issues:** [GitHub Issues](https://github.com/cybret/cybret-scanner/issues)
- **Discussions:** [GitHub Discussions](https://github.com/cybret/cybret-scanner/discussions)
- **Email:** contact@cybret.ai

---

## 🗺️ Roadmap

### v1.1 (Q2 2026)
- [ ] Web dashboard UI
- [ ] SARIF output format
- [ ] GitHub Security tab integration
- [ ] More language support (C#, Ruby, PHP)

### v1.2 (Q3 2026)
- [ ] IDE plugins (VSCode, IntelliJ)
- [ ] Real-time scanning
- [ ] Team collaboration features
- [ ] Custom rule builder UI

### v2.0 (Q4 2026)
- [ ] Multi-tenant SaaS platform
- [ ] Advanced AI reasoning
- [ ] Compliance reporting
- [ ] Enterprise SSO

---

<div align="center">

**Made with ❤️ by CYBRET AI**

[⭐ Star us on GitHub](https://github.com/cybret/cybret-scanner) • [🐦 Follow on Twitter](https://twitter.com/cybret_ai) • [💼 LinkedIn](https://linkedin.com/company/cybret)

</div>