bob-sps-helper

AI-powered security vulnerability management for IBM Verify products. Combines proactive scanning (Security Auditor Mode) with reactive issue management (MCP Server + Bob Commands) for complete security workflow coverage.

🎨 Hybrid Architecture

bob-sps-helper uses a hybrid architecture combining:

• MCP Server - Backend engine with 7 powerful tools
• Bob Commands - Natural language UI for easy interaction
• Auto-Sync - Automatic command distribution on first run

What this means for you:

• ✅ Commands auto-install to ~/.bob/commands/ on first use
• ✅ Natural language interface: "Check setup" instead of tool names
• ✅ Always up-to-date: Commands sync automatically with package updates

🎯 Quick Links

• Installation Guide - Get started in 5 minutes
• Security Auditor Guide - Proactive vulnerability scanning
• Workflows & Examples - Real-world usage patterns
• Advanced Configuration - Component mapping, troubleshooting, tuning
• Changelog - Version history and updates

🚀 Two Ways to Use

1️⃣ Security Auditor Mode (Proactive Scanning)

Discovers NEW vulnerabilities through static analysis - no test execution required.

What it does:

• Scans dependencies for CVEs (npm, Maven, Gradle, pip, etc.)
• Detects hardcoded secrets (API keys, passwords, tokens)
• Finds code vulnerabilities (SQL injection, XSS, CSRF)
• Audits configurations (Docker, nginx, security headers)
• Auto-fixes issues and creates PRs

Quick Start:

# Install globally (3 minutes)
git clone https://github.ibm.com/himanshu-sao-ibm/bob-sps-helper.git
cd bob-sps-helper
mkdir -p ~/.bob/rules-bob-security-auditor
cp -r .bob/rules-bob-security-auditor/* ~/.bob/rules-bob-security-auditor/

Then add to ~/.bob/settings/custom_modes.yaml (see Security Auditor Guide)

Usage:

Switch to Security Auditor mode
Scan this project for security vulnerabilities

📖 Full Guide: docs/SECURITY_AUDITOR.md

2️⃣ bob-sps-helper MCP Server (Issue Management)

Manages EXISTING security issues from GitHub/JIRA scanners.

What it does:

• Analyzes security issues with detailed vulnerability tables
• Suggests fixes with code snippets and upgrade paths
• Creates JIRA deviation requests automatically
• Tracks sprint progress and component health
• Generates comprehensive reports

Quick Start:

1. Set environment variables (in ~/.zshrc or ~/.bashrc):

export GITHUB_REPO_ACCESS_TOKEN="ghp_xxxx"
export GITHUB_BASE_URL="https://github.ibm.com/api/v3"
export JIRA_PAT="ATATTxxxx"
export JIRA_BASE_URL="https://jsw.ibm.com"
export JIRA_USERNAME="[email protected]"

2. Add MCP server to VS Code (User Settings JSON):

{
  "mcp": {
    "servers": {
      "bob-sps-helper": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "bob-sps-helper"],
        "env": {
          "GITHUB_REPO_ACCESS_TOKEN": "${env:GITHUB_REPO_ACCESS_TOKEN}",
          "GITHUB_BASE_URL": "${env:GITHUB_BASE_URL}",
          "JIRA_PAT": "${env:JIRA_PAT}",
          "JIRA_BASE_URL": "${env:JIRA_BASE_URL}",
          "JIRA_USERNAME": "${env:JIRA_USERNAME}"
        }
      }
    }
  }
}

3. Reload VS Code (Cmd+Q → reopen)

Usage with Bob Commands (Recommended):

Check setup
Analyze issues for component agent-bridge-supsvc sprint 158
Create deviation for issues 59200 and 59169 in component saml sprint 158

Usage with MCP Tools (Advanced):

Use the bob-sps-helper MCP server to analyze security issues for component agent-bridge-supsvc sprint 158

📖 Full Setup Guide: INSTALLATION.md

🎯 Bob Commands (Natural Language UI)

After installation, 7 Bob Commands are automatically synced to ~/.bob/commands/:

| Command | Description | Example | |---------|-------------|---------| | Check setup | Verify prerequisites and configuration | Check setup | | Analyze issues | Analyze security issues by component/sprint | Analyze issues for component saml sprint 158 | | Create deviation | Create JIRA deviation requests | Create deviation for issues 59200,59169 in component saml sprint 158 | | Suggest fix | Get detailed fix recommendations | Suggest fix for issue 59200 | | Create fix PR | Auto-create PR with fixes | Create fix PR for issues 59200,59169 in component saml | | Component health | Check component security status | Component health for saml | | Batch process | Process entire sprint | Batch process sprint 158 for component workflow |

Benefits:

• ✅ Natural language - no need to remember tool names
• ✅ Auto-complete - Bob suggests commands as you type
• ✅ Always current - commands update automatically with package
• ✅ Contextual help - each command includes examples and tips

🔄 How They Work Together

┌─────────────────────────────────────────────────────────┐
│  1. Security Auditor: Proactive Scanning                │
│     - Scan project for vulnerabilities                  │
│     - Find 10 issues (dependencies, code, configs)      │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│  2. Security Auditor: Auto-Remediation                  │
│     - Auto-fix 7 issues (dependencies, code)            │
│     - Create PR with fixes                              │
│     - Verify fixes resolve vulnerabilities              │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│  3. Handoff to bob-sps-helper                           │
│     - 3 issues cannot be fixed (no vendor fix, OS deps) │
│     - Security Auditor hands off to bob-sps-helper      │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│  4. bob-sps-helper: Deviation Management                │
│     - Create JIRA deviation requests                    │
│     - Link to GitHub issues                             │
│     - Add appropriate labels                            │
│     - Track in sprint workflow                          │
└─────────────────────────────────────────────────────────┘

Result: Complete security coverage from discovery → fix → tracking

📊 Key Features

Security Auditor Mode

• ⚡ Fast - Static analysis in seconds, no test execution
• 🎯 Accurate - Multi-layer scanning (dependencies, code, configs, secrets)
• 🔧 Automated - Auto-fixes with PR creation
• 📊 Comprehensive - Detailed reports with CVSS, CWE, remediation
• 🔄 Integrated - Works with bob-sps-helper for JIRA tracking

bob-sps-helper MCP Server

• 📋 Detailed Analysis - Vulnerability tables with CVE, CVSS, impact, remediation
• 🎯 Interactive Workflow - Actionable options after each severity group
• 🔧 Automation - Batch deviation creation, auto-fix suggestions
• 📈 Sprint Tracking - Component health, progress monitoring
• 🔗 Integration - GitHub, JIRA, component mapping

🛠️ Supported Technologies

| Language | Package Managers | Scanning | |----------|-----------------|----------| | Java | Maven, Gradle | ✅ | | Node.js | npm, yarn | ✅ | | Python | pip, pipenv | ✅ | | Go | go modules | ✅ | | Ruby | bundler | ✅ | | PHP | composer | ✅ | | .NET | NuGet | ✅ | | Rust | cargo | ✅ |

📚 Documentation

Getting Started

• Installation Guide - Quick 5-minute setup
• Security Auditor Installation - Mode installation guide

Usage Guides

• Security Auditor Guide - Scanning, auto-fix, best practices
• Workflows & Examples - Real-world usage patterns

Advanced

• Advanced Configuration - Component mapping, troubleshooting, tuning
• Changelog - Version history

🎓 Quick Examples

Security Auditor Mode

Complete project scan:

Switch to Security Auditor mode
Scan this project for security vulnerabilities

Quick dependency check:

Quick scan - dependencies only

Fix specific vulnerability type:

Find and fix all SQL injection vulnerabilities

Remove hardcoded secrets:

Remove hardcoded AWS credentials

bob-sps-helper Bob Commands (Recommended)

Check setup:

Check setup

Analyze component issues:

Analyze issues for component agent-bridge-supsvc sprint 158

Create deviation requests:

Create deviation for issues 59200,59169 in component saml sprint 158

Check component health:

Component health for notification

Batch process sprint:

Batch process sprint 158 for component workflow

bob-sps-helper MCP Tools (Advanced)

Direct tool usage:

Use the bob-sps-helper MCP server to analyze security issues for component agent-bridge-supsvc sprint 158

Create deviation with tool:

Use the bob-sps-helper MCP server to create deviation requests for issues 59200 and 59169 in component saml sprint 158

🆘 Troubleshooting

Security Auditor Mode

Mode not appearing?

# Verify files
ls -la ~/.bob/rules-bob-security-auditor/

# Reload Bob
Cmd+Shift+P → "Developer: Reload Window"

See Security Auditor Troubleshooting

MCP Server

All logs show as "errors"?

• This is normal! MCP servers write to stderr
• Look for "✅ All checks passed" message

Token issues?

# Verify environment variables
echo $GITHUB_REPO_ACCESS_TOKEN
echo $JIRA_PAT

# Reload shell and VS Code
source ~/.zshrc
# Then: Cmd+Q → reopen VS Code

See Advanced Troubleshooting

🔧 For Contributors

Clone and Build

git clone https://github.ibm.com/himanshu-sao-ibm/bob-sps-helper.git
cd bob-sps-helper
npm install
npm run build

Local Testing

# Test MCP server locally
node dist/index.js

# Test with specific tool
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"check_setup","arguments":{}}}' | node dist/index.js

Making Changes

1. Edit source files in src/
2. Run npm run build to compile
3. Test changes locally
4. Update version in package.json
5. Run npm run publish to publish

📦 Publishing a New Version

First-Time Setup

npm login --registry=https://registry.npmjs.org/

Publish

# Update version
npm version patch  # or minor, or major

# Build and publish
npm run build
npm publish

# Push changes
git push origin main --tags

Verify Publication

npm view bob-sps-helper

Teammate Updates

Teammates get updates automatically via npx. To force update:

npx clear-npx-cache

📄 License

This project is licensed under the MIT License.

Version: 1.0.0
Last Updated: 2026-04-16
Maintainer: Himanshu Sao ([email protected])