Contributing to SCAN

Overview

SCAN (Sensitive Code Analyzer for Nerds) is an open-source Gradle plugin that helps developers detect secrets and sensitive information in their codebase. We welcome contributions from the community to make this tool even better.

Code of Conduct

This project adheres to a Code of Conduct ↗. By participating, you are expected to uphold this code.

Getting Started

Prerequisites

Fork and Clone

1. Fork the repository on GitHub

2. Clone your fork locally:

git clone https://github.com/theaniketraj/SCAN.git
cd SCAN

3. Add the upstream remote:

git remote add upstream https://github.com/theaniketraj/SCAN.git

Development Setup

Project Setup

1. Import the project into your IDE

2. Install dependencies:

./gradlew build

3. Run tests to ensure everything works:

./gradlew test

Project Structure

scan-gradle-plugin/
├── src/
│   ├── main/kotlin/com/scan/
│   │   ├── core/           # Core scanning logic
│   │   ├── detectors/      # Pattern and entropy detectors
│   │   ├── filters/        # File filtering logic
│   │   ├── patterns/       # Built-in pattern definitions
│   │   ├── plugin/         # Gradle plugin implementation
│   │   ├── reporting/      # Report generation
│   │   └── utils/          # Utility classes
│   ├── test/kotlin/        # Unit tests
│   └── functionalTest/kotlin/ # Integration tests
├── docs/                   # Documentation
├── config/                 # Configuration files
└── examples/               # Usage examples

Key Development Commands

Types of Contributions

We welcome various types of contributions:

Before You Start

1. Check existing issues to see if your contribution is already being worked on
2. Create an issue to discuss major changes before implementing
3. Follow the coding standards outlined below

Code Standards

Kotlin Style Guidelines

We follow the Kotlin Coding Conventionswith project-specific guidelines:

Naming Conventions

// Classes: PascalCase
class SecretDetector

// Functions and properties: camelCase
fun detectSecrets()
val patternMatches: List<Match>

// Constants: SCREAMING_SNAKE_CASE
const val DEFAULT_ENTROPY_THRESHOLD = 4.5

Documentation

Use KDoc for public APIs:

/**
 * Detects potential secrets in the given text using pattern matching.
 *
 * @param text The text to analyze for secrets
 * @param patterns List of regex patterns to apply
 * @return List of detected secrets with metadata
 */
fun detectSecrets(
    text: String,
    patterns: List<Pattern>
): List<SecretMatch>

Testing Guidelines

Test Structure

We maintain high test coverage with different types of tests:

Unit Tests

class SecretDetectorTest {
    private val detector = SecretDetector()
    
    @Test
    fun `should detect AWS access key`() {
        // Given
        val text = "aws_access_key_id=AKIAIOSFODNN7EXAMPLE"
        
        // When
        val matches = detector.detectSecrets(text)
        
        // Then
        assertThat(matches).hasSize(1)
        assertThat(matches[0].type).isEqualTo(SecretType.AWS_ACCESS_KEY)
    }
}

Integration Tests

@Test
fun `should integrate with Gradle build lifecycle`() {
    // Given
    val projectDir = createTestProject()
    addSecretToFile(projectDir, "Config.kt", "API_KEY=secret123")
    
    // When
    val result = runGradleTask(projectDir, "build")
    
    // Then
    assertThat(result.task(":scanForSecrets")?.outcome)
        .isEqualTo(TaskOutcome.FAILED)
}

Documentation

Types of Documentation

Documentation Standards

• Clear examples: Provide working code examples
• Step-by-step guides: Break down complex procedures
• Common use cases: Cover typical scenarios
• Troubleshooting: Address common issues

Pull Request Process

Before Submitting

1. Update your branch with the latest changes:

git checkout develop
git pull upstream develop
git checkout your-feature-branch
git rebase develop

2. Run all checks:

./gradlew build
./gradlew test
./gradlew functionalTest
./gradlew spotlessCheck
./gradlew detekt

PR Guidelines

Title Format

type(scope): Brief description

Examples:
feat(patterns): Add support for Slack API tokens
fix(entropy): Correct entropy calculation for Unicode strings
docs(user-guide): Add CI/CD integration examples

Description Template

Review Process

1. Automated checks must pass
2. Code review by maintainers
3. Testing on different environments
4. Documentation review if applicable
5. Approval by project maintainers

Issue Reporting

Bug Reports

When reporting bugs, please include:

Feature Requests

For feature requests, please describe:

Community

Getting Help

Recognition

Contributors are recognized in:

• Release notes: Major contributions acknowledged
• Contributors file: All contributors listed
• Special thanks: Outstanding contributions highlighted