php-security-linter/CONTRIBUTING.md

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
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

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

Running the Linter

# 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

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:

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:

// 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
// 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:

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.