Contributing

Learn how to contribute to the scan4all project

Welcome Contributors!

We welcome contributions from the community! Whether you’re fixing bugs, adding new features, improving documentation, or creating new POCs, your help is appreciated.

Quick Links

GitHub Repository

View the source code and issues

Discussions

Ask questions and share ideas

Getting Started

Prerequisites

Before contributing, ensure you have:

• Go 1.21.4+ - The project requires Go 1.21.4 or higher
• Git - For version control
• Basic Go knowledge - Understanding of Go programming
• Development environment - Linux, macOS, or Windows

Fork and Clone

1. Fork the repository on GitHub
2. Clone your fork locally:

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

3. Add the upstream repository:

git remote add upstream https://github.com/GhostTroops/scan4all.git

Building from Source

Basic Build

# Clone the repository
git clone https://github.com/GhostTroops/scan4all.git
cd scan4all

# Build the project
go build

# Run the binary
./scan4all -h

Build with Dependencies

# Download dependencies
go mod download

# Verify dependencies
go mod verify

# Build
go build -v

Cross-Platform Builds

# Build for Linux
GOOS=linux GOARCH=amd64 go build -o scan4all-linux

# Build for Windows
GOOS=windows GOARCH=amd64 go build -o scan4all.exe

# Build for macOS
GOOS=darwin GOARCH=amd64 go build -o scan4all-mac

Development Workflow

1. Create a Branch

# Update your main branch
git checkout main
git pull upstream main

# Create a feature branch
git checkout -b feature/your-feature-name

2. Make Your Changes

Follow the project structure and coding conventions:

scan4all/
├── lib/               # Core libraries
│   ├── api/          # API interface
│   └── util/         # Utility functions
├── pkg/              # Packages
│   ├── fingerprint/  # Fingerprint detection
│   └── hydra/        # Password cracking
├── pocs_go/          # Go POCs
├── pocs_yml/         # YAML POCs
├── engine/           # Scan engine
├── brute/            # Brute force modules
└── config/           # Configuration files

3. Test Your Changes

# Run tests
go test ./...

# Test specific package
go test ./pkg/fingerprint

# Run with verbose output
go test -v ./...

# Test your changes manually
./scan4all -host http://testsite.com -v

4. Commit Your Changes

Follow conventional commit messages:

# Add your changes
git add .

# Commit with a descriptive message
git commit -m "feat: add new POC for CVE-2024-XXXXX"

Commit message format:

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation changes
• refactor: - Code refactoring
• test: - Adding tests
• chore: - Maintenance tasks

5. Push and Create Pull Request

# Push to your fork
git push origin feature/your-feature-name

Then create a Pull Request on GitHub.

Contribution Guidelines

Code Style

Go Code Style

Follow standard Go conventions:

// Good: Clear function names and comments
// CheckVulnerability checks if the target is vulnerable to CVE-XXXX
func CheckVulnerability(url string) bool {
    // Implementation
    return false
}

// Good: Proper error handling
if err != nil {
    log.Printf("Error: %v", err)
    return false
}

// Good: Use constants for magic values
const (
    DefaultTimeout = 10
    MaxRetries     = 3
)

Package Organization

• Group related functionality in packages
• Use lowercase package names
• Keep packages focused on a single responsibility
• Export only necessary functions and types

package mypackage

// Exported function (public)
func PublicFunction() {}

// Unexported function (private)
func privateHelper() {}

Error Handling

// Always check errors
result, err := doSomething()
if err != nil {
    return fmt.Errorf("failed to do something: %w", err)
}

// Use meaningful error messages
if !isValid {
    return fmt.Errorf("invalid target: %s", target)
}

Documentation

// Package documentation
// Package tomcat provides POCs for Apache Tomcat vulnerabilities.
package tomcat

// Function documentation
// CVE_2017_12615 checks for Tomcat PUT method RCE vulnerability.
// Returns true if the target is vulnerable.
func CVE_2017_12615(url string) bool {
    // Implementation
}

Contributing POCs

Go POC Contribution

