Introduction
Users have always found custom rules (and the ease of writing them) to be one of Semgrep Code's most valuable capabilities. Custom rules let users easily tailor Semgrep Code to their specific codebase, getting the performance and accuracy of a highly customized, in-house SAST solution (at a fraction of the cost).
We’re super excited to announce that Semgrep Secrets customers can now take advantage of the same functionality!
Getting started
To get started, you can create a rule from scratch or fork an existing rule and modify it to suit your needs. Once you’ve written a rule, you can immediately start scanning across your organization.
Secrets customers will now see a new entry in the Semgrep Editor Templates. You can select our HTTP Validators example, which demonstrates how to validate a GitHub API token against github.com
Anatomy of a Secrets rule
Before you can validate if a secret is active, you need to find it 🕵🏻♀️
GitHub makes this easy since their tokens are prefixed with ghp_, gho_, etc. as seen below.
Once Semgrep detects a secret, we’ll make an HTTP call to the validation URL, and based on the response, determine if the secret is valid or not. For GitHub, a 200 lets us know the secret is valid, and a 401 indicates it is invalid for github.com. For more details on custom validators, visit our docs.
But what if your company uses GitHub Enterprise Server? The default rule will report the valid token as invalid, since the token was validated again api.github.com instead of your company’s GitHub server.
Let’s look at how we can use a custom rule to correctly validate this token!
Writing a custom GitHub validation rule
To get started, visit the Semgrep Playground
1.) Load the “HTTP Validators” template using the (+) button next to Library
2.) Update the rule ID to github-and-github-enterprise
3.) Duplicate the validators.http section
4.) Change the validation URL, we will use api.githubexample.semgrep.dev
5.) Optional: You can also update the message text, which is what folks at your company will see when Semgrep detects this secret.
6.) Save the rule
Adding to policy
Once you’ve saved your rule, add it to your policy. You can read more about rules modes in our docs.
For now, let’s set it to “Monitor.” Once the rule is added to your policy, re-run semgrep ci. You’ll see a valid finding and an invalid finding, since both the existing rule and our new custom rule were run.
Disabling existing rules
Since our new rule covers both github.com and our custom endpoint, we can disable the existing rule in our policies page to remove the duplicate finding.
Below is the Secrets findings page showing the validated GitHub token:
Forking existing rules
To use a Semgrep-written rule as a foundation for your own rule, start by visiting our policies page.
1.) Click the Secrets tab at the top
2.) Click the rule you want to modify
3.) Click “Edit rule”
4.) Follow a similar process similar to the one outlined above for GitHub. You will need to make modifications to the validation logic based on the behavior of the service’s API.
Conclusion
Semgrep Secrets customers can now write rules for applications with custom subdomains (e.g. GitHub or Jira), internal applications, or other applications that Semgrep does not yet support (if it is a common service, feel free to drop us a request).
If you’re an existing Semgrep customer that needs help writing custom rules, check out our docs or reach out to our fantastic support team. If you’re not yet a customer, consider booking a demo!
We hope you leverage Semgrep Secrets to keep your organization and your customers safe!
