Advanced usage

Downloading the binary

Download the binary from your Scanners page in the Dashboard.

Running as a Systemd daemon

If you’re looking to run the scanner on a Linux system, setting it up to run as a systemd unit is a good way to ensure that it

  • starts automatically on startup
  • has logs rotated
  • is able to run without any users connected to the server

Most modern Linux distributions include systemd to manage daemons and other configuration.

We’ll provide an example below that is tailored for Ubuntu, but compatible with other systems with some minor alterations.

  1. Extract the TruffleHog scanner archive to /home/ubuntu

  2. Copy your config.yaml into /home/ubuntu

  3. Copy the Systemd Unit file given below into /etc/systemd/system/trufflehog.service

    Systemd Unit file:

    [Unit]
    Description=Run the TruffleHog scanner as a daemon
    
    [Service]
    Type=simple
    ExecStart=/home/ubuntu/scanner scan --config /home/ubuntu/config.yaml
    Restart=on-failure
    RestartSec=15s
    User=ubuntu
    PrivateUser=yes
    
    [Install]
    WantedBy=multi-user.target
    
  4. Reload Systemd to make it aware of the new service unit file: systemctl daemon-reload

  5. Configure the Systemd to run TruffleHog at boot: systemctl enable trufflehog.service

  6. Start TruffleHog right now: systemctl start trufflehog.service

  7. View the status of TruffleHog systemctl status trufflehog.service

  8. View the TruffleHog logs: journalctl logs -u trufflehog

  9. Tail the TruffleHog logs: journalctl logs -fu trufflehog

Deploying to Kubernetes via manifest

The following instructions will help you setup a basic deployment of the TruffleHog scanner in Kubernetes. Kubernetes will ensure that TruffleHog stays running, manage your configuration secrets, and collect the logs.

  1. Create the namespace
    $ kubectl create namespace trufflehog
    namespace/trufflehog created
    
  2. Create the configuration secret
    $ kubectl create secret --namespace trufflehog generic --from-file config.yaml config
    secret/config created
    
  3. Create the deployment
    1. Create a yaml file with these contents:
      
      apiVersion: apps/v1
      kind: Deployment
      metadata:
        name: trufflehog
        labels:
          app: trufflehog
      spec:
        replicas: 1
        selector:
          matchLabels:
            app: trufflehog
        template:
          metadata:
            labels:
              app: trufflehog
          spec:
            volumes:
            - name: config-secret-volume
              secret:
                secretName: config
            containers:
            - name: trufflehog
              image: us-docker.pkg.dev/thog-artifacts/public/scanner:latest
              terminationMessagePolicy: FallbackToLogsOnError
              command: ["/usr/local/bin/scanner", "scan", "--config=/secret/config.yaml", "--port=8080"]
              livenessProbe:
                httpGet:
                  path: /healthz
                  port: 8080
                initialDelaySeconds: 3
                periodSeconds: 3
              volumeMounts:
              - name: config-secret-volume
                mountPath: /secret/
      
    2. Apply the manifest
      $ kubectl apply -f /tmp/thog.yaml --namespace trufflehog
      deployment.apps/trufflehog configured
      
  4. Wait for TruffleHog to be running
    $ kubectl get pods --namespace trufflehog --watch
    NAME                          READY   STATUS    RESTARTS   AGE
    trufflehog-7f76dc4c49-szxwv   1/1     Running   0          0m22s
    
  5. Follow the logs
    $ kubectl logs --namespace trufflehog -f -l app=trufflehog 
    🐷🔑🐷 TruffleHog. Unearth your secrets. 🐷🔑🐷
    version:  v1.50.22
    
    INFO[0000] starting scanner service client               scanner_group=On-prem
    

Deploying to Kubernetes via Helm

For users who prefer to manage their Kubernetes applications with Helm, here’s how you can deploy TruffleHog using Helm. Helm simplifies deploying and managing Kubernetes applications using predefined chart’s README.

  1. Create the namespace

    $ kubectl create namespace trufflehog
    namespace/trufflehog created
    
  2. Create the configuration secret

    $ kubectl create secret --namespace trufflehog generic --from-file config.yaml config
    secret/config created
    
  3. Update your Helm repository

    $ helm repo update
    Hang tight while we grab the latest from your chart repositories...
    ...Successfully got an update from the "trufflesecurity" chart repository
    Update Complete. ⎈Happy Helming!⎈
    
  4. Install TruffleHog using Helm

    This will deploy TruffleHog with default values. The Helm chart allows you to provide your custom configuration using a custom values.yaml file. If you wish to provide custom configuration, refer to the chart’s README.

    $ helm install trufflehog trufflesecurity/trufflehog --namespace trufflehog
    NAME: trufflehog
    LAST DEPLOYED: Tue Sep 18 15:57:58 2023
    NAMESPACE: trufflehog
    STATUS: deployed
    REVISION: 1
    
  5. Verify the Deployment

    Just like in the manual deployment, you’d want to ensure your deployment is running:

    $ kubectl get pods --namespace trufflehog --watch
    NAME                          READY   STATUS    RESTARTS   AGE
    trufflehog-6b84d5f89c-tlwq6   1/1     Running   0          1m
    
  6. Follow the logs

    $ kubectl logs --namespace trufflehog -f -l app=trufflehog
    🐷🔑🐷 TruffleHog. Unearth your secrets. 🐷🔑🐷
    version:  v1.50.22
    
    INFO[0000] starting scanner service client               scanner_group=On-prem
    

Detectors Which Accept Configuration Options

Some detectors accept configuration options that can be set in the config.yaml file.

JDBC

  • ignorePattern: List of regular regular expressions used to ignore unwanted results.
detectorsConfig:
  jdbc:
    ignorePattern:
    - somep[aA]ttern[0-9]+