---
title: "Unpack archives safely · Agent Wranglers"
url: https://agentwranglers.se/playbook/application-security/requests-files-and-caches/safe-archive-extraction
id: APS-45
level: Recommended
updated: 2026-10-27
build: a2a6bdfed830
tokens: 984
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Unpack archives safely

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Requests, files and caches](https://agentwranglers.se/playbook/application-security/requests-files-and-caches.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-27.

- ID: APS-45
- Level: Recommended
- Chapter: [Requests, files and caches](https://agentwranglers.se/playbook/application-security/requests-files-and-caches.md)
- Rule: Keep every entry of an uploaded zip or tar file inside the target folder, and stop unpacking at a fixed total size and file count.
- Check: On the test copy, the agent uploads three archives. One has an entry named `../../marker.txt`, one holds a link to `/etc`, and one expands past the cap. All three are refused, and no file appears outside the target folder.
- How: Check each entry's name before writing it, as in [keep file paths inside their folder](https://agentwranglers.se/playbook/application-security/requests-files-and-caches/block-path-traversal.md). Skip links and device files. Count the bytes as you unpack, and stop at a cap such as 100 MB and 1,000 files. A small archive can expand to many gigabytes. Apply the same caps to compressed request bodies. [Scan files for malware](https://agentwranglers.se/playbook/files-and-media/uploads/scan-uploads.md) before anyone opens what came out.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### Python example

```python
# Python 3.12 or later: the data filter refuses paths outside dest, links out and device files
MAX_BYTES, MAX_FILES = 100 * 1024 * 1024, 1000
with tarfile.open(upload_path) as tar:
    members = tar.getmembers()
    if len(members) > MAX_FILES or sum(m.size for m in members) > MAX_BYTES:
        raise ValueError("archive too large")
    tar.extractall(dest, filter="data")
```

### Go example

```go
// Go 1.20 or later: filepath.IsLocal refuses absolute paths and ".."
var total uint64
for count, entry := range zipReader.File {
	if !filepath.IsLocal(entry.Name) || entry.Mode()&(fs.ModeSymlink|fs.ModeDevice) != 0 {
		return errors.New("unsafe entry: " + entry.Name)
	}
	total += entry.UncompressedSize64 // the header can lie, so also copy through io.LimitReader
	if count >= maxFiles || total > maxBytes {
		return errors.New("archive too large")
	}
}
```

## Sources

- [CWE-22 Path Traversal](https://cwe.mitre.org/data/definitions/22.html)
- [CWE-409 Improper Handling of Highly Compressed Data](https://cwe.mitre.org/data/definitions/409.html)

## Related rules

- APS-44 [Keep file paths inside their folder](https://agentwranglers.se/playbook/application-security/requests-files-and-caches/block-path-traversal.md) in Application security
- MED-44 [Scan files for malware before anyone opens them](https://agentwranglers.se/playbook/files-and-media/uploads/scan-uploads.md) in Files and media

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/application-security/requests-files-and-caches/safe-archive-extraction">Agent Wranglers application security playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Keep file paths inside their folder](https://agentwranglers.se/playbook/application-security/requests-files-and-caches/block-path-traversal.md)
- Next: [Keep private pages out of shared caches](https://agentwranglers.se/playbook/application-security/requests-files-and-caches/private-responses-uncached.md)
- [Requests, files and caches](https://agentwranglers.se/playbook/application-security/requests-files-and-caches.md)