Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
240 lines (175 loc) · 7.73 KB

CONTRIBUTING.md

File metadata and controls

240 lines (175 loc) · 7.73 KB

Contributing to SecureCodeBox Mobile Security Scanner Integration

Thank you for your interest in contributing to the SecureCodeBox Mobile Security Scanner Integration project! This document provides guidelines for contributing to this Kubernetes-based mobile application security scanning platform.

Getting the code locally

Clone your fork and set up the development environment.

# replace <your-fork-url> with your fork URL or the repository URL
git clone <your-fork-url>
cd scanners-mobile-applications

# Ensure you have the required tools installed
# Check the setup scripts for your platform:
# Linux: ./setup_linux.sh
# Windows: .\setup_windows.ps1

Prerequisites

Before contributing, ensure you have the following installed:

  • Docker Desktop (Windows/Mac) or Docker Engine (Linux)
  • Minikube (version 1.25+) for local Kubernetes cluster
  • Helm (version 3.8+) for chart deployment
  • kubectl (version 1.25+) for cluster management
  • Python 3.10+ (for GUI webapp development)
  • At least 4GB RAM available
  • Stable internet connection

Development Environment Setup

Linux/macOS

# Run the setup script
chmod +x setup_linux.sh
./setup_linux.sh

# Deploy a specific scanner (e.g., MobSF)
cd mobsf
./setup_mobsf.sh

# Deploy the GUI
cd ../gui
./deploy.sh

Windows

# Run the setup script
.\setup_windows.ps1

# Deploy a specific scanner (e.g., MobSF)
cd mobsf
.\setup_mobsf.sh

# Deploy the GUI
cd ..\gui
.\deploy.sh

GUI Development Setup

For GUI development, you'll need Python dependencies:

cd gui/webapp
pip install fastapi uvicorn boto3 kubernetes jinja2 python-multipart

Project Structure

This project integrates multiple mobile security scanners with the secureCodeBox framework:

  • mobsf/ - MobSF scanner integration (comprehensive mobile app security analysis)
  • apkhunt/ - APKHunt scanner integration (APK-specific security testing)
  • apktool-semgrep/ - APKTool-Semgrep integration (static code analysis)
  • gui/ - FastAPI-based web application interface
  • test-files/ - Sample APK/IPA files for testing
  • documentation/ - Comprehensive project documentation

Each scanner follows the secureCodeBox pattern with:

  • Scanner wrapper (scanner/) - Entry point for scan execution
  • Parser (parser/) - Processes scan results into standardized format
  • Helm charts - Kubernetes deployment configuration

Branching & workflow

  1. Fork the repository (if you don't have write access).
  2. Create a descriptive branch from main for your work:
# update main
git checkout main
git pull origin main

# create a feature branch
git checkout -b feat/short-description
# Examples:
# git checkout -b feat/add-new-scanner
# git checkout -b fix/gui-upload-validation
# git checkout -b docs/update-setup-guide

Submitting a pull request

  1. Push your branch to your fork:
git add .
git commit -m "Short, meaningful summary of changes"
git push -u origin feat/short-description
  1. Open a Pull Request against the main repository. In your PR description, include:
  • What you changed and why - Describe the specific changes made
  • Scanner affected - If modifying a scanner, specify which one (MobSF, APKHunt, APKTool-Semgrep)
  • Testing performed - Include details about testing with APK/IPA files
  • Setup requirements - Any additional setup needed to test the change
  • Screenshots or logs - If relevant to GUI changes or scan results
  1. Address review comments and push follow-up commits to the same branch. The PR will be re-reviewed.

Code style and tips

General Guidelines

  • Keep functions small and focused - Each function should have a single responsibility
  • Add comprehensive comments - Especially for scanner-specific logic and Kubernetes configurations
  • Use clear variable names - Prefer descriptive names over abbreviations
  • Follow secureCodeBox patterns - Maintain consistency with existing scanner implementations

Scanner Development

  • Wrapper scripts should handle MinIO file operations and scanner communication
  • Parser scripts should convert scanner output to secureCodeBox format
  • Dockerfiles should use minimal base images and follow security best practices
  • Helm charts should include proper resource limits and security contexts

GUI Development

  • FastAPI endpoints should include proper error handling and validation
  • Templates should be responsive and accessible
  • File upload should validate file types and sizes
  • Webhook handlers should process results efficiently

Kubernetes Resources

  • Security contexts should use non-root users
  • Resource limits should be appropriate for scanner workloads
  • Network policies should restrict unnecessary communication
  • RBAC should follow principle of least privilege

Testing Guidelines

Before submitting a PR

  1. Test with real files: Use APK/IPA files from the test-files/ directory
  2. Verify scanner integration: Ensure your changes work with the secureCodeBox operator
  3. Check GUI functionality: If modifying the GUI, test file upload and result display
  4. Validate Helm charts: Use helm lint and helm template to verify chart syntax
  5. Test on your platform: Verify changes work on your development environment

Test Commands

# Test Helm charts
helm lint ./mobsf
helm template mobsf ./mobsf

# Test GUI locally
cd gui/webapp
uvicorn main:app --reload

# Test scanner deployment
kubectl get pods -A
kubectl logs -f deployment/mobsf-scanner

PR checklist

Before requesting review, run through this checklist:

  • My code follows the repository style and secureCodeBox patterns
  • I tested the changes with real APK/IPA files
  • I updated documentation when appropriate (especially for new scanners or GUI features)
  • My PR has a clear title and description with testing details
  • I verified Helm charts are syntactically correct
  • I checked that the GUI works correctly (if applicable)
  • I ensured proper error handling and logging
  • I followed security best practices (non-root containers, proper RBAC, etc.)

Scanner-Specific Guidelines

Adding a New Scanner

  1. Create a new directory following the existing pattern
  2. Implement scanner wrapper in scanner/ directory
  3. Create parser in parser/ directory
  4. Add Helm chart with proper RBAC and security contexts
  5. Create setup script for deployment
  6. Add test files and documentation
  7. Update main documentation

Modifying Existing Scanners

  • MobSF: Focus on API integration and result parsing
  • APKHunt: Ensure proper APK analysis and output formatting
  • APKTool-Semgrep: Verify static analysis rules and result structure

Documentation

  • Update relevant docs in the documentation/ directory
  • Include setup instructions for any new dependencies
  • Document API changes if modifying the GUI
  • Update troubleshooting guides if adding new failure modes

Thank you

Thanks again for helping improve the SecureCodeBox Mobile Security Scanner Integration! If you'd like help getting started:

  • Open an issue with the label good first issue
  • Check existing issues for help wanted labels
  • Review the comprehensive documentation in the documentation/ directory
  • Message the maintainers - we're happy to guide new contributors

Resources

Community

  • Join the secureCodeBox community discussions
  • Check GitHub issues for bug reports and feature requests
  • Review the project wiki for additional resources