Skip to main content
Glama
Sentinel-One

Purple AI MCP Server

Official
by Sentinel-One
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

search_vulnerabilities

Find vulnerabilities by severity, status, exploitation status, or other criteria using advanced filters to narrow results.

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", "prod", "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": ["prod"]}, # Use "assetName" not "asset.name" {"fieldId": "severity", "filterType": "EQUALS", "value": "CRITICAL"} # Use "string_equals" not "EQUALS" ]

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
filtersNo
firstNo
afterNo
fieldsNo

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
resultYes

Tool Definition Quality

A4.9/5.0
Behavior5/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 transparently explains the filter structure, limits (max 50 filters, 100 values), datetime conversion requirements, and error types (RuntimeError, ValueError). It also notes that INT filters are not supported and that product/vendor only support STRING filters.

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 very long but well-organized with sections (Purpose, Args, Returns, Raises, Examples). It uses bullet points and clear headers. However, it is somewhat verbose, with some repetition (e.g., datetime explanation appears twice). Still, the complexity of the filter system justifies the length.

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?

The description covers all essential aspects: input parameters (with detailed sub-documentation), return value (references list_vulnerabilities for output format), error conditions, and usage examples. Given the tool's complexity and the existence of an output schema (not shown but referenced), the description is complete.

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%, but the description compensates comprehensively: it details the 'filters' parameter structure with field names, filter types, and examples; specifies 'first' range 1-100; explains 'after' for pagination; and lists available 'fields' options with examples. This adds immense semantic 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 starts with a clear verb+resource statement: 'Search vulnerabilities using advanced filters and criteria.' It distinguishes itself from sibling tools like list_vulnerabilities (simpler listing) and get_vulnerability (single item) by emphasizing advanced filtering.

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 extensive usage guidance: it enumerates valid field names with flat naming convention, explains each filter type with examples, gives correct vs. wrong examples, and includes a performance note for paging. It explicitly warns against common mistakes like using nested paths or wrong filter type names.

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