tops-bmad/security-tools/IMPLEMENTATION.md

CLI tool to install BMAD workflow files into any project with integrated Shai-Hulud 2.0 security scanning

# Shai-Hulud 2.0 Detector - Customization Implementation

## Overview

This document describes the implementation of the project path scanning feature for the Shai-Hulud 2.0 Detector, customized for TOPS BMAD organization.

## Features Implemented

### 1. Project Path Scanner (`scan-project.js`)

A CLI script that scans a specific project path using the Shai-Hulud 2.0 Detector.

**Location:** `security-tools/scripts/scan-project.js`

**Features:**
- Accepts project path as command-line argument
- Supports multiple output formats (text, JSON, SARIF)
- Configurable scan options (lockfiles, failure modes)
- Validates project path before scanning
- Provides clear error messages

**Usage:**
```bash
node security-tools/scripts/scan-project.js <project-path> [options]
```

**Example:**
```bash
node security-tools/scripts/scan-project.js ./my-project --output-format json --fail-on-critical
```

### 2. Programmatic API (`scan-project-api.js`)

A module that provides a programmatic interface for scanning projects.

**Location:** `security-tools/scripts/scan-project-api.js`

**Exported Functions:**
- `scanProject(projectPath, options)` - Main scanning function
- `getDatabaseInfo()` - Get database metadata
- `isPackageAffected(packageName)` - Check if package is affected
- `getPackageSeverity(packageName)` - Get package severity

**Usage:**
```javascript
import { scanProject } from './security-tools/scripts/scan-project-api.js';

const result = await scanProject('/path/to/project', {
  outputFormat: 'json',
  failOnCritical: true
});
```

### 3. Direct TypeScript Scanner (`scan-project-direct.ts`)

A TypeScript implementation that directly uses scanner functions for better performance.

**Location:** `security-tools/scripts/scan-project-direct.ts`

**Features:**
- Direct access to scanner functions (no process spawning)
- Better performance
- Full TypeScript type safety

**Usage:**
```bash
npx ts-node security-tools/scripts/scan-project-direct.ts <project-path> [options]
```

## Implementation Details

### Architecture

The implementation uses three approaches:

1. **Process Spawning** (scan-project.js)
   - Spawns the detector as a child process
   - Simple and reliable
   - Works with compiled detector

2. **Direct Function Calls** (scan-project-direct.ts)
   - Imports scanner functions directly
   - Better performance
   - Requires TypeScript compilation

3. **API Wrapper** (scan-project-api.js)
   - Provides a clean API interface
   - Currently uses process spawning (can be improved)

### Options Supported

All implementations support the following options:

- `--output-format <text|json|sarif>` - Output format
- `--scan-lockfiles` / `--no-scan-lockfiles` - Lockfile scanning
- `--fail-on-critical` - Fail on critical findings
- `--fail-on-high` - Fail on high/critical findings
- `--fail-on-any` - Fail on any findings

### Integration

The scanner is integrated into the project's npm scripts:

```json
{
  "scripts": {
    "security:scan:project": "node security-tools/scripts/scan-project.js"
  }
}
```

## Files Created

1. `security-tools/scripts/scan-project.js` - Main CLI script
2. `security-tools/scripts/scan-project-api.js` - Programmatic API
3. `security-tools/scripts/scan-project-direct.ts` - Direct TypeScript scanner
4. `security-tools/README.md` - Main documentation
5. `security-tools/scripts/USAGE.md` - Usage guide
6. `security-tools/IMPLEMENTATION.md` - This file

## Testing

The implementation has been tested with:
- ✅ Current directory scanning
- ✅ JSON output format
- ✅ Text output format
- ✅ Path validation
- ✅ Error handling

## Future Improvements

1. **Direct Function Access in API**
   - Update `scan-project-api.js` to use scanner functions directly
   - Remove process spawning overhead

2. **Compiled Direct Scanner**
   - Create a build script for `scan-project-direct.ts`
   - Add to npm scripts for easy use

3. **Batch Scanning**
   - Add support for scanning multiple projects at once
   - Aggregate results across projects

4. **Configuration File**
   - Support configuration file for default options
   - Organization-specific rules

## Usage Examples

### Basic Scan
```bash
npm run security:scan:project -- ./my-project
```

### JSON Output
```bash
node security-tools/scripts/scan-project.js ./my-project --output-format json
```

### With Failure on Critical
```bash
node security-tools/scripts/scan-project.js ./my-project \
  --output-format text \
  --fail-on-critical
```

### Programmatic Usage
```javascript
import { scanProject } from './security-tools/scripts/scan-project-api.js';

async function checkSecurity() {
  const result = await scanProject('./my-project', {
    outputFormat: 'json',
    failOnCritical: true
  });
  
  if (result.shouldFail) {
    console.error('Security check failed:', result.failReason);
    process.exit(1);
  }
  
  return result.summary;
}
```

## Dependencies

- Node.js 16+
- Shai-Hulud-2.0-Detector (built)
- TypeScript (for direct scanner, optional)

## Notes

- The detector must be built before use: `cd security-tools/Shai-Hulud-2.0-Detector && npm run build`
- Project paths can be absolute or relative
- All paths are validated before scanning
- Exit codes follow standard conventions (0 = success, 1 = failure)