SupaMend

SupaMend - Pluggable DevSecOps Security Scanner in TypeScript with comprehensive error handling and multiple reporting channels.

Features

• 🔍 10 Security Scanners: Complete coverage with Gitleaks, Bandit, Trivy, Semgrep, Checkov, and more
• 📊 Multiple Reporter Plugins: Report findings via GitHub Issues, Slack, Email, Discord, Teams, JSON, and Console
• 🖥️ Cross-Platform CLI: Fully compatible with Windows, macOS, and Linux
• 🎯 Interactive Mode: Guided workflows with smart project detection and scanner suggestions
• 🔧 Programmable API: Integrate into your own applications
• ⚡ GitHub Actions Integration: Automated security scanning in CI/CD
• 🏗️ Extensible Architecture: Add your own scanners and reporters
• 🛡️ Robust Error Handling: Comprehensive error recovery with retry mechanisms
• 📈 Structured Logging: Detailed logging with error statistics and recovery suggestions
• ✅ 100% Scanner Coverage: All 10 scanners tested and verified working
• 🚀 Parallel Execution: Run multiple scanners simultaneously for faster results
• 🤖 Smart Detection: Auto-detect project type and suggest appropriate scanners
• 🔄 Non-blocking: Continue scanning with available tools if some fail
• ⏱️ Scanner Timeouts: Configurable timeouts prevent hanging scanners
• 📈 Progress Tracking: Real-time progress updates during scanning

Quick Start

Prerequisites

• Node.js 18+
• Gitleaks installed (Install Guide)
• GitHub Personal Access Token with repo permissions

Installation

# Clone the repository
git clone https://github.com/zmelliti/supamend.git
cd supamend

# Install dependencies
npm install

# Build the project
npm run build

# Optional: Install globally for use from anywhere
npm install -g .

Basic Usage

Option 1: Interactive Mode (Recommended for beginners)

# Launch interactive guided workflow
npx supamend interactive
# or use short alias
npx supamend i

# Interactive mode with scan command
npx supamend scan --interactive

Option 2: Command Line (Advanced users)

# Scan a repository for security issues
npx supamend scan \
  --repo https://github.com/user/repo.git \
  --token YOUR_GITHUB_TOKEN \
  --scanners gitleaks,bandit \
  --reporters github-issue,slack

# List available scanners and reporters
npx supamend list

# Run with verbose logging
npx supamend scan --repo https://github.com/user/repo.git --verbose

Option 3: Using npm run dev (Development mode)

# Run from the project directory without building
npm run dev scan --scanners gitleaks --reporters json

Option 4: Global Installation (Recommended for regular use)

After installing globally with npm install -g ., you can use SupaMend from anywhere:

# Use from any directory
supamend scan --scanners gitleaks --reporters json

# Scan current git repository (no --repo needed)
supamend scan --scanners gitleaks,bandit --reporters console

# List available scanners and reporters
supamend list

Option 5: Direct Node.js execution

# Run the built CLI directly
node dist/cli.js scan --scanners gitleaks --reporters json

# Or use full path from anywhere
node /path/to/supamend/dist/cli.js scan --scanners gitleaks --reporters json

Interactive Mode

SupaMend features an intelligent interactive CLI that guides you through the security scanning process with smart project detection and scanner suggestions.

Features

• 📁 Smart Project Detection: Automatically detects Node.js, Python, Docker, and Infrastructure projects
• 💡 Intelligent Suggestions: Pre-selects relevant scanners based on your project type
• 📝 Guided Configuration: Step-by-step prompts for repositories, scanners, and reporters
• 💾 Config Generation: Option to save settings to .supamend.json for future use
• 📈 Interactive Results: View summaries, detailed results, and filter by severity

Usage Examples

# Launch interactive mode
npx supamend interactive

# Short alias
npx supamend i

# Interactive flag with scan command
npx supamend scan --interactive

Project Detection

The interactive CLI automatically detects your project type and suggests appropriate scanners:

