# techgaun/github-dorks: scanning GitHub and local trees for leaked credentials

> github-dorks is a Python CLI that runs a bundled dictionary of code-search patterns against a repository, a user or an organization, and can also scan a local working tree offline. The interesting part is the category split and the JSON output; the weak part is that it only sees the current tree, not git history.

**techgaun/github-dorks** — Find leaked secrets via github search

- Repository: https://github.com/techgaun/github-dorks
- Stars: 3,289 · Forks: 647
- Language: Python
- License: Apache-2.0
- Published: 2026-09-24 · Updated: 2026-09-24 · Language: en
- Canonical page: https://hysenlabs.com/projects/techgaun-github-dorks

## What github-dorks actually searches for

GitHub code search accepts qualifiers such as filename:, path:, extension: and language:, which means a query like filename:.npmrc _auth can surface npm registry authentication data sitting in a public repository. Writing those queries by hand is tedious and easy to get wrong. github-dorks packages a dictionary of them and runs the whole set against a target. The README describes the intended audience plainly: people assessing security and performing pen-testing of systems, looking for private keys, credentials and authentication tokens. It is a discovery tool for an audit, not a runtime secret scanner. The bundled dictionary is split into ai, cloud, databases, devops, frameworks, identity, observability, private-keys, saas and system categories, and the older flat github-dorks.txt file is generated from those category files by scripts/build-dorks.py for backward compatibility. If you have been maintaining your own list of dorks for bug bounty work, the category files are the part worth reading even if you never run the CLI.

## How a scan flows from query to result

The tool talks to the GitHub Search API through github3.py, which is pinned to 4.0.1 in pyproject.toml alongside requests and feedparser. Credentials come from environment variables rather than flags: GH_USER and GH_PWD for username and password, GH_TOKEN for a token, and GH_URL to point at a GitHub Enterprise base URL instead of github.com. A scan of a single repository uses -r owner/name; -u takes a user or an organization and walks all of its repositories. Each run ends with a summary of queries, matches, failures, retries and elapsed time, and the process exit status carries meaning: 0 after a complete scan, 2 when one or more queries failed, and 1 for fatal configuration, file or authentication errors. That distinction matters more than it looks. A sweep of a large organization will hit GitHub's separate search rate limit, and the README notes that searches may pause until GitHub resets it. Authenticated requests get higher limits, which is why the Docker examples pass GH_TOKEN. Recoverable failures can be retried with --max-retries. Output formats are text, csv, json and jsonl; text is the default for the terminal, but using -o without --format keeps the historical CSV default, and existing files are protected unless you pass --force. Status messages go to stderr so that structured stdout stays machine-readable, which is a deliberate choice and the right one for piping json into another tool.

## Installing github-dorks and running a first scan

The README gives two installation paths. The pip route clones the repository and installs the package from the checkout, which puts a github-dorks entry point on your PATH because pyproject.toml declares it under [project.scripts]. Python 3.10 or newer is required.

```bash
git clone https://github.com/techgaun/github-dorks.git
cd github-dorks
pip install .
```

The Docker route builds an image from the repository's Dockerfile, which is based on python:3.12-slim and uses github-dorks as its entrypoint. The README shows building the image and then running it against a user with a token passed through the environment.

```bash
docker build -t github-dorks .
docker run -e GH_TOKEN=your_github_token github-dorks -u someuser
```

Once installed, a single-repository scan is the cheapest way to see what the output looks like. Expect a per-query progress stream on stderr and a summary at the end listing queries, matches, failures, retries and elapsed time.

```bash
github-dorks -r techgaun/github-dorks
```

## Scanning an organization and a local working tree

To scan every repository under an organization, pass the token through the environment rather than the command line. The README uses dev-nepal as the example organization.

```bash
GH_TOKEN=<github_token> github-dorks -u dev-nepal
```

For a pipeline, ask for JSONL and write it to a file. The --force flag is required to replace an existing file, and -o without --format would give you CSV instead.

```bash
github-dorks -u dev-nepal --format jsonl -o results.jsonl --force
```

The offline mode is the one people miss. --local points the same dictionary at a working tree with no GitHub credentials and no network access. Inside a Git working tree the scanner checks tracked files and non-ignored untracked files; elsewhere it recurses while excluding .git. Binary files and files larger than 1 MB are skipped unless you raise the limit with --max-file-size. You can also narrow the dictionary with -c, repeated per category, or point at your own file with --dork.

```bash
github-dorks --local ./cloned-repo -c cloud -c identity
github-dorks --local . --format jsonl -o local-results.jsonl
```

Before any of this, github-dorks --list-categories prints the bundled dictionaries so you know which -c values your installed version accepts. The legacy invocation python github-dork.py ... still works, and python -m github_dorks is available as well.

## Where github-dorks stops being the right tool

