Skip to main content
Glama
Sentinel-One

Purple AI MCP Server

Official
by Sentinel-One
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

search_vulnerabilities

Search for vulnerabilities using advanced filters like severity, status, CVE exploitability, and asset details to pinpoint specific security issues.

Instructions

Search vulnerabilities using advanced filters and criteria.

Args: filters: JSON string containing an array of filter objects (optional). Each filter object must have: - fieldId: String field name - MUST use flattened camelCase names (see Valid Field Names below) - filterType: One of the supported filter types below - isNegated: Optional boolean to negate the filter (default: false)

        Valid Field Names (fieldId values):
        IMPORTANT: Use these exact field names, NOT nested paths like "cve.id" or "asset.name"

        Core Fields:
        - "id": Vulnerability ID
        - "name": Vulnerability name
        - "severity": CRITICAL, HIGH, MEDIUM, LOW, UNKNOWN
        - "status": NEW, IN_PROGRESS, ON_HOLD, RESOLVED, RISK_ACKED, SUPPRESSED, TO_BE_PATCHED
        - "detectedAt": Detection timestamp
        - "lastSeenAt": Last seen timestamp
        - "product": Product name
        - "vendor": Vendor name
        - "analystVerdict": TRUE_POSITIVE, FALSE_POSITIVE
        - "assigneeFullName": Assigned user full name

        CVE Fields (use "cve" prefix, NOT "cve."):
        - "cveId": CVE identifier (e.g. CVE-2024-1234)
        - "cveNvdBaseScore": NVD base score (SORT ONLY - not filterable)
        - "cveRiskScore": SentinelOne risk score (SORT ONLY - not filterable)
        - "cveEpssScore": EPSS probability score (STRING_IN only - use ranges: "0.0-0.35", "0.35-0.5", "0.5-0.75", "0.75-1.0")
        - "cveExploitMaturity": NOT_AVAILABLE, UNPROVEN, PROOF_OF_CONCEPT, FUNCTIONAL, HIGH
        - "cveExploitedInTheWild": Boolean - actively exploited
        - "cveKevAvailable": Boolean - in CISA KEV catalog
        - "cveReportConfidence": Report confidence level

        Software Fields (use "software" prefix, NOT "software."):
        - "softwareName": Software package name
        - "softwareVersion": Installed version
        - "softwareFixVersion": Available fix version
        - "softwareFixVersionAvailable": Boolean - fix available
        - "softwareType": OPERATING_SYSTEM, APPLICATION, LIBRARY, etc.
        - "softwareVendor": Software vendor name

        Asset Fields (use "asset" prefix, NOT "asset."):
        - "assetId": Asset identifier
        - "assetName": Asset name
        - "assetType": Asset type
        - "assetTypeCategory": Asset type category
        - "assetCategory": Asset category
        - "assetSubcategory": Asset subcategory
        - "assetCriticality": CRITICAL, HIGH, MEDIUM, LOW, UNKNOWN
        - "assetPrivileged": Boolean - privileged asset
        - "assetCloudResourceId": Cloud resource ID
        - "assetCloudAccountId": Cloud account ID
        - "assetCloudAccount": Cloud account name
        - "assetCloudRegion": Cloud region
        - "assetKubernetesCluster": Kubernetes cluster name
        - "assetKubernetesClusterId": Kubernetes cluster ID

        Other Fields:
        - "remediationInsightsAvailable": Boolean - remediation insights available
        - "accountId": Account ID (hidden)
        - "siteId": Site ID (hidden)
        - "groupId": Group ID (hidden)

        Filter Types and Required Keys:
        IMPORTANT: The vulnerabilities API does NOT support INT filters. Use STRING or BOOLEAN filters.

        String Filters (for severity, status, product, vendor, etc.):
        - "string_equals": Exact match. Requires "value" key.
          Example: {"fieldId": "severity", "filterType": "string_equals", "value": "CRITICAL"}
        - "string_in": Match any of multiple values. Requires "values" key (list).
          Example: {"fieldId": "status", "filterType": "string_in", "values": ["NEW", "IN_PROGRESS"]}
          SPECIAL CASE - cveEpssScore: Use range format like {"fieldId": "cveEpssScore", "filterType": "string_in", "values": ["0.5-0.75", "0.75-1.0"]}
          Note: product and vendor ONLY support STRING filters, NOT fulltext

        Boolean Filters (for exploited, KEV, fix available, etc.):
        - "boolean_equals": Exact match for single boolean. Requires "value" key.
          Example: {"fieldId": "cveExploitedInTheWild", "filterType": "boolean_equals", "value": true}
        - "boolean_in": Match any of multiple boolean values. Requires "values" key (list).
          Example: {"fieldId": "softwareFixVersionAvailable", "filterType": "boolean_in", "values": [true, null]}
          Note: Can include null to match missing/unset values

        DateTime Filters (for detectedAt, lastSeenAt):
        - "datetime_range": Range match using UNIX timestamps in milliseconds (UTC). Requires "start" and/or "end" keys.
          Optional: "startInclusive", "endInclusive" (default: true)

          IMPORTANT: All datetimes in the Vulnerability API are in UTC timezone.
          You MUST use the iso_to_unix_timestamp tool to convert ISO 8601 datetime strings
          to UNIX timestamps (milliseconds) before using them in datetime filters.

          IMPORTANT: Unless the user specifies a field to query a DateTime on, use detectedAt.

          The iso_to_unix_timestamp tool handles timezone conversion automatically.
          Provide datetimes in the user's preferred timezone (e.g., "2024-10-30T08:00:00-04:00" for Eastern Time)
          and the tool will convert to UTC milliseconds for the API.

          Example workflow:
          1. Call iso_to_unix_timestamp("2024-10-30T08:00:00-04:00") -> returns "1730289600000" (UTC)
          2. Use result in filter: {"fieldId": "detectedAt", "filterType": "datetime_range", "start": 1730289600000}

          Example: {"fieldId": "detectedAt", "filterType": "datetime_range", "start": 1730289600000}

        Fulltext Search (for name, CVE ID, software/asset names):
        - "fulltext": Single-value text search. Requires "values" key (list of search terms).
          Example: {"fieldId": "name", "filterType": "fulltext", "values": ["log4j"]}
        - "fulltext_in": Multi-value text search with partial matching. Requires "values" key (list).
          Example: {"fieldId": "assetName", "filterType": "fulltext_in", "values": ["server", "test", "web"]}

        Limits:
        - Maximum 50 filters per request
        - Maximum 100 values in "values" arrays

