PR-1.6: BanSubstrings Reference Scanner (~80 LOC + 110 tests)

[xiaoqi-7]

Summary

Phase 1.6: Reference implementation of a pattern detector. BanSubstringsScanner is a concrete Scanner that detects banned substring patterns in content, serving as a template for creating additional scanner types.

BanSubstringsScanner: Substring Pattern Detection

Features

• Exact substring matching: Case-sensitive detection of banned substrings
• Multi-pattern support: Can detect multiple banned patterns in priority order
• First-match reporting: Returns the first pattern found in ban list order
• Match context: Includes match index and matched text in results
• Validation: Ensures name and substrings are non-empty at construction

Constructor

scanner = BanSubstringsScanner(
    name="api_keys",
    banned_substrings=["sk-", "rk-", "pk-"]
)

Core Methods (Scanner Interface)

• name property: Unique scanner identifier
• pattern property: Human-readable pattern description
• scan(content: str) → ScanResult: Detect banned substrings

Example Usages

# API key detection
api_scanner = BanSubstringsScanner("api_keys", ["sk-", "rk-"])
result = api_scanner.scan("key: sk-1234567890")
if result.found:
    log_violation(result)

# Password keyword detection
pwd_scanner = BanSubstringsScanner("passwords", ["password", "passwd", "pwd"])
result = pwd_scanner.scan("Enter password to continue")

# SQL injection keyword detection
sql_scanner = BanSubstringsScanner("sql_injection", ["DROP TABLE", "DELETE FROM"])

# Integration with GuardEngine
registry = ScannerRegistry()
registry.register(api_scanner)
registry.register(pwd_scanner)

engine = GuardEngine(registry)
for delta in stream:
    results = engine.process_delta(delta)
    if results and any(r.found for r in results):
        trigger_security_action()

Test Coverage

33 tests, 100% pass rate

Test Categories

• Initialization (6 tests): Valid/invalid names, substring validation, empty lists
• Properties (4 tests): name/pattern/repr properties
• Scanning (10 tests): Position detection, case sensitivity, multiple patterns, partial matches
• Edge Cases (3 tests): Empty content, empty ban list, both empty
• Real-World (6 tests): API keys, passwords, tokens, SQL injection, patterns
• Integration (4 tests): Scanner interface compliance, registry integration, GuardEngine workflow

Key Test Scenarios

• Detects "sk-" prefix for API keys
• Rejects case mismatches ("password" ≠ "Password")
• Returns match position and text
• Handles multiple banned patterns with priority order
• Works seamlessly in ScannerRegistry
• Integrates with GuardEngine for streaming detection

Design Principles

1. Simple responsibility: Only detects banned substrings (no regex, no complex logic)
2. Deterministic: Same input always produces same output
3. No false positives: Substring match is exact
4. Observable: Returns match details (position, text)
5. Extensible: Template for creating other scanners

Files Changed

• scanners/ban_substrings.py - BanSubstringsScanner implementation (~80 LOC)
• tests/test_ban_substrings.py - Comprehensive test suite (~140 LOC)

Architecture

Content Stream
    ↓
GuardEngine (orchestration)
    ↓
ScannerRegistry (manages multiple scanners)
    ↓
BanSubstringsScanner (detects banned substrings) ← This PR
    ↓
ScanResult (match details)
    ↓
Action (log, block, redirect, etc)

Future Scanner Implementations

This PR demonstrates the pattern for creating new scanners:

• RegexScanner: Regex pattern matching
• PiiScanner: Personal Identifiable Information detection
• CreditCardScanner: Credit card number patterns
• EmailScanner: Email address patterns
• Custom business-logic scanners

All follow the same Scanner interface and integrate seamlessly with GuardEngine.

Dependencies

• Depends on: PR-1.1 (Skeleton), PR-1.2 (SSE Parser), PR-1.3 (Logical Stream), PR-1.4 (Scanner Interface), PR-1.5 (GuardEngine)
• Blocks: PR-1.7 (Server Integration)

Test Results

33 passed ✅