| Project Type | Detected Files | Suggested Scanners | |--------------|----------------|--------------------| | Node.js | package.json, *.js, *.ts | npm-audit, eslint-security, yarn-audit | | Python | *.py, requirements.txt, setup.py | bandit, safety | | Docker | Dockerfile, docker-compose.yml | hadolint | | Infrastructure | *.tf, *.yaml, CloudFormation | checkov | | All Projects | Always included | gitleaks, trivy, semgrep |

Configuration

Create a .supamend.json file in your repository:

{
  "scanners": [
    {
      "name": "gitleaks",
      "enabled": true,
      "options": {
        "rules": ".gitleaks.toml"
      }
    },
    {
      "name": "bandit",
      "enabled": true,
      "options": {
        "severity": ["high", "medium"]
      }
    }
  ],
  "reporters": [
    {
      "name": "github-issue",
      "enabled": true,
      "options": {
        "token": "${GITHUB_TOKEN}",
        "owner": "${GITHUB_REPOSITORY_OWNER}",
        "repo": "${GITHUB_REPOSITORY_NAME}"
      }
    },
    {
      "name": "slack",
      "enabled": true,
      "options": {
        "webhookUrl": "${SLACK_WEBHOOK_URL}",
        "channel": "#security-alerts"
      }
    }
  ]
}

Cross-Platform Requirements

Many scanners require external tools to be installed and available in your system PATH. Here are some tips for different operating systems:

• Python-based Tools (Bandit, Safety, Semgrep, Checkov):

  • Install Python 3.x and add it to your PATH.
  • Use pip install bandit safety semgrep checkov.
  • On Windows, you may need to use python -m pip install ... and ensure the Python executable is accessible.

• Gitleaks, Trivy, Hadolint:

  • Download the appropriate binary for your OS from their GitHub releases or use a package manager (brew, choco, apt, etc.).
  • On Windows, use .exe files and ensure the directory is in your PATH.

• Node.js-based Tools (npm audit, yarn audit, eslint):

  • Install Node.js (https://nodejs.org/) and ensure npm/yarn are available.
  • Fully cross-platform, but ensure you use the correct command (npm vs. npm.cmd on Windows).

• General Recommendations:

  • Always ensure the tool’s executable is in your system PATH.
  • On Windows, you may need to restart your terminal after installing new tools.
  • Some tools may require additional dependencies (e.g., Docker for Trivy image scanning).

GitHub Actions Integration

Add this workflow to your repository:

name: SupaMend Security Scan

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-node@v4
      with:
        node-version: '18'
    - run: npm ci && npm run build
    - run: |
        wget -qO- https://github.com/zricethezav/gitleaks/releases/latest/download/gitleaks_linux_x64.tar.gz | tar -xz
        sudo mv gitleaks /usr/local/bin/
    - run: |
        npx supamend scan \
          --repo "https://github.com/${{ github.repository }}.git" \
          --token ${{ secrets.GITHUB_TOKEN }} \
          --scanners "gitleaks,bandit" \
          --reporters "github-issue,slack" \
          --verbose
    env:
      SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}

Available Scanners (10/10 Working)

✅ Complete Scanner Coverage: All scanners tested and verified on Windows, macOS, and Linux.

Gitleaks ✅

Detects hardcoded secrets and credentials in your codebase.

Installation: Download from GitHub releases
Status: Windows .exe support added

Usage:

npx supamend scan --scanners gitleaks --repo https://github.com/user/repo.git

Bandit ✅

Python security linter that scans for common security issues.

Installation: pip install bandit
Status: Cross-platform Python support

Usage:

npx supamend scan --scanners bandit --repo https://github.com/user/repo.git

npm Audit ✅

Scans Node.js dependencies for known vulnerabilities.

Installation: Comes with Node.js/npm
Status: Fully cross-platform compatible

Usage:

npx supamend scan --scanners npm-audit --repo https://github.com/user/repo.git

Trivy ✅

Comprehensive vulnerability scanner for containers, filesystems, and dependencies.

