jira-search

The jira-search agent finds Jira issues using JQL queries. It validates query syntax, builds JQL from plain-language descriptions, manages saved filters, and exports results — all with mandatory JQL sanitization that prevents injection vulnerabilities when handling user-supplied search terms.

Cognitive Framing

"Every user-supplied term must be sanitized before it enters a JQL query. No exceptions."

The jira-search agent is a domain-specific agent for finding and filtering issues. Its most important discipline is JQL sanitization — every user-supplied term passes through the jql-sanitize.sh script before entering a query, preventing JQL injection attacks that could expose other teams' tickets.

Key Facts

Type	Domain (Jira)
Phase	On-demand
Model	inherit
Color	green
Safety	4-tier (search → filter create → bulk-update → filter delete)
Never does	Single-issue CRUD (jira-issue), bulk write operations (jira-bulk), skip JQL sanitization

When to Use

• When you need to find issues by criteria — status, assignee, sprint, labels, date ranges.
• When you need to validate JQL syntax before running a complex query.
• When you want to build JQL from a plain-language description — "tickets assigned to me, in progress."
• When you need to manage saved filters — create, update, share, or delete.
• When you need to export search results to CSV.

Key Capabilities

• JQL query execution — runs JQL queries with result capping (--max-results) and field projection via jq.
• JQL sanitization — all user-supplied terms pass through jql-sanitize.sh before query construction. Prevents JQL injection.
• Natural language to JQL — converts plain-language descriptions to JQL using search build --description.
• JQL validation — validates query syntax before execution using search validate.
• Filter management — creates, updates, shares, and deletes saved Jira filters.
• Result export — exports query results to CSV format.

Behavioral Checklist

• [x] Sanitizes ALL user-supplied terms via jql-sanitize.sh before embedding in JQL — mandatory
• [x] Caps result counts on every search call with --max-results
• [x] Projects output fields for readability via jq
• [x] Validates JQL syntax before executing complex queries
• [x] Runs --dry-run before bulk-update operations
• [x] Requires confirmation before destructive filter operations (delete)
• [x] Never constructs JQL by string concatenation with raw user input

Common Use Cases

Scenario	What the agent does
"Find all open bugs in project PROJ"	Sanitizes terms, runs search query "project = PROJ AND type = Bug AND status != Done"
"Show my in-progress tickets"	Runs assignee = currentUser() AND status = 'In Progress'
"Build a query for tech debt tickets"	Uses search build --description to generate JQL from natural language
"Export last week's resolved issues"	Runs query with date filter and exports to CSV
"Save this search as a filter"	Creates a named saved filter with the JQL query

Pro Tips

Always Sanitize User Input

JQL injection is a real vulnerability class. If a user says "search for issues about DROP TABLE", the raw term could manipulate query logic. The jql-sanitize.sh script strips JQL operators, functions, and special characters, then quote-wraps the result. Never skip this step, even for seemingly harmless terms.

Cap Results to Prevent Overload

Always use --max-results on search queries. An unbounded query against a large Jira instance can return thousands of issues, overwhelming the output and consuming excessive API quota. Start with 20 results and increase only if needed.

Key Takeaway

The jira-search agent provides safe, injection-resistant JQL querying with built-in sanitization that prevents a class of vulnerabilities other tools miss. Its natural-language-to-JQL capability makes complex queries accessible without requiring JQL expertise.

Related Agents

• jira-issue — handles single-issue CRUD after search identifies the target
• jira-bulk — handles bulk operations on search results (10+ issues)
• jira-fields — discovers field names and IDs used in JQL queries