Contributing to Shai Hulud Scanner

December 2, 2025 · View on GitHub

Thank you for your interest in contributing to the Shai Hulud Scanner! This tool helps protect the npm ecosystem from supply chain attacks, and your contributions make a difference.

🎯 Ways to Contribute

1. Report Bugs or False Positives

Use GitHub Issues
Include scanner version, operating system, and steps to reproduce
For false positives, include the specific package/file flagged

2. Add New IOCs

Submit pull requests with newly discovered indicators
Include source/reference for the IOC
Update documentation with detection details

3. Improve Detection Logic

Enhance existing checks
Add new detection patterns
Optimize performance

4. Documentation

Fix typos or clarify instructions
Add examples or use cases
Translate documentation

5. Testing

Test on different operating systems
Verify detection accuracy
Add integration tests

🚀 Getting Started

Prerequisites

Bash 4.0+
Git
Basic command line experience

Setup Development Environment

# Fork the repository on GitHub
# Clone your fork
git clone https://github.com/YOUR_USERNAME/shai-hulud-scanner.git
cd shai-hulud-scanner

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

# Make the script executable
chmod +x scan.sh

# Test your changes
./scan.sh /path/to/test/directory

📝 Development Guidelines

Code Style

Shell Script Best Practices:

# Use meaningful variable names
MALICIOUS_FILES=$(find ...)  # Good
x=$(find ...)                 # Bad

# Add comments for complex logic
# Check for suspicious preinstall scripts that may execute malicious code
if grep -q '"preinstall"' "$pkg_file"; then
    # ...
fi

# Handle errors appropriately
set -e  # Exit on error

# Quote variables to prevent word splitting
echo "$VARIABLE"  # Good
echo $VARIABLE    # Bad

# Use functions for reusable code
print_critical() {
    echo -e "${RED}🚨 CRITICAL: \$1${NC}"
    ((CRITICAL_ISSUES++))
}

Testing Your Changes

Manual Testing:

# Create test directory with known patterns
mkdir -p test/malicious
echo "malicious content" > test/malicious/setup_bun.js

# Run scanner
./scan.sh test/

# Verify detection
cat shai-hulud-scan-report.txt

Test Cases to Cover:

True Positives: Should detect known malicious patterns
True Negatives: Should not flag legitimate code
Edge Cases: Empty directories, permission errors, missing tools
Performance: Large repositories (1000+ files)

Commit Message Format

Use clear, descriptive commit messages:

type: brief description

Detailed explanation of changes (if needed)

Fixes #123

Types:

feat: New feature or detection
fix: Bug fix or false positive correction
docs: Documentation updates
test: Add or update tests
refactor: Code restructuring
perf: Performance improvements

Examples:

feat: add detection for malicious postinstall scripts

- Scan for postinstall in package.json
- Flag suspicious script patterns
- Update report format

Closes #45

fix: reduce false positives in AsyncAPI detection

The previous pattern was too broad and flagged legitimate @asyncapi
packages. Updated to only flag specific compromised versions.

Fixes #67

🔍 Adding New Detections

Step 1: Research the IOC

Verify with official sources (DataDog, npm security, etc.)
Document the attack vector
Identify unique fingerprints

Step 2: Implement Detection

Add your check to scan.sh:

# Check X: Your New Detection
print_header "X. Checking for New Threat"
{
    echo "======================================"
    echo "X. NEW THREAT DETECTION"
    echo "======================================"
    echo ""
    echo "Checking for: [describe what you're looking for]"
    echo ""
} >> "$REPORT_FILE"

# Your detection logic here
THREAT_COUNT=0
# ... scanning code ...

if [ $THREAT_COUNT -gt 0 ]; then
    print_critical "New threat detected!"
    echo "CRITICAL: Details..." >> "$REPORT_FILE"
else
    print_success "No new threats found"
    echo "RESULT: PASS" >> "$REPORT_FILE"
fi
echo "" >> "$REPORT_FILE"

Step 3: Update Documentation

Add to README "What This Scanner Checks" section
Document the IOC source
Provide remediation steps

Step 4: Test Thoroughly

Test with true positives (known malicious samples)
Test with true negatives (legitimate code)
Verify report output

📋 Pull Request Process

Before Submitting

Test your changes on multiple operating systems (if possible)
Update README if adding new features
Add comments to complex code
Verify no false positives introduced
Check that all existing tests still pass

Submitting PR

Create Pull Request
- Use a clear, descriptive title
- Reference related issues
- Explain what changed and why

PR Description Template

## Description
[Brief description of changes]

## Type of Change
- [ ] Bug fix (false positive/negative)
- [ ] New feature (detection method)
- [ ] Documentation update
- [ ] Performance improvement

## Testing
[How you tested your changes]

## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] Tested on multiple scenarios
- [ ] No new warnings introduced

## Related Issues
Closes #[issue number]