supamend/README.md

Pluggable DevSecOps Security Scanner with 10+ scanners and multiple reporting channels

# 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](https://github.com/zricethezav/gitleaks))
- GitHub Personal Access Token with repo permissions

### Installation

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

### Basic Usage

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

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

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

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

### Gitleaks ✅
Detects hardcoded secrets and credentials in your codebase.

**Installation**: Download from [GitHub releases](https://github.com/zricethezav/gitleaks/releases)  
**Status**: Windows `.exe` support added

**Usage**:
```bash
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**:
```bash
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**:
```bash
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](https://github.com/aquasecurity/trivy/releases)  
**Status**: Windows binary support with filesystem scanning

**Usage**:
```bash
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**:
```bash
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**:
```bash
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**:
```bash
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**:
```bash
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**:
```bash
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](https://github.com/hadolint/hadolint/releases)  
**Status**: Windows `.exe` binary support added

**Usage**:
```bash
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**:
```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](docs/GITHUB_INTEGRATION.md)**

### Slack
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](docs/SLACK_INTEGRATION.md)**

### Email
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**

### Discord
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](docs/DISCORD_INTEGRATION.md)**

### Microsoft Teams
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](docs/TEAMS_INTEGRATION.md)**

### Console
Displays formatted security findings in the console with color coding.

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

### JSON Output
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

### Common Configuration Issues

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

### Error Recovery Examples

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

### Adding a New Scanner

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<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](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](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](LICENSE) file for details.

## Documentation

- 📖 [API Documentation](docs/API.md) - Complete API reference
- 🚀 [Deployment Guide](docs/DEPLOYMENT.md) - Docker, Kubernetes, and cloud deployment
- 💬 [Slack Integration Guide](docs/SLACK_INTEGRATION.md) - Complete Slack setup and configuration
- 🐙 [GitHub Integration Guide](docs/GITHUB_INTEGRATION.md) - Automated issue creation and management
- 📧 [Email Integration Guide](docs/EMAIL_INTEGRATION.md) - SMTP configuration and email reporting
- 💬 [Discord Integration Guide](docs/DISCORD_INTEGRATION.md) - Discord webhook setup and configuration
- 👥 [Teams Integration Guide](docs/TEAMS_INTEGRATION.md) - Microsoft Teams webhook integration
- 🔧 [Troubleshooting Guide](docs/TROUBLESHOOTING.md) - Common issues and solutions
- 📋 [Contributing Guidelines](CONTRIBUTING.md) - How to contribute to SupaMend
- 🔒 [Security Policy](SECURITY.md) - Security reporting and best practices
- 📝 [Changelog](CHANGELOG.md) - Version history and changes
- 🗺️ [Development Roadmap](ROADMAP.md) - Future features and development plans

## Support

- 🐛 [Issue Tracker](https://github.com/zmelliti/supamend/issues)
- 💬 [Discussions](https://github.com/zmelliti/supamend/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

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

### Scan Command
```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
```

### List Command
```bash
# List available scanners and reporters
npx supamend list
```

## Credits

Created with ❤️ by **Zied MELLITI**