get-findings
Retrieve and summarize client findings from OnSecurity, optionally filterable by round ID or type. Presents data clearly for client understanding, with customizable sorting, limits, and optional related data inclusion.
Instructions
Get all findings data from OnSecurity from client in a high level summary, only include the summary, not the raw data and be sure to present the data in a way that is easy to understand for the client. You can optionally filter findings by round_id. HOWEVER ONLY USE THIS TOOL WHEN ASKED FOR FINDINGS RELATED TO A CLIENT OR MY FINDINGS, NOT THE BLOCKS TOOL.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| fields | No | Optional comma-separated list of fields to return (e.g. 'id,name'). Use * as wildcard. | |
| filters | No | Optional additional filters in format {field: value} or {field-operator: value} where operator can be mt (more than), mte (more than equal), lt (less than), lte (less than equal), eq (equals, default) | |
| includes | No | Optional related data to include as comma-separated values (e.g. 'client,round,target_components') | |
| limit | No | Optional limit parameter for max results per page (e.g. 15) | |
| page | No | Optional page number to fetch (default: 1) | |
| round_id | No | Optional round ID to filter findings | |
| round_type | No | Optional round type to filter rounds, 1 = pentest round, 3 = scan round | |
| search | No | Search term to find findings by name of finding or related content | |
| sort | No | Optional sort parameter in format 'field-direction'. Available values: name-asc, round_id-asc, created_at-asc, updated_at-asc, name-desc, round_id-desc, created_at-desc, updated_at-desc. Default: id-asc |
Implementation Reference
- src/index.ts:441-519 (registration)Registers the 'get-findings' tool on the MCP server with description, input schema, and handler function.server.tool( "get-findings", "Get all findings data from OnSecurity from client in a high level summary, only include the summary, not the raw data and be sure to present the data in a way that is easy to understand for the client. You can optionally filter findings by round_id. HOWEVER ONLY USE THIS TOOL WHEN ASKED FOR FINDINGS RELATED TO A CLIENT OR MY FINDINGS, NOT THE BLOCKS TOOL.", { round_id: z.number().optional().describe("Optional round ID to filter findings"), round_type: z.number().optional().describe("Optional round type to filter rounds, 1 = pentest round, 3 = scan round"), sort: z.string().optional().describe("Optional sort parameter in format 'field-direction'. Available values: name-asc, round_id-asc, created_at-asc, updated_at-asc, name-desc, round_id-desc, created_at-desc, updated_at-desc. Default: id-asc"), limit: z.number().optional().describe("Optional limit parameter for max results per page (e.g. 15)"), page: z.number().optional().describe("Optional page number to fetch (default: 1)"), includes: z.string().optional().describe("Optional related data to include as comma-separated values (e.g. 'client,round,target_components')"), fields: z.string().optional().describe("Optional comma-separated list of fields to return (e.g. 'id,name'). Use * as wildcard."), filters: FilterSchema, search: z.string().optional().describe("Search term to find findings by name of finding or related content") }, async (params) => { const filters: Record<string, string | number> = {}; // Add additional filters if provided if (params.filters) { Object.entries(params.filters).forEach(([key, value]) => { filters[key] = value; }); } // Add round_id filter if provided if (params.round_id) { filters['round_id-eq'] = params.round_id; } // Add round_type filter if provided if (params.round_type) { filters['round_type_id-eq'] = params.round_type; } const response = await fetchPage<ApiResponse<FindingFeature>>( 'findings', params.page || 1, filters, params.sort, params.includes, params.fields, params.limit, params.search ); if (!response) { return { content: [ { type: "text", text: "Error fetching findings data. Please try again." } ] }; } const paginationInfo = formatPaginationInfo(response); const formattedFindings = response.result.map(formatFinding); const responseText = [ "# Findings Summary", "", "## Pagination Information", paginationInfo, "", "## Findings Data", ...formattedFindings ].join('\n'); return { content: [ { type: "text", text: responseText } ] }; } );
- src/index.ts:455-518 (handler)The main handler function for the 'get-findings' tool. It constructs filters based on input params, fetches data from the OnSecurity API using fetchPage, formats the findings, and returns a markdown-formatted text response.async (params) => { const filters: Record<string, string | number> = {}; // Add additional filters if provided if (params.filters) { Object.entries(params.filters).forEach(([key, value]) => { filters[key] = value; }); } // Add round_id filter if provided if (params.round_id) { filters['round_id-eq'] = params.round_id; } // Add round_type filter if provided if (params.round_type) { filters['round_type_id-eq'] = params.round_type; } const response = await fetchPage<ApiResponse<FindingFeature>>( 'findings', params.page || 1, filters, params.sort, params.includes, params.fields, params.limit, params.search ); if (!response) { return { content: [ { type: "text", text: "Error fetching findings data. Please try again." } ] }; } const paginationInfo = formatPaginationInfo(response); const formattedFindings = response.result.map(formatFinding); const responseText = [ "# Findings Summary", "", "## Pagination Information", paginationInfo, "", "## Findings Data", ...formattedFindings ].join('\n'); return { content: [ { type: "text", text: responseText } ] }; }
- src/index.ts:444-454 (schema)Zod input schema defining parameters for the 'get-findings' tool, including optional filters for round_id, pagination, sorting, etc.{ round_id: z.number().optional().describe("Optional round ID to filter findings"), round_type: z.number().optional().describe("Optional round type to filter rounds, 1 = pentest round, 3 = scan round"), sort: z.string().optional().describe("Optional sort parameter in format 'field-direction'. Available values: name-asc, round_id-asc, created_at-asc, updated_at-asc, name-desc, round_id-desc, created_at-desc, updated_at-desc. Default: id-asc"), limit: z.number().optional().describe("Optional limit parameter for max results per page (e.g. 15)"), page: z.number().optional().describe("Optional page number to fetch (default: 1)"), includes: z.string().optional().describe("Optional related data to include as comma-separated values (e.g. 'client,round,target_components')"), fields: z.string().optional().describe("Optional comma-separated list of fields to return (e.g. 'id,name'). Use * as wildcard."), filters: FilterSchema, search: z.string().optional().describe("Search term to find findings by name of finding or related content") },
- src/index.ts:279-298 (helper)Helper function specifically used by the get-findings handler to format each FindingFeature into a human-readable string summary.function formatFinding(finding: FindingFeature): string { return [ `Finding ID: ${finding.id}`, `Display ID: ${finding.display_id}`, `Name: ${finding.name}`, `Client ID: ${finding.client_id}`, `Round ID: ${finding.round_id}`, `CVSS Score: ${finding.cvss?.score || "N/A"}`, `Severity: ${finding.cvss?.severity_label || "N/A"}`, `Status: ${finding.status?.label || "Unknown"} (${finding.status?.description || "No description"})`, `Published: ${finding.published}`, `Remediation Complexity: ${finding.remediation_complexity || "N/A"}`, `Executive Description: ${finding.executive_description || "N/A"}`, `Executive Risk: ${finding.executive_risk || "N/A"}`, `Executive Recommendation: ${finding.executive_recommendation || "N/A"}`, `Description: ${finding.description || "N/A"}`, `Evidence: ${finding.evidence || "N/A"}`, `Recommendation: ${finding.recommendation || "N/A"}`, `--------------------------------`, ].join('\n');