Pillager
Pillage filesystems for sensitive information with Go.
Table of Contents
- Summary
- Installation
- Usage
- Documentation
Summary
Pillager is designed to provide a simple means of leveraging Go's strong concurrency model to recursively search
directories for sensitive information in files. Pillager does this by standing on the shoulders
of a few giants. Once pillager finds files that match the specified pattern, the file is scanned
using a series of concurrent workers that each take a line of the file from the job queue and hunt for sensitive pattern
matches. The available pattern filters can be defined in a rules.toml file or you can use the default ruleset.
Installation
Go
If you have Go setup on your system, you can install Pillager with go get
go get github.com/brittonhayes/pillager
Scoop (Windows)
scoop bucket add pillager https://github.com/brittonhayes/pillager-scoop.git
scoop install pillager
Homebrew (OSX/Linux)
brew tap brittonhayes/homebrew-pillager
brew install pillager
Docker Image
docker run --rm -it ghcr.io/brittonhayes/pillager:latest hunt .
If you're looking for a binary, check the latest releases for the executable that matches your system
Usage
To see all the commands available with pillager
# To see instructions for the entire application
pillager
# From any subcommand
pillager [cmd] --help
User Interface
Pillager provides a terminal user interface built with bubbletea if you'd like to scan for secrets interactively.
Configuration
Gitleaks Rules
Pillager provides full support for Gitleaks[^gitleaks] rules. This can either be passed
in with a rules.toml[^1] file, or you can use the default ruleset by leaving the rules flag blank.
[^1]: Gitleaks Rules Reference
# rules.toml
title = "pillager rules"
[[rules]]
id = "gitlab-pat"
description = "GitLab Personal Access Token"
regex = '''glpat-[0-9a-zA-Z\-\_]{20}'''
[[rules]]
id = "aws-access-token"
description = "AWS"
regex = '''(A3T[A-Z0-9]|AKIA|AGPA|AIDA|AROA|AIPA|ANPA|ANVA|ASIA)[A-Z0-9]{16}'''
# Cryptographic keys
[[rules]]
id = "PKCS8-PK"
description = "PKCS8 private key"
regex = '''-----BEGIN PRIVATE KEY-----'''
Pillager has a series of built-in output formats available. Pick your flavor!
Basic
pillager hunt .
JSON
pillager hunt ./example -f json | jq
JSON output is designed to work seamlessly with the amazing jq utility for easy parsing.
Click to view more output formats
YAML
pillager hunt . -f yaml
TOML
pillager hunt . -f toml
HTML
pillager hunt . -f html > results.html
HTML Table
pillager hunt . -f html-table > results.html
Markdown
pillager hunt . -f markdown > results.md
Markdown Table
pillager hunt . -f table > results.md
Custom Go Template
pillager hunt . --template "{{ range .}}Secret: {{.Secret}}{{end}}"
Custom Go Template from File
pillager hunt . -t "$(cat pkg/templates/simple.tmpl)"
Custom Templates
Pillager allows you to use powerful go text/template
to customize the output format. Here are a few template examples.
Basic
{{ range . -}}
File: {{ .File }}
Secret: {{ .Secret}}
Description: {{ quote .Description }}
{{ end -}}
Markdown Styling
# Results
{{ range . -}}
## {{ .File }}
- Location: {{.StartLine}}
{{end}}
More template examples can be found in the templates directory.
Documentation
📚 View the docs
GoDoc documentation is available on pkg.go.dev for pillager but
it is also available for all packages in the repository in markdown format. Just open the folder of any package, and
you'll see the GoDocs rendered in beautiful Github-flavored markdown thanks to the
awesome gomarkdoc tool.
Development
To get involved developing features and fixes for Pillager, get started with the following:
Shoulders of Giants ⭐
What is Cobra?
Cobra is a library providing a simple interface to create powerful modern CLI interfaces similar to git & go tools.
Cobra is also an application that will generate your application scaffolding to rapidly develop a Cobra-based application.
If you've seen a CLI written in Go before, there's a pretty high chance it was built with Cobra. I can't recommend this
library enough. It empowers developers to make consistent, dynamic, and self-documenting command line tools with ease.
Some examples include kubectl
, hugo
, and Github's gh
CLI.
What is Gitleaks?
Gitleaks[^2] is a SAST tool for detecting hardcoded secrets like passwords, api keys, and tokens in git repos.
Gitleaks is an amazing tool for secret leak prevention. If you haven't implemented Gitleaks as a pre-commit checker,
it's worth your time to check it out.
Why is Gitleaks relevant to Pillager?
Pillager implements the powerful rules functionality of
Gitleaks while taking a different approach to presenting and handling the secrets found. While I have provided a
baseline set of default rules, Pillager becomes much more powerful if you allow users to create rules for their own
use-cases.
Check out the included rules[^1] for a baseline ruleset.
This goes without saying but I'm going to say it anyways: I am not responsible for any repercussions caused by your use of pillager.
This tool is intended for defensive use, educational use, and security researcher use with the consent of all involved parties.
Malicious behavior with pillager is in no way condoned, nor encouraged. Please use this tool responsibly and ensure you have permission
to scan for secrets on any systems before doing so.
At it's core, Pillager is designed to assist you in determining if a system is affected by common sources of credential leakage as documented
by the MITRE ATT&CK[^3] framework.
[^3]: MITRE ATT&CK Website
MITRE ATT&CK Technique - T1552,003 - Unsecured Credentials: Bash History
MITRE ATT&CK Technique - T1552,001 - Unsecured Credentials: Credentials In Files