Announcing TruffleHog Terminal UI

Hon Kwok

August 9, 2023

Company photo at an offsite

At Truffle Security, we have amazing biannual offsites where we all get to see each other in person, hang out, and do a little work. Part of that bit of work is a secret-finding hackathon where the entire company breaks up into teams and uses TruffleHog to see who can find the most secrets in the wild. Teams can use both the open-source command line tool and the enterprise web application.

One thing we quickly noticed was that the engineers were more comfortable using the CLI tool whereas many of the less technical members of our team leaned more heavily on the web app. Some of the engineers wrote scripts to scan sources like Pastebin and Crates, a Rust package registry. Some of the sales folks used our enterprise product to scan major organizations and repositories on GitHub and GitLab. Both approaches worked well but the CLI afforded those that are more comfortable working on the terminal a lot more creativity and versatility. So, at the start of 2023, my colleague Miccah and I decided to team up and build something different for open-source TruffleHog.

Team working on finding secrets at offsite

We set out to make the CLI tool more intuitive and user-friendly in order to lower the barriers to entry for creativity in the secrets scanning space. While terminals and command lines are powerful, they’re not the most intuitive and can be intimidating. Web applications and graphical user interfaces (GUIs) make software more accessible but you’re stuck with the abstracted paved-path interactions. We examined our recent interactions on the terminal to figure out how we could make the TruffleHog CLI a more delightful experience.

I had recently updated a bunch of NPM packages and found joy working with `yarn upgrade-interactive`. Having context for package versioning all in one place with information around patches, minor, and major changes was incredibly helpful in updating packages with ease and confidence. Similarly, Miccah had a great experience using a CLI tool for deploying software on a personal project. That tool used Survey, a Go library for building interactive and accessible prompts which he later experimented with on our enterprise product for reasons.

While these experiences were still on the command line, they were significantly more enjoyable than most CLI tools and closely mimicked concepts found in GUIs. We decided to bring that same user experience to TruffleHog.

Another goal for the CLI redesign was learnability and discoverability. Our users are often only familiar with TruffleHog in the context of scanning Git, but don’t know TruffleHog can also scan sources like CircleCI, S3/GCS buckets, and Docker. Many don’t know TruffleHog can automatically verify each secret by checking permissions with the secret provider. We’re putting our best foot forward with these projects so how can we meaningfully and unobtrusively present them?

And thus, TruffleHog TUI (Terminal User Interface) was born! It’s open source and available in TruffleHog v3.47.0 by simply running `trufflehog`.

At the very core of human computer interactions, we have user interfaces – something that handles interaction between a user and a system. Command line interfaces (CLIs) are one of the oldest interfaces for interacting with computers. CLIs often exist in the form of a terminal where the operators interact through text-based interactions. Open-source TruffleHog is an example of a CLI.

Open-source TruffleHog help view

Unfortunately, CLIs often require a user to remember a variety of complicated commands and flags. Graphical user interfaces (GUIs) are considered a reaction to the learning curve of CLIs. GUIs use widgets like textboxes and buttons to create a visual language for communication with a computer. The TruffleHog Enterprise web application is an example of a GUI.

TruffleHog Enterprise web application – Confluence integration set up

Terminal user interfaces (TUIs) are a type of CLI that use text and symbols to form GUI-like interactive elements. For example, in a TUI, instead of having to manually type everything out, users can interactively navigate through views. Colors and visual indicators provide a sense of information hierarchy that offer instant feedback unlike CLI tools which require a fully entered command before any sort of system response. TUIs are a good balance of CLIs and GUIs, so we leaned into examining our favorite computing experiences to build out the TruffleHog TUI with usability principles in mind.

Trufflehog TUI – toggling through available sources

Like any big project we started with a design document and looked at how a person might interact with TruffleHog. We noticed there were 3 instances in which a person would have to make a major decision:

Deciding on a source
Configuring source-specific information
Configuring TruffleHog flags

Taking inspiration from software installation wizards, we prototyped wireframes in Figma to lay out how the terminal user interface might look and feel.

TruffleHog Enterprise web application – Confluence integration set up

We landed on using Bubble Tea by Charm (https://charm.sh/) when developing our TUI due to the ecosystem built around it. Getting a handle on understanding the Elm Architecture took some time but the thoughtfulness and capabilities from supporting libraries made it easier. We heavily referenced their existing libraries, like Lip Gloss for styling and Bubbles for reusable components.

Getting started with TruffleHog TUI is simple.

First, install TruffleHog. Just like before, there are several options available:

# MacOS users 
brew install trufflesecurity/trufflehog/trufflehog 

# Docker 
docker run --rm -it -v "$PWD:/pwd" trufflesecurity/trufflehog:latest github --repo https://github.com/trufflesecurity/test_keys 

# Docker for M1 and M2 Mac 
docker run --platform linux/arm64 --rm -it -v "$PWD:/pwd" trufflesecurity/trufflehog:latest github --repo https://github.com/trufflesecurity/test_keys 

# Binary releases 
Download and unpack from https://github.com/trufflesecurity/trufflehog/releases 

# Compile from source 
git clone https://github.com/trufflesecurity/trufflehog.git cd trufflehog; go install

If you’re already familiar with TruffleHog, you can run scans the same as before. For example: `trufflehog docker –image trufflesecurity/secrets –only-verified`.

Previously when you ran just `trufflehog`, the help docs would print. Now, running `trufflehog` will start the terminal user interface.

Available options on TruffleHog TUI

Using your up/down arrow keys, you can navigate through the available options. The most used option will be `Scan a source using wizard`. This option provides an interactive wizard for building a TruffleHog command. In the first screen, you select which source you want to scan.

Filesystem source configuration for TruffleHog TUI

Upon selecting a source, you are then presented with a view that allows you to

Configure the source
Configure the scan (optional)
Review your selections and run TruffleHog

Using your arrow keys you navigate through the form elements or hit <tab> to get to the next page. Once all the required information is provided, you can run TruffleHog against the source you selected. You can also save the generated TruffleHog command if that suits your workflow.