# metagoofil finds the files your site left in the search index

> metagoofil is a Python tool that queries Google for specific file types hosted on a site and can download them, used for open source intelligence gathering, penetration testing and auditing what an organisation leaks to search engines. This fork is the one installed by default on Kali, and it deliberately leaves metadata analysis to exiftool.

**opsdisk/metagoofil** — Search Google and download specific file types

- Repository: https://github.com/opsdisk/metagoofil
- Stars: 598 · Forks: 115
- Language: Python
- License: NOASSERTION
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/opsdisk-metagoofil

## A filetype query turned into a harvesting tool

metagoofil searches Google for specific types of files being publicly hosted on a web site and optionally downloads them to your local box. The mechanism it is built on is a single search operator, and the README shows the example query that a human could type into any browser.

```bash
site:example.com filetype:pdf
```

That is the whole idea. Google already indexes documents that a site publishes and forgets, PDFs sitting in a uploads directory, spreadsheets exported from an internal tool, word documents left in a web root. metagoofil automates the query, iterates over the result pages, extracts the links, and with the download option pulls the files down so you can look at them. The README states the three uses plainly, and they are worth separating because they carry different levels of permission. Open source intelligence gathering is the defensive case, where you are checking your own estate. Penetration testing is the case where the scope document says you may enumerate. Determining what files your organization is leaking to search indexers like Google is the case where the target is your own employer and the exercise is a self audit. The tool does not break anything, and that is precisely why it is useful: everything it retrieves was already public.

## The Kali default, and the fork that dropped metadata analysis

This is a maintained fork of the original by laramies, and it is currently installed by default on the Kali Operating System, which is the strongest practical signal about the tool's role and its maturity. Kali ships a large set of these utilities because they cover the reconnaissance and enumeration phase of an engagement, and metagoofil is one of the ones that earns its place. The fork made one design decision that the README calls out explicitly: unlike the original, a design decision was made to not do metadata analysis and instead defer to other tools like exiftool. That is a good decision and worth explaining, because it is the kind of thing that separates a maintained fork from a copy. Metadata extraction from a corpus of downloaded documents is a job with one obvious right answer, and the tool that already does it well is exiftool, so the README shows the handover.

```bash
exiftool -r *.doc | egrep -i "Author|Creator|Email|Producer|Template" | sort -u
```

The pipeline shape is the point. metagoofil finds and downloads, exiftool reads the author and creator and email fields out of the result, and a human decides what matters. A single tool that tried to do both would have a worse version of each.

## Installing it from source, with only two dependencies

The requirements file is two lines long, and they are pinned, which tells you the tool is not carrying a dependency tree.

```bash
git clone https://github.com/opsdisk/metagoofil
cd metagoofil
python3 -m venv .venv  # If using a virtual environment.
source .venv/bin/activate  # If using a virtual environment.
pip install pip setuptools -U
pip install -r requirements.txt
```

The requirements are the google client library at version 3.0.0 and requests at 2.32.5, and the clone also brings a data/ directory, a user_agents.txt file, a Dockerfile and the single metagoofil.py script at the top level, so the whole tool is one Python file with a data directory beside it. The project is licensed under a custom licence that GitHub cannot classify, with a LICENSE file in the repository root, and since the code is distributed inside Kali as well as on its own, that licence file is the document to read before you redistribute or modify it. The releases on record are v1.4.0 from 2025-08-30 and v1.3.0 from 2025-02-08, and the repository was last pushed on 2026-05-18, so the tool is in the middle of its release cadence rather than at the end of it.

## Docker, with the output directory mounted and a fixed user id

The container route exists, and the run command in the README shows the two settings that matter for a real engagement. First, the output is written to a host directory rather than left inside the container, so the downloaded files survive the run.

```bash
git clone https://github.com/opsdisk/metagoofil
cd metagoofil
docker build -t metagoofil .

# This will save the files in the host ./data directory.
docker run -it --rm \
    --user 1000:1000 \
    -v $PWD/data:/app/data \
    metagoofil \
    -d github.com -f -n 10 -r 4 -t pdf -w
```

Second, the container runs as a fixed user id and group, 1000:1000, and that is not arbitrary. The Dockerfile creates a system group and a system user with exactly that gid and uid, and the mounted volume then has to be writable by that user, so a host directory that belongs to your own account needs to be readable and writable by uid 1000. The entrypoint is also fixed, python metagoofil.py with -o /app/data, which is the output directory inside the container, and the image is built on python:3.13.7-slim-bookworm with git installed and the package lists cleaned up afterwards. The flags in the run command are the tool's own options, and reading them is the fastest way to understand what it does: -d is the domain, -f is the download option, -n 10 and -r 4 are the number of results per page and the number of pages to walk, -t pdf is the file type, and -w is the write option.

