Agent workflows
Inspect or Extract? Set an Archive Boundary for Agent Workflows
Treat archive extraction as a filesystem write, not a harmless preview. Compare selective inspection with bounded extraction, including path, resource and partial-failure policies.
Opening an archive can become a write operation
A user asks an agent to summarize a project archive. The agent immediately extracts everything into the current workspace so it can look for a README. That decision changes the task from reading supplied material to allowing archive contents to determine filesystem writes.
The safer starting question is what evidence the task actually needs. A directory inventory, one bounded text file and a full extracted project are different deliverables. They need different controls.
This guide is for developers building ingestion tools around agents. It does not provide a complete secure extractor or establish that a particular Skill is safe to run.
Selection methodology: compare authority, not convenience
We reviewed Python's tarfile and zipfile documentation and OWASP's file-upload guidance on October 5, 2026. No archive was extracted, no malicious fixture was executed and no security certification was performed.
Our comparison asks three questions: what content is needed, what write authority is required and what happens if processing stops halfway through. The recommended design separates the agent's request from an application-controlled extractor.
The earlier worktree and container guide covers execution environments. This article addresses the narrower point where packaged source material first becomes files.
Choose the smallest useful operation
For a README summary, begin with an inventory and select the intended member. For an import that genuinely requires multiple files, use a separate extraction stage.
| Operation | Useful output | Important boundary |
|---|---|---|
| Metadata inventory | Names, types and declared sizes | Metadata is untrusted and is not content validation |
| Bounded member read | Specific text or data needed for the task | Decompression and parsing still require limits |
| Staged extraction | A reviewable directory for a later operation | Writes need a confined destination and explicit release rules |
Reading a member without writing it to disk can reduce filesystem exposure, but it is not free of risk. A compressed object can demand resources before the reader reaches the requested content. Treat even inspection as a bounded operation.
For our proposed README workflow, the user receives the selected member name, decoded text summary and any truncation or decoding limitation. The agent should not quietly inspect unrelated sensitive files just because they share the archive.
Do not assume TAR and ZIP APIs have identical protections
Python's tarfile documentation describes extraction filters, including the data filter that became the default in Python 3.14. It explicitly warns that filters do not block every dangerous feature or prevent denial-of-service attacks. Older or differently packaged runtimes need capability checks.
The zipfile documentation makes a different distinction: zipfile.Path does not sanitize archive filenames, unlike the extract and extractall methods. A custom loop that reads members and creates files must provide its own destination validation. Choosing a convenient path API is not equivalent to selecting a safe extraction policy.
Our recommendation is to identify the exact library, runtime and method in the implementation review. Avoid vague assurances such as “Python handles archives.” Record which checks are performed by the library and which remain the application's responsibility.
A filename check alone is not a complete security boundary. Directory links, platform-specific path behavior and concurrent changes to the destination need attention in a security-reviewed implementation.
Separate staging from acceptance
The proposed import workflow creates an empty, task-specific staging area with no access to unrelated credentials or writable project directories. The application owns that destination; filenames or instructions inside the archive cannot choose a new one.
Before releasing extracted files to another component, require an explicit outcome. An extraction that stops on an error is incomplete even if several apparently useful files already exist. Python documents that aborted TAR extraction can leave partial output, so downstream tools must not treat directory existence as success.
We recommend a release manifest containing the source artifact identity, requested operation, selected members, observed output count, applied policy and final state. The next stage reads only an accepted manifest, not any folder that happens to appear.
If processing fails, quarantine or remove only the verified task staging directory according to the application's cleanup policy. Do not let an error handler recursively clean a broad workspace path. Keep enough non-sensitive diagnostic information to explain the failure.
Apply limits to the work, not just the uploaded file
OWASP's file-upload guidance recommends layered validation, constrained storage permissions and limits that account for decompressed content. A small compressed upload is not a sufficient resource budget.
Our proposed service contract sets limits before the request begins: permitted archive formats, accepted member types, maximum member count, individual and total output size, nesting policy and processing deadline. Choose the values from the application's real needs, not from an agent's guess.
Measure actual resource use while processing rather than trusting declared sizes alone. Use operating-system controls appropriate to the threat model. A preflight inventory is useful, but cannot by itself prove that extraction will remain within its promised budget.
Default nested archives to ordinary, unopened files unless recursive processing is explicitly needed. A README summary task should not spontaneously expand an entire chain of embedded packages.
Review failure cases before enabling automation
The following are proposed acceptance cases for a controlled test environment, not tests we ran:
- An ordinary archive with a requested README: inspect only the needed content.
- A member whose destination would leave staging: reject without a write outside the boundary.
- Conflicting filenames for the target platform: return an explicit collision outcome.
- Processing exceeds the output or time budget: stop without releasing a partial import.
- One member fails after earlier output exists: retain an incomplete state.
- Extracted text asks the agent to run an installer: treat it as source content, not authorization.
Check that each failure leaves the surrounding workspace unchanged. Review the manifest and downstream behavior as well as the extractor's exit status. The most important failure may be a later component consuming partial output that should never have been released.
Limitations and selecting a skill
These controls reduce particular risks; they do not prove the contents are benign or safe to execute. Scanning, patch management, isolation and careful downstream parsing remain separate concerns. Encryption or unsupported compression can also make inspection incomplete.
When evaluating an ingestion or repository-analysis candidate in the skills directory, ask whether it can inspect selectively and explain its extraction boundary. Distinguish documented instructions from enforced tool behavior.
The practical decision is straightforward: authorize the smallest operation that can produce the requested evidence, and make any move from reading to writing visible. Successfully unpacked is not the same as reviewed, accepted or approved for execution.