npm package: @merchantguard/guardscan
Description: Security scanner for AI agent skills — 102 patterns, 17 categories, payment/PCI compliance, prompt injection detection. Local by default, no code leaves your machine.
Author: MerchantGuard
Latest version: 1.0.0

# @merchantguard/guardscan

Security scanner for AI agent skills. 99 patterns, 17 categories, payment/PCI compliance, prompt injection detection. **Local by default — no code leaves your machine.**

## Install

```bash
npm install @merchantguard/guardscan
```

## CLI

```bash
# Scan a directory
npx @merchantguard/guardscan .

# Scan specific files
npx @merchantguard/guardscan ./src/index.ts ./lib/auth.ts

# Output SARIF (GitHub Code Scanning, VS Code)
npx @merchantguard/guardscan . --sarif > guardscan.sarif

# Output CLAUDE.md (fix instructions for Claude Code)
npx @merchantguard/guardscan . --claudemd > GUARDSCAN.md

# JSON output
npx @merchantguard/guardscan . --json
```

### CLI Options

| Flag | Description |
|------|-------------|
| `--sarif` | SARIF 2.1.0 JSON output |
| `--claudemd` | Markdown with fix instructions for Claude Code |
| `--json` | Raw JSON result |
| `--quiet` | Summary only, no finding details |
| `--help` | Show usage |

### Exit Codes

- `0` — No critical findings
- `1` — Critical findings detected

## Library

```typescript
import { scanFiles } from '@merchantguard/guardscan';

const result = scanFiles([
  { name: 'index.ts', content: 'const key = "sk-proj-abc123..."' }
]);

console.log(result.securityScore); // 0-100
console.log(result.status);        // 'red' | 'yellow' | 'green'
console.log(result.findings);      // ScanFinding[]
```

### `scanFiles(files)`

Scans an array of `{ name: string, content: string }` objects.

Returns a `ScanResult`:

```typescript
interface ScanResult {
  scanId: string;
  status: 'red' | 'yellow' | 'green';
  statusLabel: string;
  securityScore: number;        // 0-100
  filesScanned: number;
  linesScanned: number;
  findings: ScanFinding[];
  summary: {
    total: number;
    critical: number;
    high: number;
    medium: number;
    low: number;
  };
  paymentContext: PaymentContext;
}
```

### `toSarif(result)`

Converts a `ScanResult` to SARIF 2.1.0 format for GitHub Code Scanning or VS Code SARIF Viewer.

```typescript
import { scanFiles, toSarif } from '@merchantguard/guardscan';

const result = scanFiles(files);
const sarif = toSarif(result);
fs.writeFileSync('guardscan.sarif', JSON.stringify(sarif, null, 2));
```

### `generateClaudeMd(result)`

Generates a CLAUDE.md file with fix instructions that Claude Code can follow.

```typescript
import { scanFiles, generateClaudeMd } from '@merchantguard/guardscan';

const result = scanFiles(files);
fs.writeFileSync('GUARDSCAN.md', generateClaudeMd(result));
```

## Scoring

Half-life scoring formula: `score = 100 * (0.5 ^ (deductions / 80))`

| Severity | Deduction |
|----------|-----------|
| CRITICAL | 25 |
| HIGH | 15 |
| MEDIUM | 8 |
| LOW | 3 |

| Score | Status | Label |
|-------|--------|-------|
| 90-100 | green | Safe |
| 70-89 | yellow | Caution |
| 40-69 | yellow | Risky |
| 0-39 | red | Dangerous |

## 17 Categories

secrets, auth, xss, injection, config, rate-limit, pci-dss, compliance, crypto, file, malware, prompt-injection, data-exfil, tool-abuse, autonomy-abuse, skill-manifest, obfuscation

## Payment Context

GuardScan detects payment provider usage (Stripe, Adyen, Braintree, PayPal, Square, Authorize.net, Worldpay, Checkout.com, Klarna, Affirm, Plaid, Marqeta) and flags PCI-DSS relevant findings.

## Web UI

Try GuardScan online at [merchantguard.ai/guardscan](https://merchantguard.ai/guardscan)

## License

MIT