Self-Hosted Deployment Guide

whether you're deploying trufflehog for the first time or optimizing an existing setup, this guide covers core concepts, sizing recommendations, deployment options, and scanner group strategy the sizing recommendations and resource guidance throughout this guide are based on real world customer deployments across small, medium, and large organizations use them as a starting point, your specific requirements may vary based on the sources you scan, the size of your repositories, and your scan frequency core concepts concurrency concurrency sets the number of worker threads the scanner runs in parallel for scanning and detection think of concurrency as your throughput dial higher concurrency lower concurrency parallel work more less scan speed faster (if resources allow) slower resource usage higher cpu and memory lower cpu and memory how to configure it concurrency is set in your configuration file (typically config yml ) by default, it matches the number of cpu cores detected on the host running trufflehog to override the default, set the value explicitly in your config yml example if a customer sets concurrency to 4 in their config yml , trufflehog runs 4 worker threads in parallel, each independently scanning and detecting secrets for example, with 4 sources configured, the scanner can run one job per source simultaneously concurrency is set in your configuration file (typically config yml) by default, it matches the number of cpu cores detected on the host running trufflehog to override the default, set the value explicitly in your config yml trufflehogaddress \<your trufflehog enterprise instance> trufflehogscannergroup \<name of your scanner group> trufflehogscannertoken thog agent xxxxxxxxxxxxxxxxxx logjson true loglevel info concurrency 4 important notes trufflehog scanners are designed to fully utilize the available concurrency some integrations fetch data via apis (e g , jira, confluence) that enforce server side rate limits in these cases, your cpu may not be fully saturated because trufflehog respects those limits monitor your local trufflehog logs for rate limit and timeout errors, and increase concurrency only as your scans demand it and your source apis can tolerate it cpu and memory cpu usage can vary widely during a scan the same customer may see usage range from 3 cpus to 15+ cpus across different scans, depending on the source type, repository size, and concurrency settings memory usage tends to be more predictable but can spike when scanning large repositories or processing high volumes of findings sizing guidance give cpu generous headroom scans are bursty by nature, and under provisioning cpu can cause jobs to throttle mid run or take significantly longer to complete set memory limits conservatively over allocating memory wastes resources, but setting limits too low can result in out of memory (oom) errors that kill scan jobs monitor and adjust use the sizing recommendations in the next section as a starting point, then tune based on observed usage in your environment ephemeral storage ephemeral storage is temporary disk space trufflehog uses during a scan — primarily for cloning git repositories, extracting archives, and writing intermediate scan data to the system's temporary directory this data is discarded once the scan completes ephemeral storage requirements are primarily driven by git based scanning api based sources (e g , slack, jira, confluence) stream data and do not require significant temporary disk space sizing guidance start with at least 50 gb this is a safe baseline for most deployments and accommodates moderately sized repositories increase for large repositories monorepos and repositories with deep git history can require significantly more space if you're scanning a single repo larger than 10 gb, plan for storage well above the baseline account for parallel scans higher concurrency means multiple sources may be cloned or extracted simultaneously, increasing peak storage usage sizing recommendations the following recommendations are sized by developer headcount and number of sources scanned use them as a starting point and adjust based on your observed resource usage tier developers sources cpu ram ephemeral storage small 50–250 1–4 1–4 0 5–2 gb 50 gb+ medium 251–1,000 5–15 1–8 2–8 gb 50 gb+ large 1,000+ 16+ 8–16 8–32 gb 100 gb+ x large 5,000+ 32+ 16+ 16–32 gb+ 200 gb+ these ranges reflect typical deployments, but actual requirements depend on your specific scan workload — particularly repository size, git history depth, and scan frequency monitor your scanner's resource usage over the first few scans and adjust accordingly deployment options trufflehog can be self hosted in three environments kubernetes, a linux host, or a docker container we recommend kubernetes for most production deployments because of its built in scaling, recovery, and resource management capabilities kubernetes (recommended) we recommend deploying trufflehog on kubernetes using our helm chart https //github com/trufflesecurity/helm charts a helm chart defines, installs, and manages applications on kubernetes, and ours handles the deployment, autoscaling, and configuration of trufflehog in a single install for infrastructure as code, the terraform helm provider works seamlessly with our charts why helm simple setup creates the deployment and vertical pod autoscaler (vpa) in a single install templated configuration all settings live in one place and can be version controlled open source customers can submit prs for improvements works as a template engine even without helm installed vpa integration available on google gke, aws aks, and eks, with both recommendation mode and automatic scaling upper limits can be set to prevent runaway resource usage (vpa can be disabled if required ) helm chart parameters for the full list of helm chart parameters https //github com/trufflesecurity/helm charts/blob/main/trufflehog/values yaml , see our chart documentation below are some commonly adjusted defaults parameter default replica 1 resources requests cpu 4000m resources requests memory 16gi resources limits cpu 12000m resources limits memory 48gi vpa enabled true vpa minallowed cpu 4000m vpa minallowed memory 16gi vpa maxallowed cpu 12000m vpa maxallowed memory 48gi a note on vpa and oom vertical pod autoscaler (vpa) in auto mode requires a pod restart to apply new resource limits, so it does not prevent the initial out of memory (oom) event instead, it prevents the next oom after the pod is rescheduled with more headroom no cloud service dynamically expands a running container's memory ceiling mid execution without a restart kubernetes manifests (fallback) if helm is disallowed by your platform policy, you can deploy trufflehog using a raw kubernetes manifest applied via kubectl apply note that this approach does not include vpa or any of the helm chart helpers, and configuration must be managed manually linux host trufflehog can be deployed directly on a linux host for simpler setups or environments where kubernetes isn't available see the linux host deployment guide https //docs trufflesecurity com/linux host for installation steps and configuration details docker trufflehog is also available as a docker container, which can be useful for testing, ci/cd pipelines, or environments that don't require full orchestration see the docker deployment guide https //docs trufflesecurity com/docker for setup instructions scanner group strategy every deployment has unique requirements, and the right scanner group strategy depends on your scan volume, source mix, isolation needs, and operational tolerance below are common patterns we've seen across customer deployments use them as general guidance — your specific requirements may differ single scanner group with multiple sources when to use cost effective one host, one scanner group lower operational management overhead the most common starting point for small and medium deployments trade offs single point of failure if the scanner goes down, all sources stop scanning example configuration a single scanner group handles multiple sources within one config yml trufflehogaddress \<your trufflehog enterprise instance> trufflehogscannergroup primary scanner trufflehogscannertoken thog agent xxxxxxxxxxxxxxxxxx logjson true loglevel info sources \ connection '@type' type googleapis com/sources github endpoint https //github ourbusiness com token xxxxxxxxxxxxxxxxxxxxxxxxxx name github scanperiod 12h type source type github verify true \ connection '@type' type googleapis com/sources confluence endpoint https //confluence ourbusiness com token xxxxxxxxxxxxxxxxxxxxxxxxxx name confluence scanperiod 24h type source type confluence verify true multiple scanner groups, one source per scanner when to use you want each scanner dedicated to a single source type (e g , one for github, one for docker, one for confluence) failure isolation an issue with one scanner doesn't affect the others easier troubleshooting and observability per source type resource allocation for large repos (e g , monorepos) logical separation by business unit or source category trade offs all scanners share the host's cpu, memory, and network, so heavy load on one scanner can still affect the others more configuration overhead than a single scanner group example configuration each scanner runs with its own config yml, its own scanner group, and a single source github scanner (config github yml) trufflehogaddress \<your trufflehog enterprise instance> trufflehogscannergroup github scanner trufflehogscannertoken thog agent xxxxxxxxxxxxxxxxxx logjson true loglevel info sources \ connection '@type' type googleapis com/sources github endpoint https //github ourbusiness com token xxxxxxxxxxxxxxxxxxxxxxxxxx name github scanperiod 12h type source type github verify true confluence scanner (config confluence yml) trufflehogaddress \<your trufflehog enterprise instance> trufflehogscannergroup confluence scanner trufflehogscannertoken thog agent yyyyyyyyyyyyyyyyyy logjson true loglevel info sources \ connection '@type' type googleapis com/sources confluence endpoint https //confluence ourbusiness com token yyyyyyyyyyyyyyyyyyyyyyyyyy name confluence scanperiod 24h type source type confluence verify true multiple scanner groups across multiple hosts recommended for heavy, regulated, or network segmented enterprise deployments each scanner group runs on its own dedicated host (or, in kubernetes, its own pod) when to use a single source type's resource needs are large enough to dominate a shared host (e g , gitlab or github clones of large monorepos requiring 32+ gb) network segmentation requirements (e g , the confluence scanner needs to live in an isolated zone that can reach on prem confluence server, while github scanning needs access to a different vpc) compliance requirements that mandate hard isolation between source types' credentials and processing scan windows differ enough to justify scaling instances independently (e g , spot instances for overnight gitlab scans, steady state for daytime jira scans) benefits strongest isolation scanner groups don't compete for cpu, memory, or network at any level a heavy workload on one host can't affect the others trade offs most expensive option one vm (or dedicated pod) per scanner group more operational overhead more hosts to monitor, patch, and maintain kubernetes variation single cluster, separate pods the same isolation pattern can be achieved within a single kubernetes cluster by running each scanner group as its own deployment with separate pods and dedicated resource requests/limits each scanner group is typically dedicated to a single source type (e g , jira, confluence, gitlab) failure isolation works as expected if one scanner pod runs out of memory or crashes, only that pod goes down kubernetes restarts it, and the other scanner groups keep running uninterrupted trade offs more complex to manage resource requirements calculator for an initial sizing estimate tailored to your environment, use our resource requirements calculator https //docs google com/spreadsheets/d/1jvqz6fgrgdhsv6htsssjwklte33wwfvnuma8modgi u/edit?gid=0#gid=0 the calculator takes inputs like organization size and source mix and returns a recommended starting configuration, which you can then refine based on the guidance in this document