README

VaultWatch is a comprehensive security scanner for PHP applications, powered by a Go core engine. It detects secrets, misconfigurations, and security vulnerabilities in your codebase to prevent accidental leaks and security issues.

📑 Table of Contents

Features
Installation
Usage
- Standalone CLI
- Laravel Integration
Security Agents
Output Format
Building from Source
Advanced Usage
- Custom Rules
- CI/CD Integration
Configuration
- Ignoring Files
- Excluding Paths
Contributing
License
Links
Support This Project
Credits

🚀 Features

Multi-Agent Architecture: 6 specialized security agents for comprehensive analysis
- Secrets: API keys, tokens, credentials detection
- Config: Security misconfigurations
- Exposure: Exposed endpoints and attack surface
- Hygiene: Repository hygiene and sensitive files
- Deps: Dependency security analysis
- Logic: Business logic security smells
High Performance: Powered by Go with parallel scanning and worker pools
Smart Detection: Uses Regex, Keywords, and Shannon Entropy to reduce false positives
Embedded Rules: Rules are embedded in binary - no external files needed
Laravel Ready: Native integration with Artisan commands and Facades
CI/CD Friendly: Returns exit code 1 if issues found, supports JSON output
Secure: Runs locally, no data leaves your server
Cross-Platform: Supports Linux, macOS, and Windows (amd64/arm64)

📦 Installation

composer require arjunanda/php-vaultwatch

🛠️ Usage

Standalone (CLI)

# Full security scan (all agents) - Outputs JSON by default
./vendor/bin/scan.php ./src

# Scan with human-readable output
./vendor/bin/scan.php ./src --format=text

# Scan with specific agent
./vendor/bin/scan.php ./src --agent=secrets

# Available agents: secrets, config, exposure, hygiene, deps, logic, full
./vendor/bin/scan.php ./src --agent=full

💎 Laravel Integration

This package includes a Service Provider that is automatically discovered by Laravel.

Run via Artisan:

# Full scan
php artisan vaultwatch:scan

# Scan specific directory with specific agent
php artisan vaultwatch:scan ./app --agent=secrets

# Scan with custom rules and exclude paths
php artisan vaultwatch:scan --rules=custom.yaml --exclude=tests,docs

Available Options:

php artisan vaultwatch:scan {path=.}
  {--agent=full : Agent to run (secrets, config, exposure, hygiene, deps, logic, full)}
  {--exclude= : Comma-separated exclude patterns}
  {--rules= : Path to custom rules.yaml}
  {--fail-on=HIGH : Fail CI on severity level (LOW, MEDIUM, HIGH, CRITICAL)}
  {--format=json : Output format (json, text)}
  {--json : Output as JSON (deprecated)}

Use in Code (Facade):

use VaultWatch\Facades\VaultWatch;

// Full scan
$results = VaultWatch::scan(base_path(), ['agent' => 'full']);

// Secrets only
$results = VaultWatch::scan(base_path(), ['agent' => 'secrets']);

// With excludes
$results = VaultWatch::scan(base_path(), [
    'agent' => 'full',
    'exclude' => ['vendor', 'node_modules']
]);

🔍 Security Agents

Secrets Agent

Detects hardcoded credentials and API keys:

AWS Access Keys & Secret Keys
Google API Keys
GitHub Personal Access Tokens
Stripe Keys
Slack Tokens
Private Keys (RSA, DSA, EC)
Database Connection Strings
And 20+ more patterns

Config Agent

Finds security misconfigurations:

Debug mode enabled
SSL verification disabled
Permissive CORS configuration
Default/weak credentials
Admin panels exposed

Exposure Agent

Identifies exposed endpoints:

Public API endpoints without auth
Unvalidated file uploads
Debug endpoints
Unprotected admin routes

Hygiene Agent

Detects repository hygiene issues:

.git directory in deployment
Backup files (.bak, .old)
Database dumps
Private key files
Editor swap files

Deps Agent

Analyzes dependency security:

Wildcard version constraints
Unpinned dependencies
Dev dependencies in production
Risky module replacements

Logic Agent

Finds business logic security smells:

SQL injection risks
Command execution
Code evaluation (eval)
Path traversal patterns
Weak random number generation
Hardcoded authorization

📊 Output Format

{
  "agents": [
    {
      "agent": "secrets",
      "findings": [
        {
          "id": "5b8133b7910c9ada",
          "agent": "secrets",
          "severity": "CRITICAL",
          "confidence": 0.9,
          "file": "config/app.php",
          "line": 42,
          "title": "AWS Access Key ID",
          "description": "Detected AWS Access Key ID: AK****LE",
          "recommendation": "Remove or encrypt this secret..."
        }
      ],
      "stats": {
        "files_scanned": 156,
        "secrets_found": 3
      }
    }
  ],
  "summary": {
    "total_findings": 3,
    "by_severity": {
      "CRITICAL": 2,
      "HIGH": 1
    },
    "files_scanned": 156
  }
}

🏗️ Building from Source

If you want to build the Go binary yourself:

cd core
make build-all

This will generate vaultwatch-agent binaries for all platforms in bin/:

vaultwatch-agent-linux-amd64
vaultwatch-agent-linux-arm64
vaultwatch-agent-darwin-amd64
vaultwatch-agent-darwin-arm64
vaultwatch-agent-windows-amd64.exe

🔧 Advanced Usage

Custom Rules

While rules are embedded by default, you can use custom rules:

# Go binary
./bin/vaultwatch-agent-linux-amd64 --agent=secrets --path=./src --rules=custom-rules.yaml

# PHP CLI
./vendor/bin/scan.php ./src --rules=custom-rules.yaml

# Laravel Artisan
php artisan vaultwatch:scan --rules=custom-rules.yaml

CI/CD Integration

GitHub Actions:

- name: Security Scan
  run: |
    composer install
    ./vendor/bin/scan.php . --agent=full --format=json > scan-results.json
    if [ $? -ne 0 ]; then
      echo "Security issues found!"
      exit 1
    fi

GitLab CI:

security_scan:
  script:
    - composer install
    - ./vendor/bin/scan.php . --agent=full --format=json
  allow_failure: false

📝 Configuration

Ignoring Files

Create a .vaultignore file in your project root:

# Ignore test files
tests/
*.test.php

# Ignore specific files
config/legacy.php

Excluding Paths

VaultWatch::scan(base_path(), [
    'exclude' => ['vendor', 'node_modules', 'storage', 'public']
]);

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT License - see LICENSE file for details.

🔗 Links

� Support This Project

If you find VaultWatch useful, consider supporting its development:

�🙏 Credits

Built with ❤️ using:

Go for high-performance scanning
PHP for easy integration
Laravel for seamless framework support

arjunanda / php-vaultwatch

Maintainers

Package info

Statistics

Security