---
title: "Connect Orca Security to AI Agents: Automate Scans and Remediation"
slug: connect-orca-security-to-ai-agents-automate-scans-and-remediation
date: 2026-06-09
author: Uday Gajavalli
categories: ["AI & Agents"]
excerpt: "Learn how to connect Orca Security to AI agents using Truto's /tools endpoint. Fetch tools, bind them to LLMs, and automate vulnerability remediation."
tldr: "Connecting Orca Security to AI agents requires strict schema enforcement and rate limit handling. This guide shows you how to use Truto's toolsets to automate alert triage, asset scanning, and vulnerability remediation across your cloud environment."
canonical: https://truto.one/blog/connect-orca-security-to-ai-agents-automate-scans-and-remediation/
---

# Connect Orca Security to AI Agents: Automate Scans and Remediation


You want to connect Orca Security to an AI agent so your system can autonomously query cloud assets, triage vulnerabilities, analyze attack paths, and trigger remediation scans. Here is exactly how to do it using Truto's `/tools` endpoint and SDK, bypassing the need to build and maintain a custom security connector from scratch.

The cybersecurity industry is rapidly shifting from static dashboards to agentic AI - autonomous systems that operate alongside your Security Operations Center (SOC) to investigate alerts and execute multi-step remediation workflows across your infrastructure. If your team uses ChatGPT, check out our guide on [connecting Orca Security to ChatGPT](https://truto.one/connect-orca-security-to-chatgpt-query-cloud-assets-and-alerts/), or if you are building on Anthropic's models, read our guide to [connecting Orca Security to Claude](https://truto.one/connect-orca-security-to-claude-analyze-cves-and-security-risks/). For developers building custom autonomous workflows, you need a programmatic way to fetch these tools and bind them directly to your agent framework.

Giving a Large Language Model (LLM) read and write access to a complex Cloud Security Posture Management (CSPM) platform like Orca Security is an engineering nightmare. You either spend months building, hosting, and maintaining a custom connector (as detailed in our [guide to building MCP servers](https://truto.one/the-hands-on-guide-to-building-mcp-servers-for-ai-agents-2026/)), or you use a managed infrastructure layer that handles the boilerplate for you.

This guide breaks down exactly how to fetch AI-ready tools for Orca Security, bind them natively to an LLM using LangChain (or any framework like LangGraph, CrewAI, or Vercel AI SDK), and execute complex security workflows. We will use the architectural approach described in our guide on [architecting AI agents and the SaaS integration bottleneck](https://truto.one/architecting-ai-agents-langgraph-langchain-and-the-saas-integration-bottleneck/).

## The Engineering Reality of the Orca Security API

Building AI agents is easy. Connecting them to external SaaS APIs in production is difficult. Giving an LLM access to external data sounds simple in a prototype. You write a basic Node.js function that makes a `fetch` request and wrap it in an `@tool` decorator. In reality, this approach collapses under the weight of enterprise API schemas.

Orca Security's API introduces several specific integration challenges that break standard CRUD assumptions:

### The DSL Query Barrier
Orca Security relies heavily on a custom Domain Specific Language (DSL) for querying its massive datasets. Endpoints like the inventory query or alert query do not accept simple URL parameters. They expect complex JSON payloads detailing logical operators, nested filters, and specific asset types. Teaching an LLM to reliably generate this DSL from natural language requires strict, comprehensive JSON schemas. If you do not provide the exact field structures, the LLM will hallucinate filter properties, and the API will reject the request with a 400 Bad Request.

### Disconnected Alert and Remediation Lifecycles
The Orca API does not serve up all necessary context in one flat JSON object. When a new CVE is detected, you list the alerts. However, to get the real-time status and verification of that alert, you must hit a separate state endpoint. To actually fix the issue, you need to query for the remediation template ID relevant to that specific alert type. This fragmented data model requires the agent to execute a multi-step graph - querying alerts, checking state, and mapping remediation actions - just to process a single vulnerability.

### Rate Limits and The 429 Problem
Security APIs are frequently subjected to burst traffic during incident response or mass vulnerability scanning. Orca enforces strict rate limits to protect its infrastructure. When your agent gets stuck in a loop trying to summarize 500 unpatched EC2 instances, it will hit an `HTTP 429 Too Many Requests` error.

**Factual note on how Truto handles this:** Truto normalizes upstream rate limit info into standardized headers (`ratelimit-limit`, `ratelimit-remaining`, `ratelimit-reset`) per the IETF specification. However, Truto **does not** retry, throttle, or apply backoff on rate limit errors. When Orca Security returns a 429, Truto passes that error directly to the caller. Your agent's execution loop is entirely responsible for reading the `ratelimit-reset` header, applying exponential backoff, and retrying the tool call.

## Fetching Orca Security Tools via Truto

Every integration on Truto is represented as a comprehensive JSON object mapping the underlying product's API behavior. Truto maps these to `Resources` and `Methods` - the first level of abstraction we call Proxy APIs.

Truto provides all these resources as AI-ready tools via the `/integrated-account/:id/tools` endpoint. Instead of hand-coding schemas for Orca's DSL, you fetch the definitions programmatically, leveraging [auto-generated tools](https://truto.one/auto-generated-mcp-tools-for-ai-agents-a-2026-architecture-guide/) to handle complex API parameters.

```typescript
import { TrutoToolManager } from 'truto-langchainjs-toolset';

// Initialize the tool manager for a specific connected Orca Security account
const toolManager = new TrutoToolManager({
  trutoApiKey: process.env.TRUTO_API_KEY,
  integratedAccountId: 'orca-sec-account-123'
});

// Fetch all available proxy tools
const tools = await toolManager.getTools();
```

These tools are natively compatible with LangChain's `.bindTools()` method and dynamically update if the underlying API schema changes.

## Orca Security Hero Tools

Exposing an LLM to the entire surface area of a CSPM platform is inefficient. You need to provide the agent with high-leverage operations. Here are the core "hero tools" your security agent needs to execute automated scans and remediation.

### list_all_orca_security_alerts_vulns
Fetches a specific list of vulnerability alerts. This tool is essential for threat hunting. It returns details like CVE findings, CVSS scores, affected assets, fix availability, and related cloud account data.

*Usage notes:* When using this tool, the agent should look specifically at the `fix_status` or `fix_availability` attributes. An agent should prioritize processing vulnerabilities that have a known patch available.

> "Retrieve all critical vulnerability alerts for our production AWS environment that currently have a fix available."

### orca_security_alerts_state
Retrieves the real-time, current state of a specific alert identified by its `alert_id`. The response includes verification status, risk level, Orca score, and current status.

*Usage notes:* Because security postures change rapidly between scans, an agent must always call this tool to verify an alert is still active before attempting to run a remediation workflow.

> "Check the current verification status and risk level for alert ID 'vuln-98765'. Let me know if it has already been closed."

### list_all_orca_security_query_inventory
Retrieves filtered inventory data from Orca Security using a DSL-based query. This is the core engine for finding exposed assets, unpatched servers, or misconfigured IAM roles.

*Usage notes:* This tool relies on Truto's rich schema definition to guide the LLM in constructing valid DSL. The agent can apply complex filters across asset types, cloud providers, and tag metadata.

> "Run an inventory query to find all AWS EC2 instances running Amazon Linux 2 that are exposed to the public internet."

### list_all_orca_security_alerts_remediation_actions
Gets the remediation action and template IDs relevant to a specific alert type. This bridges the gap between finding a problem and knowing how to fix it.

*Usage notes:* The agent must pass the correct alert type (e.g., 'vulnerability' or 'malware'). The response dictates which external service actions or playbooks can be triggered to patch the asset.

> "Get the required remediation template ID needed to fix a vulnerability alert on an Azure SQL database."

### create_a_orca_security_scan
Creates and launches a new on-demand security scan for a specific asset. 

*Usage notes:* After a DevOps engineer applies a patch (or after the agent triggers an automated fix), this tool must be used to rescan the asset and verify the vulnerability is actually gone.

> "Trigger an immediate security scan on the asset ID 'i-1234567890abcdef0' to verify the Log4j patch was applied successfully."

### list_all_orca_security_attack_paths_crown_jewels
Retrieves a list of "Crown Jewel" assets identified by Orca Security. These are the most critical databases, key vaults, and servers in your environment.

*Usage notes:* Use this tool to give the agent context on blast radius. If an alert is part of an attack path leading to a Crown Jewel, the agent knows to escalate it immediately to human responders.

> "List our current Crown Jewel assets in the GCP production organization so I can cross-reference them against recent malware alerts."

To view the complete schema definitions and the dozens of other tools available for querying CVEs, analyzing Sonar findings, and tracking user audit logs, visit the [Orca Security integration page](https://truto.one/integrations/detail/orcasecurity).

## Workflows in Action

When you bind these tools to a reasoning engine like GPT-4o or Claude 3.5 Sonnet, you graduate from simple chatbots to autonomous security analysts. Here is how specific personas use these tools in practice.

### Scenario 1: DevOps Automated Triage & Verification
**The Problem:** A DevOps engineer receives a page about a critical vulnerability. They need to know if the asset is critical, what the fix is, and they want the system to rescan the asset the moment they apply a patch.

> "I just received a PagerDuty alert for CVE-2024-XXXX on alert ID 'alrt-4455'. Check its current state. If it is still active, get the remediation steps. I am applying the patch now - once I say 'done', trigger a new scan on that asset to verify."

**Execution Steps:**
1.  **`orca_security_alerts_state`**: The agent checks the current status of 'alrt-4455' to ensure it is active and verifies the risk level.
2.  **`list_all_orca_security_alerts_remediation_actions`**: The agent requests the specific remediation template for this vulnerability type to provide the engineer with instructions.
3.  *(Wait for human input: 'done')*
4.  **`create_a_orca_security_scan`**: The agent triggers a targeted scan on the specific asset ID attached to the alert to verify the fix.

**The Result:** The agent acts as an interactive runbook. It verifies the alert, provides the exact fix, and autonomously handles the follow-up verification scan, saving the engineer from logging into the Orca dashboard.

### Scenario 2: Security Analyst Blast Radius Assessment
**The Problem:** A security analyst needs to assess the risk of a new zero-day vulnerability affecting a specific software package across the entire cloud fleet, particularly prioritizing critical databases.

> "Query our inventory for any assets running the vulnerable 'libwebp' package. Then, check if any of those exposed assets are classified as Crown Jewels. Output a summary of the critical risks."

**Execution Steps:**
1.  **`list_all_orca_security_query_inventory`**: The agent constructs a DSL query searching the software package inventory for 'libwebp'.
2.  **`list_all_orca_security_attack_paths_crown_jewels`**: The agent fetches the list of critical assets.
3.  *(Internal Logic)*: The agent cross-references the list of vulnerable assets against the Crown Jewels list.

**The Result:** The analyst receives an immediate, prioritized list of only the most critical servers requiring emergency patching, heavily reducing alert fatigue and focusing response efforts.

## Building Multi-Step Workflows

To build these autonomous workflows, your execution framework must handle tool calling, memory, and error handling. Because security APIs are prone to rate limiting when querying large asset bases, your code must explicitly handle HTTP 429s.

Here is how you architect a resilient agent loop using LangChain.js and Truto's proxy tools.

```mermaid
graph TD
    A[User Prompt] --> B[Agent Context]
    B --> C{LLM Decision}
    C -->|Needs Data| D[Truto Tool Call]
    D --> E[Orca Security API]
    E -->|HTTP 429| F[Read ratelimit-reset Header]
    F --> G[Exponential Backoff]
    G --> D
    E -->|HTTP 200| H[Return Data to Context]
    H --> C
    C -->|Final Answer| I[Output to User]
```

### The Resilient Agent Loop

In this example, we fetch the tools, bind them to an OpenAI model, and implement an execution wrapper that intercepts Truto's standardized rate limit headers to handle retries gracefully.

```typescript
import { ChatOpenAI } from '@langchain/openai';
import { TrutoToolManager } from 'truto-langchainjs-toolset';

async function runSecurityAgent(prompt: string) {
  // 1. Initialize Truto Tool Manager
  const toolManager = new TrutoToolManager({
    trutoApiKey: process.env.TRUTO_API_KEY,
    integratedAccountId: process.env.ORCA_ACCOUNT_ID
  });

  // 2. Fetch Orca Security Proxy Tools
  const tools = await toolManager.getTools();
  
  // 3. Initialize LLM and bind tools
  const model = new ChatOpenAI({ modelName: 'gpt-4o' });
  const modelWithTools = model.bindTools(tools);

  const messages = [{ role: 'user', content: prompt }];
  
  // 4. Execution Loop with Rate Limit Handling
  while (true) {
    const response = await modelWithTools.invoke(messages);
    messages.push(response);

    if (!response.tool_calls || response.tool_calls.length === 0) {
      // No more tools to call, return final answer
      return response.content;
    }

    // Execute each tool call requested by the LLM
    for (const toolCall of response.tool_calls) {
      const selectedTool = tools.find(t => t.name === toolCall.name);
      
      let success = false;
      let attempts = 0;
      let toolResult;

      while (!success && attempts < 3) {
        try {
          attempts++;
          toolResult = await selectedTool.invoke(toolCall.args);
          success = true;
        } catch (error: any) {
          // Fact check: Truto passes 429s directly to the caller.
          // We must handle the retry logic based on Truto's standardized headers.
          if (error.response && error.response.status === 429) {
            const resetTime = error.response.headers.get('ratelimit-reset');
            const waitMs = resetTime ? (parseInt(resetTime) * 1000) - Date.now() : 2000 * attempts;
            
            console.warn(`Rate limit hit on ${toolCall.name}. Waiting ${waitMs}ms...`);
            await new Promise(resolve => setTimeout(resolve, Math.max(waitMs, 1000)));
          } else {
            // Non-retriable error
            toolResult = `Error executing tool: ${error.message}`;
            break;
          }
        }
      }

      // Pass the result back to the LLM's context window
      messages.push({
        role: 'tool',
        tool_call_id: toolCall.id,
        content: typeof toolResult === 'string' ? toolResult : JSON.stringify(toolResult)
      });
    }
  }
}

// Example Invocation
const output = await runSecurityAgent(
  "Run an inventory query for active EC2 instances. If any are critical crown jewels, trigger a security scan on them."
);
console.log(output);
```

This architecture completely abstracts the underlying API complexity. You do not need to write URL builders, manage authentication tokens, or hardcode Orca's DSL schemas. Truto provides the structured definitions, passes through the exact execution state, and allows your agent framework to do what it does best - reason about security data.

## The Strategic Advantage of Auto-Generated Tools

Building an AI agent that can securely operate an enterprise CSPM platform is a significant technical challenge. If you tightly couple your agent's core reasoning logic to hardcoded SaaS API schemas, your system will inevitably break the moment the vendor introduces a new endpoint or modifies a vulnerability data model.

By leveraging Truto's proxy architecture, you delegate schema maintenance, authentication mapping, and parameter normalization to an infrastructure layer explicitly built for integration. Your engineering team can focus on refining agent prompts, optimizing RAG pipelines, and building better security workflows, rather than reading API documentation to fix broken JSON parsers.

:::cta{buttonText="Talk to us" buttonUrl="https://cal.com/truto/partner-with-truto"} 
Want to equip your AI agents with reliable SaaS tools without maintaining the integration code? Schedule a technical deep dive with our engineering team to see how Truto handles schema generation, auth, and pagination.
:::