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

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

Options:

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:

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

---

Methods

initialize()

Initialize the scanner and load the upstream package if available.

async initialize(): Promise<void>

Example:

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.

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

Parameters:

• url: The URL to validate

Returns:

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:

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.

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

Parameters:

• url: The URL to check

Returns:

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

Example:

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).

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

Parameters:

• content: Text content to scan (HTML, plain text, JSON, etc.)

Returns:

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:

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.

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

Parameters:

• input: User input to sanitize

Returns:

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

Example:

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.

isAvailable(): boolean

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

Example:

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

---

Configuration Examples

Whitelist Trusted Domains

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

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

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

// 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

// 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:

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

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

   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

   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

   const scanner = new BrowserSecurityScanner({
     whitelist: ['https://trusted-domain.com'],
   });
   

4. Monitor false positives and tune sensitivity

   const scanner = new BrowserSecurityScanner({
     piiSensitivity: 'balanced', // Adjust as needed
   });
   

---

See Also

• Main Integration Guide
• Visual-Accessibility Domain
• Browser Testing Best Practices