Metadata-Version: 2.4
Name: laravel-security-scanner
Version: 1.1.0
Summary: Production-grade Python CLI tool for auditing Laravel web applications for common security misconfigurations
Author: Laravel Security Scanner Team
License-Expression: MIT
Project-URL: Homepage, https://github.com/yourusername/laravel-security-scanner
Project-URL: Documentation, https://github.com/yourusername/laravel-security-scanner#readme
Project-URL: Repository, https://github.com/yourusername/laravel-security-scanner
Project-URL: Changelog, https://github.com/yourusername/laravel-security-scanner/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/yourusername/laravel-security-scanner/issues
Keywords: laravel,security,scanner,vulnerability,audit,cli
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: System :: Systems Administration
Classifier: Environment :: Console
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: pydantic-settings>=2.3.0
Requires-Dist: loguru>=0.7.2
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.2.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: black>=24.4.2; extra == "dev"
Requires-Dist: isort>=5.13.2; extra == "dev"

# 🔍 Laravel Security Scanner

Production-grade Python CLI tool for auditing Laravel web applications for common security misconfigurations.

## 🎯 What It Checks

| Check ID | Title | Severity |
|---|---|---|
| `ENV_EXPOSED` | .env file publicly accessible | 🔴 CRITICAL |
| `DEBUG_MODE` | Laravel debug mode enabled | 🔴 HIGH |
| `SENSITIVE_FILES` | Sensitive files/directories exposed | 🔴 HIGH |
| `SECURITY_HEADERS` | Missing HTTP security headers | 🟠 MEDIUM |
| `INSECURE_CONFIG` | CORS, cookie flags, server headers | 🟠 MEDIUM |
| `LARAVEL_VERSION` | Laravel version disclosure | 🟠 MEDIUM |
| `TELESCOPE_EXPOSED` | Laravel Telescope exposed | 🔴 HIGH |
| `DEBUGBAR_EXPOSED` | Laravel Debugbar exposed | 🟠 MEDIUM |
| `MIX_MANIFEST_EXPOSED` | Laravel Mix manifest exposed | 🟢 LOW |
| `HORIZON_EXPOSED` | Laravel Horizon exposed | 🟠 MEDIUM |
| `NOVA_EXPOSED` | Laravel Nova exposed | 🔴 HIGH |
| `CSRF_PROTECTION` | CSRF protection missing | 🔴 HIGH |
| `SESSION_SECURITY` | Session security configuration | 🟠 MEDIUM |
| `RATE_LIMITING` | Rate limiting missing | 🟠 MEDIUM |
| `HTTP_METHODS` | Dangerous HTTP methods enabled | 🟠 MEDIUM |
| `COMPOSER_CVE` | Composer.lock CVE scan | 🔴 CRITICAL |

## 📁 Project Structure

```
laravel-security-scanner/
├── app/
│   ├── core/
│   │   ├── settings.py        # Pydantic settings + .env loader
│   │   └── logging.py         # Loguru structured logging
│   ├── models/
│   │   └── scan.py            # ScanTarget, Finding, ScanResult models
│   ├── services/
│   │   ├── scanner.py         # ScannerService — async orchestrator
│   │   ├── reporter.py        # Console / JSON / TXT / HTML / SARIF report generator
│   │   ├── rate_limiter.py    # RateLimiter & RetryableClient
│   │   └── checks/
│   │       ├── base.py        # BaseCheck abstract class
│   │       ├── __init__.py    # Check registry (ALL_CHECKS)
│   │       ├── env_exposed.py
│   │       ├── debug_mode.py
│   │       ├── security_headers.py
│   │       ├── sensitive_files.py
│   │       ├── insecure_config.py
│   │       ├── laravel_version.py
│   │       ├── telescope_exposed.py
│   │       ├── debugbar_exposed.py
│   │       ├── mix_manifest_exposed.py
│   │       ├── horizon_exposed.py
│   │       ├── nova_exposed.py
│   │       ├── csrf_protection.py
│   │       ├── session_security.py
│   │       ├── rate_limiting.py
│   │       ├── http_methods.py
│   │       └── composer_lock_cve.py
│   └── utils/
│       └── url.py             # URL normalisation
├── tests/
│   └── unit/
│       ├── test_models.py
│       ├── test_url_utils.py
│       ├── test_env_check.py
│       ├── test_laravel_version.py
│       ├── test_telescope_exposed.py
│       ├── test_debugbar_exposed.py
│       ├── test_mix_manifest_exposed.py
│       ├── test_horizon_exposed.py
│       ├── test_nova_exposed.py
│       ├── test_csrf_protection.py
│       ├── test_session_security.py
│       ├── test_rate_limiting.py
│       ├── test_http_methods.py
│       └── test_composer_lock_cve.py
├── .github/
│   └── workflows/
│       └── ci.yml               # GitHub Actions CI/CD
├── logs/
├── reports/
├── cve_database.json            # CVE database for composer scan
├── .env.example
├── requirements.txt
├── pytest.ini
├── CHANGELOG.md
├── VERSION
└── main.py
```

