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

$3

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

$3

``bash


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 .
`

$3

#### Option 1: Interactive Mode (Recommended for beginners)
`bash


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)
`bash


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)
`bash


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:

`bash


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
`bash


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.

$3

- 📁 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

$3

`bash


Launch interactive mode

npx supamend interactive

Short alias

npx supamend i

Interactive flag with scan command

npx supamend scan --interactive
`

$3

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 |

$3

Create a .supamend.json file in your repository:

`json
{
"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:

`yaml
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.

$3

Detects hardcoded secrets and credentials in your codebase.

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

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

$3

Python security linter that scans for common security issues.

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

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

$3

Scans Node.js dependencies for known vulnerabilities.

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

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

$3

Comprehensive vulnerability scanner for containers, filesystems, and dependencies.

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

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

$3

Scans Python dependencies for security vulnerabilities.

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

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

$3

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:
`bash
npx supamend scan --scanners eslint-security --repo https://github.com/user/repo.git
`

$3

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

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

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

$3

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

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

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

$3

Scans Yarn dependencies for known vulnerabilities.

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

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

$3

Scans Dockerfiles for security issues and best practices.

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

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

Available Reporters

$3

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

Quick Setup:
`bash


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:
`bash


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:
`json
{
"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

$3

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

Quick Setup:
`bash


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:
`json
{
"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

$3

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

Quick Setup:
`bash


Set environment variables

set EMAIL_HOST=smtp.gmail.com
set EMAIL_USER=your-email@gmail.com
set EMAIL_PASS=your-app-password
set EMAIL_FROM=your-email@gmail.com
set EMAIL_TO=recipient@example.com

Scan and send email report

node dist/cli.js scan --scanners gitleaks --reporters email --repo .
`

Configuration via Config File:
`json
{
"name": "email",
"enabled": true,
"options": {
"host": "smtp.gmail.com",
"port": 587,
"secure": false,
"user": "${EMAIL_USER}",
"pass": "${EMAIL_PASS}",
"from": "security@yourcompany.com",
"to": ["security-team@yourcompany.com"],
"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

$3

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

Quick Setup:
`bash


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:
`json
{
"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

$3

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

Quick Setup:
`bash


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:
`json
{
"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

$3

Displays formatted security findings in the console with color coding.

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

$3

Saves scan results to a JSON file.

Usage:
`bash
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

$3

Email Reporter Not Available:
`bash


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_USER=your-email@gmail.com
set EMAIL_PASS=your-app-password
set EMAIL_FROM=your-email@gmail.com
set EMAIL_TO=recipient@example.com
`

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

$3

`bash


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

$3

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

Example:
`typescript
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): Promise {
// Initialize your scanner
}

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

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

export default new MyScanner();
`

$3

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

`typescript
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

`bash


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

`bash


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.

$3

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:

`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:

`bash
npx supamend scan --config .supamend.json
`

Override config values via CLI:

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

CLI Commands

$3


`bash

Launch interactive guided workflow

npx supamend interactive
npx supamend i # Short alias
npx supamend scan --interactive # Interactive flag
`

$3

`bash

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
`

$3

`bash

List available scanners and reporters

npx supamend list
``

Credits

Created with ❤️ by Zied MELLITI