Schedule icon
Webhook icon
Script icon
If icon
SlackIncomingWebhook icon
OutputValues icon

Verified Secret Leak Detection and Incident Triage with TruffleHog

Scan git repositories for leaked credentials with TruffleHog in Kestra. Verify live API tokens, eliminate false positives, and dispatch alerts to Slack.

Categories
Infrastructure

Accidental credential exposure in source code repositories is one of the most common causes of enterprise security breaches. Developers unintentionally push AWS access keys, GitHub personal access tokens, OpenAI API keys, database connection strings, or Slack webhooks into git commit histories. Conventional regex-based secret scanners generate overwhelming volumes of false positives (such as dummy test strings or example tokens), causing alert fatigue and leading real breaches to be overlooked.

This blueprint automates secret leak detection and incident response orchestrated by Kestra using TruffleHog. By automatically verifying whether detected credentials are live and active against third-party provider APIs, it eliminates false positives and immediately dispatches high-priority incident triage alerts to Slack with the compromised file, committer email, and remediation guidance.

How it works

  1. Trigger Ingestion: The flow executes on a scheduled nightly audit sweep (0 1 * * *) or in real time via an authenticated inbound Webhook triggered by GitHub or GitLab push events.
  2. TruffleHog Scanner Execution: An isolated python:3.11-slim container downloads and executes the latest TruffleHog binary against the target git repository and branch, scanning commit history to the specified depth.
  3. Live API Credential Verification: TruffleHog automatically verifies detected credentials against provider endpoints (e.g., calling AWS STS, GitHub API, Slack auth endpoints) to confirm whether the credential is active.
  4. Credential Masking: To protect your security posture, Kestra logs and Slack payloads mask raw secret keys, exposing only the service type (AWS, OpenAI), file path, commit hash, and committer metadata.
  5. Conditional Risk Gating: An io.kestra.plugin.core.flow.If condition checks verified_leaks_count > 0:
    • On Verified Active Leaks: Dispatches a high-priority Red Alert card to #security-incident-alerts detailing the compromised file and service.
    • On Clean Audits: Posts a confirmation digest confirming zero active secrets were found.
  6. Downstream SIEM Outputs: Exposes typed metrics via OutputValues for ingestion into Splunk, Datadog Security, or incident management tools.

What you get

  • Zero False-Positive Fatigue: Live verification guarantees that alerts represent genuinely active, exploitable credentials rather than dummy test mocks.
  • Rapid Mean Time to Remediation (MTTR): Alerts security teams within seconds of a commit landing, enabling key revocation before attackers can exploit it.
  • Audit History & Compliance: Provides automated, immutable execution logs demonstrating continuous secret scanning compliance for SOC2 and ISO 27001 audits.
  • Safe Credential Handling: Raw secrets are masked in execution outputs to prevent secondary exposure in notification logs.

Expected outputs

Downstream SIEM dashboards or security automation flows can reference the typed metrics produced by output_security_metrics:

Output Variable Description Expression Example
verified_leaks Count of confirmed active credentials found {{ outputs.output_security_metrics.values.verified_leaks }}
unverified_findings Count of regex matches where live verification could not be confirmed {{ outputs.output_security_metrics.values.unverified_findings }}
verdict Overall risk assessment (CRITICAL_LEAK, WARNING, or CLEAN) {{ outputs.output_security_metrics.values.verdict }}
primary_detector Compromised service provider (e.g., AWS, Slack, GitHub, OpenAI) {{ outputs.output_security_metrics.values.primary_detector }}
duration_seconds Total scan execution duration {{ outputs.output_security_metrics.values.duration_seconds }}

Who it's for

  • Security Engineers & DevSecOps Teams automating secret discovery across public and private code repositories.
  • Engineering Managers & Tech Leads enforcing pre-deployment and continuous credential hygiene.
  • Compliance & Risk Officers establishing continuous compliance monitoring for SOC2 and ISO 27001 requirements.

Why orchestrate this with Kestra

Running standalone cron scripts on developer machines leaves blind spots and lacks centralized audit trails. Kestra provides:

  • Containerized Security Tooling: Packages git and the official TruffleHog binary inside ephemeral containers without managing host server packages.
  • Encrypted Secret Isolation: Manages git tokens and Slack webhooks through Kestra's encrypted secret store with zero plaintext exposure.
  • Conditional Incident Routing: Natively routes high-severity leaks to emergency Slack channels while logging clean runs without alert spam.

Prerequisites

  • An incoming Slack webhook URL for security incident notifications.
  • (Optional) A GitHub Personal Access Token or GitLab Token if scanning private repositories.

Secrets

Configure the following secrets in your Kestra namespace or instance settings:

Secret Name Description Example
SLACK_WEBHOOK_URL Destination Slack webhook URL for security alerts https://hooks.slack.com/services/T00/B00/X00
WEBHOOK_KEY Secret authentication key for git push webhook triggers whk_live_s1e2c3r4e5
GITHUB_TOKEN (Optional) Personal access token for cloning private git repositories ghp_••••••••••••

Quick start

  1. Import this blueprint into your Kestra instance under the company.security namespace.
  2. Add your SLACK_WEBHOOK_URL into Settings > Secrets.
  3. Click Execute and enter the Git repository URL you wish to audit.
  4. Review the generated Slack card confirming scan results and verified credential status.
  5. Configure your GitHub / GitLab repository webhook to POST push events to the on_git_push_webhook URL for continuous protection.

Common pitfalls & notes

  • Private Repository Cloning: To scan private repositories, embed credentials via the GITHUB_TOKEN secret or pass an authenticated HTTPS clone URL.
  • Rate Limiting During Verification: Live verification sends HTTP requests to third-party APIs. For massive repositories, calibrate scan_depth to avoid temporary provider rate-limiting.
  • Schedule State: The scheduled nightly sweep is shipped disabled: true by default so it does not trigger before target repository URLs are configured.

How to extend

  • Automated Revocation: Add a downstream task using io.kestra.plugin.aws.cli.AwsCLI to automatically disable an exposed IAM access key via aws iam update-access-key --status Inactive.
  • Jira Issue Creation: Automatically create a high-priority security ticket in Jira via io.kestra.plugin.jira.Create when a verified leak is detected.
  • Multi-Repo Fleet Scanning: Wrap this flow inside a Loop task iterating across all repositories in your GitHub organization.

Links

See How

New to Kestra?

Use blueprints to kickstart your first workflows.