Installation: Download from GitHub releases
Status: Windows binary support with filesystem scanning

Usage:

npx supamend scan --scanners trivy --repo https://github.com/user/repo.git

Safety ✅

Scans Python dependencies for security vulnerabilities.

Installation: pip install safety
Status: Cross-platform Python dependency scanning

Usage:

npx supamend scan --scanners safety --repo https://github.com/user/repo.git

ESLint Security ✅

Scans JavaScript/TypeScript code for security issues using ESLint security plugins.

Installation: npm install -g eslint eslint-plugin-security
Status: Windows shell command execution fixed

Usage:

npx supamend scan --scanners eslint-security --repo https://github.com/user/repo.git

Checkov ✅

Scans infrastructure as code (Terraform, CloudFormation, Kubernetes) for security misconfigurations.

Installation: pip install checkov
Status: Simplified output parsing with severity mapping

Usage:

npx supamend scan --scanners checkov --repo https://github.com/user/repo.git

Semgrep ✅

Static Application Security Testing (SAST) for multiple programming languages.

Installation: pip install semgrep
Status: Multi-language SAST with comprehensive rule coverage

Usage:

npx supamend scan --scanners semgrep --repo https://github.com/user/repo.git

Yarn Audit ✅

Scans Yarn dependencies for known vulnerabilities.

Installation: Comes with Yarn
Status: Windows shell execution and error handling improved

Usage:

npx supamend scan --scanners yarn-audit --repo https://github.com/user/repo.git

Hadolint ✅

Scans Dockerfiles for security issues and best practices.

Installation: Download from GitHub releases
Status: Windows .exe binary support added

Usage:

npx supamend scan --scanners hadolint --repo https://github.com/user/repo.git

Available Reporters

GitHub Issues

Automatically creates GitHub issues for security findings, organized by severity level.

Quick Setup:

# Set credentials
set GITHUB_TOKEN=ghp_your_token
set GITHUB_OWNER=your_username  
set GITHUB_REPO=your_repository

# Scan and create issues
node dist/cli.js scan --scanners gitleaks --reporters github-issue --repo .

Auto-detection from URL:

# Automatically extracts owner/repo from GitHub URL
node dist/cli.js scan --scanners gitleaks --reporters github-issue --repo https://github.com/owner/repo.git

Configuration:

{
  "name": "github-issue",
  "enabled": true,
  "options": {
    "token": "${GITHUB_TOKEN}",
    "owner": "your-username",
    "repo": "your-repository"
  }
}

Features: Severity-based issues, detailed descriptions, automatic labeling 📖 Complete GitHub Integration Guide

Slack

Sends rich, detailed security findings to Slack channels with professional formatting.

Quick Setup:

# Method 1: Webhook URL (Recommended)
set SLACK_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL
node dist/cli.js scan --scanners gitleaks --reporters slack --repo .

# Method 2: Bot Token
set SLACK_TOKEN=xoxb-your-bot-token
set SLACK_CHANNEL=#security
node dist/cli.js scan --scanners gitleaks --reporters slack --repo .

Configuration:

{
  "name": "slack",
  "enabled": true,
  "options": {
    "webhookUrl": "${SLACK_WEBHOOK_URL}",
    "username": "SupaMend Security Scanner"
  }
}

Features: Rich formatting, severity colors, file details, scanner breakdown 📖 Complete Slack Integration Guide

Email

Sends detailed security reports via email using SMTP with rich HTML formatting.

Quick Setup:

# Set environment variables
set EMAIL_HOST=smtp.gmail.com
set [email protected]
set EMAIL_PASS=your-app-password
set [email protected]
set [email protected]

# Scan and send email report
node dist/cli.js scan --scanners gitleaks --reporters email --repo .

Configuration via Config File:

{
  "name": "email",
  "enabled": true,
  "options": {
    "host": "smtp.gmail.com",
    "port": 587,
    "secure": false,
    "user": "${EMAIL_USER}",
    "pass": "${EMAIL_PASS}",
    "from": "[email protected]",
    "to": ["[email protected]"],
    "subject": "Security Scan Results - {repo}"
  }
}

