Custom Rules

GitHub

Custom Rules

Learn how to configure and use custom analysis rules with the bundled Sentinel AI PHAR file to match your project's specific requirements and coding standards.

Overview

Sentinel AI supports custom rules that integrate seamlessly with the existing analysis framework. Since Sentinel AI is distributed as a standalone PHAR file, custom rules are configured through configuration files and external rule definitions rather than extending internal classes.

Custom Rules Configuration

Custom rules are configured through the Sentinel AI configuration file:

// .sentinel/config.php
return [
    'analysis' => [
        'tools' => ['phpcs', 'phpstan', 'phpmd', 'phpcpd'],
        'custom_rules' => [
            'path/to/custom/rules/directory',
        ],
        'custom_rules_config' => [
            'enabled' => true,
            'rules_directory' => 'app/SentinelRules',
            'rule_files' => [
                'security_rules.json',
                'style_rules.json',
                'framework_rules.json',
            ],
        ],
    ],
    'rules' => [
        'style' => [
            'enabled' => true,
            'severity_threshold' => 'low',
        ],
        'security' => [
            'enabled' => true,
            'severity_threshold' => 'high',
        ],
        'framework' => [
            'enabled' => true,
            'severity_threshold' => 'medium',
        ],
    ],
];

Custom Rule File Format

Custom rules are defined using JSON configuration files that specify patterns, conditions, and actions:

{
    "rule_name": "HardcodedCredentials",
    "category": "security",
    "severity": "high",
    "description": "Detects hardcoded credentials in code",
    "patterns": [
        {
            "type": "regex",
            "pattern": "/password\\s*=\\s*['\"][^'\"]+['\"]/i",
            "message": "Hardcoded password detected"
        },
        {
            "type": "regex",
            "pattern": "/api_key\\s*=\\s*['\"][^'\"]+['\"]/i",
            "message": "Hardcoded API key detected"
        },
        {
            "type": "regex",
            "pattern": "/secret\\s*=\\s*['\"][^'\"]+['\"]/i",
            "message": "Hardcoded secret detected"
        }
    ],
    "exclusions": [
        {
            "type": "file_pattern",
            "pattern": "*.env*"
        },
        {
            "type": "line_pattern",
            "pattern": "/\\$_ENV\\[|\\$_SERVER\\[/"
        }
    ],
    "context": {
        "file_types": ["php", "js", "py", "java"],
        "ignore_comments": false,
        "ignore_strings": false
    }
}

Creating Custom Rules

Create custom rules by defining JSON configuration files in your project:

1. Security Rules

{
    "rule_name": "SQLInjectionVulnerability",
    "category": "security",
    "severity": "high",
    "description": "Detects potential SQL injection vulnerabilities",
    "patterns": [
        {
            "type": "regex",
            "pattern": "/\\$_(GET|POST|REQUEST)\\[[^\\]]+\\]\\s*[^;]*WHERE/i",
            "message": "Potential SQL injection: User input used in WHERE clause"
        },
        {
            "type": "regex",
            "pattern": "/\\$_(GET|POST|REQUEST)\\[[^\\]]+\\]\\s*[^;]*INSERT/i",
            "message": "Potential SQL injection: User input used in INSERT statement"
        }
    ],
    "exclusions": [
        {
            "type": "line_pattern",
            "pattern": "/prepare\\(|bind_param\\(|PDO::prepare/"
        }
    ]
}

2. Style Rules

{
    "rule_name": "ConsistentNaming",
    "category": "style",
    "severity": "medium",
    "description": "Enforces consistent naming conventions",
    "patterns": [
        {
            "type": "regex",
            "pattern": "/function\\s+([a-z][a-zA-Z0-9]*)\\s*\\(/",
            "message": "Function names should use camelCase: {match}"
        },
        {
            "type": "regex",
            "pattern": "/class\\s+([A-Z][a-zA-Z0-9]*)\\s*{/",
            "message": "Class names should use PascalCase: {match}"
        }
    ],
    "context": {
        "file_types": ["php"],
        "ignore_comments": true
    }
}

3. Framework-Specific Rules

{
    "rule_name": "LaravelControllerMethods",
    "category": "framework",
    "severity": "medium",
    "description": "Enforces Laravel controller method naming conventions",
    "patterns": [
        {
            "type": "regex",
            "pattern": "/public function (\\w+)\\s*\\(/",
            "message": "Controller method '{match}' should follow Laravel conventions"
        }
    ],
    "exclusions": [
        {
            "type": "line_pattern",
            "pattern": "/index|create|store|show|edit|update|destroy/"
        }
    ],
    "context": {
        "file_types": ["php"],
        "file_pattern": "*Controller.php"
    }
}

Rule Categories

