Skip to main content
Glama
Sentinel-One

Purple AI MCP Server

Official
by Sentinel-One
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

search_misconfigurations

Search security misconfigurations using advanced filters on severity, status, asset, and more to pinpoint critical findings.

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", "prod", "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": ["prod"]}, # 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
filtersNo
firstNo
afterNo
view_typeNoALL
fieldsNo

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?

With no annotations, the description carries the full burden and discloses many behaviors: maximum 50 filters, 100 values, unsupported INT filter, UTC datetime requirement, use of iso_to_unix_timestamp, and possible exceptions (RuntimeError, ValueError). However, it does not mention authorization requirements or rate limits, which would be helpful for a full behavioral understanding.

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 very long and verbose, containing extensive nested lists and examples. While it is well-structured with clear sections (Args, Examples, etc.), it lacks conciseness and could be shortened or reorganized for easier scanning. The front-loaded purpose helps, but the bulk of the text is dense.

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 complexity (5 parameters, 0% schema coverage, output schema exists), the description covers all necessary aspects: parameter documentation, behavior, limits, examples, and error handling. It even references list_misconfigurations for additional field details, showing completeness. The output schema reduces the need for return value documentation.

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?

The input schema has 0% coverage, so the description is the sole source of parameter documentation. It exhaustively explains the 'filters' parameter with valid field names, filter types, required keys, examples, and special cases. It also details 'first', 'after', 'view_type', and 'fields' with usage guidance and examples. This adds immense value beyond the empty 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 begins with 'Search misconfigurations using advanced filters and criteria,' which clearly states the action and resource. It distinguishes this tool from sibling tools like list_misconfigurations (which likely lists without filters) and other search tools by emphasizing advanced filtering capabilities. The purpose is specific and immediately understandable.

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 guidance on when to use each filter type, including special cases (e.g., secretValidity only supports boolean_in, product/vendor only support STRING filters). It includes correct and incorrect examples, performance notes for paging, and a workflow for datetime handling. This thoroughly helps the agent select and use the tool correctly.

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