Pluggable DevSecOps Security Scanner with 10+ scanners and multiple reporting channels
npm install supamendSupaMend - Pluggable DevSecOps Security Scanner in TypeScript with comprehensive error handling and multiple reporting channels.
- π 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
- Node.js 18+
- Gitleaks installed (Install Guide)
- GitHub Personal Access Token with repo permissions
``bashClone the repository
git clone https://github.com/zmelliti/supamend.git
cd supamend
$3
#### Option 1: Interactive Mode (Recommended for beginners)
`bash
Launch interactive guided workflow
npx supamend interactive
or use short alias
npx supamend iInteractive 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,slackList available scanners and reporters
npx supamend listRun 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 jsonScan current git repository (no --repo needed)
supamend scan --scanners gitleaks,bandit --reporters consoleList 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 jsonOr 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 interactiveShort alias
npx supamend iInteractive 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 Scanon:
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 addedUsage:
`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 supportUsage:
`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 scanningUsage:
`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 fixedUsage:
`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 mappingUsage:
`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 coverageUsage:
`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 addedUsage:
`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_repositoryScan 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.comScan 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 serverFeatures: 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/URLScan 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/URLScan 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 300000Continue scanning even if some scanners fail
npx supamend scan --repo https://github.com/user/repo.git --continue-on-errorVerbose 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 defaultExample:
`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 defaultSee 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 installRun in development mode
npm run devRun tests
npm testRun tests with coverage
npm run test:coverageLint code
npm run lintFormat code
npm run formatBuild for production
npm run build
`Testing
`bash
Run all tests
npm testRun specific test suites
npm test -- --testNamePattern="reporter"Run tests with verbose output
npm test -- --verboseRun 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 requestLicense
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 consoleScan with configuration file
npx supamend scan --config .supamend.jsonScan specific repository
npx supamend scan --repo https://github.com/user/repo.git --token TOKENVerbose output
npx supamend scan --scanners all --reporters json --verbose
`$3
`bash
List available scanners and reporters
npx supamend list
``Created with β€οΈ by Zied MELLITI