## 🔧 Setup

```bash
# 1. Clone / download
git clone https://github.com/AlgoDev/Laravel-Security-Scanner.git
cd laravel-security-scanner

# 2. Create virtualenv
python3.11 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Configure
cp .env.example .env
# Edit .env as needed
```

## 🚀 Usage

```bash
# Scan a single target (all formats)
python main.py https://your-laravel-app.com

# Multiple targets
python main.py https://app1.com https://app2.com

# JSON report only
python main.py https://app.com --format json --output ./my-reports

# HTML report only
python main.py https://app.com --format html --output ./my-reports

# SARIF report for GitHub Security tab
python main.py https://app.com --format sarif --output ./my-reports

# Skip SSL verification (e.g. staging with self-signed cert)
python main.py https://staging.app.com --no-ssl-verify

# Set custom timeout
python main.py https://app.com --timeout 20

# Run specific checks only
python main.py https://app.com --checks ENV_EXPOSED,DEBUG_MODE,COMPOSER_CVE
```

## 🎯 Features

- **Multiple Output Formats**: Console, JSON, TXT, HTML, and SARIF reports
- **Progress Bar**: Real-time progress tracking with rich library during scans
- **CI/CD Integration**: GitHub Actions workflow included (`.github/workflows/ci.yml`)
- **Async Scanning**: Concurrent checks for faster results
- **Comprehensive Checks**: 16 security checks covering critical Laravel vulnerabilities
- **SARIF Support**: SARIF format output for GitHub Security tab integration
- **Rate Limiting**: Built-in rate limiter to avoid overwhelming target servers
- **Retry Mechanism**: Automatic retry for failed requests with exponential backoff
- **Connection Pooling**: HTTP connection reuse for better performance
- **Check Selection**: Use `--checks` to run specific checks only

## 🧪 Running Tests

```bash
pytest tests/unit/ -v
pytest tests/ -v --tb=short   # all tests
```

**Current Test Coverage**: 51 tests passing ✅

## ➕ Adding a New Check

1. Create `app/services/checks/my_check.py` extending `BaseCheck`
2. Implement `async def run(self, target: ScanTarget) -> Finding`
3. Register in `app/services/checks/__init__.py → ALL_CHECKS`

That's it — the `ScannerService` picks it up automatically.

## 📤 Exit Codes

| Code | Meaning |
|---|---|
| `0` | All targets clean |
| `1` | One or more vulnerabilities found |

Useful for CI/CD pipelines: `python main.py https://app.com || echo "Security issues found!"`

## 📋 Changelog

See [CHANGELOG.md](CHANGELOG.md) for detailed version history.

## 📌 Version

Current version: **v1.1.0** (see [VERSION](VERSION) file)

---

**🎯 Total Security Checks**: 16  
**📊 Output Formats**: 5 (Console, JSON, TXT, HTML, SARIF)  
**🧪 Tests**: 51 passing  
**🚀 CI/CD**: GitHub Actions ready