The README's own limitations section is the honest part of this project, and it should shape how you use it. Offline scanning inspects the current working tree only; Git history scanning is not yet supported. That is a real gap for the most common leak scenario, where a key was committed, noticed and removed while remaining in history. github-dorks will not find it locally, and on GitHub the search index is not a history browser either. The second constraint is rate limiting. Large category combinations take time because GitHub applies a separate search rate limit, and an unauthenticated or lightly authenticated run over an organization can stall. The third is the nature of pattern matching itself. The README's own table flags this on one row, noting that a dork might return false negatives. A dictionary of filename and extension patterns will miss credentials stored under unexpected names, and it will produce matches that are test fixtures, examples or intentionally public keys. There is no triage step in the tool; sorting signal from noise is your job. Finally, the project is a Beta per its classifier, with a single 0.1 release dated 2016-09-08 and ongoing work landing on main.

## How it compares with trufflehog and gitleaks

The closest alternatives are trufflehog and gitleaks, and the difference is architectural rather than cosmetic. Those tools scan git history and apply entropy analysis plus provider-specific detectors to decide whether a string is a live credential; they are built to run in a pre-commit hook or a CI job over a repository you control. github-dorks does the opposite: it queries GitHub's code search with filename, path, extension and language qualifiers, so its reach extends to repositories you do not own and cannot clone, which is the bug bounty and external-audit use case. It also runs the same dictionary offline against a local tree, but without history. A practical split is to use github-dorks for external recon and organization-wide sweeps, and a history-aware scanner for the repositories in your own pipeline. The two answer different questions: one asks what is publicly exposed right now, the other asks what was ever committed.

## Maintenance, packaging and licence

pyproject.toml requires Python 3.10 or newer and pins github3.py to exactly 4.0.1 while allowing feedparser 6.x and requests 2.x. The exact pin on github3.py is a trade-off: it protects against upstream API changes in the GitHub client, but it means security fixes in that library only arrive when the pin is bumped. The dependency-free unit test suite runs with python -m unittest discover -s tests -v, and the CI matrix covers Python 3.10 through 3.13, so the supported interpreter range is explicit. The Dockerfile builds from python:3.12-slim, installs the package with pip install --no-cache-dir ., sets PYTHONUNBUFFERED and PYTHONIOENCODING, declares /app/output as a volume and uses github-dorks as the entrypoint, which matches the docker run examples in the README. The licence is Apache-2.0, declared in both pyproject.toml and the LICENSE file at the repository root. Apache-2.0 is permissive and includes an explicit patent grant, which matters if you plan to vendor the dork dictionary into an internal tool; the usual obligation to preserve notices applies, and the dork list itself is data you may want to fork. This is a description of the licence text, not legal advice.

## Conclusion

Adopt github-dorks if you already have a GitHub token with search access and want a repeatable way to sweep a repository or an organization with a maintained dork list, especially in CI where the JSON and JSONL formats and the exit codes 0, 1 and 2 let you fail a job on partial query failure. Do not adopt it if you need to find secrets that were committed and later removed: the README states that offline scanning inspects the current working tree only and that Git history scanning is not yet supported, so a rotated-but-still-in-history key will not appear. Before relying on it, run github-dorks --list-categories against your installed version to confirm which categories exist, and check the exit code of a single-repository scan, because a scan that partially fails returns 2 rather than 0 and a pipeline that only checks for a non-zero exit will treat that as a clean result.

## FAQ

### Does github-dorks need a GitHub token to run?

No. Local scans with --local require no GitHub credentials and no network access. For searches against GitHub the README recommends a token via GH_TOKEN, and notes that authenticated requests receive higher rate limits, which matters because GitHub applies a separate search rate limit.

### Can github-dorks scan a local repository instead of GitHub?

Yes, using --local, for example github-dorks --local ./cloned-repo -c ai -c identity. In a Git working tree it checks tracked files and non-ignored untracked files; elsewhere it recurses while excluding .git, skipping binary files and files larger than 1 MB unless --max-file-size raises the limit.

### What output formats does github-dorks support?

Text, csv, json and jsonl. Text is the default for terminal output, and using -o without --format preserves the historical CSV default. Existing files are protected unless --force is provided, and status messages go to stderr so structured stdout stays machine-readable.

### Does github-dorks scan git history for removed secrets?

No. The README states that offline scanning inspects the current working tree only and that Git history scanning is not yet supported. A credential that was committed and later removed will not be found by a local scan.

### What do the github-dorks exit codes mean?

The command exits with 0 after a complete scan, 2 when one or more queries failed, and 1 for fatal configuration, file or authentication errors. A pipeline that treats any non-zero exit as a hard failure will need to handle 2 separately, since it means the scan was partial rather than unusable.

## Sources

- [Issues](https://github.com/techgaun/github-dorks/issues)
- [License: Apache-2.0](https://github.com/techgaun/github-dorks/blob/main/LICENSE)
- [README](https://github.com/techgaun/github-dorks/blob/main/README.md)
- [Releases](https://github.com/techgaun/github-dorks/releases)
- [techgaun/github-dorks on GitHub](https://github.com/techgaun/github-dorks)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/techgaun-github-dorks