## When Google decides you are a bot, and how to keep going

The README has a section titled Google is blocking me, and it is the most operationally useful part of the document. If you start getting HTTP 429 errors, Google has rightfully detected you as a bot and will block your IP for a set period of time. The proposed solution is to use proxychains and a bank of proxies to round robin the lookups. Installing the tool is one package.

```bash
apt install proxychains4 -y
```

Then you edit the proxychains configuration to round robin the lookups through different proxy servers, and the README gives the shape of the file, with two dynamic SOCKS proxies on different local listening ports.

```bash
round_robin
chain_len = 1
proxy_dns
remote_dns_subnet 224
tcp_read_time_out 15000
tcp_connect_time_out 8000
[ProxyList]
socks4 127.0.0.1 9050
socks4 127.0.0.1 9051
```

The round_robin directive with a chain length of one is what distributes the requests, and proxy_dns keeps the DNS resolution inside the tunnel rather than leaking it. The README also points at a book and an interactive lab for anyone who does not already know how to use SSH and dynamic SOCKS proxies, which is a reasonable warning because the SOCKS ports in that example have to be fed by your own tunnel for it to work at all. The final invocation shows the tool running through the chain.

```bash
proxychains4 python metagoofil.py -d https://github.com -f -t pdf,doc,xls
```

And the README notes you could even tune down the -e delay time because you will be leveraging different proxy boxes. The delay exists to stay under the rate limit, and once the requests are spread across addresses it is less necessary.

## What the tool will not find, and when it is the wrong choice

Two limits decide whether this is the right tool for a given question. The first is that the mechanism is a filetype query, so it finds documents by extension on indexed pages, and it will not find a document whose name you know but whose extension is unusual, nor anything behind a login, nor anything on a host that has asked search engines not to index it. If your goal is to find one specific file that a colleague says was emailed to a partner, this is the wrong tool and a proper search of your own mail or storage is the right one. The second limit is the one the README is most candid about, which is that everything depends on Google's index and on Google's tolerance. The tool has no dataset of its own, so its coverage is exactly what Google decides to show, which changes over time and differs by requester and by geography. There is also an ethical and legal boundary the README does not spell out but that the tool's own framing implies. Searching for and downloading files that a site published is a different act from searching for files that a site accidentally exposed, and the latter is where a tool like this can cross from a self audit into someone else's data. The topics recorded for the repository include osint, information-leakage and penetration-testing, and all three of those describe legitimate work only when the target is in scope.

## Conclusion

metagoofil suits a security engineer auditing what an organisation has exposed to search engines, or a penetration tester working through the reconnaissance phase where a filetype query over a domain beats guessing paths. It is the wrong tool if you need to find a specific named document, since the mechanism is a filetype query rather than a search for content, and it is the wrong tool for anything that requires the target to be indexed, since a site that has asked Google not to index it will simply produce no results. Before you point it at a domain, confirm you are authorised to collect what it returns, and read the blocking section, because the tool will start returning HTTP 429 errors as soon as Google decides your traffic looks automated, and the proxychains route in the README is the difference between a usable run and a blocked one.

## FAQ

### What does metagoofil do and how does it work?

It searches Google for specific types of files being publicly hosted on a web site and optionally downloads them to your local box, using a query such as site:example.com filetype:pdf. The README lists OSINT gathering, penetration testing and finding out what your organization leaks to search indexers as the three uses.

### How do I install metagoofil?

Clone the repository, create a virtual environment, upgrade pip and setuptools, and install from requirements.txt, which pins only google 3.0.0 and requests 2.32.5. A Dockerfile is included, and the run command mounts a host data directory and passes the user id 1000:1000 so the container can write to it.

### What should I do if metagoofil starts returning HTTP 429 errors?

Google has detected the traffic as bot activity and will block the IP for a period. The README suggests running the tool through proxychains4 with a bank of proxies in round_robin mode, editing /etc/proxychains4.conf, and invoking proxychains4 python metagoofil.py with your target domain and file types.

## Sources

- [Issues](https://github.com/opsdisk/metagoofil/issues)
- [opsdisk/metagoofil on GitHub](https://github.com/opsdisk/metagoofil)
- [README](https://github.com/opsdisk/metagoofil/blob/master/README.md)
- [Releases](https://github.com/opsdisk/metagoofil/releases)

---

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