ts: true, ...config, }; }

async inspect(payload: string): Promise<ScanResult> { const inputBuffer = Buffer.from(payload, 'utf-8');

try {
  const output = execFileSync(this.config.binaryPath, {
    input: inputBuffer,
    timeout: this.config.timeoutMs,
    encoding: 'utf-8',
    maxBuffer: 1024 * 1024,
  });

  const result: ScanResult = JSON.parse(output);

  if (result.suspicious && result.confidence >= this.config.minConfidence) {
    return this.applyPolicy(result);
  }

  return result;
} catch (error) {
  throw new Error(`BoundaryGuard inspection failed: ${(error as Error).message}`);
}

}

private applyPolicy(result: ScanResult): ScanResult { if (this.config.redactSecrets) { result.sanitized_text = result.sanitized_text.replace( /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+.[A-Z|a-z]{2,}\b/g, '[REDACTED_EMAIL]' ); } return result; } }

export { BoundaryGuard, ScanResult };

### Architecture Decisions & Rationale

**Rust Core Selection:** The detection engine is implemented in Rust to guarantee memory safety, predictable latency, and zero garbage collection pauses. Agent runtimes often operate under strict SLAs; a managed runtime with unpredictable pause times would introduce tail latency spikes during high-throughput inspection.

**TF-IDF Linear Classifier:** Instead of deploying a full neural network, the semantic detection lane uses a Rust-native TF-IDF linear classifier exported from pre-trained artifacts. This choice is deliberate:
- TF-IDF vectorization is deterministic and requires no GPU or heavy CPU inference
- Linear classification executes in microseconds with consistent memory footprint
- The model artifacts are lightweight (~15 MB), enabling fast cold starts
- Accuracy remains high (Macro F1: 0.9833) for the targeted detection classes

**JSON I/O Contract:** Standard input/output with JSON serialization ensures language agnosticism. The wrapper in TypeScript, Python, or Go only needs to handle process lifecycle and parsing. This prevents security logic duplication and centralizes rule updates to the binary.

**Confidence Thresholding:** The scanner outputs a continuous confidence score rather than a binary flag. This enables policy-driven decision making. High-risk boundaries (e.g., tool execution) can enforce stricter thresholds, while low-risk boundaries (e.g., logging) can tolerate higher false positive rates with redaction fallbacks.

## Pitfall Guide

### 1. Scanning Only Inbound Prompts
**Explanation:** Teams frequently place the scanner only at the chat interface, assuming that once a prompt passes inspection, all downstream data is safe. This ignores tool outputs, retrieved documents, and memory mutations that can contain injection payloads.
**Fix:** Implement boundary gates at every data transition: retrieval, tool arguments, tool outputs, memory writes, and final responses.

### 2. Hard-Blocking on Low Confidence Scores
**Explanation:** Treating any `suspicious: true` flag as a hard block causes legitimate agent workflows to fail. Semantic classifiers operate on probability distributions, and edge cases in technical documentation or internal APIs often trigger low-confidence flags.
**Fix:** Use confidence thresholds aligned with risk tolerance. Apply redaction or human-in-the-loop escalation for scores between 0.6–0.85, and reserve hard blocks for scores above 0.90.

### 3. Ignoring Redaction Capabilities
**Explanation:** Many teams focus solely on blocking malicious input but fail to sanitize outputs. Sensitive data can leak through logs, error messages, or tool responses even when the primary injection is blocked.
**Fix:** Enable automatic redaction for credential patterns, PII, and internal identifiers. Ensure the scanner's `sanitized_text` field is used for all downstream logging and context window insertion.

### 4. Treating the Scanner as a Model Replacement
**Explanation:** Boundary scanners detect patterns and semantic signals; they do not reason. Expecting them to understand complex multi-turn jailbreaks or novel adversarial strategies leads to false security assumptions.
**Fix:** Position the scanner as a runtime filter, not a reasoning engine. Combine it with model-level guardrails, structured tool schemas, and least-privilege execution policies.

