proffesor-for-testing__agentic-qe/docs/api/security-scanner.md

# BrowserSecurityScanner API Reference

**Package:** `@agentic-qe/v3/domains/visual-accessibility`
**Source:** `/v3/src/domains/visual-accessibility/services/browser-security-scanner.ts`
**Upstream:** `@claude-flow/browser` (optional peer dependency)

## Overview

The `BrowserSecurityScanner` provides security validation for browser automation workflows, including URL validation, phishing detection, and PII scanning. It wraps the `@claude-flow/browser` security scanner with AQE v3's `Result<T,E>` pattern and provides graceful fallbacks when the package is unavailable.

---

## Class: BrowserSecurityScanner

### Constructor

```typescript
class BrowserSecurityScanner {
  constructor(options?: SecurityScannerOptions);
}
```

**Options:**

```typescript
interface SecurityScannerOptions {
  // URL whitelist for known safe domains
  whitelist?: string[];

  // Custom phishing patterns (regex)
  phishingPatterns?: RegExp[];

  // PII detection sensitivity: 'strict' | 'balanced' | 'lenient'
  piiSensitivity?: 'strict' | 'balanced' | 'lenient';

  // Enable XSS prevention
  xssPrevention?: boolean;

  // Timeout for security checks (ms)
  timeout?: number;
}
```

**Default Configuration:**

```typescript
{
  whitelist: [],
  phishingPatterns: [], // Uses built-in patterns
  piiSensitivity: 'balanced',
  xssPrevention: true,
  timeout: 5000
}
```

---

### Methods

#### initialize()

Initialize the scanner and load the upstream package if available.

```typescript
async initialize(): Promise<void>
```

**Example:**

```typescript
const scanner = new BrowserSecurityScanner();
await scanner.initialize();

if (scanner.isAvailable()) {
  console.log('Full security scanner available');
} else {
  console.log('Using fallback implementation');
}
```

---

#### validateUrl()

Validate a URL for security issues including SSRF, open redirects, and known malicious patterns.

```typescript
async validateUrl(url: string): Promise<Result<SecurityScanResult, Error>>
```

**Parameters:**
- `url`: The URL to validate

**Returns:**

```typescript
interface SecurityScanResult {
  safe: boolean;           // Overall safety verdict
  threats: string[];       // List of detected threats
  score: number;          // Security score (0-1, 1 = safe)
  details?: {
    protocol?: string;    // http, https, file, data, etc.
    domain?: string;      // Extracted domain
    hasPrivateIP?: boolean; // true if points to private IP
    isLocalhost?: boolean;  // true if localhost
    isDataUri?: boolean;    // true if data: URI
  };
}
```

**Threat Types:**
- `ssrf-private-ip`: URL points to private IP range
- `ssrf-localhost`: URL points to localhost
- `open-redirect`: Suspicious redirect patterns
- `phishing-domain`: Known phishing domain
- `data-uri-xss`: Potentially malicious data: URI
- `file-protocol`: Suspicious file: protocol usage

**Example:**

```typescript
const result = await scanner.validateUrl('https://example.com');

if (result.ok) {
  if (result.value.safe) {
    console.log('URL is safe to visit');
    console.log('Security score:', result.value.score);
  } else {
    console.error('URL has security issues:', result.value.threats);
  }
} else {
  console.error('Validation failed:', result.error.message);
}
```

**Fallback Behavior:**

When `@claude-flow/browser` is unavailable, performs basic validation:
- Protocol check (rejects `file:`, `data:`)
- URL parsing validation
- Returns `safe: true` for `http:` and `https:` with valid parsing

---

#### detectPhishing()

Check if a URL matches known phishing patterns.

```typescript
async detectPhishing(url: string): Promise<Result<PhishingResult, Error>>
```

**Parameters:**
- `url`: The URL to check

**Returns:**

```typescript
interface PhishingResult {
  isPhishing: boolean;
  confidence: number;    // 0-1, 1 = definitely phishing
  patterns: string[];    // Matched patterns
  suggestions?: string[];// Similar legitimate domains
}
```

**Example:**

```typescript
const result = await scanner.detectPhishing('https://paypa1.com');

if (result.ok && result.value.isPhishing) {
  console.log('Phishing detected!');
  console.log('Confidence:', result.value.confidence);
  console.log('Did you mean:', result.value.suggestions);
}
```

**Fallback Behavior:**

When package unavailable:
- Returns `isPhishing: false` for all domains
- No pattern matching

---

#### scanForPII()

Scan content for Personally Identifiable Information (PII).

