Skip to content

fix(ENG-12236): document useDefaultToolRules and add ATS/CRM tool rules #10

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hiskudin merged 1 commit into from
Mar 3, 2026
Merged

fix(ENG-12236): document useDefaultToolRules and add ATS/CRM tool rules #10

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 21 additions & 7 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,11 @@ import { createPromptDefense } from '@stackone/defender';

// Create defense with Tier 1 (patterns) + Tier 2 (ML classifier)
// blockHighRisk: true enables the allowed/blocked decision
const defense = createPromptDefense({ enableTier2: true, blockHighRisk: true });
const defense = createPromptDefense({
enableTier2: true,
blockHighRisk: true,
useDefaultToolRules: true, // Enable built-in per-tool base risk and field-handling rules (risky-field overrides always apply)
});

// Defend a tool result — ONNX model (~22MB) auto-loads on first call
const result = await defense.defendToolResult(toolOutput, 'gmail_get_message');
Expand Down Expand Up @@ -71,6 +75,8 @@ Use `allowed` for blocking decisions:

`riskLevel` is diagnostic metadata. It starts at the tool's base risk level and can only be escalated by detections — never reduced. Use it for logging and monitoring, not for allow/block logic.

The following base risk levels apply when `useDefaultToolRules: true` is set. Without it, tools use `defaultRiskLevel` (defaults to `medium`).

| Tool Pattern | Base Risk | Why |
|--------------|-----------|-----|
| `gmail_*`, `email_*` | `high` | Emails are the #1 injection vector |
Expand Down Expand Up @@ -98,9 +104,10 @@ Create a defense instance.

```typescript
const defense = createPromptDefense({
enableTier1: true, // Pattern detection (default: true)
enableTier2: true, // ML classification (default: false)
blockHighRisk: true, // Block high/critical content (default: false)
enableTier1: true, // Pattern detection (default: true)
enableTier2: true, // ML classification (default: false)
blockHighRisk: true, // Block high/critical content (default: false)
useDefaultToolRules: true, // Enable built-in per-tool base risk and field-handling rules (default: false)
defaultRiskLevel: 'medium',
});
```
Expand Down Expand Up @@ -179,7 +186,11 @@ await mlpDefense.warmupTier2();
import { generateText, tool } from 'ai';
import { createPromptDefense } from '@stackone/defender';

const defense = createPromptDefense({ enableTier2: true, blockHighRisk: true });
const defense = createPromptDefense({
enableTier2: true,
blockHighRisk: true,
useDefaultToolRules: true,
});
await defense.warmupTier2(); // optional, avoids first-call latency

const result = await generateText({
Expand All @@ -204,15 +215,18 @@ const result = await generateText({

## Tool-Specific Rules

Built-in rules define which fields to sanitize and what base risk level to use for each tool provider. See the [base risk table](#understanding-allowed-vs-risklevel) for risk levels.
> **Note:** `useDefaultToolRules: true` enables built-in per-tool **risk rules** (base risk, skip fields, max lengths, thresholds). Risky-field detection (which fields get sanitized) uses tool-specific overrides regardless of this setting.

Built-in per-tool rules define the base risk level and field-handling parameters for each tool provider. See the [base risk table](#understanding-allowed-vs-risklevel) for risk levels.

| Tool Pattern | Risky Fields | Notes |
|---|---|---|
| `gmail_*`, `email_*` | subject, body, snippet, content | Base risk `high` — primary injection vector |
| `documents_*` | name, description, content, title | User-generated content |
| `github_*` | name, title, body, description | PRs, issues, comments |
| `hris_*` | name, notes, bio, description | Employee free-text fields |
| `ats_*`, `crm_*` | _(default risky fields)_ | Uses global defaults |
| `ats_*` | name, notes, description, summary | Candidate data |
| `crm_*` | name, description, notes, content | Customer data |

Tools not matching any pattern use `medium` base risk with default risky field detection.

Expand Down
26 changes: 26 additions & 0 deletions src/config.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,32 @@ export const DEFAULT_TOOL_RULES: ToolSanitizationRule[] = [
skipFields: ["id", "employee_id", "created_at", "updated_at"],
},

// ATS tools - candidate data with free-text fields
{
toolPattern: /^ats_/,
sanitizationLevel: "medium",
maxFieldLengths: {
name: 200,
notes: 5000,
description: 2000,
summary: 2000,
},
skipFields: ["id", "candidate_id", "application_id", "created_at", "updated_at"],
},

// CRM tools - customer data with free-text fields
{
toolPattern: /^crm_/,
sanitizationLevel: "medium",
maxFieldLengths: {
name: 200,
description: 2000,
notes: 5000,
content: 10000,
},
skipFields: ["id", "contact_id", "account_id", "created_at", "updated_at"],
},

// Email tools - higher risk due to external content
{
toolPattern: /^gmail_|^email_/,
Expand Down