# Contributing to PHP/Laravel Security Linter

Thank you for your interest in contributing to this project! This document provides guidelines and instructions for contributing.

## Code of Conduct

Please be respectful and constructive in all interactions. We welcome contributors of all experience levels.

## How to Contribute

### Reporting Bugs

1. Check if the issue already exists in [Gitea Issues](https://opensource.rogarithm.net/rogarithm/php-security-linter/issues)
2. If not, create a new issue with:
   - Clear description of the problem
   - Steps to reproduce
   - Expected vs actual behavior
   - PHP/Laravel versions
   - Sample code that triggers the issue

### Reporting False Positives/Negatives

Security linters can produce false positives (safe code flagged as vulnerable) or false negatives (vulnerable code not detected). Please report these with:
- The code snippet being analyzed
- Why you believe it's a false positive/negative
- Any relevant context

### Suggesting Features

1. Check existing issues and discussions
2. Create a new issue describing:
   - The vulnerability type you want to detect
   - Example vulnerable and safe code patterns
   - References to security documentation (CWE, OWASP, etc.)

### Pull Requests

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/your-feature-name`
3. Make your changes
4. Test your changes
5. Commit with clear messages
6. Push and create a Pull Request

## Development Setup

### Requirements

- PHP 8.1+
- Composer

### Installation

```bash
git clone https://opensource.rogarithm.net/rogarithm/php-security-linter.git
cd php-laravel
composer install
```

### Running the Linter

```bash
# Analyze a file
php bin/security-lint path/to/file.php

# Analyze a directory
php bin/security-lint path/to/directory/
```

### Project Structure

```
├── bin/
│   └── security-lint      # CLI entry point
├── src/
│   ├── SecurityLinter.php # Main linter class
│   ├── Rules/             # Detection rules
│   │   ├── XssRule.php
│   │   ├── SqlInjectionRule.php
│   │   ├── CommandInjectionRule.php
│   │   ├── PathTraversalRule.php
│   │   ├── AuthenticationRule.php
│   │   ├── CsrfRule.php
│   │   ├── InsecureConfigRule.php
│   │   └── LaravelSecurityRule.php
│   ├── Analysis/          # Analysis utilities
│   │   ├── TaintAnalyzer.php
│   │   └── FunctionAnalyzer.php
│   ├── Report/            # Report generation
│   │   ├── Vulnerability.php
│   │   └── ReportGenerator.php
│   └── I18n/              # Internationalization
│       └── Messages.php
├── docs/                  # Documentation
│   ├── DETECTION_RULES.md
│   └── QUICK_REFERENCE.md
└── test-samples/          # Test samples
```

## Adding New Detection Rules

### 1. Create a New Rule Class

Create a new file in `src/Rules/`:

```php
<?php

namespace SecurityLinter\Rules;

use PhpParser\Node;
use SecurityLinter\Report\Vulnerability;

class YourNewRule extends AbstractRule
{
    protected string $name = 'your_rule';

    public function analyze(Node $node, string $file, array $context = []): array
    {
        $vulnerabilities = [];

        // Your detection logic here

        return $vulnerabilities;
    }
}
```

### 2. Register the Rule

Add your rule to `SecurityLinter.php`:

```php
private function registerDefaultRules(): void
{
    $this->rules = [
        // ... existing rules
        new YourNewRule(),
    ];
}
```

### 3. Add Messages

Add messages in `src/I18n/Messages.php` for both Japanese and English:

```php
// Japanese
'your_rule.name' => 'ルール名',
'your_rule.vulnerability_message' => '脆弱性の説明...',

// English
'your_rule.name' => 'Rule Name',
'your_rule.vulnerability_message' => 'Vulnerability description...',
```

### 4. Update Documentation

- Add detection patterns to `docs/DETECTION_RULES.md`
- Update README.md if needed

## Testing

### Manual Testing

Create test files in `test-samples/` to verify detection:

```php
<?php
// test-samples/your-test.php

// VULNERABLE: Should be detected
vulnerable_pattern();

// SAFE: Should not be detected
safe_pattern();
```

Run the linter against your test files:

```bash
php bin/security-lint test-samples/your-test.php -c
```

## Commit Guidelines

- Use clear, descriptive commit messages
- Reference issue numbers when applicable
- Keep commits focused on single changes

Example:
```
Add detection for insecure deserialization

- Detect unserialize() with allowed_classes => true
- Add messages in Japanese and English
- Update DETECTION_RULES.md

Fixes #123
```

## Questions?

Feel free to open an issue for questions or discussions.