Trident Core Concepts: Projects, Agents, and Findings

Trident organizes your security data around a small set of concepts that appear consistently across the dashboard, SDKs, and APIs. Understanding them helps you navigate the platform, interpret what you see, and take action faster. This page defines each concept and explains how they relate to one another.

Projects

A project is your primary workspace in Trident. It holds your API keys (a public key and a secret key), your registered agents, all traces, all findings, and your firewall and signal configuration. Everything in Trident is scoped to a project — data from one project is never visible in another. You authenticate the SDK and the REST API using your project’s key pair as HTTP Basic credentials: base64(projectPublicKey:projectSecretKey). Manage your keys from the Settings page inside your project.

Agents

An agent is an AI system you register and instrument within a project. Each agent has a unique agentId that you assign when you call trident.init() or vouch_sdk.init(). Trident uses this identifier to group traces, scope firewall scans, target red-team campaigns, and surface per-agent findings and analytics. You don’t have to pre-register an agent before instrumenting it — Trident creates an agent record automatically the first time it receives a trace carrying that agentId. Agents appear in the Agent Inventory view, where you can see their connected status, trace volume, and current finding counts at a glance.

Traces

A trace is a full-fidelity recording of one execution of your agent. It captures every LLM call, tool invocation, MCP interaction, and human-approval event as a span — each span carries a timestamp, duration, the input sent to the model or tool, and the output received. Spans nest hierarchically so you can see the exact sequence of steps the agent took to complete a request. Trident collects traces over OpenTelemetry (OTLP). After you call init(), every supported LLM client in your process emits spans automatically. You view traces on the Traces page; click any row to open a waterfall view of its spans.

Findings

A finding is a security issue discovered by Trident. Findings can come from several sources:

Source	What triggers it
`REDTEAM`	An adversarial attack succeeded during a red-team run
`FIREWALL`	The runtime firewall blocked a prompt or output
`MONITOR`	The background monitor detected a suspicious pattern in production traces
`SAST`	Static analysis found a vulnerability in your agent’s source code
`CSPM` / `KSPM` / `IAC` / `RUNTIME`	A cloud security scanner reported a cloud-layer issue

Every finding is scored by OWASP category (mapped to the OWASP LLM Top-10 and Agentic Top-10) and AIVSS severity (LOW, MEDIUM, HIGH, CRITICAL). Operator-confirmed findings automatically promote ban rules to the runtime firewall within 5 minutes. You triage findings in the Findings inbox, where you can group them by incident, replay the original attack, and generate remediation PRs via Sentinel.

Red-Team Runs

A red-team run is an automated adversarial attack campaign that Trident fires against your agent. Each run draws from a library of 200+ attack vectors organized into named skills — prompt injection, jailbreaks, tool-call hijack, indirect injection, encoding bypass, MCP exploitation, resource exhaustion, and more — covering the full OWASP Agentic Top-10 attack surface. You launch a run from the Red Team page by selecting a preset intensity (Quick, Nightly, Deep, or Exhaustive) and a target agent endpoint. Trident streams live results back to a cockpit view as each attack attempt resolves. Successful attacks land directly in the Findings inbox with OWASP scores and attacker/response evidence attached.

Firewall

The Trident firewall is a runtime layer that scans every prompt your agent receives and every response it emits before they reach the model or the end user. It uses a two-stage decision process:

Tenant deny-bank — checks the prompt against your project’s ban rules (substrings and regexes auto-minted from confirmed findings). This stage is fast and runs first.
LLM Guard scanners — runs a configurable suite of ML-based detectors, including prompt injection, toxicity, PII detection, structural injection, and canary-leak detection.

If either stage flags a request, the firewall returns an is_valid: false verdict. You can invoke the firewall explicitly from the SDK, or route your agent traffic through the Trident Gateway for transparent scanning with no code changes.

TypeScript
Python

Use trident.scan() to check a prompt before passing it to your model:

import { trident } from "@vouch-ai/sdk";

const verdict = await trident.scan({ prompt: userMessage });
if (!verdict.ok || !verdict.is_valid) {
  return "I can't help with that.";
}

