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, or if you are building on Anthropic's models, read our guide on connecting SecurityScorecard to Claude. For developers building custom autonomous workflows, you need a programmatic way to fetch these tools and bind them to your agent framework.

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.

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

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

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 using TypeScript, LangChain, and Truto's SDK.

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.

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.