### 5. Misaligning Timeout Budgets
**Explanation:** Agent workflows often have strict latency budgets. If the scanner timeout is set too high, it masks performance degradation. If set too low, it causes unnecessary process kills during high-load periods.
**Fix:** Set the wrapper timeout to 2–3x the average classifier latency (e.g., 50 ms for a 0.0247 ms classifier). Monitor p99 latency in production and adjust based on actual process scheduling overhead.

### 6. Overlooking Licensing Constraints
**Explanation:** Source-available local scanners often use non-commercial licenses for community distribution. Deploying them in production SaaS or enterprise environments without proper licensing creates compliance risk.
**Fix:** Audit license terms before production deployment. Secure commercial licenses where required, and maintain clear separation between development/testing and production environments.

### 7. Failing to Normalize Input Encoding
**Explanation:** Adversarial payloads frequently use Unicode normalization, zero-width characters, or mixed encoding to bypass pattern matching. Scanners that process raw bytes without normalization are vulnerable to evasion.
**Fix:** Implement input normalization before scanning: strip zero-width characters, normalize Unicode, decode HTML entities, and collapse whitespace. Apply normalization consistently across all boundary gates.

## Production Bundle

### Action Checklist
- [ ] Map all data boundaries in your agent architecture (input, retrieval, tools, memory, output)
- [ ] Deploy the scanner binary to the same host as the agent runtime
- [ ] Configure confidence thresholds based on boundary risk level (strict for tools, lenient for logs)
- [ ] Enable automatic redaction for credentials, PII, and internal identifiers
- [ ] Implement fallback policies for scanner timeouts or crashes (fail-open vs fail-closed)
- [ ] Monitor p99 latency and false positive rates in production dashboards
- [ ] Audit license compliance for commercial deployment environments
- [ ] Add normalization pre-processing to handle Unicode and encoding evasion techniques

### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
|----------|---------------------|-----|-------------|
| High-throughput agent pipeline (>100 req/s) | Local Rust scanner | Sub-millisecond latency, zero network overhead, deterministic throughput | $0 API cost, minimal compute |
| Compliance-heavy enterprise (HIPAA/SOC2) | Local scanner + audit logging | Keeps sensitive data on-prem, enables full audit trail without egress | Licensing cost, infrastructure overhead |
| Rapid prototyping / internal tools | Cloud guardrail API | Zero deployment, managed updates, simple integration | $0.002–$0.005 per request, scales linearly |
| Multi-tenant SaaS with strict data residency | Local scanner per tenant | Guarantees data never leaves tenant boundary, meets residency requirements | Higher infra cost, complex deployment |

### Configuration Template

```json
{
  "scanner": {
    "binary_path": "/opt/agents/bin/guard_scanner",
    "timeout_ms": 50,
    "max_buffer_bytes": 1048576
  },
  "policies": {
    "min_confidence_block": 0.90,
    "min_confidence_redact": 0.75,
    "redact_secrets": true,
    "redact_patterns": [
      "email",
      "api_key",
      "internal_ip",
      "jwt_token"
    ]
  },
  "boundaries": {
    "inbound_prompt": { "enabled": true, "action": "block" },
    "retrieved_context": { "enabled": true, "action": "redact" },
    "tool_arguments": { "enabled": true, "action": "block" },
    "tool_output": { "enabled": true, "action": "redact" },
    "memory_write": { "enabled": true, "action": "log" },
    "final_response": { "enabled": true, "action": "redact" }
  },
  "detection_classes": [
    "prompt_injection",
    "system_prompt_extraction",
    "data_exfiltration",
    "sensitive_data_request",
    "safety_bypass",
    "destructive_command",
    "credential_leakage",
    "risky_tool_call"
  ]
}

Quick Start Guide

1. Download the scanner binary for your target architecture and place it in a dedicated directory (e.g., /opt/agents/bin/).
2. Verify execution by running a test payload through the binary using standard input. Confirm JSON output matches the expected schema.
3. Initialize the wrapper in your agent codebase using the configuration template. Set boundary-specific actions and confidence thresholds.
4. Integrate at one boundary first (e.g., tool arguments). Run a controlled workload and monitor latency, false positive rate, and redaction accuracy.
5. Expand to remaining boundaries once the initial gate stabilizes. Update dashboards to track inspection throughput and policy enforcement actions.