```typescript
async scanForPII(content: string): Promise<Result<PIIScanResult, Error>>
```

**Parameters:**
- `content`: Text content to scan (HTML, plain text, JSON, etc.)

**Returns:**

```typescript
interface PIIScanResult {
  hasPII: boolean;
  detectedTypes: PIIType[];
  locations: PIILocation[];
  masked?: string;        // Content with PII masked (if requested)
}

type PIIType =
  | 'email'
  | 'ssn'
  | 'credit-card'
  | 'phone'
  | 'ip-address'
  | 'api-key'
  | 'jwt-token'
  | 'password'
  | 'address';

interface PIILocation {
  type: PIIType;
  start: number;
  end: number;
  value?: string;         // Redacted preview (e.g., "***@example.com")
  context?: string;       // Surrounding text for context
}
```

**Example:**

```typescript
const pageContent = await page.textContent();
const result = await scanner.scanForPII(pageContent);

if (result.ok && result.value.hasPII) {
  console.log('PII detected:', result.value.detectedTypes);

  for (const location of result.value.locations) {
    console.log(`Found ${location.type} at position ${location.start}`);
  }

  // Use masked content for logging
  console.log('Masked content:', result.value.masked);
}
```

**Detection Patterns:**

| PII Type | Pattern | Example |
|----------|---------|---------|
| Email | RFC 5322 compliant | `user@example.com` |
| SSN | XXX-XX-XXXX | `123-45-6789` |
| Credit Card | Luhn algorithm | `4532-1234-5678-9010` |
| Phone | North America, E.164 | `(555) 123-4567`, `+1-555-123-4567` |
| IP Address | IPv4, IPv6 | `192.168.1.1`, `2001:db8::1` |
| API Key | Common patterns | `sk-proj-...`, `ghp_...` |
| JWT Token | Base64 JWT structure | `eyJhbGc...` |

**Sensitivity Levels:**

- **Strict**: Detects all patterns, higher false positives
- **Balanced** (default): Moderate detection with context validation
- **Lenient**: Only clear PII patterns, fewer false positives

**Fallback Behavior:**

When package unavailable, uses regex-based detection for:
- Email addresses
- SSN patterns
- Credit card patterns (Luhn validation)
- Phone numbers (US format)

---

#### preventXSS()

Sanitize input to prevent XSS attacks.

```typescript
preventXSS(input: string): Result<SanitizedResult, Error>
```

**Parameters:**
- `input`: User input to sanitize

**Returns:**

```typescript
interface SanitizedResult {
  sanitized: string;     // Cleaned input
  hadThreats: boolean;   // true if threats were found
  removedPatterns: string[]; // Patterns that were removed
}
```

**Example:**

```typescript
const userInput = '<script>alert("xss")</script>Hello';
const result = scanner.preventXSS(userInput);

if (result.ok) {
  console.log('Safe input:', result.value.sanitized); // "Hello"

  if (result.value.hadThreats) {
    console.log('Removed:', result.value.removedPatterns); // ["<script>"]
  }
}
```

**Fallback Behavior:**

Basic HTML entity encoding when package unavailable.

---

#### isAvailable()

Check if the full security scanner is available.

```typescript
isAvailable(): boolean
```

**Returns:** `true` if `@claude-flow/browser` is loaded, `false` if using fallback

**Example:**

```typescript
if (!scanner.isAvailable()) {
  console.warn('Using fallback security scanner - install @claude-flow/browser for full features');
}
```

---

## Configuration Examples

### Whitelist Trusted Domains

```typescript
const scanner = new BrowserSecurityScanner({
  whitelist: [
    'https://example.com',
    'https://*.example.com',     // Wildcard subdomain
    'https://localhost:*',        // Wildcard port
    'http://127.0.0.1:*',        // Local development
  ],
});

// These will pass validation even with suspicious patterns
await scanner.validateUrl('https://api.example.com');
await scanner.validateUrl('https://localhost:3000');
```

### Custom Phishing Patterns

```typescript
const scanner = new BrowserSecurityScanner({
  phishingPatterns: [
    /paypa[1l]/i,                // paypal lookalikes
    /g[o0]{2}gle/i,              // google lookalikes
    /micr[o0]s[o0]ft/i,          // microsoft lookalikes
  ],
});
```

### Strict PII Detection

```typescript
const scanner = new BrowserSecurityScanner({
  piiSensitivity: 'strict',
});

// Will detect more potential PII with higher false positives
const result = await scanner.scanForPII(content);
```

---

## Integration with Visual Testing

### Pre-Capture URL Validation

