README

Security scanner for BEAR.Sunday applications with OWASP Top 10 compliance.

Features

• SAST - Static Application Security Testing (14 detectors)
• DAST - Dynamic Application Security Testing
• AI Auditor - Context-aware analysis via Claude API
• OWASP Top 10 - 100% coverage for BEAR.Sunday applications
• Multiple Output Formats - Console, JSON, SARIF, HTML
• GitHub Security Integration - SARIF output for Security tab

See also: Detection Matrix | Enterprise Comparison

Installation

composer require --dev bear/security

Usage

Basic Scan

vendor/bin/bear.security-scan src

Output Formats

# Console output (default)
vendor/bin/bear.security-scan src

# JSON for CI/CD
vendor/bin/bear.security-scan src --format=json > report.json

# SARIF for GitHub Security
vendor/bin/bear.security-scan src --format=sarif > report.sarif

# OWASP Top 10 Checklist
vendor/bin/bear.security-scan src --format=checklist
vendor/bin/bear.security-scan src --format=checklist-html -o report.html

Exclude Patterns

vendor/bin/bear.security-scan src --exclude='/vendor/' --exclude='/tests/'

False Positive Suppression

Use @security-ignore comment on the same line (like @phpstan-ignore-line):

$cache->query($key); // @security-ignore
shell_exec($cmd); // @security-ignore DANGEROUS_EXEC
shell_exec("date"); // @security-ignore DANGEROUS_EXEC: Static command

OWASP Top 10 Coverage

Detectors

SAST (14 Detectors)

AI Auditor (Context-Aware)

Detects vulnerabilities that require context understanding:

Authentication

Two authentication methods are supported:

Option 1: API Key (Direct API)

export ANTHROPIC_API_KEY=sk-ant-...
vendor/bin/bear-security-audit src

Option 2: Claude CLI (Max Plan)

For Max plan subscribers, use the authenticated Claude CLI:

# Install Claude CLI
npm install -g @anthropic-ai/claude-code

# Authenticate
claude auth login

# Run audit (no API key required)
vendor/bin/bear-security-audit src

Output Formats

# Console output (default)
vendor/bin/bear-security-audit src

# JSON output
vendor/bin/bear-security-audit src --format=json

# SARIF for GitHub Security
vendor/bin/bear-security-audit src --format=sarif --output=results.sarif

DAST (Dynamic Analysis)

Automatic endpoint discovery and security testing for BEAR.Sunday applications.

./bin/bear-security-dast "MyVendor\MyApp" prod /path/to/app

Demo

Run the included demo to see DAST in action:

cd demo
composer install
cd ..
./bin/bear-security-dast "BEAR\Security\Demo" hal-app demo

Output:

  BEAR Security DAST Scanner

  App:     BEAR\Security\Demo
  Context: hal-app
  AppDir:  demo

  Discovering endpoints...
    GET /(?string $name)
    GET /safe/json-output(string $name)
    GET /vulnerable/xss(string $name)
    ...

  Found 9 endpoints

HIGH: XSS - GET /?name=<script>alert(1)</script>:0 - Cross-Site Scripting...
  see https://bearsunday.github.io/BEAR.Security/issues/en/xss
  ...

22 issues found: 22 high
Scanned 9 endpoints in 0.02s

Detectors

• SQL Injection payloads
• XSS payloads
• Command Injection payloads
• Path Traversal payloads
• Security Headers analysis

GitHub Actions Integration

name: Security

on: [push, pull_request]

jobs:
  security:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
    steps:
      - uses: actions/checkout@v4

      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.1'

      - run: composer install --no-interaction

      - name: Security Scan
        run: |
          composer require --dev bear/security
          vendor/bin/bear.security-scan src --format=sarif > results.sarif

      - name: Upload to GitHub Security
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

Programmatic Usage

use BEAR\Security\Scanner;
use BEAR\Security\Output\JsonOutput;

$scanner = new Scanner();
$result = $scanner->scanDirectory('./src');

// Get vulnerabilities
foreach ($result->getVulnerabilities() as $vuln) {
    echo sprintf(
        "[%s] %s in %s:%d\n",
        $vuln->getSeverity(),
        $vuln->getType(),
        $vuln->getFile(),
        $vuln->getLine()
    );
}

// JSON output
$output = new JsonOutput();
echo $output->format($result);

OWASP Checklist Report

use BEAR\Security\Scanner;
use BEAR\Security\Report\SecurityChecklistReport;

$scanner = new Scanner();
$result = $scanner->scanDirectory('./src');

$report = new SecurityChecklistReport();

// Text report
echo $report->generate($result, 'text');

// JSON report
echo $report->generate($result, 'json');

// HTML report
echo $report->generate($result, 'html');

Custom Detectors

use BEAR\Security\Scanner;
use BEAR\Security\Detector\AbstractDetector;

class CustomDetector extends AbstractDetector
{
    protected array $patterns = [
        'CUSTOM_ISSUE' => [
            'pattern' => '/dangerous_function\s*\(/i',
            'severity' => 'HIGH',
            'description' => 'Dangerous function detected',
            'recommendation' => 'Use safer alternative',
        ],
    ];
}

$scanner = new Scanner();
$scanner->addDetector(new CustomDetector());

Psalm Taint Analysis

This package includes a Psalm plugin for BEAR.Sunday taint analysis. It marks ResourceObject::on*() method parameters as taint sources, enabling end-to-end vulnerability detection.

vendor/bin/psalm --taint-analysis

See Psalm Taint Plugin for configuration and details.

Requirements

• PHP 8.1+
• BEAR.Sunday application (recommended)

Documentation

• Issue Types - Vulnerability documentation (日本語)
• Psalm Taint Plugin - Taint analysis for BEAR.Sunday ResourceObject
• Security through Architecture - Why BEAR.Sunday is secure by design
• Detection Matrix - Full detection capability matrix
• Enterprise Tools Comparison - vs Snyk, SonarQube, Checkmarx
• VADDY Comparison - vs VADDY SaaS
• GitHub Actions - CI/CD integration guide
• LLM Context | Full

License

MIT License