Joe Leon

The Dig

September 18, 2023

How to Rotate: Key Rotation Tutorials

How to Rotate: Key Rotation Tutorials

Joe Leon

September 18, 2023

We’re excited to introduce ‘How to Rotate‘, an open-source collection of API key rotation tutorials (including AWS, GitHub, Mailchimp and more). Want to see the tutorials? Click here. Curious why we built ‘How to Rotate,’ please keep reading.

Secret Scanning + Key Rotation

Security engineers and developers run our open-source secret scanner, TruffleHog, to find and remediate leaked secrets across their SDLC. While TruffleHog can detect over 750 types of leaked secrets, that only solves part of the problem. Users often seek our advice on remediation.

With very, very few exceptions, the most effective way to remediate a leaked secret is with key rotation. Simply deleting the code that exposes the key or editing git history is insufficient

The key rotation process is rather simple: (1) create a new key, (2) replace the leaked key with the new one, (3) revoke the leaked key. Unfortunately, each SaaS provider handles key rotation slightly differently. 

For example, the payment processing platform Square has a simple “Replace token” button that both creates a new key and revokes the old one.


Square Key Rotation


Note: Despite the ease of clicking just one button, this pattern makes it impossible to rotate without downtime.  

By contrast, the payment processor Stripe requires users to first create a new key and then delete the leaked key.


Stripe Key Rotation


If you’re only rotating one key, this process is annoying, but tolerable.

Imagine TruffleHog identifies leaked keys from 10 different SaaS providers. 

Now, you have to figure out where to go in each platform’s web portal to change the key, understand how each provider handles key rotation, actually rotate the keys, and then update your code. And you have to do this 10 times! It’s a very friction-filled process.

Introducing: How to Rotate

We dreamed of a world where every SaaS provider’s key rotation documentation lived in one place. Since that didn’t exist, we decided to invest in creating it. 

How to Rotate is an open-source project on GitHub, sponsored by Truffle Security. At the time of this blog post, the project contains key rotation tutorials for the 20 most commonly leaked keys. We’re not stopping at 20: our goal is to provide guidance on rotating all keys that the TruffleHog detection engine can identify (that’s over 750!). 

To get there, we’ll need some help. Just like TruffleHog, we’re looking to the open-source security community for contributions – please consider submitting a PR (CONTRIBUTING documentation can be found here). The How to Rotate project is freely available to all and any GitHub user is welcome to fork the project.