---
title: "Connect SecurityScorecard to AI Agents: Automate Issues & Reporting"
slug: connect-securityscorecard-to-ai-agents-automate-issues-reporting
date: 2026-09-07
author: Nachi Raman
categories: ["AI & Agents"]
excerpt: "Learn how to connect SecurityScorecard to AI Agents using Truto's SDK. Build autonomous workflows for risk auditing, issue tracking, and automated reporting."
tldr: "Connect SecurityScorecard to AI Agents via Truto's /tools endpoint. This guide covers bypassing API quirks, handling rate limits, and building autonomous risk workflows."
canonical: https://truto.one/blog/connect-securityscorecard-to-ai-agents-automate-issues-reporting/
---

# Connect SecurityScorecard to AI Agents: Automate Issues & Reporting


You want to connect SecurityScorecard to AI Agents so your system can autonomously monitor vendor risk, investigate score drops, track patching cadence, and trigger compliance workflows. Here is exactly how to do it using Truto's `/tools` endpoint and SDK, bypassing the need to maintain a custom, deeply nested cybersecurity integration layer from scratch.

If your team uses ChatGPT, check out our guide on [connecting SecurityScorecard to ChatGPT](https://truto.one/connect-securityscorecard-to-chatgpt-track-risk-portfolios/), or if you are building on Anthropic's models, read our guide on [connecting SecurityScorecard to Claude](https://truto.one/connect-securityscorecard-to-claude-audit-trends-compliance/). For developers building custom autonomous workflows, you need a programmatic way to fetch these tools and bind them to your [agent framework](https://truto.one/architecting-ai-agents-langgraph-langchain-and-the-saas-integration-bottleneck/).

Giving a Large Language Model (LLM) read and write access to your threat intelligence and vendor risk platform is an engineering challenge. Standard REST assumptions break down when dealing with highly fragmented issue categories, asynchronous reporting pipelines, and complex portfolio hierarchies. If you hardcode these interactions into your agent, you will spend your sprints writing defensive integration code instead of improving your model's reasoning.

This guide breaks down exactly how to fetch AI-ready tools for SecurityScorecard, bind them natively to an LLM using frameworks like LangChain, LangGraph, CrewAI, or the Vercel AI SDK, and execute complex security operations workflows. For a broader look at this design pattern, read our guide on [Architecting AI Agents: LangGraph, LangChain, and the SaaS Saas Integration Bottleneck](https://truto.one/architecting-ai-agents-langgraph-langchain-and-the-saas-integration-bottleneck/).

## The Engineering Reality of the SecurityScorecard API

Giving an LLM access to external data sounds simple in a prototype. You write a Node.js function that makes a fetch request and wrap it in an `@tool` decorator. In production against complex cybersecurity systems, this approach collapses.

SecurityScorecard's API introduces several specific integration challenges. If your agent is responsible for navigating these raw endpoints, it will [hallucinate payloads](https://truto.one/what-is-llm-function-calling-for-integrations-2026-guide/) and crash your workflows.

### The Fragmented Issue Type Architecture

Most REST APIs group similar entities under a single endpoint with query filters - for example, `GET /issues?type=patching_cadence`. SecurityScorecard does not do this. Because of the vast complexity of cybersecurity findings, SecurityScorecard exposes completely separate, discrete endpoints for almost every single issue type.

If an agent wants to check for malware, it needs to hit the malware endpoint. If it wants to check for expired TLS certificates, it needs to hit the TLS certificate endpoint. There are dozens of highly specific issue endpoints (e.g., `list_all_security_scorecard_issues_patching_cadence_highs`, `list_all_security_scorecard_issues_tlscert_expireds`). Exposing the raw API means teaching the LLM an encyclopedic routing table of threat categories. By passing these through a unified tool layer, the agent simply selects from a strictly defined schema of [available functions](https://truto.one/what-is-llm-function-calling-for-integrations-2026-guide/).

### The Portfolio Prerequisite Trap

SecurityScorecard enforces strict relationship models for data access. You cannot simply pull deep factor-level data or issue-level context for any arbitrary domain on the internet. To access detailed metrics (like `list_all_security_scorecard_companie_factors`), the target company must first be added to one of your active Portfolios.

If an LLM attempts to query factor data for a raw domain that is not in a portfolio, the API will reject the request. The agent must first query the portfolio, check if the company exists, optionally add it using a bulk update endpoint, and then query the factor data. This requires complex, multi-step [agent reasoning](https://truto.one/architecting-ai-agents-langgraph-langchain-and-the-saas-integration-bottleneck/) that will fail if the underlying tool schemas are ambiguous.

### Asynchronous Reporting Workflows

Generating compliance or detailed assessment reports in SecurityScorecard is an asynchronous process. When you request a detailed report, the API does not return a PDF or CSV in the HTTP response. It returns a `status` (e.g., "processing") and a `report_url`.

The agent must understand the concept of polling. It must store the `report_url`, yield execution, and check back later until the status changes to "completed" before attempting to download the actual asset. If you expose the raw API, the LLM will inevitably try to parse the "processing" JSON response as the final report data, causing a critical workflow failure.

## Why a Unified Tool Layer Matters for Agent Safety

Direct API tools - mapping one tool per raw SecurityScorecard endpoint manually - push provider quirks directly into the LLM's context window. Every quirk is a hallucination waiting to happen.

A unified tool layer collapses these endpoints behind a strict, predictable schema. That gives you concrete safety wins:

1. **Deterministic input validation.** Every tool has a strict JSON schema. Invalid arguments (like sending a domain string instead of a `portfolio_id`) are rejected by the tool boundary before they ever hit the SecurityScorecard API. Broken tool calls fail fast instead of causing cascading logic errors.
2. **Standardized error handling.** SecurityScorecard has strict rate limits. When integrating programmatically, handling these limits is paramount. Truto does not retry, throttle, or apply backoff on rate limit errors. Instead, when SecurityScorecard returns an HTTP 429, Truto passes that error to the caller, normalizing the upstream rate limit info into standardized IETF headers (`ratelimit-limit`, `ratelimit-remaining`, `ratelimit-reset`). This predictable error contract allows you to build durable backoff logic in your agent's execution loop.
3. **Smaller attack surface.** The LLM only ever chooses from stable function names with typed parameters. It never invents endpoint paths or malformed JSON payloads.

## 5 Hero Tools for SecurityScorecard AI Agents

Rather than forcing your agent to memorize the entire SecurityScorecard REST documentation, you provide it with discrete, highly leveraged tools. Here are five of the most powerful tools to expose to your AI agents for security operations.

### 1. List Portfolio Companies

**Tool Name:** `list_all_security_scorecard_portfolio_companies`

This tool allows the agent to retrieve all companies (scorecards) currently tracked within a specific portfolio. It returns critical baseline data including the domain, overall grade, industry, and tracking status. This is almost always the first step in a portfolio audit workflow.

> "Audit the 'Critical Vendors' portfolio and list any companies that currently have a grade of 'C' or lower."

### 2. Retrieve Factor Scores

**Tool Name:** `list_all_security_scorecard_companie_factors`

SecurityScorecard grades are broken down into specific factors (Network Security, Application Security, Patching Cadence, etc.). This tool fetches the individual factor scores and issue counts for a specific company scorecard, allowing the agent to pinpoint exactly why a company's overall grade is dropping.

> "Get the detailed factor scores for vendor-domain.com and tell me which specific category is dragging their grade down."

### 3. Query Scorecard Event History

**Tool Name:** `list_all_security_scorecard_history_events`

This tool acts as a news feed for a scorecard, returning an event log of score changes, newly detected issues, resolved issues, and reported breaches over the last 12 months. Agents use this to build a timeline of a vendor's security posture and identify exactly when a vulnerability was introduced.

> "Pull the event history for our key supplier for the last 30 days and summarize any new vulnerabilities that were detected."

### 4. Fetch Patching Cadence Issues

**Tool Name:** `list_all_security_scorecard_issues_patching_cadence_highs`

Because SecurityScorecard segments issue types into dedicated endpoints, exposing this specific tool allows an agent to instantly retrieve high-severity patching cadence issues for a given `effective_date`. This is crucial for SLA monitoring and identifying vendors who fail to apply critical security patches on time.

> "Check the high-severity patching cadence issues for partner-domain.com as of yesterday's effective date. Are there any outstanding CVEs?"

### 5. Generate Detailed Reports

**Tool Name:** `create_a_security_scorecard_reports_detailed`

This tool initiates the asynchronous generation of a detailed SecurityScorecard report. The agent receives a `report_url` and a `status` in response. The agent can then use this URL in a subsequent step to poll for the completed file and extract the data for external sharing or compliance logging.

> "Generate a detailed security report for the newly onboarded vendor and notify me once the processing is complete."

To view the complete schema definitions and the full list of available tools, visit the [SecurityScorecard integration page](https://truto.one/integrations/detail/securityscorecard).

## Building Multi-Step Workflows

To build a reliable agent, you must connect the LLM to Truto's `/tools` endpoint, bind the returned schemas, and execute an agent loop. This approach is completely framework-agnostic. Whether you use LangChain, LangGraph, CrewAI, or the Vercel AI SDK, the core concept remains the same.

Because Truto normalizes rate limits into standardized headers (`ratelimit-limit`, `ratelimit-remaining`, `ratelimit-reset`) and passes HTTP 429s directly to the caller without automatic retries, your agent execution loop must handle these errors durably. 

Here is how you architect a durable [tool-calling loop](https://truto.one/what-is-llm-function-calling-for-integrations-2026-guide/) using TypeScript, LangChain, and Truto's SDK.

```typescript
import { ChatOpenAI } from "@langchain/openai";
import { TrutoToolManager } from "truto-langchainjs-toolset";
import { HumanMessage, SystemMessage } from "@langchain/core/messages";

// 1. Initialize the Truto SDK and fetch SecurityScorecard tools
// The integratedAccountId represents the specific SecurityScorecard instance
const truto = new TrutoToolManager({
  apiKey: process.env.TRUTO_API_KEY!,
});

async function runSecurityAgent(prompt: string, accountId: string) {
  // Fetch all proxy APIs available for this SecurityScorecard account
  const tools = await truto.getTools(accountId);

  // 2. Bind the fetched tools to the LLM
  const llm = new ChatOpenAI({
    modelName: "gpt-4o",
    temperature: 0,
  }).bindTools(tools);

  const messages = [
    new SystemMessage(
      "You are a Security Operations Center (SOC) analyst. You investigate vendor risk data and summarize security findings. Always rely on the provided tools to fetch actual data."
    ),
    new HumanMessage(prompt),
  ];

  // 3. Execute the agent loop with explicit rate limit handling
  while (true) {
    const response = await llm.invoke(messages);
    messages.push(response);

    if (!response.tool_calls || response.tool_calls.length === 0) {
      // The agent has finished reasoning and provided a final answer
      return response.content;
    }

    // 4. Execute requested tool calls
    for (const toolCall of response.tool_calls) {
      const tool = tools.find((t) => t.name === toolCall.name);
      if (tool) {
        try {
          const result = await tool.invoke(toolCall.args);
          messages.push({
            role: "tool",
            name: toolCall.name,
            tool_call_id: toolCall.id,
            content: JSON.stringify(result),
          });
        } catch (error: any) {
          // Explicitly handle HTTP 429 Rate Limits passed through by Truto
          if (error.status === 429) {
            const resetTime = error.headers['ratelimit-reset'];
            const waitTime = resetTime ? (parseInt(resetTime) * 1000) - Date.now() : 5000;
            
            console.warn(`Rate limit hit. Waiting ${waitTime}ms before retrying...`);
            await new Promise(resolve => setTimeout(resolve, waitTime));
            
            // Inform the LLM that a rate limit occurred, allowing it to decide 
            // to retry or take an alternative action.
            messages.push({
              role: "tool",
              name: toolCall.name,
              tool_call_id: toolCall.id,
              content: JSON.stringify({ 
                error: "Rate limit exceeded. System backed off and will retry next turn.",
                retry_recommended: true 
              }),
            });
          } else {
            // Handle standard API errors
            messages.push({
              role: "tool",
              name: toolCall.name,
              tool_call_id: toolCall.id,
              content: JSON.stringify({ error: error.message }),
            });
          }
        }
      }
    }
  }
}

// Execute a real-world workflow
runSecurityAgent(
  "Find the portfolio ID for 'Tier 1 Vendors', then list all companies in it. Identify any company with an overall grade below 'B'.",
  "your-integrated-account-id"
).then(console.log);
```

## Workflows in Action

When you give an LLM safe, deterministic access to SecurityScorecard via Truto, you unlock autonomous workflows that previously required manual SOC intervention or custom Python scripting. Here are three concrete examples of how different personas utilize this architecture.

### 1. The CISO / Risk Manager: Weekly Portfolio Risk Summary

Risk managers need to understand macro trends across their third-party ecosystem without manually clicking through dashboards. They can instruct the agent to build a comprehensive risk summary.

> "Audit the 'Critical SaaS Providers' portfolio. List all companies, retrieve their factor scores, and generate a summary highlighting any vendor that dropped below a 'B' in Application Security or Patching Cadence over the last 7 days."

**Agent Execution Steps:**
1.  Calls `list_all_security_scorecard_portfolios` to resolve the string "Critical SaaS Providers" into a concrete `portfolio_id`.
2.  Calls `list_all_security_scorecard_portfolio_companies` using the `portfolio_id` to get the baseline list of domains and overall grades.
3.  Iterates through the domains and calls `list_all_security_scorecard_companie_factors` for each to extract the Application Security and Patching Cadence factor scores.
4.  Calls `list_all_security_scorecard_history_events` for any vendor showing a low score to pinpoint the exact date the grade dropped.

**Result:** The user receives a formatted markdown report identifying two vendors whose Application Security dropped due to newly discovered exposed web UI issues, complete with the date of the event.

### 2. The SOC Analyst: Investigating a Score Drop

When a critical vendor's score drops suddenly, SOC analysts must investigate the root cause immediately to determine if the enterprise is exposed to supply chain risk.

> "The overall score for supplier-domain.com just dropped to a 'C'. Pull their event history for the last 48 hours, identify the new issues, and pull the specific CVEs if it is a high-severity vulnerability host issue."

**Agent Execution Steps:**
1.  Calls `list_all_security_scorecard_history_events` for `supplier-domain.com` with a date filter for the last 48 hours.
2.  Parses the event log to discover that the score drop was caused by a `web_vuln_host_v3_high` event on a specific `effective_date`.
3.  Calls `list_all_security_scorecard_issues_web_vuln_host_v_3_highs` passing the `scorecard_identifier` and the exact `effective_date` discovered in the previous step.

**Result:** The LLM returns a concise alert: "Supplier-domain.com dropped to a 'C' on Tuesday because 3 new high-severity web vulnerabilities were detected. The exposed assets are associated with CVE-2023-XXXX. Recommend immediate outreach to their security team."

### 3. The TPRM Lead: Automating Vendor Onboarding

Third-Party Risk Management (TPRM) teams process hundreds of new vendors a quarter. Manual scorecard lookups slow down procurement.

> "We are onboarding a new vendor at newvendor.io. Add them to the 'Onboarding Evaluation' portfolio, fetch their current scorecard summary, and initiate a detailed assessment report for our records."

**Agent Execution Steps:**
1.  Calls `list_all_security_scorecard_portfolios` to get the ID for "Onboarding Evaluation".
2.  Calls `security_scorecard_portfolio_companies_bulk_update` to inject `newvendor.io` into the portfolio.
3.  Calls `list_all_security_scorecard_companies` to fetch the immediate high-level summary (score, grade, industry).
4.  Calls `create_a_security_scorecard_reports_detailed` to trigger the asynchronous report generation, logging the returned `report_url` for a chron job to download later.

**Result:** The vendor is seamlessly added to the tracking portfolio, the procurement team gets an immediate Slack summary of the vendor's grade, and the formal compliance report is queued for download - all from a single natural language prompt.

```mermaid
sequenceDiagram
  autonumber
  participant User as TPRM Lead
  participant Agent as AI Agent
  participant Truto as Truto Unified Tools
  participant Upstream as "Upstream API (SecurityScorecard)"

  User->>Agent: "Add newvendor.io to Onboarding portfolio and generate a report."
  Agent->>Truto: Call list_all_security_scorecard_portfolios
  Truto->>Upstream: GET /portfolios
  Upstream-->>Truto: Return portfolio IDs
  Truto-->>Agent: JSON Response
  
  Agent->>Truto: Call security_scorecard_portfolio_companies_bulk_update
  Truto->>Upstream: PUT /portfolios/{id}/companies
  Upstream-->>Truto: 200 OK
  Truto-->>Agent: JSON Response
  
  Agent->>Truto: Call create_a_security_scorecard_reports_detailed
  Truto->>Upstream: POST /reports/detailed
  Upstream-->>Truto: 202 Accepted (status: processing, report_url: https://...)
  Truto-->>Agent: JSON Response
  
  Agent-->>User: "Vendor added. Score is B. Detailed report is generating."
```

## Moving from Scripting to Autonomous Security

Integrating SecurityScorecard into your application using custom Python scripts or point-to-point hardcoding is a recipe for technical debt. You will spend your time managing pagination cursors, parsing nested portfolio requirements, mapping hundreds of discrete issue endpoints, and fighting strict rate limits.

By leveraging Truto's `/tools` endpoint, you abstract away the API mechanics. Your AI agents interact with a clean, deterministic JSON schema that allows them to reason about security data, execute multi-step audits, and handle rate limits natively. You stop writing boilerplate integration code and start building truly autonomous security operations workflows.

> Stop hardcoding security API integrations. Give your AI agents safe, deterministic access to SecurityScorecard and 100+ other SaaS APIs using Truto.
>
> [Talk to us](https://truto.one/book-a-demo/)