tops-bmad/security-tools/scripts/USAGE.md

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

# Security Scanner Usage Guide

## Overview

The TOPS BMAD Security Scanner provides multiple ways to scan projects for Shai-Hulud 2.0 indicators:

1. **CLI Script** (`scan-project.js`) - Spawns the detector process
2. **Direct TypeScript** (`scan-project-direct.ts`) - Uses scanner functions directly
3. **Programmatic API** (`scan-project-api.js`) - For use in your own scripts

## Method 1: CLI Script (Recommended)

The simplest way to scan a project:

```bash
# Basic usage
node security-tools/scripts/scan-project.js /path/to/project

# With options
node security-tools/scripts/scan-project.js /path/to/project \
  --output-format json \
  --scan-lockfiles \
  --fail-on-critical
```

**Pros:**
- Simple and reliable
- Works with the compiled detector
- No TypeScript compilation needed

**Cons:**
- Spawns a separate process
- Less control over output formatting

## Method 2: Direct TypeScript (Best Performance)

Uses scanner functions directly for better performance:

```bash
# Requires ts-node
npx ts-node security-tools/scripts/scan-project-direct.ts /path/to/project

# Or compile first
npx tsc security-tools/scripts/scan-project-direct.ts --module commonjs --esModuleInterop
node security-tools/scripts/scan-project-direct.js /path/to/project
```

**Pros:**
- Direct access to scanner functions
- Better performance (no process spawning)
- Full control over output

**Cons:**
- Requires TypeScript/ts-node
- Needs compilation step

## Method 3: Programmatic API

Use in your own scripts:

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

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

console.log(result.summary);
```

**Pros:**
- Easy integration
- Promise-based API
- Returns structured data

**Cons:**
- Currently uses process spawning (will be improved)

## Examples

### Example 1: Quick Scan

```bash
npm run security:scan:project -- ./ai-embedding
```

### Example 2: JSON Output

```bash
node security-tools/scripts/scan-project.js ./ai-embedding --output-format json
```

### Example 3: SARIF Report

```bash
node security-tools/scripts/scan-project.js ./vector-embedding/nestjs \
  --output-format sarif
```

### Example 4: Fail on Critical

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

### Example 5: Use in CI/CD

```javascript
// In your CI script
import { scanProject } from './security-tools/scripts/scan-project-api.js';

const result = await scanProject('./src', {
  outputFormat: 'sarif',
  failOnCritical: true
});

if (result.shouldFail) {
  console.error('Security scan failed:', result.failReason);
  process.exit(1);
}
```

## Options Reference

| Option | Description | Default |
|--------|-------------|---------|
| `--output-format` | Output format: text, json, or sarif | text |
| `--scan-lockfiles` | Scan package-lock.json files | true |
| `--no-scan-lockfiles` | Skip lockfile scanning | false |
| `--fail-on-critical` | Exit with error on critical findings | false |
| `--fail-on-high` | Exit with error on high/critical findings | false |
| `--fail-on-any` | Exit with error on any findings | false |

## Output Formats

### Text Format
Human-readable output with detailed findings:
```
======================================================================
  SHAI-HULUD 2.0 SUPPLY CHAIN ATTACK DETECTOR
======================================================================

  STATUS: CLEAN
  No compromised packages or security issues detected.
```

### JSON Format
Structured JSON for programmatic processing:
```json
{
  "affectedCount": 0,
  "securityFindings": [],
  "results": [],
  "scannedFiles": [...],
  "scanTime": 123
}
```

### SARIF Format
SARIF 2.1.0 compliant output for GitHub Security tab.
File written to `shai-hulud-results.sarif` in project directory.

## Troubleshooting

### "Failed to load scanner"
Make sure the detector is built:
```bash
cd security-tools/Shai-Hulud-2.0-Detector
npm install
npm run build
```

### "Project path does not exist"
Use absolute paths or relative paths from workspace root:
```bash
# Absolute path
node security-tools/scripts/scan-project.js /absolute/path/to/project

# Relative path
node security-tools/scripts/scan-project.js ./relative/path/to/project
```

### TypeScript errors with direct method
Install TypeScript dependencies:
```bash
npm install -D typescript ts-node
```