Skip to main content
Glama
Sentinel-One

Purple AI MCP Server

Official
by Sentinel-One
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

search_misconfigurations

Search and filter misconfigurations by severity, status, asset, and other criteria to identify security gaps.

Instructions

Search misconfigurations 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 "asset.name" or "evidence.secret"

        Core Fields:
        - "id": Misconfiguration ID
        - "name": Misconfiguration name
        - "severity": CRITICAL, HIGH, MEDIUM, LOW, INFO, UNKNOWN
        - "status": NEW, IN_PROGRESS, ON_HOLD, RESOLVED, RISK_ACKED, SUPPRESSED, TO_BE_PATCHED
        - "detectedAt": Detection timestamp
        - "lastSeenAt": Last seen timestamp
        - "environment": Environment type
        - "product": Product name
        - "vendor": Vendor name
        - "analystVerdict": TRUE_POSITIVE, FALSE_POSITIVE
        - "assigneeFullName": Assigned user full name
        - "exposureReason": Reason for exposure
        - "mitigable": Boolean - can be mitigated

        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

        Policy Fields (use appropriate prefixes):
        - "policyId": Policy identifier
        - "policyVersion": Policy version
        - "policyGroup": Policy group name
        - "organization": Organization name
        - "enforcementAction": Enforcement action type
        - "iacFramework": Infrastructure as Code framework

        Compliance & Classification:
        - "complianceStandards": Compliance standards
        - "hasClassifiedData": Boolean - contains classified data
        - "dataClassificationCategories": Data classification categories
        - "dataClassificationDataTypes": Data classification types

        Secret Fields (use "secret" prefix, NOT "evidence.secret."):
        - "secretId": Secret identifier
        - "secretHash": Secret hash
        - "secretType": Type of secret
        - "secretValidity": Secret validity status

        Request Fields (for admission controller, use "request" prefix):
        - "requestResourceName": Resource name
        - "requestResourceType": Resource type
        - "requestResourceNamespace": Resource namespace
        - "requestUserName": User name
        - "requestUserUid": User UID
        - "requestUserGroup": User group
        - "requestCategory": Request category

        Other Fields:
        - "commitedBy": Committed by (IaC findings)
        - "verifiedExploitable": Boolean - verified as exploitable
        - "accountId": Account ID (hidden)
        - "siteId": Site ID (hidden)
        - "groupId": Group ID (hidden)

        Filter Types and Required Keys:
        IMPORTANT: The misconfigurations 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"]}
          Note: product and vendor ONLY support STRING filters, NOT fulltext

        Boolean Filters (for mitigable, verifiedExploitable, hasClassifiedData, etc.):
        - "boolean_equals": Exact match for single boolean. Requires "value" key.
          Example: {"fieldId": "mitigable", "filterType": "boolean_equals", "value": true}
        - "boolean_in": Match any of multiple boolean values. Requires "values" key (list).
          Example: {"fieldId": "hasClassifiedData", "filterType": "boolean_in", "values": [true, null]}
          Note: Can include null to match missing/unset values
          SPECIAL CASE - secretValidity: ONLY supports boolean_in (NOT boolean_equals)

        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 Misconfiguration 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 lastSeenAt.

          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, exposureReason, asset/resource names, compliance, etc.):
        - "fulltext": Single-value text search. Requires "values" key (list of search terms).
          Example: {"fieldId": "name", "filterType": "fulltext", "values": ["s3"]}
        - "fulltext_in": Multi-value text search with partial matching. Requires "values" key (list).
          Example: {"fieldId": "assetName", "filterType": "fulltext_in", "values": ["server", "test", "web"]}
          SPECIAL CASES - secretHash/secretId: ONLY support fulltext/fulltext_in (NOT string_equals)

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

first: Number of misconfigurations to retrieve (1-100, default: 10).
after: Cursor for pagination (optional).
view_type: Filter by environment - ALL, CLOUD, KUBERNETES, etc.
fields: Optional JSON string containing an array of field names to return.
        If not specified, returns all default fields.
        See list_misconfigurations for available fields and examples.

        Available fields:
        - Basic: "id", "externalId", "name", "severity", "status"
        - Timing: "detectedAt", "lastSeenAt", "eventTime"
        - Context: "environment", "product", "vendor", "organization"
        - Analysis: "analystVerdict", "mitigable", "exposureReason"
        - Type: "misconfigurationType"
        - IDs: "resourceUid", "exploitId", "exclusionPolicyId"
        - Nested objects: "asset", "scope", "assignee", "evidence", "cnapp",
                        "admissionRequest", "remediation", "mitreAttacks"
          (See list_misconfigurations for exact subfields returned)
        - Lists: "complianceStandards", "dataClassificationDataTypes",
                "dataClassificationCategories"

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

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 misconfigurations in JSON format.

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

Examples: CORRECT: filters=[ {"fieldId": "severity", "filterType": "string_equals", "value": "CRITICAL"}, {"fieldId": "status", "filterType": "string_in", "values": ["NEW", "IN_PROGRESS"]}, {"fieldId": "assetCloudRegion", "filterType": "string_in", "values": ["us-east-1", "us-west-2"]} ] WRONG: filters=[ {"fieldId": "asset.name", "filterType": "fulltext", "values": ["test"]}, # Use "assetName" not "asset.name" {"fieldId": "evidence.secret.hash", "filterType": "string_equals", "value": "abc123"}, # Use "secretHash" not "evidence.secret.hash" {"fieldId": "severity", "filterType": "EQUALS", "value": "CRITICAL"} # Use "string_equals" not "EQUALS" ]

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
afterNo
firstNo
fieldsNo
filtersNo
view_typeNoALL

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
resultYes

Tool Definition Quality

A4.6/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 the full burden. It discloses the filter syntax, limits (50 filters, 100 values), unsupported INT filters, and error types (RuntimeError, ValueError). It does not explicitly state the tool is read-only, but the search context implies it. Missing explicit read-only mention prevents a 5.

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

Conciseness3/5

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

The description is highly detailed but overly long, with extensive lists of field names and examples. While well-structured with sections (Args, Valid Field Names, Filter Types, etc.), it could be more concise. Some redundancy exists (e.g., repeated emphasis on flat camelCase names).

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 presence of an output schema (not shown but known), the description covers all necessary aspects: parameters, error conditions, usage patterns, and references to sibling tools. It is complete for a complex filtering tool, addressing edge cases like date format conversion and secretValidity constraints.

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 description coverage is 0%, but the description thoroughly explains all five parameters: 'filters' (detailed JSON structure with examples), 'first' (default 10, range 1-100), 'after' (cursor for pagination), 'view_type' (ALL, CLOUD, etc.), and 'fields' (examples and performance note). This adds substantial meaning 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 the tool's purpose: 'Search misconfigurations using advanced filters and criteria.' It distinguishes itself from siblings like 'list_misconfigurations' (referenced in the fields section) and 'get_misconfiguration' by emphasizing advanced filtering capabilities.

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 detailed usage guidance, including when to use specific filter types, field naming conventions, and performance tips (e.g., using minimal fields for paging). It references 'list_misconfigurations' for available fields, helping users decide between tools.

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