Contributing to Ferret Security Scanner

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

🚀 Getting Started

Prerequisites

Node.js >= 20.0.0
npm >= 9.0.0
Git
TypeScript knowledge
Understanding of security concepts

Development Setup

Fork and Clone

git clone https://github.com/YOUR-USERNAME/ferret-scan.git
cd ferret-scan

Install Dependencies

npm install

Build Project

npm run build

Note: The lsp/ directory is a separate package. Run npm run build from inside lsp/ if you're working on the Language Server.

npm run build

Run Tests

npm test

Start Development Mode

npm run dev

Project Structure

ferret-scan/
├── src/                   # Source code
│   ├── analyzers/         # Core analysis engines
│   ├── intelligence/      # Threat intelligence
│   ├── remediation/       # Auto-fix functionality
│   ├── reporters/         # Output formatters
│   ├── rules/            # Security rules
│   └── utils/            # Utilities
├── test/                 # Test files
├── bin/                  # CLI executable
├── docs/                 # Documentation
└── docker/               # Docker configurations

🔍 Types of Contributions

1. Security Rules

Adding new threat detection rules

Create rules in src/rules/ following this pattern:

export const newRule: Rule = {
  id: 'EXFIL-999',
  name: 'Descriptive Threat Name',
  description: 'Clear description of what this detects',
  category: 'exfiltration',
  severity: 'HIGH',
  patterns: [/curl\\s+.*-d/gi],
  fileTypes: ['sh', 'md', 'json'],
  components: ['hook', 'skill', 'settings'],
  remediation: 'Remove external data transmission or gate it behind explicit approval.',
  references: ['https://example.com/threat-documentation'],
  enabled: true,
  excludePatterns: [/example.com/gi],
  requireContext: [/api[_-]?key/gi],
};

2. Bug Fixes

Steps for bug fixes:

Create an issue describing the bug
Create a branch: git checkout -b fix/bug-description
Write a failing test that reproduces the bug
Fix the bug
Ensure all tests pass
Submit a pull request

3. Feature Enhancements

For new features:

Create an issue with feature proposal
Discuss design and implementation
Create feature branch: git checkout -b feature/feature-name
Implement with tests and documentation
Submit pull request

4. Documentation

Documentation improvements:

README updates
API documentation
Configuration guides
Tutorial content
Code comments

🧪 Testing Guidelines

Test Requirements

All contributions must include tests:

// test/rules/new-rule.test.ts
import { newRule } from '../../src/rules/new-rule';
import { testRule } from '../utils/rule-tester';

describe('New Rule', () => {
  it('should detect malicious pattern', () => {
    const result = testRule(newRule, 'malicious content');
    expect(result.findings).toHaveLength(1);
    expect(result.findings[0].severity).toBe('HIGH');
  });

  it('should not flag legitimate use', () => {
    const result = testRule(newRule, 'legitimate content');
    expect(result.findings).toHaveLength(0);
  });
});

Running Tests

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

# Run specific test file
npm test -- new-rule.test.ts

Test Categories

Unit Tests: Test individual functions/classes
Integration Tests: Test component interactions
End-to-End Tests: Test CLI functionality
Security Tests: Test security rule effectiveness

📝 Coding Standards

TypeScript Guidelines

// Use explicit types
function processFile(filePath: string): ScanResult {
  // implementation
}

// Use interfaces for object types
interface ScanOptions {
  readonly severity: Severity;
  readonly includePatterns: string[];
}

// Use enums for constants
enum Severity {
  Critical = 'CRITICAL',
  High = 'HIGH',
  Medium = 'MEDIUM',
  Low = 'LOW'
}

Code Style

Use ESLint configuration provided
Follow existing naming conventions
Write meaningful variable names
Add JSDoc comments for public APIs
Keep functions small and focused

Linting

# Check linting
npm run lint

# Fix automatically fixable issues
npm run lint:fix

🔒 Security Considerations

Security Rule Development

Validate Patterns: Ensure regex patterns are safe and don't cause ReDoS
Test False Positives: Minimize false positives with proper filters
Document Threats: Provide clear threat descriptions and references
Test Coverage: Include both positive and negative test cases

Sensitive Data

Never commit real API keys, passwords, or credentials
Use placeholder values in test fixtures
Sanitize any logs or error messages

Performance

Test rule performance with large files
Avoid exponential regex patterns
Cache expensive operations
Monitor memory usage

📋 Pull Request Process

Before Submitting

Update Documentation: Update relevant docs
Add Tests: Ensure 80%+ test coverage for new code (project threshold)
Check Linting: Run npm run lint
Run Tests: All tests must pass
Update Changelog: Add entry to CHANGELOG.md

PR Template

When creating a PR, include:

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
- [ ] All tests pass
- [ ] New tests added
- [ ] Manual testing completed

## Security Impact
- [ ] No security implications
- [ ] Security review required
- [ ] New security rules added

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] Changelog updated

Review Process

Automated Checks: GitHub Actions run automatically
Code Review: Maintainers review code quality
Security Review: Security implications assessed
Testing: Additional testing if needed
Merge: Approved PRs are merged

🌟 Recognition

Contributors

All contributors are recognized in:

README.md contributors section
GitHub contributors page
Release notes for significant contributions

Maintainer Path

Active contributors may be invited to become maintainers based on:

Quality of contributions
Understanding of project goals
Community involvement
Security expertise

📞 Getting Help

Community Support

GitHub Discussions: Ask questions and share ideas
Issues: Report bugs or request features
Discord: Join our community chat (link in README)

Development Questions

Tag maintainers in GitHub for urgent questions
Use GitHub Discussions for general development questions
Join our weekly contributor calls (schedule in Discord)

🎯 Contribution Ideas

Good First Issues

Look for issues labeled:

good first issue: Perfect for new contributors
help wanted: Community help needed
documentation: Documentation improvements
enhancement: Feature requests

Advanced Contributions

Performance optimizations
New output formats
Advanced detection algorithms
Integration with security tools
Machine learning models

📜 Legal

License Agreement

By contributing, you agree that your contributions will be licensed under the MIT License.

Copyright

Retain original copyright notices
Add your copyright for significant new files
Follow existing copyright patterns

🚀 Development Workflow

Branch Strategy

# Main branches
main          # Stable releases
develop       # Integration branch

# Feature branches
feature/name  # New features
fix/name      # Bug fixes
docs/name     # Documentation
security/name # Security fixes

Commit Messages

Follow conventional commits:

feat: add new threat detection rule for API key exposure
fix: resolve false positive in credential detection
docs: update installation instructions
test: add integration tests for SARIF output
security: patch regex DoS vulnerability

Release Process

Feature Freeze: No new features, only fixes
Testing: Comprehensive testing phase
Security Review: Security audit of changes
Documentation: Update all documentation
Release: Tagged release with changelog

🎉 Thank You!

Your contributions make Ferret better for everyone. Whether it's a small bug fix or a major feature, every contribution is valuable.

For questions about contributing, reach out to the maintainers or ask in GitHub Discussions.

Happy coding! 🦫

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History