Use vouch_sdk.firewall_headers() to build the authentication headers required when calling the Trident firewall service directly:

import vouch_sdk

headers = vouch_sdk.firewall_headers(
    agent_id="my-agent",
)
# Pass `headers` to your HTTP client when calling the firewall endpoint.

Operator-confirmed findings feed new ban rules to the firewall within approximately 5 minutes via a polling mechanism — your firewall protection automatically tightens as your red-team campaigns discover new attack patterns.

PII Redaction

Both SDKs support edge PII redaction — stripping emails, card numbers, secrets, IP addresses, and other sensitive values from span attributes in your own process before any trace data leaves your infrastructure. Redaction is enabled by default. The Python SDK also exports two utility functions you can use to scrub arbitrary text and values in your own code:

import vouch_sdk

# Redact PII from a string — returns the cleaned string.
clean = vouch_sdk.redact_text("Contact support@example.com or call 555-0100")
# → "Contact [REDACTED] or call [REDACTED]"

# Redact a single value — returns None if the value matches a PII pattern.
safe = vouch_sdk.redact_value("4111111111111111")  # credit card
# → None

To disable automatic redaction or supply custom rules, pass the redact_pii option to init():

TypeScript
Python

trident.init({
  projectPk: process.env.TRIDENT_PROJECT_PUBLIC_KEY,
  projectSk: process.env.TRIDENT_PROJECT_SECRET_KEY,
  redactPII: false, // disable redaction entirely
});

vouch_sdk.init(
    project_pk=os.environ["TRIDENT_PROJECT_PUBLIC_KEY"],
    project_sk=os.environ["TRIDENT_PROJECT_SECRET_KEY"],
    redact_pii=False,  # disable redaction entirely
)

Security Graph

The Trident cloud security graph maps your cloud infrastructure — accounts, compute instances, Kubernetes pods, IAM roles, S3 buckets, databases, and other assets — as nodes connected by typed edges (for example, assumes_role, reaches, connects_to). It ingests data from OSS scanners (Prowler, Trivy, Kubescape, Falco, CloudQuery, and others) through the push-ingest API or triggered scans. The toxic-combo engine runs on top of this graph to find multi-hop attack paths. It applies deterministic rules and a generalized graph search to surface paths like: publicly accessible agent with a known prompt-injection finding → IAM role with broad S3 permissions → sensitive customer data bucket. These combos appear on the Cloud tab, scored by reachability and data sensitivity, with proposed Terraform/IAM remediations and draft guardrail policies available on demand. This is the differentiator: where a traditional cloud security tool finds cloud-only attack paths, Trident makes your AI agents first-class attack origins in the graph.

Signals

A signal is a no-code monitor that watches one metric over a rolling time window and opens a finding when it crosses a threshold you define. Available metrics include error rate, latency p95, LLM cost, trace volume, negative feedback rate, new findings count, and new high/critical findings count. You create signals from the Signals page using a form builder with a live plain-English preview. No query language is required. When a signal transitions from OK to FIRING, Trident opens a MONITOR-source finding in your Findings inbox, giving you automatic alerting without writing any alert logic yourself.

Sentinel

Sentinel is Trident’s built-in AI assistant, accessible from any project page. You can ask Sentinel questions about your findings, traces, agents, and cloud posture in plain English. It has read access to your project data through a set of tools — listing findings, querying traces, previewing toxic combos, and more. Beyond answering questions, Sentinel can take action: it can generate a remediation PR for a finding via the GitHub App integration (draft only — you always review and merge), stage firewall rules, replay attacks against your agent, and export a SOC 2-shaped compliance summary. Sentinel is your first stop when you need to understand what happened, why a finding fired, or what to do next.

​Projects

​Agents

​Traces

​Findings

​Red-Team Runs

​Firewall

​PII Redaction

​Security Graph

​Signals

​Sentinel

Projects

Agents

Traces

Findings

Red-Team Runs

Firewall

PII Redaction

Security Graph

Signals

Sentinel