1. Check if fingerprint exists in pkg/fingerprint/localFingerData.go
2. Create POC file in appropriate directory under pocs_go/
3. Register POC in pocs_go/go_poc_check.go
4. Test thoroughly against vulnerable and non-vulnerable targets

// Example POC structure
package mypackage

import (
    "fmt"
    "github.com/GhostTroops/scan4all/pkg"
)

// CVE_XXXX_XXXXX checks for [vulnerability description]
func CVE_XXXX_XXXXX(url string) bool {
    req, err := pkg.HttpRequset(
        url+"/vulnerable/path",
        "GET",
        "",
        false,
        nil,
    )
    
    if err != nil {
        return false
    }
    
    if req.StatusCode == 200 {
        pkg.POClog(fmt.Sprintf(
            "Found vuln CVE_XXXX_XXXXX at %s\n",
            url,
        ))
        return true
    }
    
    return false
}

YAML POC Contribution

1. Check fingerprint in pkg/fingerprint/localFingerData.go
2. Create YAML file in pocs_yml/ymlFiles/
3. Name format: <tech>-<vuln>-<type>.yml
4. Test with scan4all

name: poc-yaml-[technology]-[vulnerability]
manual: true
transport: http
rules:
    r0:
        request:
            cache: true
            method: GET
            path: /vulnerable/path
        expression: response.status == 200 && response.body.bcontains(b"vulnerable")
expression: r0()
detail:
    author: your-name
    severity: high|medium|low
    links:
        - https://reference-url.com

Testing

Unit Tests

package mypackage

import "testing"

func TestCheckVulnerability(t *testing.T) {
    tests := []struct {
        name     string
        url      string
        expected bool
    }{
        {"vulnerable target", "http://vuln.example.com", true},
        {"safe target", "http://safe.example.com", false},
    }
    
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            result := CheckVulnerability(tt.url)
            if result != tt.expected {
                t.Errorf("got %v, want %v", result, tt.expected)
            }
        })
    }
}

Integration Tests

# Test against local test environment
./scan4all -host http://localhost:8080 -v

# Test with specific modules
./scan4all -host http://testsite.com -v -debug

# Test POC detection
FingerPrint="Apache Tomcat" ./scan4all -host http://tomcat-test.com

Pull Request Process

Before Submitting

• Code builds without errors
• All tests pass
• Code follows project style guidelines
• Documentation is updated if needed
• Commit messages follow conventions
• Branch is up to date with main

PR Checklist

## Description
Brief description of changes

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

## Testing
- [ ] Tested locally
- [ ] Added/updated tests
- [ ] All tests passing

## Additional Notes
Any additional information

Review Process

1. Submit PR with clear description
2. Automated checks must pass
3. Code review by maintainers
4. Address feedback if requested
5. Merge after approval

Community

Communication Channels

GitHub Issues

Report bugs and request features

Discussions

Ask questions and share ideas

WeChat/QQ

Join the community chat groups

Getting Help

If you need help:

1. Check the documentation
2. Search existing issues
3. Ask in discussions
4. Join community chat groups

Recognition

Contributors

All contributors are recognized in:

• GitHub contributors page
• Project README
• Release notes

Donors

Special thanks to project donors listed in the README.

Code of Conduct

Our Standards

• Be respectful and inclusive
• Welcome newcomers
• Focus on constructive feedback
• Respect different viewpoints
• Prioritize community well-being

Unacceptable Behavior

• Harassment or discrimination
• Trolling or insulting comments
• Publishing private information
• Malicious or destructive contributions

Resources

Custom Modules

Learn to create custom scan modules

Custom POCs

Write custom POCs

API Integration

Integrate scan4all into your apps

GitHub Repo

View the source code

License

By contributing to scan4all, you agree that your contributions will be licensed under the project’s license.

Thank You!

Thank you for contributing to scan4all! Your contributions help make security testing more accessible and effective for everyone.

Start Small: If you’re new to contributing, start with small improvements like:

• Fixing typos in documentation
• Adding code comments
• Improving error messages
• Writing tests for existing code