first: Number of vulnerabilities to retrieve (1-100, default: 10).
after: Cursor for pagination (optional).
fields: Optional JSON string containing an array of field names to return.
        If not specified, returns all default fields.
        See list_vulnerabilities for available fields and examples.

        Available fields:
        - Basic: "id", "name", "severity", "status"
        - Timing: "detectedAt", "lastSeenAt"
        - Context: "product", "vendor"
        - Analysis: "analystVerdict"
        - IDs: "exclusionPolicyId"
        - Nested objects: "cve", "software", "asset", "scope", "assignee"
          (See list_vulnerabilities for exact subfields returned)

        Examples:
        - Minimal for paging: '["id"]'
        - Summary: '["id", "severity", "status", "name", "detectedAt"]'
        - With CVE: '["id", "name", "cve", "software"]'

Performance Note: When paging through many results, use fields='["id"]' for intermediate pages to conserve context window space. Use totalCount to gauge result set size.

Returns: Filtered list of vulnerabilities in JSON format.

Raises: RuntimeError: If there's an error searching vulnerabilities. ValueError: If parameters are invalid.

Examples: CORRECT: filters=[ {"fieldId": "severity", "filterType": "string_equals", "value": "CRITICAL"}, {"fieldId": "cveExploitedInTheWild", "filterType": "boolean_equals", "value": true}, {"fieldId": "assetType", "filterType": "string_in", "values": ["SERVER", "WORKSTATION"]} ] WRONG: filters=[ {"fieldId": "cve.id", "filterType": "string_equals", "value": "CVE-2024-1234"}, # Use "cveId" not "cve.id" {"fieldId": "asset.name", "filterType": "fulltext", "values": ["test"]}, # Use "assetName" not "asset.name" {"fieldId": "severity", "filterType": "EQUALS", "value": "CRITICAL"} # Use "string_equals" not "EQUALS" ]

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
afterNo
firstNo
fieldsNo
filtersNo

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
resultYes

Tool Definition Quality

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It discloses that the tool raises RuntimeError or ValueError on failure, returns JSON, and has limitations (no INT filters). It does not explicitly state that the operation is read-only or idempotent, but that is implied by its search nature. Overall, it clearly explains the filtering behavior and error conditions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but well-structured with clear sections (Args, Returns, Raises, Examples), bullet points, and code formatting. It is front-loaded with the main purpose. Some redundancy exists (e.g., repeated prefix explanations), but the complexity of the filter system justifies the length. Minor trimming could improve conciseness without losing clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (4 parameters, 0% schema coverage, no annotations) and the existence of an output schema, the description is remarkably complete. It covers all parameters with extensive detail, includes examples, notes about timezone conversion, performance advice, and error conditions. The output schema covers return values, so no additional explanation needed there.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must fully explain parameters. It does so exhaustively: 'filters' gets a multi-page guide with valid field names, filter types, examples, and special cases. 'first' and 'after' are described with defaults and pagination. 'fields' lists available fields and sample JSON arrays. The description adds immense value beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Search vulnerabilities using advanced filters and criteria.' It names the verb 'search' and resource 'vulnerabilities.' It distinguishes itself from sibling tools like list_vulnerabilities by emphasizing advanced filtering capabilities, and from other search tools like search_alerts by specifying the domain. The extensive detail on filter structure reinforces purpose clarity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use filters, how to structure them, and includes examples of correct and incorrect usage. It advises using iso_to_unix_timestamp for datetime conversions, notes that product/vendor only support STRING filters, and gives a performance tip for paging. It also mentions the maximum filter limits and valid field names, leaving little ambiguity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

Other Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Sentinel-One/purple-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server