TealSecrets

TealSecrets is a governance module that scans content for leaked secrets, credentials, and sensitive tokens. It detects over 500 patterns across 9 categories with confidence scoring.

Overview

TealSecrets runs as part of the TealEngine v1.2 module pipeline. When the policy includes a secrets key, the engine dispatches to TealSecrets in parallel with other active modules.

500+ Patterns

Regex and entropy-based detection across all major providers

9 Categories

API keys, tokens, credentials, certificates, and more

Confidence Scoring

Each finding includes a 0–1 confidence score

Quick Start

import { TealEngineV12, TealSecrets } from 'tealtiger';

const engine = new TealEngineV12({
  policy: {
    secrets: {
      enabled: true,
      confidence_threshold: 0.8
    }
  },
  modules: [new TealSecrets()]
});

const decision = await engine.evaluateV12(
  { content: 'My API key is sk-proj-abc123def456...' },
  { correlation_id: 'req-001' }
);

console.log(decision.action);    // 'DENY'
console.log(decision.findings);  // [{ type: 'openai_api_key', ... }]

Detection Categories

TealSecrets organizes patterns into 9 categories:

Category	Examples	Pattern Count
API Keys	OpenAI, Anthropic, Google, AWS, Azure	80+
Tokens	OAuth, JWT, Bearer, session tokens	60+
Credentials	Username/password pairs, connection strings	50+
Certificates	PEM, PKCS, X.509 private keys	30+
Cloud Secrets	AWS Secret Access Key, GCP service accounts	70+
Database	Connection strings, Redis URLs, MongoDB URIs	40+
Messaging	Slack webhooks, Twilio, SendGrid	35+
Payment	Stripe, PayPal, Square API keys	25+
Infrastructure	SSH keys, Terraform tokens, Docker registry	40+

SecretFinding Type

Each detected secret produces a SecretFinding:

interface SecretFinding {
  /** Unique finding identifier */
  finding_id: string;

  /** Detection pattern type (e.g., 'openai_api_key') */
  type: string;

  /** Category (e.g., 'api_keys', 'tokens', 'credentials') */
  category: string;

  /** Confidence score (0.0 – 1.0) */
  confidence: number;

  /** Severity level: 'critical' | 'high' | 'medium' | 'low' */
  severity: string;

  /** Content fingerprint (hash, not the actual secret) */
  fingerprint: string;
}

TealSecrets never includes the actual secret value in findings. The fingerprint field contains a hash for deduplication and tracking.

Policy Configuration

Configure TealSecrets through the secrets key in your policy:

const engine = new TealEngineV12({
  policy: {
    secrets: {
      // Enable secret detection
      enabled: true,

      // Minimum confidence to trigger (0.0 – 1.0)
      confidence_threshold: 0.8,

      // Categories to scan (omit for all)
      categories: ['api_keys', 'tokens', 'credentials', 'certificates'],

      // Action override (default: DENY for critical/high)
      actions: {
        critical: 'DENY',
        high: 'DENY',
        medium: 'REDACT',
        low: 'ALLOW'
      }
    }
  },
  modules: [new TealSecrets()]
});

Reason Codes

TealSecrets emits these TEEC reason codes:

Code	Severity	Default Action	When
`SECRET_DETECTED`	critical	DENY	A high-confidence secret is found
`CREDENTIAL_LEAKAGE`	critical	DENY	Credential pair detected (user + password)
`CREDENTIAL_TTL_EXCEEDED`	high	DENY	Expired or long-lived credential
`CREDENTIAL_ROTATION_REQUIRED`	medium	REQUIRE_APPROVAL	Credential needs rotation
`SECRET_SCAN_SKIPPED_PERF_BUDGET`	medium	DEGRADE	Scan skipped due to content size limits

Event Types

Event Type	Description
`secret.detection`	Secret detection scan completed
`credential.ttl`	Credential TTL enforcement check

Examples

Scanning Content

const decision = await engine.evaluateV12(
  {
    content: `
      Here are the deployment credentials:
      AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
      AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
    `
  },
  { correlation_id: 'scan-001' }
);

// decision.action === 'DENY'
// decision.findings === [
//   { type: 'aws_access_key', category: 'cloud_secrets', confidence: 0.95, ... },
//   { type: 'aws_secret_key', category: 'cloud_secrets', confidence: 0.98, ... }
// ]
// decision.reason_codes === ['SECRET_DETECTED', 'CREDENTIAL_LEAKAGE']

Using the Sidecar

curl -X POST http://localhost:8080/scan \
  -H "Content-Type: application/json" \
  -d '{
    "content": "My token is ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "correlation_id": "scan-002"
  }'

{
  "correlation_id": "scan-002",
  "findings": [
    {
      "finding_id": "f-abc123",
      "type": "github_pat",
      "category": "tokens",
      "confidence": 0.97,
      "severity": "critical",
      "fingerprint": "sha256:a1b2c3..."
    }
  ],
  "action": "DENY",
  "risk_score": 100
}

Python

from tealtiger import TealEngineV12, TealSecrets

engine = TealEngineV12(
    policy={"secrets": {"enabled": True, "confidence_threshold": 0.8}},
    modules=[TealSecrets()]
)

decision = await engine.evaluate_v12(
    request={"content": "API key: sk-proj-abc123..."},
    ctx={"correlation_id": "scan-003"}
)

for finding in decision.findings:
    print(f"{finding.type}: {finding.confidence}")

Getting Started

Core Concepts

Governance Domains

Policy Authoring

Architecture

Integrations

Deployment

API Reference

Cookbook

Compliance & GRC

Guides

Reference

Versions

Playground

Dashboard

Blog

Overview

500+ Patterns

9 Categories

Confidence Scoring

Quick Start

Detection Categories

SecretFinding Type

Policy Configuration

Reason Codes

Event Types

Examples

Scanning Content

Using the Sidecar

Python

​Overview

500+ Patterns

9 Categories

Confidence Scoring

​Quick Start

​Detection Categories

​SecretFinding Type

​Policy Configuration

​Reason Codes

​Event Types

​Examples

​Scanning Content

​Using the Sidecar

​Python

​Related Documentation

Overview

Quick Start

Detection Categories

SecretFinding Type

Policy Configuration

Reason Codes

Event Types

Examples

Scanning Content

Using the Sidecar

Python

Related Documentation