Organize your rules into categories for better management:

  • Security: Authentication, authorization, data protection, vulnerability detection
  • Performance: Optimization, caching, resource usage, efficiency checks
  • Framework: Framework-specific best practices and conventions
  • Style: Coding standards, formatting, naming conventions
  • Business Logic: Domain-specific rules and validations

Advanced Rule Patterns

Complex Pattern Matching

Use advanced pattern matching for complex analysis:

{
    "rule_name": "ComplexSecurityCheck",
    "category": "security",
    "severity": "high",
    "description": "Multi-pattern security analysis",
    "patterns": [
        {
            "type": "multi_line",
            "patterns": [
                "/\\$user_input\\s*=/",
                "/\\$query\\s*=\\s*\"SELECT.*WHERE.*\"\\s*\\+\\s*\\$user_input/"
            ],
            "message": "Potential SQL injection: User input concatenated with SQL query"
        },
        {
            "type": "conditional",
            "condition": "file_contains",
            "condition_pattern": "extends Controller",
            "patterns": [
                "/\\$_(GET|POST)\\[[^\\]]+\\]\\s*[^;]*->save\\(\\)/"
            ],
            "message": "Potential mass assignment vulnerability in controller"
        }
    ]
}

Context-Aware Rules

Create rules that adapt based on file context:

{
    "rule_name": "ContextAwareRule",
    "category": "framework",
    "severity": "medium",
    "description": "Framework-aware analysis",
    "context": {
        "file_types": ["php"],
        "framework_detection": true,
        "ignore_vendor": true,
        "custom_contexts": [
            {
                "name": "laravel_controller",
                "file_pattern": "*Controller.php",
                "content_pattern": "extends Controller"
            },
            {
                "name": "laravel_model",
                "file_pattern": "*.php",
                "content_pattern": "extends Model"
            }
        ]
    },
    "patterns": [
        {
            "type": "context_specific",
            "context": "laravel_controller",
            "pattern": "/public function (\\w+)\\s*\\(/",
            "message": "Controller method '{match}' should follow Laravel conventions"
        },
        {
            "type": "context_specific",
            "context": "laravel_model",
            "pattern": "/protected \\$fillable\\s*=\\s*\\[/",
            "message": "Model should define \$fillable property for mass assignment protection"
        }
    ]
}

Using Custom Rules with Sentinel AI

To use your custom rules with the bundled Sentinel AI PHAR file:

1. Create Rules Directory

mkdir -p .sentinel/custom-rules

2. Add Your Rule Files

# Create security rules
cat > .sentinel/custom-rules/security_rules.json << 'EOF'
{
    "rule_name": "HardcodedCredentials",
    "category": "security",
    "severity": "high",
    "patterns": [
        {
            "type": "regex",
            "pattern": "/password\\s*=\\s*['\"][^'\"]+['\"]/i",
            "message": "Hardcoded password detected"
        }
    ]
}
EOF

3. Update Configuration

# Update .sentinel/config.php
return [
    'analysis' => [
        'custom_rules_config' => [
            'enabled' => true,
            'rules_directory' => '.sentinel/custom-rules',
        ],
    ],
];

4. Run Analysis

# Run Sentinel AI with custom rules
./sentinel.phar analyze --custom-rules

# Or with specific rule files
./sentinel.phar analyze --custom-rules --rules-file .sentinel/custom-rules/security_rules.json

Testing Custom Rules

Test your custom rules to ensure they work correctly:

# Test a specific rule file
./sentinel.phar test-rule .sentinel/custom-rules/security_rules.json

# Test with sample code
echo 'password = "secret123";' > test.php
./sentinel.phar analyze test.php --custom-rules

# Validate rule syntax
./sentinel.phar validate-rule .sentinel/custom-rules/security_rules.json

Rule Development Best Practices

  • Clear Naming: Use descriptive rule names that indicate the rule's purpose
  • Proper Categorization: Assign appropriate categories and severity levels
  • Context Awareness: Consider file types and project structure
  • Performance: Optimize patterns for large codebases
  • Error Handling: Handle edge cases and malformed code gracefully
  • Documentation: Document rule purpose and configuration options
  • Testing: Test rules with various code patterns
  • Exclusions: Define proper exclusions to avoid false positives
  • Compatibility: Ensure rules work across different project structures

Sharing Rules

Share your custom rules with the community:

  • GitHub Repository: Create a public repository for your rules
  • Documentation: Provide clear documentation and examples
  • Testing: Include comprehensive test cases
  • Examples: Provide real-world usage examples
  • Contributing Guidelines: Encourage community contributions

Next Steps

Now that you understand custom rules:

  • Create your first custom rule JSON file
  • Integrate rules into your development workflow
  • Share rules with your team
  • Contribute to the community
  • Explore advanced patterns and techniques