Skip to main content

​
Finding

A single issue detected by a skill during code analysis.
​
id
string
required
Unique identifier for the finding. Generated automatically using a short alphanumeric format (e.g., "sec_xss_42a").
​
severity
Severity
required
Severity level: "high", "medium", or "low"Determines urgency and filtering behavior. See Severity for ordering rules.
​
confidence
Confidence
default:"undefined"
Confidence level: "high", "medium", or "low"How certain the skill is about this finding. Used for filtering low-confidence results.
​
title
string
required
Brief title summarizing the issue (e.g., "SQL injection vulnerability in user query")
​
description
string
required
Detailed explanation of the issue, including context and impact
​
verification
string
default:"undefined"
Steps to verify the issue manually or programmatically
​
location
Location
default:"undefined"
Primary location of the finding in the codebase
​
additionalLocations
Location[]
default:"undefined"
Related locations (e.g., all places where a vulnerable pattern appears)
​
suggestedFix
SuggestedFix
default:"undefined"
Proposed fix with unified diff format
​
elapsedMs
number
default:"undefined"
Time taken to generate this finding in milliseconds (must be non-negative)

​
Location

Specifies where a finding occurs in the codebase.
​
path
string
required
File path relative to repository root (e.g., "src/auth/login.ts")
​
startLine
number
required
Starting line number (1-indexed, must be positive)
​
endLine
number
default:"undefined"
Ending line number (1-indexed, must be positive). If omitted, defaults to startLine.

​
SuggestedFix

A proposed code change to resolve a finding.
​
description
string
required
Human-readable explanation of what the fix does and why it resolves the issue
​
diff
string
required
Unified diff format showing the change:
@@ -42,3 +42,3 @@
-const query = `SELECT * FROM users WHERE id = ${userId}`;
+const query = db.prepare('SELECT * FROM users WHERE id = ?');
+const result = query.get(userId);
Warden can automatically apply suggested fixes using --apply-fixes or generate PRs with fixes using schedule triggers.

​
Severity

Severity levels for findings. 
type Severity = 'high' | 'medium' | 'low';

​
Severity Ordering

Warden uses consistent ordering for filtering and comparison: 
import { SEVERITY_ORDER, filterFindingsBySeverity } from '@sentry/warden';

console.log(SEVERITY_ORDER);
// { high: 0, medium: 1, low: 2 }
// Lower number = more severe

// Filter to only high and medium severity
const filtered = filterFindingsBySeverity(findings, 'medium');

​
Backward Compatibility

Warden normalizes legacy severity values:
  • "critical" → "high" (for old JSONL logs)
  • "info" → "low" (for old LLM responses)
Skills should only use the three-level scale (high, medium, low). The normalization exists for backward compatibility with historical data.

​
Confidence

Confidence levels indicate how certain a skill is about a finding. 
type Confidence = 'high' | 'medium' | 'low';

​
Confidence Ordering

import { CONFIDENCE_ORDER, filterFindingsByConfidence } from '@sentry/warden';

console.log(CONFIDENCE_ORDER);
// { high: 0, medium: 1, low: 2 }
// Lower number = more confident

// Filter out low-confidence findings
const filtered = filterFindingsByConfidence(findings, 'medium');

​
Configuration

Control confidence filtering in warden.toml: 
[defaults]
minConfidence = "medium"  # Filter out low-confidence findings

[[skills]]
name = "security-audit"
minConfidence = "high"    # Override for this skill

​
Example: Complete Finding

import type { Finding } from '@sentry/warden';

const finding: Finding = {
  id: 'sec_sqli_7f2',
  severity: 'high',
  confidence: 'high',
  title: 'SQL injection vulnerability in user query',
  description: `The user ID is interpolated directly into the SQL query without sanitization. 
An attacker can manipulate the userId parameter to execute arbitrary SQL commands, 
potentially exposing or modifying sensitive data.`,
  verification: 'Try passing userId="1 OR 1=1" to retrieve all user records',
  location: {
    path: 'src/auth/login.ts',
    startLine: 42,
    endLine: 43
  },
  suggestedFix: {
    description: 'Use parameterized queries to prevent SQL injection',
    diff: `@@ -42,2 +42,3 @@
-const query = \`SELECT * FROM users WHERE id = \${userId}\`;
-const user = db.get(query);
+const query = db.prepare('SELECT * FROM users WHERE id = ?');
+const user = query.get(userId);
`
  },
  elapsedMs: 1847
};

​
Filtering and Comparison

Warden provides utilities for working with findings:

​
Filter by Severity and Confidence

import { filterFindings } from '@sentry/warden';

// Apply both severity and confidence filters
const filtered = filterFindings(
  findings,
  'medium',  // reportOn: include medium and high severity
  'medium'   // minConfidence: include medium and high confidence
);

​
Compare Finding Priority

import { compareFindingPriority } from '@sentry/warden';

// Sort findings by priority
// Higher severity > higher confidence > earlier file path > earlier line number
const sorted = findings.sort(compareFindingPriority);

​
Get Effective Line Number

import { findingLine } from '@sentry/warden';

// Returns endLine if present, otherwise startLine, otherwise 0
const line = findingLine(finding);

​
Validation

All finding types use Zod schemas for runtime validation: 
import {
  FindingSchema,
  LocationSchema,
  SuggestedFixSchema,
  SeveritySchema,
  ConfidenceSchema
} from '@sentry/warden';

// Parse and validate a finding
const validated = FindingSchema.parse(rawFinding);

// Safe parse with error handling
const result = FindingSchema.safeParse(rawFinding);
if (!result.success) {
  console.error('Invalid finding:', result.error);
}
Skills must return findings that conform to the FindingSchema. Invalid findings will cause analysis to fail with detailed validation errors.

Build docs developers (and LLMs) love

Get started for freeTalk to us