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 when the node starts up, and automatically restarts as well
uses centralized system logging with rotation
can be isolated if needed for security purposes

Most modern Linux distributions include systemd to manage daemons and system services.

By default, systemd services run as the root user of a system, thus inheriting root user permissions. While this is a perfectly valid configuration for many services, it could potentially represent an increased security risk. If you wish to configure the service to run as a non-root user, you will need to ensure you specify User= in the service configuration (similar to the example below), and that the user has permissions to:

Read and write to the directory in which the scanner binary is located
Read any directories that you would like to scan for secrets

If you would like to create a specific user for the scanner to run as, perform the following command on Debian-based systems (using truffle as an example):

sudo adduser truffle

For other Linux distributions:

sudo useradd -m truffle

A home directory (assuming a user name of truffle) should be created at /home/truffle, which the user will have ownership of, and thus read and write permissions. If you would like to give it permissions to scan other directories, such as other users’ home directories, run the following command:

chown -R truffle: /home

Debian-based systems

Cloud providers like AWS have a default user already configured on Debian and Ubuntu machine images. The example below references ubuntu

Debian: admin
Ubuntu: ubuntu

If you’ve created a special user for running the scanner, substitute it in the configuration below.

Extract the TruffleHog scanner archive to /home/ubuntu
Copy your config.yaml into /home/ubuntu

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

[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

[Install]
WantedBy=multi-user.target

Amazon Linux

For Amazon Linux-based nodes, the default user is: ec2-user.

If you’ve created a special user for running the scanner, substitute it in the configuration below.

Extract the TruffleHog scanner archive to /home/
Copy your config.yaml into /home/ec2-user
Copy the Systemd Unit file given below into /etc/systemd/system/trufflehog.service

    [Unit]
    Description=Run the TruffleHog scanner as a daemon

    [Service]
    Type=simple
    ExecStart=/home/ec2-user/scanner scan --config=/home/ec2-user/config.yaml
    Restart=on-failure
    RestartSec=15s
    User=ec2-user

    [Install]
    WantedBy=multi-user.target

Reload Systemd to make it aware of the new service unit file: sudo systemctl daemon-reload
Configure the Systemd to run TruffleHog at boot: sudo systemctl enable trufflehog.service
Start TruffleHog right now: sudo systemctl start trufflehog.service
View the status of TruffleHog sudo systemctl status trufflehog.service
View the TruffleHog logs: sudo journalctl -u trufflehog
Tail the TruffleHog logs: sudo journalctl -fu trufflehog

Configuring Proxy Connections when running as a systemd service

In some instances, you may want to run a local scanner on a node that does not have outbound connectivity due to firewall configuration or other network topology. In that instance, you can configure systemd services with a proxy by making use of the Environment= setting. Using the above ubuntu example again:

    [Unit]
    Description=Run the TruffleHog scanner as a daemon

    [Service]
    Environment="HTTP_PROXY=http://proxy.server.com:8000"
    Environment="HTTPS_PROXY=https://proxy.server.com:8000"
    Type=simple
    ExecStart=/home/ubuntu/scanner scan --config=/home/ubuntu/config.yaml
    Restart=on-failure
    RestartSec=15s
    User=ubuntu

    [Install]
    WantedBy=multi-user.target

Be sure to change the URL to the actual address or IP of your proxy server.

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.

Create the namespace

$ kubectl create namespace trufflehog
namespace/trufflehog created

Create the configuration secret

$ kubectl create secret --namespace trufflehog generic --from-file config.yaml config
secret/config created

Create the deployment

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/

Apply the manifest

$ kubectl apply -f /tmp/thog.yaml --namespace trufflehog
deployment.apps/trufflehog configured

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

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.

Create the namespace

$ kubectl create namespace trufflehog
namespace/trufflehog created

Create the configuration secret

$ kubectl create secret --namespace trufflehog generic --from-file config.yaml config
secret/config created

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!⎈

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
```

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

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]+