Supported Email Providers:

• Gmail: smtp.gmail.com:587 (requires app password)
• Outlook: smtp-mail.outlook.com:587
• Mailgun: smtp.mailgun.org:587 or smtp.us.mailgun.org:587
• SendGrid: smtp.sendgrid.net:587
• Custom SMTP: Any SMTP server

Features: HTML formatting, severity-based styling, detailed issue breakdown, attachment support 📖 See .supamend.email-example.json for complete configuration example

Discord

Sends rich, detailed security findings to Discord channels via webhooks with professional formatting.

Quick Setup:

# Set Discord webhook URL
set DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/YOUR/WEBHOOK/URL

# Scan and send to Discord
node dist/cli.js scan --scanners gitleaks --reporters discord --repo .

Configuration:

{
  "name": "discord",
  "enabled": true,
  "options": {
    "webhookUrl": "${DISCORD_WEBHOOK_URL}",
    "username": "SupaMend Security Scanner",
    "avatarUrl": "https://your-domain.com/supamend-avatar.png",
    "threadId": "optional-thread-id"
  }
}

Features: Rich embeds, severity-based colors, detailed issue breakdown, repository links, file information 📖 Complete Discord Integration Guide

Microsoft Teams

Sends security findings to Microsoft Teams channels via webhooks with adaptive card formatting.

Quick Setup:

# Set Teams webhook URL
set TEAMS_WEBHOOK_URL=https://outlook.office.com/webhook/YOUR/WEBHOOK/URL

# Scan and send to Teams
node dist/cli.js scan --scanners gitleaks --reporters teams --repo .

Configuration:

{
  "name": "teams",
  "enabled": true,
  "options": {
    "webhookUrl": "${TEAMS_WEBHOOK_URL}",
    "title": "Security Scan Results",
    "themeColor": "FF0000"
  }
}

Features: Adaptive cards, severity-based colors, structured layout, repository links 📖 Complete Teams Integration Guide

Console

Displays formatted security findings in the console with color coding.

Configuration:

{
  "name": "console",
  "enabled": true,
  "options": {
    "format": "detailed",
    "showProgress": true,
    "colorize": true
  }
}

JSON Output

Saves scan results to a JSON file.

Usage:

npx supamend scan --reporters json --output results.json

Error Handling & Recovery

SupaMend includes comprehensive error handling with:

• Automatic Retries: Exponential backoff for transient failures
• Graceful Degradation: Continues scanning even if some scanners fail
• Detailed Logging: Structured logs with error statistics
• Recovery Suggestions: Helpful tips for resolving common issues
• Timeout Management: Configurable timeouts for all operations
• Configuration Validation: Clear error messages for missing or invalid configurations

Common Configuration Issues

Email Reporter Not Available:

# Error: Missing environment variables: EMAIL_HOST, EMAIL_USER, EMAIL_PASS, EMAIL_FROM, EMAIL_TO
# Solution: Set required environment variables or use config file
set EMAIL_HOST=smtp.gmail.com
set [email protected]
set EMAIL_PASS=your-app-password
set [email protected]
set [email protected]

SMTP Connection Issues:

• Verify SMTP server hostname and port
• Check firewall and network connectivity
• Ensure credentials are correct
• For Gmail: Use app passwords instead of regular passwords

Error Recovery Examples

# Retry failed operations with custom timeout
npx supamend scan --repo https://github.com/user/repo.git --timeout 300000

# Continue scanning even if some scanners fail
npx supamend scan --repo https://github.com/user/repo.git --continue-on-error

# Verbose logging for debugging
npx supamend scan --repo https://github.com/user/repo.git --verbose

Extending SupaMend

Adding a New Scanner

1. Create a new file in src/scanners/
2. Implement the Scanner interface
3. Export your scanner as default

Example:

