tops-bmad/security-tools/README.md

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

# TOPS BMAD Security Tools

Customized Shai-Hulud 2.0 Detector for TOPS BMAD organization.

## Features

- **Multi-project scanning**: Scan all projects in the workspace
- **Project-specific scanning**: Scan a single project by path
- **Programmatic API**: Use the scanner in your own scripts
- **Multiple output formats**: Text, JSON, or SARIF
- **CI/CD integration**: GitHub Actions support

## Quick Start

### Scan Current Project

```bash
npm run security:scan
```

### Scan All Projects

```bash
npm run security:scan:all
```

### Scan Specific Project

```bash
# Scan a specific project path
npm run security:scan:project -- .

# With options
npm run security:scan:project -- . --output-format json --fail-on-critical
```

### Direct Script Usage

```bash
# Scan a project (positional argument)
node security-tools/scripts/scan-workspace.js /path/to/project

# Scan a project (flag)
node security-tools/scripts/scan-workspace.js --project /path/to/project

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

## Programmatic API

Use the scanner in your own scripts:

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

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

console.log('Scan results:', result.summary);
console.log('Has issues:', result.hasIssues);
console.log('Should fail:', result.shouldFail);

// Get database info
const dbInfo = getDatabaseInfo();
console.log('Total packages:', dbInfo.totalPackages);

// Check specific package
if (isPackageAffected('some-package')) {
  console.log('Package is affected!');
}
```

## Options

### CLI Options

- `--output-format <text|json|sarif>` - Output format (default: text)
- `--scan-lockfiles` - Scan lockfiles (default: true)
- `--no-scan-lockfiles` - Skip lockfile scanning
- `--fail-on-critical` - Exit with error code if critical findings detected
- `--fail-on-high` - Exit with error code if high/critical findings detected
- `--fail-on-any` - Exit with error code if any findings detected

### API Options

```javascript
{
  scanLockfiles: boolean,    // Default: true
  outputFormat: string,      // 'text' | 'json' | 'sarif', Default: 'text'
  failOnCritical: boolean,   // Default: false
  failOnHigh: boolean,        // Default: false
  failOnAny: boolean         // Default: false
}
```

## Output Formats

### Text Format
Human-readable output with detailed findings and recommendations.

### JSON Format
Structured JSON output with all scan results:
```json
{
  "affectedCount": 0,
  "securityFindings": [],
  "results": [],
  "scannedFiles": [],
  "scanTime": 123,
  "projectPath": "/path/to/project",
  "databaseInfo": { ... }
}
```

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

## Configuration

Edit `security-tools/config/organization-config.json` to customize:
- Project paths
- Custom detection rules
- Notification settings

## Integration

The detector runs automatically:
- Before `npm install` (via preinstall hook)
- In CI/CD (GitHub Actions)
- On schedule (weekly)

## Examples

### Example 1: Scan and get JSON results

```bash
node security-tools/scripts/scan-workspace.js . --output-format json
```

### Example 2: Scan with failure on critical findings

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

### Example 3: Generate SARIF report

```bash
node security-tools/scripts/scan-workspace.js . \
  --output-format sarif
```

### Example 4: Use in your own script

```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);
  }
  
  console.log('Security check passed!');
}

checkSecurity();
```

## Troubleshooting

### Error: "Failed to load scanner"

Make sure the detector is built:
```bash
cd security-tools/Shai-Hulud-2.0-Detector
npm install
npm run build
```

### Error: "Project path does not exist"

Ensure the path is correct and accessible:
```bash
# Use absolute path
node security-tools/scripts/scan-project.js /absolute/path/to/project

# Or relative path from workspace root
node security-tools/scripts/scan-project.js ./relative/path/to/project
```

## Related Documentation

- [Shai-Hulud 2.0 Detector README](../Shai-Hulud-2.0-Detector/README.md)
- [Package Database Guide](../Shai-Hulud-2.0-Detector/docs/PACKAGE_DATABASE.md)