```typescript
// v3/src/domains/visual-accessibility/services/visual-tester.ts

export class VisualTester {
  constructor(
    private readonly securityScanner: BrowserSecurityScanner,
    private readonly browser: Browser
  ) {}

  async captureScreenshot(url: string): Promise<Result<Screenshot, Error>> {
    // Validate URL first
    const securityCheck = await this.securityScanner.validateUrl(url);

    if (!securityCheck.ok) {
      return err(new Error(`Security validation failed: ${securityCheck.error.message}`));
    }

    if (!securityCheck.value.safe) {
      return err(new Error(`Unsafe URL: ${securityCheck.value.threats.join(', ')}`));
    }

    // Proceed with capture
    return await this.browser.screenshot(url);
  }
}
```

### PII Detection in Accessibility Reports

```typescript
// v3/src/domains/visual-accessibility/services/accessibility-tester.ts

export class AccessibilityTester {
  async auditPage(url: string): Promise<Result<AccessibilityReport, Error>> {
    const report = await this.runAxeAudit(url);

    // Scan report for PII before saving
    const piiCheck = await this.securityScanner.scanForPII(
      JSON.stringify(report)
    );

    if (piiCheck.ok && piiCheck.value.hasPII) {
      console.warn('PII detected in accessibility report');

      // Use masked version for logs
      report.maskedContent = piiCheck.value.masked;
    }

    return ok(report);
  }
}
```

---

## Error Handling

The scanner returns `Result<T, Error>` for all operations:

```typescript
const result = await scanner.validateUrl(url);

if (result.ok) {
  // Success case
  const scanResult = result.value;
  if (scanResult.safe) {
    // URL is safe
  } else {
    // URL has threats
    console.error(scanResult.threats);
  }
} else {
  // Error case
  console.error('Validation error:', result.error.message);

  // Handle specific errors
  if (result.error.message.includes('timeout')) {
    // Retry with longer timeout
  }
}
```

---

## Performance Considerations

| Operation | Latency (p95) | Throughput |
|-----------|---------------|------------|
| URL Validation (full) | 50ms | 200 ops/sec |
| URL Validation (fallback) | 5ms | 2000 ops/sec |
| Phishing Detection | 30ms | 300 ops/sec |
| PII Scan (1KB content) | 120ms | 80 ops/sec |
| PII Scan (fallback) | 80ms | 120 ops/sec |
| XSS Prevention | 10ms | 1000 ops/sec |

**Memory Usage:**
- Base: ~10MB
- Per-scan: ~1MB temporary

---

## Testing

### Unit Tests

```typescript
import { describe, it, expect } from 'vitest';
import { BrowserSecurityScanner } from './browser-security-scanner';

describe('BrowserSecurityScanner', () => {
  it('should detect SSRF attempts', async () => {
    const scanner = new BrowserSecurityScanner();
    await scanner.initialize();

    const result = await scanner.validateUrl('http://169.254.169.254/metadata');

    expect(result.ok).toBe(true);
    expect(result.value.safe).toBe(false);
    expect(result.value.threats).toContain('ssrf-private-ip');
  });

  it('should detect PII in content', async () => {
    const scanner = new BrowserSecurityScanner();
    await scanner.initialize();

    const content = 'Contact: user@example.com or 123-45-6789';
    const result = await scanner.scanForPII(content);

    expect(result.ok).toBe(true);
    expect(result.value.hasPII).toBe(true);
    expect(result.value.detectedTypes).toContain('email');
    expect(result.value.detectedTypes).toContain('ssn');
  });
});
```

---

## Security Best Practices

1. **Always validate URLs before browser operations**
   ```typescript
   const check = await scanner.validateUrl(url);
   if (!check.ok || !check.value.safe) {
     throw new Error('Security check failed');
   }
   ```

2. **Scan content before saving or logging**
   ```typescript
   const piiCheck = await scanner.scanForPII(content);
   if (piiCheck.ok && piiCheck.value.hasPII) {
     content = piiCheck.value.masked; // Use masked version
   }
   ```

3. **Use whitelists for trusted domains**
   ```typescript
   const scanner = new BrowserSecurityScanner({
     whitelist: ['https://trusted-domain.com'],
   });
   ```

4. **Monitor false positives and tune sensitivity**
   ```typescript
   const scanner = new BrowserSecurityScanner({
     piiSensitivity: 'balanced', // Adjust as needed
   });
   ```

---

## See Also

- [Main Integration Guide](../integration/claude-flow-browser.md)
- [Visual-Accessibility Domain](../domains/visual-accessibility.md)
- [Browser Testing Best Practices](../guides/browser-testing.md)