import { Scanner } from '../interfaces/scanner';
import { ScanResult } from '../types';

export class MyScanner implements Scanner {
  name = 'my-scanner';
  description = 'My custom security scanner';
  version = '1.0.0';

  async init(config?: Record<string, any>): Promise<void> {
    // Initialize your scanner
  }

  async scan(repoPath: string, options?: Record<string, any>): Promise<ScanResult[]> {
    // Implement scanning logic
    return [];
  }

  async isAvailable(): Promise<boolean> {
    // Check if dependencies are available
    return true;
  }
}

export default new MyScanner();

Adding a New Reporter

1. Create a new file in src/reporters/
2. Implement the Reporter interface
3. Export your reporter as default

See CONTRIBUTING.md for detailed guidelines.

API Usage

import { SupaMend } from 'supamend';

const supamend = new SupaMend();

const results = await supamend.scan({
  repo: 'https://github.com/user/repo.git',
  token: 'your-github-token',
  scanners: ['gitleaks', 'bandit'],
  reporters: ['github-issue', 'slack'],
  options: {
    timeout: 300000,
    continueOnError: true,
    verbose: true
  }
});

console.log(`Found ${results.length} security issues`);

Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint code
npm run lint

# Format code
npm run format

# Build for production
npm run build

Testing

# Run all tests
npm test

# Run specific test suites
npm test -- --testNamePattern="reporter"

# Run tests with verbose output
npm test -- --verbose

# Run tests in watch mode
npm test -- --watch

Contributing

We welcome contributions! Please see CONTRIBUTING.md for detailed guidelines.

Development Setup

1. Fork the repository
2. Clone your fork
3. Install dependencies: npm install
4. Create a feature branch
5. Make your changes
6. Add tests for new functionality
7. Run tests: npm test
8. Submit a pull request

License

MIT License - see LICENSE file for details.

Documentation

• 📖 API Documentation - Complete API reference
• 🚀 Deployment Guide - Docker, Kubernetes, and cloud deployment
• 💬 Slack Integration Guide - Complete Slack setup and configuration
• 🐙 GitHub Integration Guide - Automated issue creation and management
• 📧 Email Integration Guide - SMTP configuration and email reporting
• 💬 Discord Integration Guide - Discord webhook setup and configuration
• 👥 Teams Integration Guide - Microsoft Teams webhook integration
• 🔧 Troubleshooting Guide - Common issues and solutions
• 📋 Contributing Guidelines - How to contribute to SupaMend
• 🔒 Security Policy - Security reporting and best practices
• 📝 Changelog - Version history and changes
• 🗺️ Development Roadmap - Future features and development plans

Support

• 🐛 Issue Tracker
• 💬 Discussions

Using a Config File for Defaults

You can specify default options (such as repo, scanners, reporters, etc.) in a config file (e.g., .supamend.json). Any CLI options you provide will override the values in the config file.

Example .supamend.json:

{
  "repo": "https://github.com/user/repo.git",
  "scanners": [
    { "name": "gitleaks", "enabled": true },
    { "name": "bandit", "enabled": true }
  ],
  "reporters": [
    { "name": "json", "enabled": true }
  ],
  "output": "results.json",
  "verbose": true
}

Minimal CLI usage with config file:

npx supamend scan --config .supamend.json

Override config values via CLI:

npx supamend scan --config .supamend.json --scanners gitleaks,semgrep --output custom.json

CLI Commands

Interactive Mode

# Launch interactive guided workflow
npx supamend interactive
npx supamend i                    # Short alias
npx supamend scan --interactive   # Interactive flag

Scan Command

# Basic scan
npx supamend scan --scanners gitleaks,bandit --reporters console

# Scan with configuration file
npx supamend scan --config .supamend.json

# Scan specific repository
npx supamend scan --repo https://github.com/user/repo.git --token TOKEN

# Verbose output
npx supamend scan --scanners all --reporters json --verbose

List Command

# List available scanners and reporters
npx supamend list

Credits

Created with ❤️ by Zied MELLITI